dojo-token

Dojo Tokens

Implement ERC20/ERC721 tokens in Cairo, deploy them alongside your Dojo world, and configure Torii to index balances, transfers, and metadata.

When to Use This Skill

• "Implement ERC20 token for game currency"
• "Create NFT items with ERC721"
• "Deploy an ERC20 token with my world"
• "Index token balances with Torii"
• "Query token transfers"
• "Use Origami for tokens"

What This Skill Does

• Implement ERC20 fungible tokens and ERC721 NFTs in Cairo
• Deploy token contracts as external contracts via sozo migrate
• Configure Torii to index token balances, transfers, and metadata
• Query token data via SQL and client SDKs

Using Origami Library

Add to Scarb.toml:

[dependencies]
origami_token = { git = "https://github.com/dojoengine/origami", tag = "v1.0.0" }

Origami provides reusable token components following standard interfaces. Refer to the Origami documentation for the latest API.

Simple Token Implementation

You can implement tokens using standard Dojo models without Origami.

ERC20-like Currency

#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Gold {
    #[key]
    pub player: ContractAddress,
    pub amount: u256,
}

#[starknet::interface]
trait IGoldToken<T> {
    fn mint(ref self: T, to: ContractAddress, amount: u256);
    fn transfer(ref self: T, to: ContractAddress, amount: u256);
    fn balance_of(self: @T, account: ContractAddress) -> u256;
}

#[dojo::contract]
mod gold_token {
    use super::{IGoldToken, Gold};
    use starknet::{ContractAddress, get_caller_address};
    use dojo::model::ModelStorage;

    #[abi(embed_v0)]
    impl GoldTokenImpl of IGoldToken<ContractState> {
        fn mint(ref self: ContractState, to: ContractAddress, amount: u256) {
            let mut world = self.world_default();

            let mut balance: Gold = world.read_model(to);
            balance.amount += amount;
            world.write_model(@balance);
        }

        fn transfer(ref self: ContractState, to: ContractAddress, amount: u256) {
            let mut world = self.world_default();
            let from = get_caller_address();

            let mut from_balance: Gold = world.read_model(from);
            let mut to_balance: Gold = world.read_model(to);

            assert(from_balance.amount >= amount, 'insufficient balance');

            from_balance.amount -= amount;
            to_balance.amount += amount;

            world.write_model(@from_balance);
            world.write_model(@to_balance);
        }

        fn balance_of(self: @ContractState, account: ContractAddress) -> u256 {
            let world = self.world_default();
            let balance: Gold = world.read_model(account);
            balance.amount
        }
    }

    #[generate_trait]
    impl InternalImpl of InternalTrait {
        fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
            self.world(@"my_game")
        }
    }
}

ERC721-like NFT

#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct Weapon {
    #[key]
    pub token_id: u256,
    pub owner: ContractAddress,
    pub damage: u32,
    pub rarity: u8,
}

#[starknet::interface]
trait IWeaponNFT<T> {
    fn mint(ref self: T, to: ContractAddress, damage: u32) -> u256;
    fn transfer(ref self: T, to: ContractAddress, token_id: u256);
    fn owner_of(self: @T, token_id: u256) -> ContractAddress;
}

#[dojo::contract]
mod weapon_nft {
    use super::{IWeaponNFT, Weapon};
    use starknet::{ContractAddress, get_caller_address};
    use dojo::model::ModelStorage;

    #[abi(embed_v0)]
    impl WeaponNFTImpl of IWeaponNFT<ContractState> {
        fn mint(ref self: ContractState, to: ContractAddress, damage: u32) -> u256 {
            let mut world = self.world_default();

            let token_id: u256 = world.uuid().into();

            let weapon = Weapon {
                token_id,
                owner: to,
                damage,
                rarity: 1,
            };

            world.write_model(@weapon);
            token_id
        }

        fn transfer(ref self: ContractState, to: ContractAddress, token_id: u256) {
            let mut world = self.world_default();
            let from = get_caller_address();

            let mut weapon: Weapon = world.read_model(token_id);
            assert(weapon.owner == from, 'not owner');

            weapon.owner = to;
            world.write_model(@weapon);
        }

