Struct TIP20Token 

pub struct TIP20Token {

    pub roles: <Mapping<Address, Mapping<B256, bool>> as StorableType>::Handler,
    pub role_admins: <Mapping<B256, B256> as StorableType>::Handler,
    pub name: <String as StorableType>::Handler,
    pub symbol: <String as StorableType>::Handler,
    pub currency: <String as StorableType>::Handler,
    pub _domain_separator: <B256 as StorableType>::Handler,
    pub quote_token: <Address as StorableType>::Handler,
    pub next_quote_token: <Address as StorableType>::Handler,
    pub transfer_policy_id: <u64 as StorableType>::Handler,
    pub total_supply: <U256 as StorableType>::Handler,
    pub balances: <Mapping<Address, U256> as StorableType>::Handler,
    pub allowances: <Mapping<Address, Mapping<Address, U256>> as StorableType>::Handler,
    pub permit_nonces: <Mapping<Address, U256> as StorableType>::Handler,
    pub paused: <bool as StorableType>::Handler,
    pub supply_cap: <U256 as StorableType>::Handler,
    pub _salts: <Mapping<B256, bool> as StorableType>::Handler,
    pub global_reward_per_token: <U256 as StorableType>::Handler,
    pub opted_in_supply: <u128 as StorableType>::Handler,
    pub user_reward_info: <Mapping<Address, UserRewardInfo> as StorableType>::Handler,
    address: Address,
    storage: StorageCtx,
}

Fields

roles: <Mapping<Address, Mapping<B256, bool>> as StorableType>::Handler

role_admins: <Mapping<B256, B256> as StorableType>::Handler

name: <String as StorableType>::Handler

symbol: <String as StorableType>::Handler

currency: <String as StorableType>::Handler

_domain_separator: <B256 as StorableType>::Handler

quote_token: <Address as StorableType>::Handler

next_quote_token: <Address as StorableType>::Handler

transfer_policy_id: <u64 as StorableType>::Handler

total_supply: <U256 as StorableType>::Handler

balances: <Mapping<Address, U256> as StorableType>::Handler

allowances: <Mapping<Address, Mapping<Address, U256>> as StorableType>::Handler

permit_nonces: <Mapping<Address, U256> as StorableType>::Handler

paused: <bool as StorableType>::Handler

supply_cap: <U256 as StorableType>::Handler

_salts: <Mapping<B256, bool> as StorableType>::Handler

global_reward_per_token: <U256 as StorableType>::Handler

opted_in_supply: <u128 as StorableType>::Handler

user_reward_info: <Mapping<Address, UserRewardInfo> as StorableType>::Handler

address: Address

storage: StorageCtx

Implementations

impl TIP20Token

pub fn distribute_reward( &mut self, msg_sender: Address, call: distributeRewardCall, ) -> Result<()>

Distributes amount of reward tokens from the caller into the opted-in reward pool. Transfers tokens to the contract and increases the global reward-per-token accumulator proportionally to the opted-in supply.

Errors

• Paused — token transfers are currently paused
• InvalidAmount — amount is zero
• PolicyForbids — TIP-403 policy rejects the transfer
• SpendingLimitExceeded — access key spending limit exceeded
• InsufficientBalance — caller balance lower than amount
• NoOptedInSupply — no tokens are currently opted into rewards

pub fn update_rewards(&mut self, holder: Address) -> Result<Address>

Updates and accumulates accrued rewards for a specific token holder.

This function calculates the rewards earned by a holder based on their balance and the reward per token difference since their last update. Rewards are accumulated in the delegated recipient’s rewardBalance. Returns the holder’s delegated recipient address.

pub fn set_reward_recipient( &mut self, msg_sender: Address, call: setRewardRecipientCall, ) -> Result<()>

Sets or changes the reward recipient for a token holder.

This function allows a token holder to designate who should receive their share of rewards. Setting to zero address opts out of rewards.

Errors

• Paused — token transfers are currently paused
• PolicyForbids — TIP-403 policy rejects the sender→recipient transfer authorization

pub fn claim_rewards(&mut self, msg_sender: Address) -> Result<U256>

Claims accumulated rewards for a recipient.

