@totems/evm 1.0.0

package/interfaces/IMarket.sol

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: MIT
+// AUTO-GENERATED - DO NOT EDIT
+// Generated from ModMarket
+pragma solidity ^0.8.28;
+
+import "../library/ITotemTypes.sol";
+
+interface IMarket {
+    // ==================== FUNCTIONS ====================
+
+    /**
+     * @notice Set your referrer fee for mod publishing
+     * @dev Referrers earn fees when users publish mods using their address.      Fee must be at least minBaseFee. The referrer receives (fee - burnedFee).
+     * @param fee The fee amount in wei (must be >= minBaseFee)
+     */
+    function setReferrerFee(uint256 fee) external;
+
+    /**
+     * @notice Get the fee for creating a totem or publishing a mod
+     * @param referrer The referrer address (or zero address for no referrer)
+     * @return The total fee required (at least minBaseFee)
+     */
+    function getFee(address referrer) external view returns (uint256);
+
+    /**
+     * @notice Publish a mod to the marketplace
+     * @dev Only the mod's seller (returned by mod.getSeller()) can publish.      Validates: contract exists, not already published, name 3-100 chars,      summary 10-150 chars, image URL present, valid hooks with no duplicates.      Excess payment is refunded to sender.
+     * @param mod Deployed mod contract address
+     * @param hooks Array of supported hook identifiers (Created, Mint, Burn, Transfer, TransferOwnership)
+     * @param price Price in wei to use this mod (paid when totem creator adds the mod)
+     * @param details Mod display details (name, summary, image, website, etc.)
+     * @param requiredActions Setup actions users must call after totem creation
+     * @param referrer Optional referrer address (receives fee minus burned amount)
+     */
+    function publish(address mod, ITotemTypes.Hook[] calldata hooks, uint256 price, ITotemTypes.ModDetails calldata details, ITotemTypes.ModRequiredAction[] calldata requiredActions, address payable referrer) external payable;
+
+    /**
+     * @notice Update mod price and details
+     * @param mod Mod contract address
+     * @param newPrice New price in wei
+     * @param details New mod details
+     */
+    function update(address mod, uint256 newPrice, ITotemTypes.ModDetails calldata details) external;
+
+    /**
+     * @notice Update required actions for a mod
+     * @param mod Mod contract address
+     * @param requiredActions New required setup actions
+     */
+    function updateRequiredActions(address mod, ITotemTypes.ModRequiredAction[] calldata requiredActions) external;
+
+    /**
+     * @notice Get a single mod by address
+     * @param mod Mod contract address
+     * @return Mod struct
+     */
+    function getMod(address mod) external view returns (ITotemTypes.Mod memory);
+
+    /**
+     * @notice Get the usage price for a single mod
+     * @param mod Mod contract address
+     * @return The price in wei to use this mod
+     */
+    function getModFee(address mod) external view returns (uint256);
+
+    /**
+     * @notice Get required actions for a mod (setup actions called after totem creation)
+     * @param mod Mod contract address
+     * @return Array of required actions
+     */
+    function getModRequiredActions(address mod) external view returns (ITotemTypes.ModRequiredAction[] memory);
+
+    /**
+     * @notice Get multiple mods by their addresses
+     * @param contracts Array of mod contract addresses
+     * @return Array of Mod structs
+     */
+    function getMods(address[] calldata contracts) external view returns (ITotemTypes.Mod[] memory);
+
+    /**
+     * @notice Get the total usage price for multiple mods
+     * @dev Useful for calculating total cost when creating a totem with multiple mods
+     * @param contracts Array of mod contract addresses
+     * @return Total price in wei for all mods combined
+     */
+    function getModsFee(address[] calldata contracts) external view returns (uint256);
+
+    /**
+     * @notice Get the hooks supported by a mod
+     * @dev Hooks determine when the mod is called (Created, Mint, Burn, Transfer, TransferOwnership)
+     * @param mod Mod contract address
+     * @return Array of Hook enum values
+     */
+    function getSupportedHooks(address mod) external view returns (ITotemTypes.Hook[] memory);
+
+    /**
+     * @notice Check if a mod requires unlimited minting capability
+     * @dev Mods with needsUnlimited=true can mint tokens without supply cap restrictions.      Returns false for unpublished mods.
+     * @param mod Mod contract address
+     * @return True if the mod needs unlimited minting capability
+     */
+    function isUnlimitedMinter(address mod) external view returns (bool);
+
+    /**
+     * @notice List mods with pagination
+     * @param perPage Number of results per page
+     * @param cursor Index to start from (for pagination)
+     * @return mods_ Array of Mod structs
+     * @return nextCursor Next cursor value
+     * @return hasMore Whether more results exist
+     */
+    function listMods(uint32 perPage, uint256 cursor) external view returns (ITotemTypes.Mod[] memory mods_, uint256 nextCursor, bool hasMore);
+
+    /**
+     * @notice Ordered list of all published mod addresses (for pagination)
+     */
+    function modList(uint256) external view returns (address);
+
+    /**
+     * @notice Fee amount that is always burned (set once in constructor, never changed)
+     */
+    function burnedFee() external view returns (uint256);
+
+    /**
+     * @notice Minimum base fee for mod publishing (set once in constructor, never changed)
+     */
+    function minBaseFee() external view returns (uint256);
+
+    // ==================== EVENTS ====================
+
+    event ModPublished(address indexed mod);
+    event ModUpdated(address indexed mod);
+
+    // ==================== ERRORS ====================
+
+    error DuplicateHook(ITotemTypes.Hook hook);
+    error EmptyModImage();
+    error EmptyModName();
+    error EmptyModSummary();
+    error InsufficientFee(uint256 required, uint256 provided);
+    error InvalidContractAddress();
+    error InvalidHook(ITotemTypes.Hook hook);
+    error ModAlreadyPublished(address mod);
+    error ModNameTooLong(uint256 length);
+    error ModNameTooShort(uint256 length);
+    error ModNotFound(address mod);
+    error ModSummaryTooLong(uint256 length);
+    error ModSummaryTooShort(uint256 length);
+    error NoHooksSpecified();
+    error ReferrerFeeTooLow(uint256 minFee);
+    error TransferFailed();
+    error Unauthorized();
+}

