> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`.
# TIP-20 Tokens Specification

## Abstract

TIP-20 tokens are a suite of precompiles that provide a built-in optimized token implementation in the core protocol. They extend 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](/docs/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);
    
    /// @notice Returns the on-chain logo URI for this token (empty if unset)
    function logoURI() external view returns (string memory);
    
    // =========================================================================
    //                            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;
    
    /// @notice Updates the logo URI (requires DEFAULT_ADMIN_ROLE)
    /// @param newLogoURI The new logo URI (max 256 bytes; empty string clears the field)
    /// @dev If non-empty, MUST be a syntactically valid URI with a scheme in the
    ///      allowlist {https, http, ipfs, data} (case-insensitive).
    ///      Reverts LogoURITooLong if length > 256 bytes.
    ///      Reverts InvalidLogoURI if the scheme is not in the allowlist or the URI is malformed.
    function setLogoURI(string calldata newLogoURI) 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
    );

    /// @notice Emitted when the logo URI changes
    /// @param updater The address that updated the logo URI (msg.sender)
    /// @param newLogoURI The new logo URI value
    event LogoURIUpdated(address indexed updater, string newLogoURI);

    // =========================================================================
    //                                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();

    /// @notice The provided logoURI exceeds the 256-byte cap
    error LogoURITooLong();

    /// @notice The provided logoURI is malformed or uses a scheme outside the allowlist
    error InvalidLogoURI();

}
```

:::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.

## Virtual Address Recipients