This function allows a reward recipient to claim their accumulated rewards and receive them as token transfers to their own balance.

Errors

• Paused — token transfers are currently paused
• PolicyForbids — TIP-403 policy rejects the contract→caller transfer authorization

pub fn get_global_reward_per_token(&self) -> Result<U256>

Gets the accumulated global reward per token.

fn set_global_reward_per_token(&mut self, value: U256) -> Result<()>

Sets the accumulated global reward per token in storage.

pub fn get_opted_in_supply(&self) -> Result<u128>

Gets the total supply of tokens opted into rewards from storage.

pub fn set_opted_in_supply(&mut self, value: u128) -> Result<()>

Sets the total supply of tokens opted into rewards.

pub fn handle_rewards_on_transfer( &mut self, from: Address, to: Address, amount: U256, ) -> Result<()>

Handles reward accounting for both sender and receiver during token transfers.

pub fn handle_rewards_on_mint( &mut self, to: Address, amount: U256, ) -> Result<()>

Handles reward accounting when tokens are minted to an address.

pub fn get_user_reward_info(&self, account: Address) -> Result<UserRewardInfo>

Retrieves user reward information for a given account.

pub fn get_pending_rewards(&self, account: Address) -> Result<u128>

Calculates the pending claimable rewards for an account without modifying state.

This function returns the total pending claimable reward amount, which includes:

1. The stored reward balance from previous updates
2. Newly accrued rewards based on the current global reward per token

For accounts that have delegated their rewards to another recipient, this returns 0 since their rewards accrue to their delegate instead.

impl TIP20Token

pub fn initialize_roles(&mut self) -> Result<()>

Initializes the roles precompile by setting UNGRANTABLE_ROLE to be self-administered.

pub fn grant_default_admin( &mut self, msg_sender: Address, admin: Address, ) -> Result<()>

Grants DEFAULT_ADMIN_ROLE to admin. Used during token initialization.

pub fn has_role(&self, call: hasRoleCall) -> Result<bool>

Returns whether account holds the given role.

pub fn get_role_admin(&self, call: getRoleAdminCall) -> Result<B256>

Returns the admin role that governs role.

pub fn grant_role( &mut self, msg_sender: Address, call: grantRoleCall, ) -> Result<()>

Grants role to account.

Errors

• Unauthorized — caller does not hold the admin role for role

pub fn revoke_role( &mut self, msg_sender: Address, call: revokeRoleCall, ) -> Result<()>

Revokes role from account.

Errors

• Unauthorized — caller does not hold the admin role for role

pub fn renounce_role( &mut self, msg_sender: Address, call: renounceRoleCall, ) -> Result<()>

Allows the caller to voluntarily give up their own role.

Errors

• Unauthorized — caller does not hold role

pub fn set_role_admin( &mut self, msg_sender: Address, call: setRoleAdminCall, ) -> Result<()>

Changes the admin role that governs role.

Errors

• Unauthorized — caller does not hold the current admin role for role

pub fn check_role(&self, account: Address, role: B256) -> Result<()>

Reverts if account does not hold role.

Errors

• Unauthorized — account does not hold role

pub fn has_role_internal(&self, account: Address, role: B256) -> Result<bool>

Low-level role check without calldata decoding.

pub fn grant_role_internal( &mut self, account: Address, role: B256, ) -> Result<()>

Low-level role grant without authorization checks or events.

fn revoke_role_internal(&mut self, account: Address, role: B256) -> Result<()>

fn get_role_admin_internal(&self, role: B256) -> Result<B256>

If sloads 0, will be equal to DEFAULT_ADMIN_ROLE

fn set_role_admin_internal( &mut self, role: B256, admin_role: B256, ) -> Result<()>

fn check_role_internal(&self, account: Address, role: B256) -> Result<()>

impl TIP20Token

fn __new(address: Address) -> Self

fn __initialize(&mut self) -> Result<()>

fn emit_event(&mut self, event: impl IntoLogData) -> Result<()>

pub fn emitted_events(&self) -> &Vec<LogData>

Available on crate features test-utils only.

pub fn clear_emitted_events(&mut self)

Available on crate features test-utils only.