package/interfaces/IRelayFactory.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+interface IRelayFactory {
+    event RelayCreated(
+        string indexed ticker,
+        address indexed relayContract
+    );
+
+    function createRelay(
+        string calldata ticker
+    ) external returns (address);
+}

package/interfaces/ITotemTypes.sol

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title ITotemTypes
+ * @notice Interface and types for the Totems ecosystem
+ * @dev This library provides core types and structures for Totems and Mods
+ */
+interface ITotemTypes {
+
+    struct RelayInfo {
+        address relay;
+        string standard;
+    }
+
+    /// @notice Valid hook identifiers
+    enum Hook {
+        Created,
+        Mint,
+        Burn,
+        Transfer,
+        TransferOwnership
+    }
+
+    /**
+     * @notice Display details for a mod
+     * @param name Mod name
+     * @param summary Short description
+     * @param markdown Detailed markdown description
+     * @param image Image URL or IPFS hash
+     * @param website Website URL
+     * @param websiteTickerPath Path template for token-specific pages
+     * @param isMinter Whether this mod is a token minter
+     */
+    struct ModDetails {
+        string name;
+        string summary;
+        string markdown;
+        string image;
+        string website;
+        string websiteTickerPath;
+        bool isMinter;
+        bool needsUnlimited;
+    }
+
+    // Input mode for mod action fields
+    enum ModActionFieldInputMode {
+        // Request input from the user
+        DYNAMIC,
+        // Predefined static value
+        STATIC,
+        // Auto-fill with the current totem ticker
+        TOTEM
+    }
+
+    struct ModActionField {
+        // ex: "totem, mintPerMine"
+        string name;
+        ModActionFieldInputMode mode;
+        // only used for STATIC mode
+        string value;
+        // Human-readable description of this field for UIs (optional)
+        string description;
+        // Minimum value constraint for numeric inputs (0 = no minimum)
+        uint256 min;
+        // Maximum value constraint for numeric inputs (0 = no maximum)
+        uint256 max;
+        // Is this field expecting to receive totem amounts?
+        bool isTotems;
+    }
+
+    struct ModRequiredAction {
+        // ex: "setup(string totem, uint256 mintPerMine)"
+        // (only the ~canonical function signature, no "function" keyword, modifiers, or mutability)
+        // Also no return types!
+        string signature;
+        ModActionField[] inputFields;
+        // Is there a msg.value required to perform this action?
+        // If > 0 this will make the function payable
+        uint256 cost;
+        // Explain to users why this action is required for UIs
+        string reason;
+    }
+
+    /**
+     * @notice On-chain Mod entry in the marketplace
+     * @param mod The deployed mod contract address
+     * @param seller Address that receives payments for this mod
+     * @param price Price in wei to use this mod
+     * @param details Display details
+     * @param hooks Array of supported hook names
+     * @param publishedAt Timestamp of publication
+     * @param updatedAt Timestamp of last update
+     */
+    struct Mod {
+        address mod;
+        address payable seller;
+        uint64 publishedAt;
+        uint64 updatedAt;
+        uint256 price;
+        Hook[] hooks;
+        ModDetails details;
+    }
+
+    /**
+     * @notice Allocation of tokens at creation time
+     * @param label Human-readable label
+     * @param recipient Address to receive tokens
+     * @param amount Amount of tokens
+     * @param isMinter Whether this recipient is a minter mod
+     */
+    struct MintAllocation {
+        address payable recipient;
+        bool isMinter;
+        uint256 amount;
+        string label;
+    }
+
+    /**
+     * @notice Display details for a totem
+     * @param name Totem name
+     * @param description Detailed description
+     * @param image Image URL or IPFS hash
+     * @param website Website URL
+     * @param seed Generative seed for totem properties
+     */
+    struct TotemDetails {
+        bytes32 seed;
+        uint8 decimals;
+        string ticker;
+        string name;
+        string description;
+        string image;
+        string website;
+    }
+
+    /**
+     * @notice Mods assigned to each hook type
+     * @param transfer Mods for transfer hook
+     * @param mint Mods for mint hook
+     * @param burn Mods for burn hook
+     * @param created Mods for created hook
+     * @param transferOwnership Mods for transfer ownership hook
+     */
+    struct TotemMods {
+        address[] transfer;
+        address[] mint;
+        address[] burn;
+        address[] created;
+        address[] transferOwnership;
+    }
+
+    /**
+     * @notice Complete totem information
+     * @param creator Address that created the totem
+     * @param supply Current circulating supply
+     * @param maxSupply Maximum possible supply
+     * @param allocations Initial token allocations
+     * @param mods Mods for each hook type
+     * @param details Display information
+     * @param createdAt Creation timestamp
+     * @param updatedAt Last update timestamp
+     */
+    struct Totem {
+        address payable creator;
+        uint64 createdAt;
+        uint64 updatedAt;
+        bool isActive;
+        uint256 supply;
+        uint256 maxSupply;
+        MintAllocation[] allocations;
+        TotemMods mods;
+        TotemDetails details;
+    }
+
+    /**
+     * @notice Statistics for a totem
+     * @param ticker Token symbol
+     * @param mints Total number of mint operations
+     * @param burns Total number of burn operations
+     * @param transfers Total number of transfers
+     * @param holders Total number of unique holders
+     */
+    struct TotemStats {
+        uint64 mints;
+        uint64 burns;
+        uint64 transfers;
+        uint64 holders;
+    }
+
+    /**
+     * @notice Fee disbursement information
+     * @param recipient Address to receive funds
+     * @param amount Amount in wei
+     */
+    struct FeeDisbursement {
+        address payable recipient;
+        uint256 amount;
+    }
+}