Recipient-bearing TIP-20 paths — `transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo`, `mint`, and `mintWithMemo` — resolve [TIP-1022](https://github.com/tempoxyz/tempo/blob/main/tips/tip-1022.md) virtual addresses before running recipient authorization and mint-recipient checks. When a recipient `to` is a registered virtual address, the effective recipient becomes the registered master wallet, and authorization, balance updates, and event emission target that master wallet.

Virtual addresses are valid TIP-20 recipients on those paths but remain forwarding aliases rather than canonical TIP-20 holders. Non-TIP-20 tokens sent to a virtual address do not forward. Forwarded deposits appear as two-hop standard `Transfer` events in the same transaction; indexers and explorers should collapse that pair into one logical deposit to the resolved master wallet.

## Currencies and Quote Tokens

Each TIP-20 token declares a [currency identifier](/docs/protocol/tip20/overview#currency-declaration) and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. 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](/docs/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](https://github.com/tempoxyz/tempo/blob/main/tips/tip-1004.md) for rationale).

## Logo URI (TIP-1026)

Every TIP-20 exposes an optional on-chain `logoURI`, added in the [T5 network upgrade](/docs/protocol/upgrades/t5) ([TIP-1026](https://tips.sh/1026)). Wallets and explorers read the icon directly from the token contract via `logoURI()`, without an off-chain registry round-trip. Tokens without a `logoURI` continue to work; the field is empty by default.

The admin (`DEFAULT_ADMIN_ROLE`) sets or clears it via `setLogoURI(string newLogoURI)`, which emits `LogoURIUpdated(msg.sender, newLogoURI)`. An empty string is valid and clears the field. A non-empty value must be at most 256 bytes (`LogoURITooLong` otherwise) and a syntactically valid URI whose scheme is in the allowlist `{https, http, ipfs, data}`, matched case-insensitively (`InvalidLogoURI` otherwise).

Per [TIP-1026's recommended formats](https://tips.sh/1026#recommended-formats), use a square, single-frame rasterized image (PNG or WebP). SVG is allowed by the scheme allowlist but not recommended — integrators that accept SVG must follow TIP-1026's SVG-handling guidance.

## 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.

### Implicit approvals for listed precompiles (TIP-1035)

An Implicit Approval List names the precompiles that may pull TIP-20 tokens without a prior `approve`. Listed precompiles call the internal `system_transfer_from(from, to, amount)` entrypoint, which:

* Is **not** part of the public TIP-20 ABI and is **not** callable by external contracts or EOAs.
* Skips allowance checks and the allowance storage write.
* Still enforces balance checks, TIP-403 transfer policies, and AccountKeychain spending limits.
* Emits the standard TIP-20 `Transfer` event.

This generalizes the system-only path described above (`systemTransferFrom`, `transferFeePreTx`, `transferFeePostTx`) to an allow-list of precompiles — the StablecoinDEX, FeeAMM, and the `TIP20ChannelReserve` precompile. Normal `approve`, `permit`, `allowance`, and `transferFrom` behavior is unchanged.

### Payment-channel reserve (TIP-1034)

The enshrined `TIP20ChannelReserve` precompile at [`0x4D50500000000000000000000000000000000000`](https://explore.tempo.xyz/address/0x4D50500000000000000000000000000000000000) (ASCII `MPP`) is a TIP-20 consumer rather than a change to the TIP-20 contract itself — it pulls funds via the implicit-approval path above and emits standard `Transfer` events from the host TIP-20. See the [enshrined TIP-20 reserve channel section of the T5 page](/docs/protocol/upgrades/t5#enshrined-tip-20-reserve-channel) for the channel lifecycle, channel ID derivation, and event surface.

## Token Rewards Distribution

See [rewards distribution](/docs/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 factory provides two `createToken` overloads: the original 6-argument form, and a 7-argument form that additionally sets an initial [`logoURI`](#logo-uri-tip-1026) at creation (validated with the same rules as `setLogoURI`). The 6-argument overload is unchanged.

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 currency identifier (ISO 4217 code, when available). Immutable after creation. See Currency Declaration (https://docs.tempo.xyz/docs/protocol/tip20/overview#currency-declaration).
    /// @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);

    /// @notice Creates and deploys a new TIP-20 token with an initial logoURI
    /// @dev Identical to the 6-arg overload, but additionally sets logoURI at creation.
    ///      Validation rules for logoURI are the same as setLogoURI (256-byte cap,
    ///      allowlisted schemes, syntactically valid URI). Empty string is valid and
    ///      leaves logoURI unset (no LogoURIUpdated event emitted). When non-empty, the
    ///      new token emits LogoURIUpdated(msg.sender, logoURI) from its own address.
    function createToken(
        string memory name,
        string memory symbol,
        string memory currency,
        ITIP20 quoteToken,
        address admin,
        bytes32 salt,
        string memory logoURI
    ) 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()`.
* `bytes(logoURI()).length` must always be `<= 256`.

## T5 → T6 migration

:::info\[Migration appendix]
This section captures TIP-20 changes introduced by the [T6 network upgrade](/docs/protocol/upgrades/t6). These changes are active on both testnet and mainnet.
:::

T6 introduces one change that affects the TIP-20 transfer and mint surface:

### TIP-1028: account-level receive policies

The TIP-20 `transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo`, `systemTransferFrom`, `mint`, and `mintWithMemo` flows gain a receive-policy check after the existing TIP-403 transfer-policy check. The receive policy is owned by the receiver and configured on the TIP-403 precompile via a new `setReceivePolicy(...)` function; it is enforced via `validateReceivePolicy(token, sender, receiver)`. For `transfer`/`transferFrom`/memo variants/`systemTransferFrom`, the sender for policy purposes is the `from` argument; for `mint`/`mintWithMemo` it is `msg.sender`.

If the receive policy blocks the operation, **the call still succeeds**. Delivery is redirected to a new `ReceivePolicyGuard` precompile at `0xB10C000000000000000000000000000000000000`, which records a receipt for the transfer or mint. The originator or a recovery address designated by the receiver can later claim the recorded amount from the guard.

* The token's existing TIP-403 policy is checked first and continues to revert on failure. Only receive-policy failures redirect.
* The host TIP-20 emits its standard `Transfer` event to `0xB10C000000000000000000000000000000000000` on a redirected transfer; the guard separately emits a `TransferBlocked` event with the information needed to claim the receipt. Blocked receipts are not enumerable on chain — indexers must subscribe to `TransferBlocked` to surface claimable funds.
* TIP-1022 virtual addresses are resolved to the master address before any receive-policy check. Receipts are recorded against the master while preserving the original `to` for attribution.
* `approve`, `permit`, and `burn` are not affected. Fee deposits and refunds via `transfer_fee_pre_tx` and `transfer_fee_post_tx` are not affected. TIP-20 internal balances and reward flows are not affected.

See [TIP-1028](https://tips.sh/1028) for the full specification, including the `ReceivePolicyGuard` claim interface and recovery-authority rules.