pub fn assert_emitted_events(&self, expected: Vec<impl IntoLogData>)

Available on crate features test-utils only.

impl TIP20Token

pub fn name(&self) -> Result<String>

Returns the token name.

pub fn symbol(&self) -> Result<String>

Returns the token symbol.

pub fn decimals(&self) -> Result<u8>

Returns the token decimals (always 6 for TIP-20).

pub fn currency(&self) -> Result<String>

Returns the token’s currency denomination (e.g. "USD").

pub fn total_supply(&self) -> Result<U256>

Returns the current total supply.

pub fn quote_token(&self) -> Result<Address>

Returns the active quote token address used for pricing.

pub fn next_quote_token(&self) -> Result<Address>

Returns the pending next quote token address (set but not yet finalized).

pub fn supply_cap(&self) -> Result<U256>

Returns the maximum mintable supply.

pub fn paused(&self) -> Result<bool>

Returns whether the token is currently paused.

pub fn transfer_policy_id(&self) -> Result<u64>

Returns the TIP-403 transfer policy ID governing this token’s transfers.

pub fn pause_role() -> B256

Returns the PAUSE_ROLE constant

This role identifier grants permission to pause the token contract. The role is computed as keccak256("PAUSE_ROLE").

pub fn unpause_role() -> B256

Returns the UNPAUSE_ROLE constant

This role identifier grants permission to unpause the token contract. The role is computed as keccak256("UNPAUSE_ROLE").

pub fn issuer_role() -> B256

Returns the ISSUER_ROLE constant

This role identifier grants permission to mint and burn tokens. The role is computed as keccak256("ISSUER_ROLE").

pub fn burn_blocked_role() -> B256

Returns the BURN_BLOCKED_ROLE constant

This role identifier grants permission to burn tokens from blocked accounts. The role is computed as keccak256("BURN_BLOCKED_ROLE").

pub fn balance_of(&self, call: balanceOfCall) -> Result<U256>

Returns the token balance of account.

pub fn allowance(&self, call: allowanceCall) -> Result<U256>

Returns the remaining allowance that spender can transfer on behalf of owner.

pub fn change_transfer_policy_id( &mut self, msg_sender: Address, call: changeTransferPolicyIdCall, ) -> Result<()>

Updates the TIP403Registry transfer policy governing this token’s transfers.

Errors

• Unauthorized — caller does not hold DEFAULT_ADMIN_ROLE
• InvalidTransferPolicyId — policy does not exist in the TIP403Registry

pub fn set_supply_cap( &mut self, msg_sender: Address, call: setSupplyCapCall, ) -> Result<()>

Sets a new supply cap. Must be ≥ current total supply and ≤ U128_MAX.

Errors

• Unauthorized — caller does not hold DEFAULT_ADMIN_ROLE
• InvalidSupplyCap — new cap is below current total supply
• SupplyCapExceeded — new cap exceeds U128_MAX

pub fn pause(&mut self, msg_sender: Address, _call: pauseCall) -> Result<()>

Pauses all token transfers.

Errors

• Unauthorized — caller does not hold PAUSE_ROLE

pub fn unpause(&mut self, msg_sender: Address, _call: unpauseCall) -> Result<()>

Unpauses token transfers.

Errors

• Unauthorized — caller does not hold UNPAUSE_ROLE

pub fn set_next_quote_token( &mut self, msg_sender: Address, call: setNextQuoteTokenCall, ) -> Result<()>

Stages a new quote token. Must be finalized via Self::complete_quote_token_update. Validates that the candidate is a deployed TIP-20 token (via TIP20Factory) and, for USD-denominated tokens, that the candidate is also USD-denominated.

Errors

• Unauthorized — caller does not hold DEFAULT_ADMIN_ROLE
• InvalidQuoteToken — token is pathUSD, candidate is not a deployed TIP-20, or USD currency mismatch

pub fn complete_quote_token_update( &mut self, msg_sender: Address, _call: completeQuoteTokenUpdateCall, ) -> Result<()>

Finalizes the staged quote token update. Walks the quote-token chain to detect cycles before committing the change.

Errors

• Unauthorized — caller does not hold DEFAULT_ADMIN_ROLE
• InvalidQuoteToken — update would create a cycle in the quote-token graph

