Realms SDK

How to navigate the repo

⋅⋅⋅ src/utils

Contain helper functions, including a function to easily instanciate a realm contract. After instanciation, you can call any functions on this contract (names correspond to the Cairo contract function names).

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_NODE_URL! });
const { buildingsModuleClass } = getRealmsClasses(provider);

const TOKEN_ID = "141";
const buildings = await buildingsModuleClass.getBuildingsUnpacked(TOKEN_ID);

Note: no need to worry about contract abis or addresses.

Multicall.ts: Class allowing you to make multicalls (= calling multiple view function at once without waiting)

Unpacker.ts: Class allowing you to unpack realm data like costs, armies, ...

ValueAdapter.ts: Class used internally to adapt and reuse output more easily

data: Folder containing multiple data about realms like coordinates, resources held, orders, ...

src/constants

Folder containing all Realms constants

• Building ids
• Resources ids
• Battalion ids
• Battalion stats
• ...

⋅⋅⋅ src/game

Folder containing all contract abstactions and game types. This is where you can interact with contracts (see src/utils to instanciate).

Write functions

Write methods like initiateCombat or buildArmyFromBattalion don't immediately write on the blockchain. Instead they return a starknetjs call that can be used later. This allow someone to make custom multicalls more easily.

Example:

import dotenv from "dotenv";
dotenv.config();
import { getRealmsClasses } from "realms-sdk/lib/src/utils";
import { Account, RpcProvider } from "starknet";
import { getKeyPair } from "starknet/dist/utils/ellipticCurve";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_GOERLI_NODE_URL! });

const settle = async function() {
    // get starknetjs account from already deployed account
    const keyPair = getKeyPair(process.env.ARGENT_PRIVATE_KEY!);
    const account = new Account(provider, process.env.ARGENT_ACCOUNT_ADDRESS!, keyPair);

    // get class
    const { settleModuleClass } = getRealmsClasses(provider);

    // get settle calls
    const realmIds = ["271", "2715"];
    const calls = realmIds.map(id => settleModuleClass.settle(id));

    // execute the calls
    const tx = await account.execute(calls);
    console.log(tx.transaction_hash);
}

settle();

⋅⋅⋅ src/organizers

Folder containing classes to group, decode and analyze Realms transactions. Calldata used to be unreadable back in the days, and this help to filter and read all that happened on the Realm battleground.

It analyze every interactions with every contract behind the scene, decode transaction calldata and events, and match them with the associated contract interaction (Lords, Combat, ...)

You can instanciate the RealmBlockAnalyzer.ts class the same way you instanciate other classes. You can also add some parameters like:

import _data from "./data/realmsTxsPerBlocks/10-3-2022.json"; // allready organized data from RealmsBlockOrganizer

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_NODE_URL! });

const { realmsBlocksOrganizerClass } = getRealmsClasses(provider, {
    organizedRealmsBlocks: data, // add pre-fetched data to only organize and read it
    msBetweenQueries: 0 // put more in case you are rate limited
});

const lastestBlockNumber = await provider.getBlockNumber();
// get Realms transactions and organize them for the last 10 blocks
const allTxs = await realmsBlocksOrganizerClass.getRealmsTxsInBlockRange(lastestBlockNumber - 1, lastestBlockNumber - 10);

⋅⋅⋅ tests

There is an example for every function of every class. Go to the tests folder for a more detailed way to use it.

⋅⋅⋅ scripts

A folder containing scripts I used for multiple reason. I've let them for transaprency purposes. They have been used to deploy Multicall.cairo and fetch realm data.