Totems Library

The TotemsLibrary is a helper library that simplifies interactions with the Totems contract from within your Mod. It provides convenient wrappers around common operations like getting totem information, balances, and totem operations.

Import

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

License Verification

These functions help ensure your Mod is properly licensed before executing logic.

hasLicense

function hasLicense(address totems, string memory ticker, address mod) internal view returns (bool);

Returns true if the specified mod address is licensed for the totem, false otherwise. This is used internally by the onlyLicensed modifier in TotemMod.

// Check if another mod is licensed (not yourself)
if (TotemsLibrary.hasLicense(totemsContract, ticker, someOtherMod)) {
    // Handle case where another mod is also licensed
}

Note

For your own mod’s license check, use the built-in onlyLicensed(ticker) modifier from TotemMod instead of calling this directly.

checkLicense

function checkLicense(address totems, string memory ticker) internal view;

Verifies that the calling contract (your Mod) is licensed for the specified totem. Reverts if the license is invalid or missing.

This is a convenience function that reverts on failure. The onlyLicensed modifier uses hasLicense internally, but checkLicense is available if you need to check license status at a specific point in your function rather than at the entry point.

Totem Data

getCreator

function getCreator(address totems, string memory ticker) internal view returns (address);

Returns the address of the account that created the totem. Useful for implementing creator-only functionality.

address creator = TotemsLibrary.getCreator(totemsContract, ticker);
require(msg.sender == creator, "Only creator allowed");

isMinter

function isMinter(address totems, string calldata ticker, address account) internal view returns (bool);

Checks whether an address is a minter mod for a specific totem. Returns true if the account appears in the totem’s allocations with isMinter set to true.

// Check if an address is an authorized minter for a totem
if (TotemsLibrary.isMinter(totemsContract, ticker, someAddress)) {
    // Handle minter-specific logic
}

getTotem

function getTotem(address totems, string memory ticker) internal view returns (ITotemTypes.Totem memory);

Returns the full totem details struct containing metadata and configuration. See Totem Details for the struct definition.

ITotemTypes.Totem memory totem = TotemsLibrary.getTotem(totemsContract, ticker);
// Access totem.creator, totem.supply, totem.details.name, totem.details.decimals, etc.

getTotemStats

function getTotemStats(address totems, string memory ticker) internal view returns (ITotemTypes.TotemStats memory);

Returns statistics about the totem including mint/burn/transfer counts and holder count. See Totem Stats for the struct definition.

ITotemTypes.TotemStats memory stats = TotemsLibrary.getTotemStats(totemsContract, ticker);
uint64 totalMints = stats.mints;
uint64 holderCount = stats.holders;

Balance & Transfers

getBalance

function getBalance(address totems, string memory ticker, address account) internal view returns (uint256);

Returns the totem balance for any address.

// Get this mod's balance
uint256 modBalance = TotemsLibrary.getBalance(totemsContract, ticker, address(this));

// Get a user's balance
uint256 userBalance = TotemsLibrary.getBalance(totemsContract, ticker, userAddress);

transfer

function transfer(address totems, string memory ticker, address to, uint256 amount, string memory memo) internal;

Transfers totems from your Mod’s balance to another address. The Mod must have sufficient balance.

// Send 100 tokens from this mod to the user
TotemsLibrary.transfer(totemsContract, ticker, userAddress, 100, "Reward payout");

Utilities

tickerToBytes

function tickerToBytes(string calldata ticker) internal pure returns (bytes32);

Converts a ticker string to a bytes32 hash.

The function normalizes tickers to uppercase and validates that:

Length is between 1-10 characters
Only contains letters A-Z (case-insensitive input)

Note

This is used internally in the Totems contract to validate and store tickers, however you don’t have to use this yourself. Storing a string into a variable in Solidity will already keccak256 hash it when used as a mapping key, and the Totems contract has done pre-validation of all tickers you’ll ever get a hook event for.

mapping(bytes32 => bool) public frozen;

function freeze(string calldata ticker) external {
    bytes32 tickerHash = TotemsLibrary.tickerToBytes(ticker);
    frozen[tickerHash] = true;
}

Errors:

Error	Description
`InvalidTickerLength(uint256 length)`	Ticker is empty or longer than 10 characters
`InvalidTickerChar(uint8 char)`	Ticker contains non-letter characters

<- Minter Mods

Testing