# TIP20 ## Abstract TIP20 is a suite of precompiles that provide a built-in optimized token implementation in the core protocol. It extends the ERC-20 token standard with built-in functionality like memo fields and reward distribution. ## Motivation All major stablecoins today use the ERC-20 token standard. While ERC-20 provides a solid foundation for fungible tokens, it lacks features critical for stablecoin issuers today such as memos, transfer policies, and rewards distribution. Additionally, since each ERC-20 token has its own implementation, integrators can't depend on consistent behavior across tokens. TIP-20 extends ERC-20, building these features into precompiled contracts that anyone can permissionlessly deploy on Tempo. This makes token operations much more efficient, allows issuers to quickly set up on Tempo, and simplifies integrations since it ensures standardized behavior across tokens. It also enables deeper integration with token-specific Tempo features like paying gas in stablecoins and payment lanes. ## Specification TIP-20 tokens support standard fungible token operations such as transfers, mints, and burns. They also support transfers, mints, and burns with an attached 32-byte memo; a role-based access control system for token administrative operations; and a system for opt-in [reward distribution](/protocol/tip20-rewards/spec). ## TIP20 The core TIP-20 contract exposes standard ERC-20 functions for balances, allowances, transfers, and delegated transfers, and also adds: * 32-byte memo support on transfers, mints, and burns. * A `TIP20Roles` module for permissioned actions like issuing, pausing, unpausing, and burning blocked balances. * Configuration options for currencies, quote tokens, and transfer policies. The complete TIP20 interface is defined below: ```solidity interface ITIP20 { // ========================================================================= // ERC-20 standard functions // ========================================================================= /// @notice Returns the name of the token /// @return The token name function name() external view returns (string memory); /// @notice Returns the symbol of the token /// @return The token symbol function symbol() external view returns (string memory); /// @notice Returns the number of decimals for the token /// @return Always returns 6 for TIP-20 tokens function decimals() external pure returns (uint8); /// @notice Returns the total amount of tokens in circulation /// @return The total supply of tokens function totalSupply() external view returns (uint256); /// @notice Returns the token balance of an account /// @param account The address to check the balance for /// @return The token balance of the account function balanceOf(address account) external view returns (uint256); /// @notice Transfers tokens from caller to recipient /// @param to The recipient address /// @param amount The amount of tokens to transfer /// @return True if successful function transfer(address to, uint256 amount) external returns (bool); /// @notice Returns the remaining allowance for a spender /// @param owner The token owner address /// @param spender The spender address /// @return The remaining allowance amount function allowance(address owner, address spender) external view returns (uint256); /// @notice Approves a spender to spend tokens on behalf of caller /// @param spender The address to approve /// @param amount The amount to approve /// @return True if successful function approve(address spender, uint256 amount) external returns (bool); /// @notice Transfers tokens from one address to another using allowance /// @param from The sender address /// @param to The recipient address /// @param amount The amount to transfer /// @return True if successful function transferFrom(address from, address to, uint256 amount) external returns (bool); /// @notice Mints new tokens to an address (requires ISSUER_ROLE) /// @param to The recipient address /// @param amount The amount of tokens to mint function mint(address to, uint256 amount) external; /// @notice Burns tokens from caller's balance (requires ISSUER_ROLE) /// @param amount The amount of tokens to burn function burn(uint256 amount) external; // ========================================================================= // TIP-20 extended functions // ========================================================================= /// @notice Transfers tokens from caller to recipient with a memo /// @param to The recipient address /// @param amount The amount of tokens to transfer /// @param memo A 32-byte memo attached to the transfer function transferWithMemo(address to, uint256 amount, bytes32 memo) external; /// @notice Transfers tokens from one address to another with a memo using allowance /// @param from The sender address /// @param to The recipient address /// @param amount The amount to transfer /// @param memo A 32-byte memo attached to the transfer /// @return True if successful function transferFromWithMemo(address from, address to, uint256 amount, bytes32 memo) external returns (bool); /// @notice Mints new tokens to an address with a memo (requires ISSUER_ROLE) /// @param to The recipient address /// @param amount The amount of tokens to mint /// @param memo A 32-byte memo attached to the mint function mintWithMemo(address to, uint256 amount, bytes32 memo) external; /// @notice Burns tokens from caller's balance with a memo (requires ISSUER_ROLE) /// @param amount The amount of tokens to burn /// @param memo A 32-byte memo attached to the burn function burnWithMemo(uint256 amount, bytes32 memo) external; /// @notice Burns tokens from a blocked address (requires BURN_BLOCKED_ROLE) /// @param from The address to burn tokens from (must be unauthorized by transfer policy) /// @param amount The amount of tokens to burn function burnBlocked(address from, uint256 amount) external; /// @notice Returns the quote token used for DEX pairing /// @return The quote token address function quoteToken() external view returns (ITIP20); /// @notice Returns the next quote token staged for update /// @return The next quote token address (zero if none staged) function nextQuoteToken() external view returns (ITIP20); /// @notice Returns the currency identifier for this token /// @return The currency string function currency() external view returns (string memory); /// @notice Returns whether the token is currently paused /// @return True if paused, false otherwise function paused() external view returns (bool); /// @notice Returns the maximum supply cap for the token /// @return The supply cap (checked on mint operations) function supplyCap() external view returns (uint256); /// @notice Returns the current transfer policy ID from TIP-403 registry /// @return The transfer policy ID function transferPolicyId() external view returns (uint64); // ========================================================================= // Admin Functions // ========================================================================= /// @notice Pauses the contract, blocking transfers (requires PAUSE_ROLE) function pause() external; /// @notice Unpauses the contract, allowing transfers (requires UNPAUSE_ROLE) function unpause() external; /// @notice Changes the transfer policy ID (requires DEFAULT_ADMIN_ROLE) /// @param newPolicyId The new policy ID from TIP-403 registry /// @dev Validates that the policy exists using TIP403Registry.policyExists(). /// Built-in policies (ID 0 = always-reject, ID 1 = always-allow) are always valid. /// For custom policies (ID >= 2), the policy must exist in the TIP-403 registry. /// Reverts with InvalidTransferPolicyId if the policy does not exist. function changeTransferPolicyId(uint64 newPolicyId) external; /// @notice Stages a new quote token for update (requires DEFAULT_ADMIN_ROLE) /// @param newQuoteToken The new quote token address function setNextQuoteToken(ITIP20 newQuoteToken) external; /// @notice Completes the quote token update process (requires DEFAULT_ADMIN_ROLE) function completeQuoteTokenUpdate() external; /// @notice Sets the maximum supply cap (requires DEFAULT_ADMIN_ROLE) /// @param newSupplyCap The new supply cap (cannot be less than current supply) function setSupplyCap(uint256 newSupplyCap) external; // ========================================================================= // Role Management // ========================================================================= /// @notice Returns the BURN_BLOCKED_ROLE constant /// @return keccak256("BURN_BLOCKED_ROLE") function BURN_BLOCKED_ROLE() external view returns (bytes32); /// @notice Returns the ISSUER_ROLE constant /// @return keccak256("ISSUER_ROLE") function ISSUER_ROLE() external view returns (bytes32); /// @notice Returns the PAUSE_ROLE constant /// @return keccak256("PAUSE_ROLE") function PAUSE_ROLE() external view returns (bytes32); /// @notice Returns the UNPAUSE_ROLE constant /// @return keccak256("UNPAUSE_ROLE") function UNPAUSE_ROLE() external view returns (bytes32); /// @notice Grants a role to an account (requires role admin) /// @param role The role to grant (keccak256 hash) /// @param account The account to grant the role to function grantRole(bytes32 role, address account) external; /// @notice Revokes a role from an account (requires role admin) /// @param role The role to revoke (keccak256 hash) /// @param account The account to revoke the role from function revokeRole(bytes32 role, address account) external; /// @notice Allows an account to remove a role from itself /// @param role The role to renounce (keccak256 hash) function renounceRole(bytes32 role) external; /// @notice Changes the admin role for a specific role (requires current role admin) /// @param role The role whose admin is being changed /// @param adminRole The new admin role function setRoleAdmin(bytes32 role, bytes32 adminRole) external; // ========================================================================= // EIP-2612 Permit (TIP-1004) // ========================================================================= /// @notice Approves a spender via an off-chain signature (EIP-2612) /// @param owner The token owner who signed the permit /// @param spender The address being approved /// @param value The allowance amount /// @param deadline The timestamp after which the signature expires /// @param v ECDSA recovery byte (must be 27 or 28; 0/1 is not normalized) /// @param r ECDSA signature component /// @param s ECDSA signature component function permit( address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s ) external; /// @notice Returns the current nonce for an owner (incremented on each permit) /// @param owner The address to query /// @return The current nonce function nonces(address owner) external view returns (uint256); /// @notice Returns the EIP-712 domain separator for this token /// @return The domain separator hash (computed dynamically using block.chainid) function DOMAIN_SEPARATOR() external view returns (bytes32); // ========================================================================= // System Functions // ========================================================================= /// @notice System-level transfer function (restricted to precompiles) /// @param from The sender address /// @param to The recipient address /// @param amount The amount to transfer /// @return True if successful function systemTransferFrom(address from, address to, uint256 amount) external returns (bool); /// @notice Pre-transaction fee transfer (restricted to precompiles) /// @param from The account to charge fees from /// @param amount The fee amount function transferFeePreTx(address from, uint256 amount) external; /// @notice Post-transaction fee handling (restricted to precompiles) /// @param to The account to refund /// @param refund The refund amount /// @param actualUsed The actual fee used function transferFeePostTx(address to, uint256 refund, uint256 actualUsed) external; // ========================================================================= // Events // ========================================================================= /// @notice Emitted when a new allowance is set by `owner` for `spender` /// @param owner The account granting the allowance /// @param spender The account being approved to spend tokens /// @param amount The new allowance amount event Approval(address indexed owner, address indexed spender, uint256 amount); /// @notice Emitted when tokens are burned from an address /// @param from The address whose tokens were burned /// @param amount The amount of tokens that were burned event Burn(address indexed from, uint256 amount); /// @notice Emitted when tokens are burned from a blocked address /// @param from The blocked address whose tokens were burned /// @param amount The amount of tokens that were burned event BurnBlocked(address indexed from, uint256 amount); /// @notice Emitted when new tokens are minted to an address /// @param to The address receiving the minted tokens /// @param amount The amount of tokens that were minted event Mint(address indexed to, uint256 amount); /// @notice Emitted when a new quote token is staged for this token /// @param updater The account that staged the new quote token /// @param nextQuoteToken The quote token that has been staged event NextQuoteTokenSet(address indexed updater, ITIP20 indexed nextQuoteToken); /// @notice Emitted when the pause state of the token changes /// @param updater The account that changed the pause state /// @param isPaused The new pause state; true if paused, false if unpaused event PauseStateUpdate(address indexed updater, bool isPaused); /// @notice Emitted when the quote token update process is completed /// @param updater The account that completed the quote token update /// @param newQuoteToken The new quote token that has been set event QuoteTokenUpdate(address indexed updater, ITIP20 indexed newQuoteToken); /// @notice Emitted when a holder sets or updates their reward recipient address /// @param holder The token holder configuring the recipient /// @param recipient The address that will receive claimed rewards event RewardRecipientSet(address indexed holder, address indexed recipient); /// @notice Emitted when a reward distribution is scheduled /// @param funder The account funding the reward distribution /// @param amount The total amount of tokens allocated to the reward event RewardDistributed( address indexed funder, uint256 amount, ); /// @notice Emitted when the token's supply cap is updated /// @param updater The account that updated the supply cap /// @param newSupplyCap The new maximum total supply event SupplyCapUpdate(address indexed updater, uint256 indexed newSupplyCap); /// @notice Emitted for all token movements, including mints and burns /// @param from The address sending tokens (address(0) for mints) /// @param to The address receiving tokens (address(0) for burns) /// @param amount The amount of tokens transferred event Transfer(address indexed from, address indexed to, uint256 amount); /// @notice Emitted when the transfer policy ID is updated /// @param updater The account that updated the transfer policy /// @param newPolicyId The new transfer policy ID from the TIP-403 registry event TransferPolicyUpdate(address indexed updater, uint64 indexed newPolicyId); /// @notice Emitted when a transfer, mint, or burn is performed with an attached memo /// @param from The address sending tokens (address(0) for mints) /// @param to The address receiving tokens (address(0) for burns) /// @param amount The amount of tokens transferred /// @param memo The 32-byte memo associated with this movement event TransferWithMemo( address indexed from, address indexed to, uint256 amount, bytes32 indexed memo ); /// @notice Emitted when the membership of a role changes for an account /// @param role The role being granted or revoked /// @param account The account whose membership was changed /// @param sender The account that performed the change /// @param hasRole True if the role was granted, false if it was revoked event RoleMembershipUpdated( bytes32 indexed role, address indexed account, address indexed sender, bool hasRole ); /// @notice Emitted when the admin role for a role is updated /// @param role The role whose admin role was changed /// @param newAdminRole The new admin role for the given role /// @param sender The account that performed the update event RoleAdminUpdated( bytes32 indexed role, bytes32 indexed newAdminRole, address indexed sender ); // ========================================================================= // Errors // ========================================================================= /// @notice The token operation is blocked because the contract is currently paused error ContractPaused(); /// @notice The permit signature has expired (block.timestamp > deadline) error PermitExpired(); /// @notice The recovered signer does not match the permit owner error InvalidSignature(); /// @notice The spender does not have enough allowance for the attempted transfer error InsufficientAllowance(); /// @notice The account does not have the required token balance for the operation /// @param currentBalance The current balance of the account /// @param expectedBalance The required balance for the operation to succeed /// @param token The address of the token contract error InsufficientBalance(uint256 currentBalance, uint256 expectedBalance, address token); /// @notice The provided amount is zero or otherwise invalid for the attempted operation error InvalidAmount(); /// @notice The provided currency identifier is invalid or unsupported error InvalidCurrency(); /// @notice The specified quote token is invalid, incompatible, or would create a circular reference error InvalidQuoteToken(); /// @notice The recipient address is not a valid destination for this operation /// (for example, another TIP-20 token contract) error InvalidRecipient(); /// @notice The specified transfer policy ID does not exist in the TIP-403 registry error InvalidTransferPolicyId(); /// @notice The new supply cap is invalid, for example lower than the current total supply error InvalidSupplyCap(); /// @notice A rewards operation was attempted when no opted-in supply exists error NoOptedInSupply(); /// @notice The configured transfer policy denies authorization for the sender or recipient error PolicyForbids(); /// @notice The attempted operation would cause total supply to exceed the configured supply cap error SupplyCapExceeded(); /// @notice The caller does not have the required role or permission for this operation error Unauthorized(); } ``` :::warning When interacting with precompiles, **always use the provided ABI** rather than reading directly from storage slots. Direct storage access may lead to undefined behavior. ::: ## Memos Memo functions `transferWithMemo`, `transferFromWithMemo`, `mintWithMemo`, and `burnWithMemo` behave like their ERC-20 equivalents but additionally emit memo data in dedicated events. The memo is always a fixed 32-byte field. Callers should pack shorter strings or identifiers directly into this field, and use hashes or external references when the underlying payload exceeds 32 bytes. ## TIP-403 Transfer Policies All operations that move tokens: `transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo`, `mint`, `burn`, `mintWithMemo`, and `burnWithMemo` — enforce the token’s configured TIP-403 transfer policy. Internally, this is implemented via a `transferAuthorized` modifier that: * Calls `TIP403_REGISTRY.isAuthorized(transferPolicyId, from)` for the sender. * Calls `TIP403_REGISTRY.isAuthorized(transferPolicyId, to)` for the recipient. Both checks must return `true`, otherwise the call reverts with `PolicyForbids`. Reward operations (`distributeReward`, `setRewardRecipient`, `claimRewards`) also perform the same TIP-403 authorization checks before moving any funds. ## Invalid Recipient Protection TIP-20 tokens cannot be sent to other TIP-20 token contract addresses. The implementation uses a `validRecipient` guard that rejects recipients whose address is zero, or has the TIP-20 prefix (`0x20c000000000000000000000`). Any attempt to transfer to a TIP-20 token address must revert with `InvalidRecipient`. This prevents accidental token loss by sending funds to token contracts instead of user accounts. ## Currencies and Quote Tokens Each TIP-20 token declares a currency identifier and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. Stablecoin currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter codes representing the underlying fiat currency (e.g., `"USD"`, `"EUR"`, `"GBP"`) — not the token's own symbol. The currency is set at token creation and **cannot be changed afterward**. **Only tokens with `currency == "USD"` are eligible for paying transaction fees.** Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token. 2. `completeQuoteTokenUpdate` finalizes the change. The implementation must validate that the new quote token is a TIP-20 token, matches currency rules, and does not create circular quote-token chains. :::note While quote tokens can be changed, choose carefully as the update process requires careful coordination with the DEX. ::: ## Permit (TIP-1004) TIP-20 tokens support [EIP-2612](https://eips.ethereum.org/EIPS/eip-2612) `permit`, added in the [T2 network upgrade](/protocol/upgrades/t2). A token owner signs an EIP-712 typed message off-chain authorizing a spender, and any third party can submit that signature on-chain — combining approve and action into a single transaction without the owner paying gas. The `DOMAIN_SEPARATOR` is computed dynamically on every call using `block.chainid`, so it remains correct after a chain fork. Each owner has a monotonically increasing `nonce` to prevent replay. Only `v = 27` or `v = 28` is accepted; `v = 0` or `v = 1` is intentionally **not** normalized (see [TIP-1004](/protocol/tips/tip-1004) for rationale). ## Pause Controls Pause controls `pause` and `unpause` govern all transfer operations and reward related flows. When paused, transfers and memo transfers halt, but administrative and configuration functions remain allowed. The `paused()` getter reflects the current state and must be checked by all affected entrypoints. ## TIP-20 Roles TIP-20 uses a role-based authorization system. The main roles are: * `ISSUER_ROLE`: controls minting and burning. * `PAUSE_ROLE` / `UNPAUSE_ROLE`: controls the token’s paused state. * `BURN_BLOCKED_ROLE`: allows burning balances belonging to addresses that fail TIP-403 authorization. Roles are assigned and managed through `grantRole`, `revokeRole`, `renounceRole`, and `setRoleAdmin`, via the contract admin. ## System Functions System level functions `systemTransferFrom`, `transferFeePreTx`, and `transferFeePostTx` are only callable by other Tempo protocol precompiles. These entrypoints power transaction fee collection, refunds, and internal accounting within the Fee AMM and Stablecoin DEX. They must not be callable by general contracts or users. `transferFeePreTx` respects the token's pause state and will revert if the token is paused. However, `transferFeePostTx` is intentionally allowed to execute even when the token is paused. This ensures that a transaction which pauses the token can still complete successfully and receive its fee refund. Apart from this specific refund transfer, no other token transfers can occur after a pause event. ## Token Rewards Distribution See [rewards distribution](/protocol/tip20-rewards/spec) for more information. ## TIP20Factory The `TIP20Factory` contract is the canonical entrypoint for creating new TIP-20 tokens on Tempo. The factory derives deterministic deployment addresses using a caller-provided salt, combined with the caller's address, under a fixed 12-byte TIP-20 prefix. This ensures that every TIP-20 token exists at a predictable, collision-free address. The `TIP20Factory` precompile is deployed at `0x20Fc000000000000000000000000000000000000`. Newly created TIP-20 addresses are deployed to a deterministic address derived from `TIP20_PREFIX || lowerBytes`, where: * `TIP20_PREFIX` is the 12-byte prefix `20C000000000000000000000` * `lowerBytes` is the highest 64 bits of `keccak256(msg.sender, salt)` The first 1000 addresses (where `lowerBytes < 1000`) are reserved for protocol use and cannot be deployed to via the factory. When creating a token, the factory performs several checks to guarantee consistency across the TIP-20 ecosystem: * The specified Quote token must be a currently deployed TIP20. * Tokens that specify their currency as USD must also specify a quote token that is denoted in USD. * At deployment, the factory initializes defaults on the TIP-20:\ `transferPolicyId = 1`, `supplyCap = type(uint128).max`, `paused = false`, and `totalSupply = 0`. * The provided `admin` address receives `DEFAULT_ADMIN_ROLE`, enabling it to manage roles and token configurations. The complete `TIP20Factory` interface is defined below: ```solidity /// @title TIP-20 Factory Interface /// @notice Deploys and initializes new TIP-20 tokens at deterministic addresses interface ITIP20Factory { /// @notice Creates and deploys a new TIP-20 token /// @param name The token's ERC-20 name /// @param symbol The token's ERC-20 symbol /// @param currency The token's ISO 4217 currency code (e.g. "USD", "EUR"). Immutable after creation. /// @param quoteToken The TIP-20 quote token used for exchange pricing /// @param admin The address to receive DEFAULT_ADMIN_ROLE on the new token /// @param salt A unique salt for deterministic address derivation /// /// @return token The deployed TIP-20 token address /// @dev /// - Computes the TIP-20 deployment address as TIP20_PREFIX || lowerBytes, /// where lowerBytes is the highest 64 bits of keccak256(msg.sender, salt) /// - Reverts with AddressReserved if lowerBytes < 1000 /// - Ensures the provided quote token is itself a valid TIP-20 /// - Enforces USD-denomination rules (USD tokens must use USD quote tokens) /// - Initializes the token with default settings: /// transferPolicyId = 1 (always-allow) /// supplyCap = type(uint128).max /// paused = false /// totalSupply = 0 /// - Grants DEFAULT_ADMIN_ROLE on the new token to `admin` /// - Emits a {TokenCreated} event function createToken( string memory name, string memory symbol, string memory currency, ITIP20 quoteToken, address admin, bytes32 salt ) external returns (address token); // ========================================================================= // Helpers // ========================================================================= /// @notice Returns true if `token` is a valid TIP-20 address /// @param token The address to check /// @return True if the address is a well-formed TIP-20 /// @dev Checks the TIP-20 prefix and verifies the token has code deployed function isTIP20(address token) external view returns (bool); /// @notice Computes the deterministic TIP-20 address for a given sender and salt /// @param sender The address that will call {createToken} /// @param salt The salt that will be passed to {createToken} /// @return token The TIP-20 address that would be deployed /// @dev Computes the address as TIP20_PREFIX || lowerBytes, where lowerBytes is /// the highest 64 bits of keccak256(sender, salt), matching the factory deployment scheme. function getTokenAddress(address sender, bytes32 salt) external pure returns (address token); // ========================================================================= // Events // ========================================================================= /// @notice Emitted when a new TIP-20 token is created /// @param token The newly deployed TIP-20 address /// @param name The token name /// @param symbol The token symbol /// @param currency The token currency /// @param quoteToken The token's assigned quote token /// @param admin The address receiving DEFAULT_ADMIN_ROLE /// @param salt The salt used for deterministic address derivation event TokenCreated( address indexed token, string name, string symbol, string currency, ITIP20 quoteToken, address admin, bytes32 salt ); // ========================================================================= // Errors // ========================================================================= /// @notice The computed address falls within the reserved range (lowerBytes < 1000) error AddressReserved(); /// @notice The provided quote token address is invalid or not a TIP-20 error InvalidQuoteToken(); } ``` ## Invariants * `totalSupply()` must always equal to the sum of all `balanceOf(account)` over all accounts. * `totalSupply()` must always be `<= supplyCap` * When `paused` is `true`, no functions that move tokens (`transfer`, `transferFrom`, memo variants, `systemTransferFrom`, `transferFeePreTx`, `distributeReward`, `setRewardRecipient`, `claimRewards`) can succeed. * TIP20 tokens cannot be transferred to another TIP20 token contract address. * `systemTransferFrom`, `transferFeePreTx`, and `transferFeePostTx` never change `totalSupply()`.