pub fn mint(&mut self, msg_sender: Address, call: mintCall) -> Result<()>

Mints amount tokens to the specified to address. Enforces mint-recipient compliance via TIP403Registry and validates against supply cap.

Errors

• PolicyForbids — TIP-403 policy rejects the mint recipient
• Unauthorized — caller does not hold the ISSUER_ROLE role
• SupplyCapExceeded — minting would push total supply above the cap

pub fn mint_with_memo( &mut self, msg_sender: Address, call: mintWithMemoCall, ) -> Result<()>

Like Self::mint, but attaches a 32-byte memo.

fn _mint( &mut self, msg_sender: Address, to: Address, amount: U256, ) -> Result<()>

Internal helper to mint new tokens and update balances

pub fn burn(&mut self, msg_sender: Address, call: burnCall) -> Result<()>

Burns amount from the caller’s balance and reduces total supply.

Errors

• Unauthorized — caller does not hold the ISSUER_ROLE role
• InsufficientBalance — caller balance lower than burn amount

pub fn burn_with_memo( &mut self, msg_sender: Address, call: burnWithMemoCall, ) -> Result<()>

Like Self::burn, but attaches a 32-byte memo.

pub fn burn_blocked( &mut self, msg_sender: Address, call: burnBlockedCall, ) -> Result<()>

Burns tokens from addresses blocked by TIP403Registry policy.

Errors

• Unauthorized — caller does not hold BURN_BLOCKED_ROLE
• PolicyForbids — target address is not blocked by policy
• ProtectedAddress — cannot burn from fee manager or stablecoin DEX addresses

fn _burn(&mut self, msg_sender: Address, amount: U256) -> Result<()>

pub fn approve( &mut self, msg_sender: Address, call: approveCall, ) -> Result<bool>

Sets spender’s allowance to amount for the caller’s tokens. Deducts from the caller’s AccountKeychain spending limit when the new allowance exceeds the previous one.

Errors

• SpendingLimitExceeded — new allowance exceeds access key spending limit

pub fn nonces(&self, call: noncesCall) -> Result<U256>

Returns the current nonce for an address (EIP-2612)

pub fn domain_separator(&self) -> Result<B256>

Returns the EIP-712 domain separator, computed dynamically from the token name and chain ID.

pub fn permit(&mut self, call: permitCall) -> Result<()>

Sets allowance via a signed EIP-2612 permit. Validates the ECDSA signature, checks the deadline, and increments the nonce. Allowed even when the token is paused.

Errors

• PermitExpired — current timestamp exceeds permit deadline
• InvalidSignature — ECDSA recovery failed or recovered signer ≠ owner

pub fn transfer( &mut self, msg_sender: Address, call: transferCall, ) -> Result<bool>

Transfers amount tokens from the caller to to. Enforces compliance via the TIP403Registry and deducts from the caller’s AccountKeychain spending limit.

Errors

• Paused — token transfers are currently paused
• InvalidRecipient — recipient address is zero
• PolicyForbids — TIP-403 policy rejects sender or recipient
• SpendingLimitExceeded — access key spending limit exceeded
• InsufficientBalance — sender balance lower than transfer amount

pub fn transfer_from( &mut self, msg_sender: Address, call: transferFromCall, ) -> Result<bool>

Transfers amount on behalf of from using the caller’s allowance. Enforces compliance via the TIP403Registry.

Errors

• Paused — token transfers are currently paused
• InvalidRecipient — recipient address is zero
• PolicyForbids — TIP-403 policy rejects sender or recipient
• InsufficientAllowance — caller allowance lower than transfer amount
• InsufficientBalance — from balance lower than transfer amount

pub fn transfer_from_with_memo( &mut self, msg_sender: Address, call: transferFromWithMemoCall, ) -> Result<bool>

Like Self::transfer_from, but attaches a 32-byte memo.

pub fn system_transfer_from( &mut self, from: Address, to: Address, amount: U256, ) -> Result<bool>

Transfers amount from from to to without approval, for use by other precompiles only (not exposed via ABI). Enforces compliance via the TIP403Registry and AccountKeychain.

Errors