package/interfaces/ITotems.sol

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: MIT
+// AUTO-GENERATED - DO NOT EDIT
+// Generated from Totems
+pragma solidity ^0.8.28;
+
+import "../library/ITotemTypes.sol";
+
+interface ITotems {
+    // ==================== FUNCTIONS ====================
+
+    /**
+     * @notice Creates a new totem with the specified details, allocations, and mods
+     */
+    function create(ITotemTypes.TotemDetails calldata details, ITotemTypes.MintAllocation[] calldata allocations, ITotemTypes.TotemMods calldata mods, address payable referrer) external payable;
+
+    /**
+     * @notice Burns tokens from a totem, permanently reducing supply
+     */
+    function burn(string calldata ticker, address owner, uint256 amount, string calldata memo) external;
+
+    /**
+     * @notice Mints tokens for a totem using an authorized minter mod
+     */
+    function mint(address mod, address minter, string calldata ticker, uint256 amount, string calldata memo) external payable;
+
+    /**
+     * @notice Transfers tokens between addresses
+     */
+    function transfer(string calldata ticker, address from, address to, uint256 amount, string calldata memo) external;
+
+    /**
+     * @notice Transfers ownership of a totem to a new address
+     */
+    function transferOwnership(string calldata ticker, address payable newOwner) external;
+
+    /**
+     * @notice Authorizes an existing relay address for a totem
+     */
+    function addRelay(string calldata ticker, address relay, string calldata standard) external;
+
+    /**
+     * @notice Creates a new relay for a totem using a relay factory
+     */
+    function createRelay(string calldata ticker, address relayFactory, string calldata standard) external returns (address relay);
+
+    /**
+     * @notice Revokes authorization for a relay from a totem
+     */
+    function removeRelay(string calldata ticker, address relay) external;
+
+    /**
+     * @notice Gets the relay address for a specific standard on a totem
+     */
+    function getRelayOfStandard(string calldata ticker, string calldata standard) external view returns (address);
+
+    /**
+     * @notice Gets all authorized relays for a totem
+     */
+    function getRelays(string calldata ticker) external view returns (ITotemTypes.RelayInfo[] memory);
+
+    /**
+     * @notice Grants a mod license for a totem, callable only by the proxy mod
+     */
+    function setLicenseFromProxy(bytes32 tickerBytes, address mod) external;
+
+    /**
+     * @notice Checks if a mod is licensed for a specific totem
+     */
+    function isLicensed(string calldata ticker, address mod) external view returns (bool);
+
+    /**
+     * @notice Sets the referrer fee for the caller
+     */
+    function setReferrerFee(uint256 fee) external;
+
+    /**
+     * @notice Gets the fee for creating a totem
+     */
+    function getFee(address referrer) external view returns (uint256);
+
+    /**
+     * @notice Retrieves a totem by its ticker symbol
+     */
+    function getTotem(string calldata ticker) external view returns (ITotemTypes.Totem memory);
+
+    /**
+     * @notice Retrieves multiple totems by their ticker symbols
+     */
+    function getTotems(string[] calldata tickers) external view returns (ITotemTypes.Totem[] memory);
+
+    /**
+     * @notice Lists totems with pagination support
+     */
+    function listTotems(uint32 perPage, uint256 cursor) external view returns (ITotemTypes.Totem[] memory, uint256, bool);
+
+    /**
+     * @notice Gets the token balance for an account on a specific totem
+     */
+    function getBalance(string calldata ticker, address account) external view returns (uint256);
+
+    /**
+     * @notice Gets the statistics for a totem
+     */
+    function getStats(string calldata ticker) external view returns (ITotemTypes.TotemStats memory);
+
+    /**
+     * @notice Gets the proxy mod address
+     */
+    function getProxyMod() external view returns (address);
+
+    /**
+     * @notice Converts a ticker string to its normalized bytes32 representation
+     */
+    function tickerToBytes(string calldata ticker) external pure returns (bytes32);
+
+    /**
+     * @notice Fee amount that is always burned (set once in constructor, never changed)
+     */
+    function burnedFee() external view returns (uint256);
+
+    /**
+     * @notice Address of the mod market contract
+     */
+    function marketContract() external view returns (address);
+
+    /**
+     * @notice Minimum base fee for totem creation (set once in constructor, never changed)
+     */
+    function minBaseFee() external view returns (uint256);
+
+    /**
+     * @notice Address of the proxy mod for license delegation
+     */
+    function proxyMod() external view returns (address);
+
+    /**
+     * @notice Array of all totem ticker bytes for enumeration
+     */
+    function totemList(uint256) external view returns (bytes32);
+
+    // ==================== EVENTS ====================
+
+    event RelayAuthorized(string ticker, address indexed relay);
+    event RelayRevoked(string ticker, address indexed relay);
+    event TotemBurned(string ticker, address indexed owner, uint256 amount);
+    event TotemCreated(string ticker, address indexed creator);
+    event TotemMinted(string ticker, address indexed minter, address mod, uint256 minted, uint256 payment);
+    event TotemOwnershipTransferred(string ticker, address indexed previousOwner, address indexed newOwner);
+    event TotemTransferred(string ticker, address indexed from, address indexed to, uint256 amount);
+
+    // ==================== ERRORS ====================
+
+    error CannotTransferToUnlimitedMinter();
+    error CantSetLicense();
+    error DescriptionTooLong(uint256 length);
+    error EmptyImage();
+    error InsufficientBalance(uint256 required, uint256 available);
+    error InsufficientFee(uint256 required, uint256 provided);
+    error InvalidAllocation(string message);
+    error InvalidCursor();
+    error InvalidSeed();
+    error InvalidTickerChar(uint8 char);
+    error InvalidTickerLength(uint256 length);
+    error ModDoesntSupportHook(address mod, ITotemTypes.Hook hook);
+    error ModMustSupportUnlimitedMinting(address mod);
+    error ModNotMinter(address mod);
+    error NameTooLong(uint256 length);
+    error NameTooShort(uint256 length);
+    error ReferrerFeeTooLow(uint256 minFee);
+    error TooManyAllocations();
+    error TooManyMods();
+    error TotemAlreadyExists(string ticker);
+    error TotemNotActive();
+    error TotemNotFound(string ticker);
+    error TransferFailed();
+    error Unauthorized();
+    error ZeroSupply();
+}