        fn owner_of(self: @ContractState, token_id: u256) -> ContractAddress {
            let world = self.world_default();
            let weapon: Weapon = world.read_model(token_id);
            weapon.owner
        }
    }

    #[generate_trait]
    impl InternalImpl of InternalTrait {
        fn world_default(self: @ContractState) -> dojo::world::WorldStorage {
            self.world(@"my_game")
        }
    }
}

Token Events

Emit events so Torii and clients can track token operations:

#[derive(Copy, Drop, Serde)]
#[dojo::event]
pub struct TokenTransferred {
    #[key]
    pub from: ContractAddress,
    #[key]
    pub to: ContractAddress,
    pub amount: u256,
}

// Emit in your functions
world.emit_event(@TokenTransferred { from, to, amount });

Deploying Token Contracts

Token contracts are deployed as external contracts alongside your Dojo world. See dojo-deploy skill for general deployment workflow.

Add to Scarb.toml

[[target.starknet-contract]]
build-external-contracts = [
    "dojo::world::world_contract::world",
    "tokens::models::m_ERC20Token"
]

Configure in Profile

In dojo_dev.toml, define the token as an external contract:

[[external_contracts]]
contract_name = "ERC20Token"
instance_name = "GoldToken"
salt = "1"
constructor_data = [
    "str:Gold Coin",                # Token name
    "sstr:GOLD",                    # Symbol
    "u256:1000000000000000000",     # Total supply (1e18)
    "0x1234567890abcdef..."         # Owner address
]

Add more [[external_contracts]] blocks for additional tokens. Deploy with sozo build && sozo migrate. Note the contract addresses from the output — you need them for Torii.

Indexing Tokens with Torii

Torii indexes ERC token contracts separately from Dojo world state. You must explicitly tell Torii which contracts to watch. See dojo-indexer skill for general Torii configuration.

Configuration

Add token contracts to [indexing] using the ERC20: or ERC721: prefix:

# torii.toml
[indexing]
contracts = [
    "ERC20:0xYOUR_GOLD_TOKEN_ADDRESS",
    "ERC721:0xYOUR_WEAPON_NFT_ADDRESS",
]

Or via CLI:

torii --world 0xYOUR_WORLD \
  --indexing.contracts "ERC20:0xGOLD_TOKEN" \
  --indexing.contracts "ERC721:0xWEAPON_NFT"

You can also index well-known tokens on the network:

[indexing]
contracts = [
    "ERC20:0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", # ETH
    "ERC20:0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d", # STRK
]

Querying Token Data

Once indexed, three database tables become available:

• tokens — metadata (name, symbol, decimals)
• balances — per-account balances
• erc_transfers — transfer history

SQL

SELECT * FROM tokens;
SELECT * FROM balances WHERE account_address = '0xPLAYER';
SELECT * FROM erc_transfers ORDER BY rowid DESC LIMIT 20;

JavaScript SDK

import { useTokens } from "@dojoengine/sdk/react";

function TokenBalance({ address }: { address: string }) {
    const { tokens, getBalance, toDecimal } = useTokens({
        accountAddresses: [address],
    });

    return (
        <div>
            {tokens.map((token, idx) => (
                <div key={idx}>
                    {token.symbol}: {toDecimal(token, getBalance(token))}
                </div>
            ))}
        </div>
    );
}

Troubleshooting

"Empty tokens/balances tables"

• Verify the contract address matches what was deployed
• Check the prefix is correct (ERC20: vs ERC721:)
• Ensure the contract implements standard ERC Transfer events

"Token not showing in Torii"

• Restart Torii after adding new contracts
• Check Torii logs for indexing errors

"Balance shows 0"

• Tokens are indexed from transfer events, not storage reads
• Mint or transfer tokens to generate events Torii can index

Related Skills

• dojo-model: Token models extend Dojo models
• dojo-system: Token logic in systems
• dojo-test: Test token operations
• dojo-deploy: General world deployment workflow
• dojo-indexer: Full Torii configuration and queries
• dojo-client: Client SDK integration