• Paused — token transfers are currently paused
• InvalidRecipient — recipient address is zero
• PolicyForbids — TIP-403 policy rejects sender or recipient
• SpendingLimitExceeded — access key spending limit exceeded
• InsufficientBalance — from balance lower than transfer amount

fn _transfer_from( &mut self, msg_sender: Address, from: Address, to: Address, amount: U256, ) -> Result<bool>

pub fn transfer_with_memo( &mut self, msg_sender: Address, call: transferWithMemoCall, ) -> Result<()>

Like Self::transfer, but attaches a 32-byte memo.

impl TIP20Token

pub fn from_address(address: Address) -> Result<Self>

Creates a TIP20Token handle from a raw address.

Errors

• InvalidToken — address does not carry the 0x20C0 TIP-20 prefix

pub fn from_address_unchecked(address: Address) -> Self

Creates a TIP20Token without validating the prefix.

Safety

Caller must ensure is_tip20_prefix(address) returns true.

pub fn initialize( &mut self, msg_sender: Address, name: &str, symbol: &str, currency: &str, quote_token: Address, admin: Address, ) -> Result<()>

Initializes the TIP-20 token precompile with metadata, quote token, supply cap, and default admin role. Called once by TIP20Factory during token creation.

fn get_balance(&self, account: Address) -> Result<U256>

fn set_balance(&mut self, account: Address, amount: U256) -> Result<()>

fn get_allowance(&self, owner: Address, spender: Address) -> Result<U256>

fn set_allowance( &mut self, owner: Address, spender: Address, amount: U256, ) -> Result<()>

fn set_total_supply(&mut self, amount: U256) -> Result<()>

fn check_not_paused(&self) -> Result<()>

fn check_recipient(&self, to: Address) -> Result<()>

Validates that the recipient is not:

• the zero address (preventing accidental burns)
• another TIP20 token

pub fn is_transfer_authorized(&self, from: Address, to: Address) -> Result<bool>

Check whether a transfer is authorized by the token’s TIP403Registry policy. TIP-1015: For T2+, uses directional sender/recipient checks.

pub fn ensure_transfer_authorized( &self, from: Address, to: Address, ) -> Result<()>

Ensures the transfer is authorized by the token’s TIP403Registry policy.

Errors

• PolicyForbids — sender or recipient is not authorized by the active transfer policy

pub fn check_and_update_spending_limit( &mut self, from: Address, amount: U256, ) -> Result<()>

Checks and deducts amount from the caller’s AccountKeychain spending limit.

Errors

• SpendingLimitExceeded — access key spending limit exceeded

fn _transfer(&mut self, from: Address, to: Address, amount: U256) -> Result<()>

pub fn transfer_fee_pre_tx(&mut self, from: Address, amount: U256) -> Result<()>

Transfers fee tokens from from to the fee manager before transaction execution. Respects the token’s pause state and deducts from the AccountKeychain spending limit.

Errors

• Paused — token transfers are currently paused
• InsufficientBalance — sender balance lower than fee amount
• SpendingLimitExceeded — access key spending limit exceeded

pub fn transfer_fee_post_tx( &mut self, to: Address, refund: U256, actual_spending: U256, ) -> Result<()>

Refunds unused fee tokens from the fee manager back to to and emits a transfer event for the actual gas spent. Intentionally allowed when paused so that a pause transaction can still receive its fee refund. On T1C+, also restores the AccountKeychain spending limit by the refund amount.

impl TIP20Token

pub fn create_precompile( address: Address, cfg: &CfgEnv<TempoHardfork>, ) -> DynPrecompile

Creates the EVM precompile for this type.

Trait Implementations

impl ContractStorage for TIP20Token

fn address(&self) -> Address

Contract address.

fn storage(&self) -> &StorageCtx

Contract storage accessor.

fn storage_mut(&mut self) -> &mut StorageCtx

Contract storage mutable accessor.

fn is_initialized(&self) -> Result<bool>

Returns true if the contract has been initialized (has bytecode deployed).

impl Precompile for TIP20Token

fn call(&mut self, calldata: &[u8], msg_sender: Address) -> PrecompileResult

Dispatches an EVM call to this precompile.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 1552 bytes