package/mods/TotemMod.sol

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "../library/ITotemTypes.sol";
+import {TotemsLibrary} from "../library/TotemsLibrary.sol";
+
+interface ITotemsProxyModGetter {
+    function getProxyMod() external view returns (address);
+}
+
+interface IMod {
+    function getSeller() external view returns (address payable);
+}
+
+interface IModTransfer {
+    function onTransfer(
+        string calldata ticker,
+        address from,
+        address to,
+        uint256 amount,
+        string calldata memo
+    ) external;
+}
+
+interface IModMint {
+    function onMint(
+        string calldata ticker,
+        address minter,
+        uint256 amount,
+        uint256 payment,
+        string calldata memo
+    ) external;
+}
+
+interface IModMinter {
+    function mint(
+        string calldata ticker,
+        address minter,
+        uint256 amount,
+        string calldata memo
+    ) external payable;
+}
+
+interface IModBurn {
+    function onBurn(
+        string calldata ticker,
+        address owner,
+        uint256 amount,
+        string calldata memo
+    ) external;
+}
+
+interface IModCreated {
+    function onCreated(
+        string calldata ticker,
+        address creator
+    ) external;
+}
+
+interface IModTransferOwnership {
+    function onTransferOwnership(
+        string calldata ticker,
+        address previousOwner,
+        address newOwner
+    ) external;
+}
+
+/**
+ * @title TotemMod
+ * @notice Base contract for building mods
+ */
+abstract contract TotemMod {
+
+    address payable private seller;
+    function getSeller() external view returns (address payable) {
+        return seller != address(0) ? payable(address(seller)) : payable(address(this));
+    }
+
+    function isSetupFor(string calldata ticker) virtual external view returns (bool);
+
+    error InvalidModEventOrigin();
+    error NotLicensed();
+
+
+
+    /// @notice Address of the Totems contract
+    address public immutable totemsContract;
+
+    /**
+     * @notice Constructor
+     * @param _totemsContract Totems contract address
+     * @param _seller The seller that will publish this mod (gets paid)
+     */
+    constructor(address _totemsContract, address payable _seller) {
+        totemsContract = _totemsContract;
+        seller = _seller;
+    }
+
+    /**
+     * @notice Ensure caller is the Totems contract
+     */
+    modifier onlyTotems() {
+        // sender must be either the totems contract or the proxy mod
+        if(msg.sender != totemsContract){
+            if(msg.sender != ITotemsProxyModGetter(totemsContract).getProxyMod()){
+                revert InvalidModEventOrigin();
+            }
+        }
+        _;
+    }
+
+    /**
+     * @notice Ensure the mod is licensed for the given ticker
+     */
+    modifier onlyLicensed(string calldata ticker) {
+        if (!TotemsLibrary.hasLicense(totemsContract, ticker, address(this))) {
+            revert NotLicensed();
+        }
+        _;
+    }
+
+    modifier onlyCreator(string calldata ticker) {
+        address creator = TotemsLibrary.getCreator(totemsContract, ticker);
+        if (msg.sender != creator) {
+            revert("Only totem creator can call this");
+        }
+        _;
+    }
+
+    modifier onlySetup(string calldata ticker) {
+        if (!this.isSetupFor(ticker)) {
+            revert("Mod is not setup for this totem");
+        }
+        _;
+    }
+}