Totem Details

Every Totem stores comprehensive information onchain, from basic metadata to allocation records and mod assignments.

Totem Struct

struct Totem {
    address payable creator;       // Creator's address
    uint64 createdAt;              // Creation timestamp
    uint64 updatedAt;              // Last update timestamp
    bool isActive;                 // Whether Totem is active
    uint256 supply;                // Current circulating supply
    uint256 maxSupply;             // Maximum possible supply
    MintAllocation[] allocations;  // Initial allocations
    TotemMods mods;                // Licensed mods per hook
    TotemDetails details;          // Display and identity info
}

Query with TotemsLibrary.getTotem():

import "@totems/evm/mods/TotemsLibrary.sol";

ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

address creator = totem.creator;
uint256 currentSupply = totem.supply;
uint256 maxSupply = totem.maxSupply;
bool active = totem.isActive;
string memory ticker = totem.details.ticker;
uint8 decimals = totem.details.decimals;
bytes32 seed = totem.details.seed;

TotemDetails Struct

The TotemDetails struct contains identity and display metadata:

struct TotemDetails {
    bytes32 seed;        // Generative seed
    uint8 decimals;      // Decimal places
    string ticker;       // Ticker symbol (1-10 uppercase letters)
    string name;         // Display name
    string description;  // Description text
    string image;        // Image URL or IPFS hash
    string website;      // Website URL
}

Access details from the Totem:

ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

string memory name = totem.details.name;
string memory description = totem.details.description;
uint8 decimals = totem.details.decimals;

Seeds

Every totem has a seed - a 32-byte value that can be used for generative properties, randomization, and deterministic behavior.

What Seeds Provide

• Creator-defined: The creator chooses the seed at creation time
• Determinism: The same seed always produces the same results
• Immutability: Set at creation and cannot be changed
• On-chain data: A source of pseudo-random data for mods

Using Seeds in Mods

Derive consistent properties from the seed:

function getTotemRarity(string calldata ticker) external view returns (uint8) {
    ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

    // Derive rarity from seed (0-100)
    return uint8(uint256(totem.details.seed) % 101);
}

function getTotemTraits(string calldata ticker) external view returns (uint8[4] memory) {
    ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

    // Derive multiple traits from different parts of the seed
    return [
        uint8(uint256(totem.details.seed) % 256),
        uint8(uint256(totem.details.seed >> 8) % 256),
        uint8(uint256(totem.details.seed >> 16) % 256),
        uint8(uint256(totem.details.seed >> 24) % 256)
    ];
}

Deterministic Randomness

Combine the seed with other data for unique-per-holder values:

function getRandomForHolder(
    string calldata ticker,
    address holder
) external view returns (uint256) {
    ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

    // Combine seed with holder address
    return uint256(keccak256(abi.encodePacked(totem.details.seed, holder)));
}

Mint Allocations

Initial token distribution is stored in allocations:

struct MintAllocation {
    address payable recipient; // Address to receive totems
    bool isMinter;             // Whether recipient is a minter mod
    uint256 amount;            // Amount (0 = unlimited)
    string label;              // Human-readable label
}

Query allocations:

ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);

for (uint i = 0; i < totem.allocations.length; i++) {
    ITotemTypes.MintAllocation memory alloc = totem.allocations[i];
    // alloc.label, alloc.recipient, alloc.amount, alloc.isMinter
}

Totem Mods

Licensed mods are organized by hook type:

struct TotemMods {
    address[] transfer;            // Mods for transfer hook
    address[] mint;                // Mods for mint hook
    address[] burn;                // Mods for burn hook
    address[] created;             // Mods for created hook
    address[] transferOwnership;   // Mods for ownership transfer hook
}