Totem Stats

The Totems contract tracks onchain statistics for every Totem. These stats are useful for analytics, leaderboards, and mod logic.

TotemStats Struct

struct TotemStats {
    uint64 mints;      // Total mint operations
    uint64 burns;      // Total burn operations
    uint64 transfers;  // Total transfer operations
    uint64 holders;    // Current unique holders
}

Querying Stats

Use TotemsLibrary.getTotemStats() to retrieve stats in your mod:

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

function checkStats(string calldata ticker) external view {
    ITotemTypes.TotemStats memory stats = TotemsLibrary.getTotemStats(totemsContract, ticker);

    uint64 totalMints = stats.mints;
    uint64 totalBurns = stats.burns;
    uint64 totalTransfers = stats.transfers;
    uint64 currentHolders = stats.holders;
}

Stat Descriptions

mints

The total number of mint operations that have occurred for this Totem. Increments each time Totems are minted, regardless of amount.

burns

The total number of burn operations. Increments each time totems are burned, regardless of amount.

transfers

The total number of transfer operations. Increments on every transfer, including transfers triggered by mints (when totems are allocated to recipients).

holders

The current count of unique addresses holding a non-zero balance. This value:

• Increases when an address receives totems for the first time
• Decreases when an address’s balance drops to zero

Using Stats in Mods

Stats enable powerful mod logic:

contract HolderGatedMod is TotemMod, IModTransfer {

    constructor(address _totemsContract, address payable _seller)
        TotemMod(_totemsContract, _seller) {}

    function isSetupFor(string calldata ticker) external view override returns (bool) {
        return true;
    }

    function onTransfer(
        string calldata ticker,
        address from,
        address to,
        uint256 amount,
        string calldata memo
    ) external onlyTotems onlyLicensed(ticker) {
        // Only allow transfers if totem has < 1000 holders
        ITotemTypes.TotemStats memory stats = TotemsLibrary.getTotemStats(totemsContract, ticker);
        require(stats.holders < 1000, "Max holders reached");
    }
}