tempo_precompiles/tip20/

mod.rs

//! [TIP-20] token standard — Tempo's native fungible token implementation.
//!
//! Provides ERC-20-like balances, allowances, and transfers with Tempo extensions:
//! role-based access control, pausability, supply caps, transfer policies ([TIP-403]), opt-in
//! staking rewards, EIP-2612 permits (T2+), quote-token graphs, and virtual addresses ([TIP-1022]).
//!
//! [TIP-20]: <https://docs.tempo.xyz/protocol/tip20>
//! [TIP-403]: <https://docs.tempo.xyz/protocol/tip403>
//! [TIP-1022]: <https://docs.tempo.xyz/protocol/tip1022>

pub mod dispatch;
pub mod rewards;
pub mod roles;

pub use tempo_contracts::precompiles::{
    IRolesAuth, ITIP20, RolesAuthError, RolesAuthEvent, TIP20Error, TIP20Event, USD_CURRENCY,
};
pub use tempo_primitives::is_tip20_prefix;

// Re-export the generated slots module for external access to storage slot constants
pub use slots as tip20_slots;

use crate::{
    PATH_USD_ADDRESS, RECEIVE_POLICY_GUARD_ADDRESS, TIP_FEE_MANAGER_ADDRESS,
    account_keychain::AccountKeychain,
    address_registry::AddressRegistry,
    error::{Result, TempoPrecompileError},
    receive_policy_guard::{InboundKind, ReceivePolicyGuard, RecoveryMode},
    storage::{Handler, Mapping},
    tip20::{rewards::UserRewardInfo, roles::DEFAULT_ADMIN_ROLE},
    tip20_factory::TIP20Factory,
    tip403_registry::{AuthRole, ITIP403Registry, TIP403Registry},
};
use alloy::{
    primitives::{Address, B256, U256, keccak256, uint},
    sol_types::SolValue,
};
use std::sync::LazyLock;
use tempo_chainspec::hardfork::TempoHardfork;
use tempo_contracts::precompiles::{
    DECIMALS as TIP20_DECIMALS, ReceivePolicyGuardError, STABLECOIN_DEX_ADDRESS,
    TIP20_CHANNEL_RESERVE_ADDRESS,
};
use tempo_precompiles_macros::contract;
use tempo_primitives::TempoAddressExt;
use tracing::trace;

/// u128::MAX as U256
pub const U128_MAX: U256 = uint!(0xffffffffffffffffffffffffffffffff_U256);

/// Validates that the given token's currency is `"USD"`.
///
/// # Errors
/// - `InvalidToken` — address does not have the TIP-20 prefix
/// - `InvalidCurrency` — token currency is not `"USD"`
pub fn validate_usd_currency(token: Address) -> Result<()> {
    if TIP20Token::from_address(token)?.currency()? != USD_CURRENCY {
        return Err(TIP20Error::invalid_currency().into());
    }
    Ok(())
}

/// TIP-20 token contract — the native token standard on Tempo.
///
/// Implements ERC-20-like functionality (balances, allowances, transfers) with additional
/// features: role-based access control, pausability, supply caps, transfer policies ([TIP-403]),
/// virtual addresses ([TIP-1022]), and opt-in staking rewards.
///
/// [TIP-403]: <https://docs.tempo.xyz/protocol/tip403>
/// [TIP-1022]: <https://docs.tempo.xyz/protocol/tip1022>
///
/// Each token lives at a deterministic address with the `0x20C0` prefix.
///
/// The struct fields define the on-chain storage layout; the `#[contract]` macro generates the
/// storage handlers which provide an ergonomic way to interact with the EVM state.
#[contract]
pub struct TIP20Token {
    // RolesAuth
    roles: Mapping<Address, Mapping<B256, bool>>,
    role_admins: Mapping<B256, B256>,

    // TIP20 Metadata
    name: String,
    symbol: String,
    currency: String,
    // TIP-1026: Token Logo URI.
    // Reuses the previously-unused `_domain_separator` slot (always 0 on
    // pre-T5 tokens), which reads as the empty string under Solidity's
    // short-string encoding — matching the spec's "default empty" semantics.
    // Assumes the slot was never written; do not write to it from pre-T5 code.
    logo_uri: String,
    quote_token: Address,
    next_quote_token: Address,
    transfer_policy_id: u64,

    // TIP20 Token
    total_supply: U256,
    balances: Mapping<Address, U256>,
    allowances: Mapping<Address, Mapping<Address, U256>>,
    permit_nonces: Mapping<Address, U256>,
    paused: bool,
    supply_cap: U256,
    // Unused slot, kept for storage layout compatibility
    _salts: Mapping<B256, bool>,

    // TIP20 Rewards
    global_reward_per_token: U256,
    opted_in_supply: u128,
    user_reward_info: Mapping<Address, UserRewardInfo>,
}

/// EIP-712 Permit typehash: keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)")
pub static PERMIT_TYPEHASH: LazyLock<B256> = LazyLock::new(|| {
    keccak256(b"Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)")
});

/// EIP-712 domain separator typehash
pub static EIP712_DOMAIN_TYPEHASH: LazyLock<B256> = LazyLock::new(|| {
    keccak256(b"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
});

/// EIP-712 version hash: keccak256("1")
pub static VERSION_HASH: LazyLock<B256> = LazyLock::new(|| keccak256(b"1"));

/// Role hash for pausing token transfers.
pub static PAUSE_ROLE: LazyLock<B256> = LazyLock::new(|| keccak256(b"PAUSE_ROLE"));
/// Role hash for unpausing token transfers.
pub static UNPAUSE_ROLE: LazyLock<B256> = LazyLock::new(|| keccak256(b"UNPAUSE_ROLE"));
/// Role hash for minting new tokens.
pub static ISSUER_ROLE: LazyLock<B256> = LazyLock::new(|| keccak256(b"ISSUER_ROLE"));
/// Role hash that authorizes burning tokens from blocked accounts.
pub static BURN_BLOCKED_ROLE: LazyLock<B256> = LazyLock::new(|| keccak256(b"BURN_BLOCKED_ROLE"));

#[rustfmt::skip]
/// System custody addresses added to burn-blocked protection at each hardfork.
pub const PROTECTED: &[(TempoHardfork, &[Address])] = &[
    (TempoHardfork::Genesis, &[TIP_FEE_MANAGER_ADDRESS, STABLECOIN_DEX_ADDRESS]),
    (TempoHardfork::T5, &[TIP20_CHANNEL_RESERVE_ADDRESS]),
    (TempoHardfork::T6, &[RECEIVE_POLICY_GUARD_ADDRESS]),
];

impl TIP20Token {
    /// Returns the token name.
    pub fn name(&self) -> Result<String> {
        self.name.read()
    }

    /// Returns the token symbol.
    pub fn symbol(&self) -> Result<String> {
        self.symbol.read()
    }

    /// Returns the token decimals (always 6 for TIP-20).
    pub fn decimals(&self) -> Result<u8> {
        Ok(TIP20_DECIMALS)
    }

    /// Returns the token's currency denomination (e.g. `"USD"`).
    pub fn currency(&self) -> Result<String> {
        self.currency.read()
    }

    /// Returns the logo URI for this token (TIP-1026).
    ///
    /// Returns an empty string if not set.
    pub fn logo_uri(&self) -> Result<String> {
        self.logo_uri.read()
    }

    /// Returns the current total supply.
    pub fn total_supply(&self) -> Result<U256> {
        self.total_supply.read()
    }

    /// Returns the active quote token address used for pricing.
    pub fn quote_token(&self) -> Result<Address> {
        self.quote_token.read()
    }

    /// Returns the pending next quote token address (set but not yet finalized).
    pub fn next_quote_token(&self) -> Result<Address> {
        self.next_quote_token.read()
    }

    /// Returns the maximum mintable supply.
    pub fn supply_cap(&self) -> Result<U256> {
        self.supply_cap.read()
    }

    /// Returns whether the token is currently paused.
    pub fn paused(&self) -> Result<bool> {
        self.paused.read()
    }

    /// Returns the TIP-403 transfer policy ID governing this token's transfers.
    pub fn transfer_policy_id(&self) -> Result<u64> {
        self.transfer_policy_id.read()
    }

    /// 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 pause_role() -> B256 {
        *PAUSE_ROLE
    }

    /// 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 unpause_role() -> B256 {
        *UNPAUSE_ROLE
    }

    /// 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 issuer_role() -> B256 {
        *ISSUER_ROLE
    }

    /// 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 burn_blocked_role() -> B256 {
        *BURN_BLOCKED_ROLE
    }

    /// Returns the token balance of `account`.
    pub fn balance_of(&self, call: ITIP20::balanceOfCall) -> Result<U256> {
        self.balances[call.account].read()
    }

    /// Returns the remaining allowance that `spender` can transfer on behalf of `owner`.
    pub fn allowance(&self, call: ITIP20::allowanceCall) -> Result<U256> {
        self.allowances[call.owner][call.spender].read()
    }

    /// 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 change_transfer_policy_id(
        &mut self,
        msg_sender: Address,
        call: ITIP20::changeTransferPolicyIdCall,
    ) -> Result<()> {
        self.check_role(msg_sender, DEFAULT_ADMIN_ROLE)?;

        // Validate that the policy exists
        if !TIP403Registry::new().policy_exists(ITIP403Registry::policyExistsCall {
            policyId: call.newPolicyId,
        })? {
            return Err(TIP20Error::invalid_transfer_policy_id().into());
        }

        self.transfer_policy_id.write(call.newPolicyId)?;

        self.emit_event(TIP20Event::transfer_policy_update(
            msg_sender,
            call.newPolicyId,
        ))
    }

    /// 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 set_supply_cap(
        &mut self,
        msg_sender: Address,
        call: ITIP20::setSupplyCapCall,
    ) -> Result<()> {
        self.check_role(msg_sender, DEFAULT_ADMIN_ROLE)?;
        if call.newSupplyCap < self.total_supply()? {
            return Err(TIP20Error::invalid_supply_cap().into());
        }

        if call.newSupplyCap > U128_MAX {
            return Err(TIP20Error::supply_cap_exceeded().into());
        }

        self.supply_cap.write(call.newSupplyCap)?;

        self.emit_event(TIP20Event::supply_cap_update(msg_sender, call.newSupplyCap))
    }

    // ========== TIP-1026: Logo URI ==========

    /// Maximum byte length of a token logo URI (TIP-1026).
    pub const MAX_LOGO_URI_BYTES: usize = 256;

    /// Allowlist of ASCII-case-insensitive URI schemes accepted for [`Self::set_logo_uri`].
    ///
    /// TIP-1026 guarantees that the protocol validates the scheme prefix to make integration easier
    /// and reject obviously dangerous values (e.g. `javascript:`). What the consumer does with the URI
    /// afterwards (rendering, fetching, etc.) is out of scope and remains the consumer's responsibility.
    pub const ALLOWED_LOGO_URI_SCHEMES: &'static [&'static str] =
        &["https", "http", "ipfs", "data"];

    /// Validates a logo URI against the TIP-1026 protocol rules:
    /// - length ≤ [`Self::MAX_LOGO_URI_BYTES`]
    /// - syntactically well-formed URI schemes in [`Self::ALLOWED_LOGO_URI_SCHEMES`].
    ///
    /// Empty strings are accepted unconditionally.
    pub(crate) fn validate_logo_uri(uri: &str) -> Result<()> {
        if uri.len() > Self::MAX_LOGO_URI_BYTES {
            return Err(TIP20Error::logo_uri_too_long().into());
        }
        if !uri.is_empty() && !Self::is_allowed_logo_uri(uri) {
            return Err(TIP20Error::invalid_logo_uri().into());
        }
        Ok(())
    }

    fn is_allowed_logo_uri(uri: &str) -> bool {
        let Some((scheme, _rest)) = uri.split_once(':') else {
            return false;
        };

        let mut bytes = scheme.bytes();
        let Some(first) = bytes.next() else {
            return false;
        };
        if !first.is_ascii_alphabetic() {
            return false;
        }
        if !bytes.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'+' | b'-' | b'.')) {
            return false;
        }

        Self::ALLOWED_LOGO_URI_SCHEMES
            .iter()
            .any(|allowed| scheme.eq_ignore_ascii_case(allowed))
    }

    /// Sets the logo URI for this token (TIP-1026). Empty strings are valid
    /// and clear the URI.
    ///
    /// # Errors
    /// - `Unauthorized` — caller does not hold `DEFAULT_ADMIN_ROLE`
    /// - `LogoURITooLong` — `bytes(newLogoURI).length > 256`
    /// - `InvalidLogoURI` — `newLogoURI` is non-empty and either has no
    ///   parseable scheme (RFC 3986 §3.1) or its scheme is not in
    ///   [`Self::ALLOWED_LOGO_URI_SCHEMES`]
    pub fn set_logo_uri(
        &mut self,
        msg_sender: Address,
        call: ITIP20::setLogoURICall,
    ) -> Result<()> {
        self.check_role(msg_sender, DEFAULT_ADMIN_ROLE)?;
        self.write_logo_uri(msg_sender, call.newLogoURI)
    }

    /// Internal helper: runs [`Self::validate_logo_uri`] (length cap + scheme allowlist), stores the
    /// value, and emits `LogoURIUpdated`.
    ///
    /// **IMPORTANT:** this function performs NO role check. It is the caller's responsibility.
    pub(crate) fn write_logo_uri(&mut self, updater: Address, new_logo_uri: String) -> Result<()> {
        Self::validate_logo_uri(&new_logo_uri)?;

        self.logo_uri.write(new_logo_uri.clone())?;

        self.emit_event(TIP20Event::LogoURIUpdated(ITIP20::LogoURIUpdated {
            updater,
            newLogoURI: new_logo_uri,
        }))
    }

    // ========== End TIP-1026 ==========

    /// Pauses all token transfers.
    ///
    /// # Errors
    /// - `Unauthorized` — caller does not hold `PAUSE_ROLE`
    pub fn pause(&mut self, msg_sender: Address, _call: ITIP20::pauseCall) -> Result<()> {
        self.check_role(msg_sender, *PAUSE_ROLE)?;
        self.paused.write(true)?;

        self.emit_event(TIP20Event::pause_state_update(msg_sender, true))
    }

    /// Unpauses token transfers.
    ///
    /// # Errors
    /// - `Unauthorized` — caller does not hold `UNPAUSE_ROLE`
    pub fn unpause(&mut self, msg_sender: Address, _call: ITIP20::unpauseCall) -> Result<()> {
        self.check_role(msg_sender, *UNPAUSE_ROLE)?;
        self.paused.write(false)?;

        self.emit_event(TIP20Event::pause_state_update(msg_sender, false))
    }

    /// 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 set_next_quote_token(
        &mut self,
        msg_sender: Address,
        call: ITIP20::setNextQuoteTokenCall,
    ) -> Result<()> {
        self.check_role(msg_sender, DEFAULT_ADMIN_ROLE)?;

        if self.address == PATH_USD_ADDRESS {
            return Err(TIP20Error::invalid_quote_token().into());
        }

        // Verify the new quote token is a valid TIP20 token that has been deployed
        // use factory's `is_tip20()` which checks both prefix and counter
        if !TIP20Factory::new().is_tip20(call.newQuoteToken)? {
            return Err(TIP20Error::invalid_quote_token().into());
        }

        // Check if the currency is USD, if so then the quote token's currency MUST also be USD
        let currency = self.currency()?;
        if currency == USD_CURRENCY {
            let quote_token_currency = Self::from_address(call.newQuoteToken)?.currency()?;
            if quote_token_currency != USD_CURRENCY {
                return Err(TIP20Error::invalid_quote_token().into());
            }
        }

        self.next_quote_token.write(call.newQuoteToken)?;

        self.emit_event(TIP20Event::next_quote_token_set(
            msg_sender,
            call.newQuoteToken,
        ))
    }

    /// 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 complete_quote_token_update(
        &mut self,
        msg_sender: Address,
        _call: ITIP20::completeQuoteTokenUpdateCall,
    ) -> Result<()> {
        self.check_role(msg_sender, DEFAULT_ADMIN_ROLE)?;

        let next_quote_token = self.next_quote_token()?;

        // Check that this does not create a loop
        // Loop through quote tokens until we reach the root (pathUSD)
        let mut current = next_quote_token;
        while current != PATH_USD_ADDRESS {
            if current == self.address {
                return Err(TIP20Error::invalid_quote_token().into());
            }

            current = Self::from_address(current)?.quote_token()?;
        }

        // Update the quote token
        self.quote_token.write(next_quote_token)?;

        self.emit_event(TIP20Event::quote_token_update(msg_sender, next_quote_token))
    }

    // Token operations

    /// Mints `amount` tokens to the resolved target `to` address:
    /// - Enforces mint-recipient compliance via [`TIP403Registry`] and validates against supply cap
    /// - Resolves `to` via the [`AddressRegistry`]. If `to` is a virtual address, credits the
    ///   resolved master and emits a two-hop `Transfer` and `Mint(virtual, amount)` events
    ///
    /// # Errors
    /// - `Unauthorized` — caller does not hold the `ISSUER_ROLE` role
    /// - `ContractPaused` — (+T3) token is paused
    /// - `InvalidRecipient` — (+T3) recipient is zero or a TIP-20 prefix address
    /// - `PolicyForbids` — TIP-403 policy rejects the mint recipient
    /// - `SupplyCapExceeded` — minting would push total supply above the cap
    pub fn mint(&mut self, msg_sender: Address, call: ITIP20::mintCall) -> Result<()> {
        let Some((total_supply, to)) =
            self.validate_mint(msg_sender, call.to, call.amount, B256::ZERO)?
        else {
            return Ok(());
        };

        self._mint(&to, total_supply, call.amount)?;
        self.emit_event(TIP20Event::mint(call.to, call.amount))?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }

        Ok(())
    }

    /// Like [`Self::mint`], but attaches a 32-byte memo.
    pub fn mint_with_memo(
        &mut self,
        msg_sender: Address,
        call: ITIP20::mintWithMemoCall,
    ) -> Result<()> {
        let Some((total_supply, to)) =
            self.validate_mint(msg_sender, call.to, call.amount, call.memo)?
        else {
            return Ok(());
        };

        self._mint(&to, total_supply, call.amount)?;
        self.emit_event(TIP20Event::transfer_with_memo(
            Address::ZERO,
            call.to,
            call.amount,
            call.memo,
        ))?;
        self.emit_event(TIP20Event::mint(call.to, call.amount))?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }
        Ok(())
    }

    /// Internal helper to mint new tokens and update balances.
    pub(crate) fn _mint(&mut self, to: &Recipient, total_supply: U256, amount: U256) -> Result<()> {
        let new_supply = total_supply
            .checked_add(amount)
            .ok_or(TempoPrecompileError::under_overflow())?;

        let supply_cap = self.supply_cap()?;
        if new_supply > supply_cap {
            return Err(TIP20Error::supply_cap_exceeded().into());
        }

        self.handle_rewards_on_mint(to.target, amount)?;

        self.set_total_supply(new_supply)?;
        self.increment_balance(to.target, amount)?;

        self.emit_event(to.build_transfer_event(Address::ZERO, amount))
    }

    /// Burns `amount` from the caller's balance and reduces total supply.
    ///
    /// # Errors
    /// - `ContractPaused` — (+T3) token is paused
    /// - `Unauthorized` — caller does not hold the `ISSUER_ROLE` role
    /// - `InsufficientBalance` — caller balance lower than burn amount
    pub fn burn(&mut self, msg_sender: Address, call: ITIP20::burnCall) -> Result<()> {
        self._burn(msg_sender, call.amount)?;
        self.emit_event(TIP20Event::burn(msg_sender, call.amount))
    }

    /// Like [`Self::burn`], but attaches a 32-byte memo.
    pub fn burn_with_memo(
        &mut self,
        msg_sender: Address,
        call: ITIP20::burnWithMemoCall,
    ) -> Result<()> {
        self._burn(msg_sender, call.amount)?;

        self.emit_event(TIP20Event::transfer_with_memo(
            msg_sender,
            Address::ZERO,
            call.amount,
            call.memo,
        ))?;
        self.emit_event(TIP20Event::burn(msg_sender, call.amount))
    }

    /// Burns tokens from addresses blocked by [`TIP403Registry`] policy. Where `owner` refers to
    /// the account with ownership of the funds, either directly, or via the `ReceivePolicyGuard`.
    ///
    /// # Errors
    /// - `ContractPaused` — (+T3) token is paused
    /// - `Unauthorized` — caller does not hold `BURN_BLOCKED_ROLE`
    /// - `PolicyForbids` — target address is not blocked by policy
    /// - `ProtectedAddress` — cannot burn from protected system custody addresses
    pub fn burn_blocked(
        &mut self,
        msg_sender: Address,
        owner: Address,
        amount: U256,
        check_protected: bool,
    ) -> Result<()> {
        let hardfork = self.storage.spec();

        // Validate burner role and (+T3) ensure token is not paused
        if hardfork.is_t3() {
            self.check_not_paused()?;
        }
        self.check_role(msg_sender, *BURN_BLOCKED_ROLE)?;

        if check_protected {
            // Prevent burning from system custody addresses to protect accounting invariants.
            if PROTECTED
                .iter()
                .any(|(hf, addr)| hardfork >= *hf && addr.contains(&owner))
                || (hardfork.is_t5() && owner == self.address)
            {
                return Err(TIP20Error::protected_address().into());
            }
        }

        // Check if the address is blocked from transferring (sender authorization)
        let policy_id = self.transfer_policy_id()?;
        if TIP403Registry::new().is_authorized_as(policy_id, owner, AuthRole::sender())? {
            // Only allow burning from addresses that are blocked from transferring
            return Err(TIP20Error::policy_forbids().into());
        }

        let burn_from = if check_protected {
            owner
        } else {
            RECEIVE_POLICY_GUARD_ADDRESS
        };
        self._transfer(burn_from, &Recipient::direct(Address::ZERO), amount)?;

        let total_supply = self.total_supply()?;
        let new_supply =
            total_supply
                .checked_sub(amount)
                .ok_or(TIP20Error::insufficient_balance(
                    total_supply,
                    amount,
                    self.address,
                ))?;
        self.set_total_supply(new_supply)?;

        self.emit_event(TIP20Event::burn_blocked(owner, amount))
    }

    fn _burn(&mut self, msg_sender: Address, amount: U256) -> Result<()> {
        // Validate issuer role and (+T3) ensure token is not paused
        if self.storage.spec().is_t3() {
            self.check_not_paused()?;
        }
        self.check_role(msg_sender, *ISSUER_ROLE)?;

        self._transfer(msg_sender, &Recipient::direct(Address::ZERO), amount)?;

        let total_supply = self.total_supply()?;
        let new_supply =
            total_supply
                .checked_sub(amount)
                .ok_or(TIP20Error::insufficient_balance(
                    total_supply,
                    amount,
                    self.address,
                ))?;
        self.set_total_supply(new_supply)
    }

    /// 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 approve(&mut self, msg_sender: Address, call: ITIP20::approveCall) -> Result<bool> {
        // Check and update spending limits for access keys
        AccountKeychain::new().authorize_approve(
            msg_sender,
            self.address,
            self.get_allowance(msg_sender, call.spender)?,
            call.amount,
        )?;

        // Set the new allowance
        self.set_allowance(msg_sender, call.spender, call.amount)?;

        self.emit_event(TIP20Event::approval(msg_sender, call.spender, call.amount))?;

        Ok(true)
    }

    // EIP-2612 Permit

    /// Returns the current nonce for an address (EIP-2612)
    pub fn nonces(&self, call: ITIP20::noncesCall) -> Result<U256> {
        self.permit_nonces[call.owner].read()
    }

    /// Returns the EIP-712 domain separator, computed dynamically from the token name and chain ID.
    pub fn domain_separator(&self) -> Result<B256> {
        let name = self.name()?;
        let name_hash = self.storage.keccak256(name.as_bytes())?;
        let chain_id = U256::from(self.storage.chain_id());

        let encoded = (
            *EIP712_DOMAIN_TYPEHASH,
            name_hash,
            *VERSION_HASH,
            chain_id,
            self.address,
        )
            .abi_encode();

        self.storage.keccak256(&encoded)
    }

    /// 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.
    ///
    /// [EIP-2612]: https://eips.ethereum.org/EIPS/eip-2612
    ///
    /// # Errors
    /// - `PermitExpired` — current timestamp exceeds permit deadline
    /// - `InvalidSignature` — ECDSA recovery failed or recovered signer ≠ owner
    pub fn permit(&mut self, call: ITIP20::permitCall) -> Result<()> {
        // 1. Check deadline
        if self.storage.timestamp() > call.deadline {
            return Err(TIP20Error::permit_expired().into());
        }

        // 2. Construct EIP-712 struct hash
        let nonce = self.permit_nonces[call.owner].read()?;
        let struct_hash = self.storage.keccak256(
            &(
                *PERMIT_TYPEHASH,
                call.owner,
                call.spender,
                call.value,
                nonce,
                call.deadline,
            )
                .abi_encode(),
        )?;

        // 3. Construct EIP-712 digest
        let domain_separator = self.domain_separator()?;
        let digest = self.storage.keccak256(
            &[
                &[0x19, 0x01],
                domain_separator.as_slice(),
                struct_hash.as_slice(),
            ]
            .concat(),
        )?;

        // 4. Validate ECDSA signature
        // Only v=27/28 is accepted; v=0/1 is intentionally NOT normalized (see TIP-1004 spec).
        let recovered = self
            .storage
            .recover_signer(digest, call.v, call.r, call.s)?
            .ok_or(TIP20Error::invalid_signature())?;
        if recovered != call.owner {
            return Err(TIP20Error::invalid_signature().into());
        }

        // 5. Increment nonce
        self.permit_nonces[call.owner].write(
            nonce
                .checked_add(U256::from(1))
                .ok_or(TempoPrecompileError::under_overflow())?,
        )?;

        // 6. Set allowance
        self.set_allowance(call.owner, call.spender, call.value)?;

        // 7. Emit Approval event
        self.emit_event(TIP20Event::approval(call.owner, call.spender, call.value))
    }

    /// 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(&mut self, msg_sender: Address, call: ITIP20::transferCall) -> Result<bool> {
        trace!(%msg_sender, ?call, "transferring TIP20");
        let Some(to) =
            self.validate_transfer(None, msg_sender, call.to, call.amount, B256::ZERO)?
        else {
            return Ok(true);
        };

        self._transfer(msg_sender, &to, call.amount)?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }

        Ok(true)
    }

    /// 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(
        &mut self,
        msg_sender: Address,
        call: ITIP20::transferFromCall,
    ) -> Result<bool> {
        let Some(to) = self.validate_transfer(
            Some(msg_sender),
            call.from,
            call.to,
            call.amount,
            B256::ZERO,
        )?
        else {
            return Ok(true);
        };

        self._transfer(call.from, &to, call.amount)?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }

        Ok(true)
    }

    /// Like [`Self::transfer_from`], but attaches a 32-byte memo.
    pub fn transfer_from_with_memo(
        &mut self,
        msg_sender: Address,
        call: ITIP20::transferFromWithMemoCall,
    ) -> Result<bool> {
        let Some(to) =
            self.validate_transfer(Some(msg_sender), call.from, call.to, call.amount, call.memo)?
        else {
            return Ok(true);
        };

        self._transfer(call.from, &to, call.amount)?;
        self.emit_event(TIP20Event::transfer_with_memo(
            call.from,
            call.to,
            call.amount,
            call.memo,
        ))?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }
        Ok(true)
    }

    /// Transfers `amount` from `from` to `to` without checking allowances. For use by precompiles
    /// on the [`crate::address_registry::IMPLICIT_APPROVAL_LIST`] only — not exposed via ABI.
    /// Enforces compliance via the [`TIP403Registry`] and [`AccountKeychain`].
    ///
    /// `caller` is the address of the precompile invoking this function. Starting at
    /// `TempoHardfork::T5` (TIP-1035), the call returns `Unauthorized` unless `caller` is on the
    /// Implicit Approval List. Pre-T5, `caller` is unchecked (preserves pre-TIP-1035 behavior of
    /// the existing internal-only caller, `TipFeeManager`).
    ///
    /// Callers are also expected to pull only from the current `msg.sender`; this is a security
    /// guideline of TIP-1035 enforced at the call site, not by this function.
    ///
    /// # Errors
    /// - `Unauthorized` — `caller` is not on the Implicit Approval List (T5+)
    /// - `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
    pub fn system_transfer_from(
        &mut self,
        caller: Address,
        from: Address,
        amount: U256,
    ) -> Result<bool> {
        // [TIP-1035] List gating: at T5+, only listed precompiles may invoke this entrypoint.
        let spec = self.storage.spec();
        if spec.is_t5() && !crate::address_registry::is_implicitly_approved(caller, spec) {
            return Err(TIP20Error::unauthorized().into());
        }

        let Some(to) = self.validate_transfer(None, from, caller, amount, B256::ZERO)? else {
            return Ok(true);
        };

        self._transfer(from, &to, amount)?;
        if let Some(hop) = to.build_virtual_transfer_event(amount) {
            self.emit_event(hop)?;
        }

        Ok(true)
    }

    /// Debits `spender`'s allowance on `owner`. No-op when unlimited.
    fn consume_allowance(&mut self, owner: Address, spender: Address, amount: U256) -> Result<()> {
        let allowed = self.get_allowance(owner, spender)?;
        if amount > allowed {
            return Err(TIP20Error::insufficient_allowance().into());
        }

        if allowed != U256::MAX {
            let new_allowance = allowed
                .checked_sub(amount)
                .ok_or(TIP20Error::insufficient_allowance())?;
            self.set_allowance(owner, spender, new_allowance)?;
        }
        Ok(())
    }

    /// Like [`Self::transfer`], but attaches a 32-byte memo.
    pub fn transfer_with_memo(
        &mut self,
        msg_sender: Address,
        call: ITIP20::transferWithMemoCall,
    ) -> Result<()> {
        let Some(to) = self.validate_transfer(None, msg_sender, call.to, call.amount, call.memo)?
        else {
            return Ok(());
        };

        self._transfer(msg_sender, &to, call.amount)?;
        self.emit_event(TIP20Event::transfer_with_memo(
            msg_sender,
            call.to,
            call.amount,
            call.memo,
        ))?;
        if let Some(hop) = to.build_virtual_transfer_event(call.amount) {
            self.emit_event(hop)?;
        }
        Ok(())
    }
}

// Utility functions
impl TIP20Token {
    /// Creates a `TIP20Token` handle from a raw address.
    ///
    /// # Errors
    /// - `InvalidToken` — address does not carry the `0x20C0` TIP-20 prefix
    pub fn from_address(address: Address) -> Result<Self> {
        if !address.is_tip20() {
            return Err(TIP20Error::invalid_token().into());
        }
        Ok(Self::__new(address))
    }

    /// Creates a TIP20Token without validating the prefix.
    ///
    /// # Safety
    /// Caller must ensure `is_tip20_prefix(address)` returns true.
    #[inline]
    pub fn from_address_unchecked(address: Address) -> Self {
        debug_assert!(address.is_tip20(), "address must have TIP20 prefix");
        Self::__new(address)
    }

    /// Initializes the TIP-20 token precompile with metadata, quote token, supply cap, and
    /// default admin role. Called once by [`TIP20Factory`] during token creation.
    pub fn initialize(
        &mut self,
        msg_sender: Address,
        name: &str,
        symbol: &str,
        currency: &str,
        quote_token: Address,
        admin: Address,
    ) -> Result<()> {
        trace!(%name, address=%self.address, "Initializing token");

        // must ensure the account is not empty, by setting some code
        self.__initialize()?;

        self.name.write(name.to_string())?;
        self.symbol.write(symbol.to_string())?;
        self.currency.write(currency.to_string())?;

        self.quote_token.write(quote_token)?;
        // Initialize nextQuoteToken to the same value as quoteToken
        self.next_quote_token.write(quote_token)?;

        // Set default values
        self.supply_cap.write(U128_MAX)?;
        self.transfer_policy_id.write(1)?;

        // Initialize roles system and grant admin role
        self.initialize_roles()?;
        self.grant_default_admin(msg_sender, admin)
    }

    fn get_balance(&self, account: Address) -> Result<U256> {
        self.balances[account].read()
    }

    fn set_balance(&mut self, account: Address, amount: U256) -> Result<()> {
        self.balances[account].write(amount)
    }

    fn increment_balance(&mut self, account: Address, amount: U256) -> Result<()> {
        self.balances[account].sinc(amount).map_err(|err| {
            if err == TempoPrecompileError::under_overflow() {
                TIP20Error::supply_cap_exceeded().into()
            } else {
                err
            }
        })
    }

    fn decrement_balance(&mut self, account: Address, amount: U256) -> Result<()> {
        self.balances[account]
            .sdec(amount)
            .map_err(|err| match err {
                TempoPrecompileError::StorageDeltaUnderflow(current) => {
                    TIP20Error::insufficient_balance(current, amount, self.address).into()
                }
                err => err,
            })
    }

    fn get_allowance(&self, owner: Address, spender: Address) -> Result<U256> {
        self.allowances[owner][spender].read()
    }

    fn set_allowance(&mut self, owner: Address, spender: Address, amount: U256) -> Result<()> {
        self.allowances[owner][spender].write(amount)
    }

    fn set_total_supply(&mut self, amount: U256) -> Result<()> {
        self.total_supply.write(amount)
    }

    pub fn check_not_paused(&self) -> Result<()> {
        if self.paused()? {
            return Err(TIP20Error::contract_paused().into());
        }
        Ok(())
    }

    /// Resolves `to`, checks pause state and recipient validity, ensures TIP-403 transfer
    /// authorization, and runs the caller-specific spend check. Additionally (+T6) applies
    /// TIP-1028 address-level receive policies.
    ///
    /// Updates the sender's [`AccountKeychain`] spending limit for direct transfers, and
    /// consumes allowance for `transfer_from` style calls.
    ///
    /// Returns `Some(to)` when the caller should perform the normal transfer.
    /// Returns `None` when funds were blocked, and the caller should return immediately.
    fn validate_transfer(
        &mut self,
        spender: Option<Address>,
        from: Address,
        to: Address,
        amount: U256,
        memo: B256,
    ) -> Result<Option<Recipient>> {
        let to = Recipient::resolve(to)?;
        self.check_not_paused()?;
        to.validate()?;
        self.ensure_transfer_authorized(from, to.target)?;

        if let Some(spender) = spender {
            self.consume_allowance(from, spender, amount)?;
        } else {
            self.check_and_update_spending_limit(from, amount)?;
        }

        if self.validate_inbound_or_block(from, &to, amount, None, memo)? {
            return Ok(None);
        }

        Ok(Some(to))
    }

    /// Resolves `to`, checks the issuer role, and ensures TIP-403 mint-recipient authorization.
    /// Additionally (+T3) checks pause state and validates the effective recipient; also
    /// (+T6) applies TIP-1028 address-level receive policies.
    ///
    /// Returns `Some(to)` when the caller should proceed with the regular mint.
    /// Returns `None` when funds were minted and blocked, and the caller should return immediately.
    fn validate_mint(
        &mut self,
        msg_sender: Address,
        to: Address,
        amount: U256,
        memo: B256,
    ) -> Result<Option<(U256, Recipient)>> {
        let to = Recipient::resolve(to)?;
        self.check_role(msg_sender, *ISSUER_ROLE)?;
        let total_supply = self.total_supply()?;

        if self.storage.spec().is_t3() {
            self.check_not_paused()?;
            to.validate()?;
        }

        // Check if the resolved target address is authorized to receive minted tokens
        if !TIP403Registry::new().is_authorized_as(
            self.transfer_policy_id()?,
            to.target,
            AuthRole::mint_recipient(),
        )? {
            return Err(TIP20Error::policy_forbids().into());
        }

        if self.validate_inbound_or_block(msg_sender, &to, amount, Some(total_supply), memo)? {
            return Ok(None);
        }

        Ok(Some((total_supply, to)))
    }

    /// Check whether a transfer is authorized by the token's [`TIP403Registry`] policy.
    /// [TIP-1015]: For T2+, uses directional sender/recipient checks.
    ///
    /// [TIP-1015]: <https://docs.tempo.xyz/protocol/tips/tip-1015>
    pub fn is_transfer_authorized(&self, from: Address, to: Address) -> Result<bool> {
        let policy_id = self.transfer_policy_id()?;
        let registry = TIP403Registry::new();

        // (spec: +T2) short-circuit and skip recipient check if sender fails
        let sender_auth = registry.is_authorized_as(policy_id, from, AuthRole::sender())?;
        if self.storage.spec().is_t2() && !sender_auth {
            return Ok(false);
        }
        let recipient_auth = registry.is_authorized_as(policy_id, to, AuthRole::recipient())?;
        Ok(sender_auth && recipient_auth)
    }

    /// 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 ensure_transfer_authorized(&self, from: Address, to: Address) -> Result<()> {
        if !self.is_transfer_authorized(from, to)? {
            return Err(TIP20Error::policy_forbids().into());
        }

        Ok(())
    }

    /// Check whether a user is authorized by the token's [`TIP403Registry`] policy for a given role.
    ///
    /// # Errors
    /// - `PolicyForbids` — user is not authorized for the requested role by the active transfer policy
    pub fn ensure_authorized_as(&self, user: Address, role: AuthRole) -> Result<()> {
        let policy_id = self.transfer_policy_id()?;
        if !TIP403Registry::new().is_authorized_as(policy_id, user, role)? {
            return Err(TIP20Error::policy_forbids().into());
        }
        Ok(())
    }

    /// Checks and deducts `amount` from the caller's [`AccountKeychain`] spending limit.
    ///
    /// # Errors
    /// - `SpendingLimitExceeded` — access key spending limit exceeded
    pub fn check_and_update_spending_limit(&mut self, from: Address, amount: U256) -> Result<()> {
        AccountKeychain::new().authorize_transfer(from, self.address, amount)
    }

    /// Core transfer: debits `from`, credits `to.target`, emits `Transfer(from, event_addr, amount)`.
    ///
    /// For virtual recipients the event address is the virtual alias; the balance update always
    /// targets `to.target` (the resolved master).
    pub(crate) fn _transfer(&mut self, from: Address, to: &Recipient, amount: U256) -> Result<()> {
        let from_balance = if !self.storage.spec().is_t8() {
            let from_balance = self.get_balance(from)?;
            if amount > from_balance {
                return Err(
                    TIP20Error::insufficient_balance(from_balance, amount, self.address).into(),
                );
            }
            Some(from_balance)
        } else {
            None
        };

        self.handle_rewards_on_transfer(from, to.target, amount)?;

        // Adjust balances
        //
        // We can't just use `decrement_balance` in both pre- and post-T8 codepaths, because `decrement_balance`
        // charges gas for balance SLOAD that we already do above for pre-T8.
        if let Some(from_balance) = from_balance {
            // pre-T8 path
            let new_from_balance = from_balance
                .checked_sub(amount)
                .ok_or(TempoPrecompileError::under_overflow())?;

            self.set_balance(from, new_from_balance)?;
        } else {
            // post-T8 path
            self.decrement_balance(from, amount)?;
        }

        if to.target != Address::ZERO {
            self.increment_balance(to.target, amount)?;
        }

        self.emit_event(to.build_transfer_event(from, amount))
    }

    /// Validates the receive policy of `to.target`. If blocked, moves the funds into the guard
    /// account and stores a claim receipt; returns `true`. Returns `false` when the inbound is
    /// authorized and the caller should proceed with the normal transfer or mint.
    pub(crate) fn validate_inbound_or_block(
        &mut self,
        originator: Address,
        to: &Recipient,
        amount: U256,
        mint_total_supply: Option<U256>,
        memo: B256,
    ) -> Result<bool> {
        if !self.storage.spec().is_t6() {
            return Ok(false);
        }
        if to.target == RECEIVE_POLICY_GUARD_ADDRESS {
            return Err(ReceivePolicyGuardError::address_reserved().into());
        }

        let token = self.address;
        let Some((reason, recovery)) =
            TIP403Registry::new().check_receive_policy(token, originator, to.target)?
        else {
            return Ok(false);
        };

        let guard = Recipient::direct(RECEIVE_POLICY_GUARD_ADDRESS);
        let kind = if let Some(total_supply) = mint_total_supply {
            self._mint(&guard, total_supply, amount)?;
            self.emit_event(TIP20Event::mint(guard.target, amount))?;
            InboundKind::MINT
        } else {
            self._transfer(originator, &guard, amount)?;
            InboundKind::TRANSFER
        };
        ReceivePolicyGuard::new()
            .store_blocked(token, originator, to, recovery, amount, reason, kind, memo)?;

        Ok(true)
    }

    /// Releases guarded funds to `to`. Resumes skip policy checks. Reroutes
    /// revalidate the transfer and receive policies and meter the spending limit.
    pub(crate) fn release_blocked_funds(
        &mut self,
        originator: Address,
        receiver: Address,
        to: Address,
        amount: U256,
        recovery_mode: RecoveryMode,
        recovery_auth: Address,
    ) -> Result<()> {
        debug_assert!(
            to != RECEIVE_POLICY_GUARD_ADDRESS,
            "checked in ReceivePolicyGuard::claim"
        );

        self.check_not_paused()?;
        let destination = Recipient::resolve(to)?;
        destination.validate()?;
        if recovery_mode.is_reroute(to, receiver) {
            let policy_subject = recovery_mode.policy_subject(originator, receiver);
            self.ensure_transfer_authorized(policy_subject, destination.target)?;
            if TIP403Registry::new()
                .validate_receive_policy(self.address, policy_subject, destination.target)?
                .is_some()
            {
                return Err(TIP20Error::policy_forbids().into());
            }
            if let Some(addr) = recovery_mode.spending_account(recovery_auth) {
                self.check_and_update_spending_limit(addr, amount)?;
            }
        } else {
            self.ensure_authorized_as(destination.target, AuthRole::recipient())?;
        }

        self._transfer(RECEIVE_POLICY_GUARD_ADDRESS, &destination, amount)?;
        if let Some(hop) = destination.build_virtual_transfer_event(amount) {
            self.emit_event(hop)?;
        }
        Ok(())
    }

    /// 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_pre_tx(&mut self, from: Address, amount: U256) -> Result<()> {
        // This function respects the token's pause state and will revert if the token is paused.
        // transfer_fee_post_tx 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.
        self.check_not_paused()?;
        self.check_and_update_spending_limit(from, amount)?;

        // Update rewards for the sender and get their reward recipient
        let from_reward_recipient = self.update_rewards(from)?;

        // If user is opted into rewards, decrease opted-in supply
        if from_reward_recipient != Address::ZERO {
            let opted_in_supply = U256::from(self.get_opted_in_supply()?)
                .checked_sub(amount)
                .ok_or(TempoPrecompileError::under_overflow())?;
            self.set_opted_in_supply(
                opted_in_supply
                    .try_into()
                    .map_err(|_| TempoPrecompileError::under_overflow())?,
            )?;
        }

        self.decrement_balance(from, amount)?;
        self.increment_balance(TIP_FEE_MANAGER_ADDRESS, amount)?;

        Ok(())
    }

    /// 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.
    pub fn transfer_fee_post_tx(
        &mut self,
        to: Address,
        refund: U256,
        actual_spending: U256,
    ) -> Result<()> {
        self.emit_event(TIP20Event::transfer(
            to,
            TIP_FEE_MANAGER_ADDRESS,
            actual_spending,
        ))?;

        // Exit early if there is no refund
        if refund.is_zero() {
            return Ok(());
        }

        if self.storage.spec().is_t1c() {
            AccountKeychain::new().refund_spending_limit(to, self.address, refund)?;
        }

        // Update rewards for the recipient and get their reward recipient
        let to_reward_recipient = self.update_rewards(to)?;

        // If user is opted into rewards, increase opted-in supply by refund amount
        if to_reward_recipient != Address::ZERO {
            let opted_in_supply = U256::from(self.get_opted_in_supply()?)
                .checked_add(refund)
                .ok_or(TempoPrecompileError::under_overflow())?;
            self.set_opted_in_supply(
                opted_in_supply
                    .try_into()
                    .map_err(|_| TempoPrecompileError::under_overflow())?,
            )?;
        }

        self.decrement_balance(TIP_FEE_MANAGER_ADDRESS, refund)?;
        self.increment_balance(to, refund)?;

        Ok(())
    }
}

/// Resolved transfer recipient for [TIP-1022] virtual address support.
///
/// `target` is always the effective (resolved) address where the balance is credited. For virtual
/// recipients, `virtual_addr` carries the original virtual address for event emission.
///
/// [TIP-1022]: <https://docs.tempo.xyz/protocol/tip1022>
#[derive(Debug, PartialEq)]
pub(crate) struct Recipient {
    /// The effective (resolved) address where the balance is credited.
    pub(crate) target: Address,
    /// The virtual address, if registered.
    pub(crate) virtual_addr: Option<Address>,
}

impl Recipient {
    /// Creates a [`Recipient`] with no virtual indirection.
    #[inline]
    pub(crate) fn direct(addr: Address) -> Self {
        Self {
            target: addr,
            virtual_addr: None,
        }
    }

    /// Resolves a recipient via the [`AddressRegistry`].
    ///
    /// If `addr` is a virtual address its registered master is looked up and stored in `target`,
    /// with the original virtual address preserved in `virtual_addr`.
    pub(crate) fn resolve(addr: Address) -> Result<Self> {
        let effective = AddressRegistry::new().resolve_recipient(addr)?;
        Ok(if effective == addr {
            Self::direct(addr)
        } else {
            Self {
                target: effective,
                virtual_addr: Some(addr),
            }
        })
    }

    /// Validates that the recipient is not:
    /// - the zero address (preventing accidental burns)
    /// - an address with the TIP-20 prefix (preventing transfers to token contracts)
    pub(crate) fn validate(&self) -> Result<()> {
        if self.target.is_zero() || self.target.is_tip20() {
            return Err(TIP20Error::invalid_recipient().into());
        }
        Ok(())
    }

    /// Builds the primary `Transfer(from, to, amount)` event.
    ///
    /// For virtual recipients `to` is the virtual address (first hop); for regular
    /// recipients this is the only `Transfer` event needed.
    pub(crate) fn build_transfer_event(&self, from: Address, amount: U256) -> TIP20Event {
        TIP20Event::transfer(from, self.virtual_addr.unwrap_or(self.target), amount)
    }

    /// Builds the forwarding `Transfer(virtual, master, amount)` event for virtual recipients.
    /// Returns `None` for non-virtual recipients.
    pub(crate) fn build_virtual_transfer_event(&self, amount: U256) -> Option<TIP20Event> {
        self.virtual_addr
            .map(|virtual_addr| TIP20Event::transfer(virtual_addr, self.target, amount))
    }
}

#[cfg(test)]
mod recipient_tests {
    use super::*;
    use crate::{
        address_registry::{AddressRegistry, MasterId, UserTag},
        error::TempoPrecompileError,
        storage::{StorageCtx, hashmap::HashMapStorageProvider},
        test_util::{VIRTUAL_MASTER, register_virtual_master},
    };
    use alloy::primitives::{Address, U256};
    use tempo_chainspec::hardfork::TempoHardfork;

    #[test]
    fn test_resolve() -> eyre::Result<()> {
        // direct (non-virtual)
        let addr = Address::repeat_byte(0x11);
        assert_eq!(
            Recipient::direct(addr),
            Recipient {
                target: addr,
                virtual_addr: None
            }
        );

        // T3: non-virtual → direct
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T3);
        StorageCtx::enter(&mut storage, || {
            let r = Recipient::resolve(addr)?;
            assert_eq!(
                r,
                Recipient {
                    target: addr,
                    virtual_addr: None
                }
            );

            // T3: registered virtual → master
            let mut registry = AddressRegistry::new();
            let (_, virtual_addr) = register_virtual_master(&mut registry)?;
            let r = Recipient::resolve(virtual_addr)?;
            assert_eq!(
                r,
                Recipient {
                    target: VIRTUAL_MASTER,
                    virtual_addr: Some(virtual_addr)
                }
            );

            // T3: unregistered virtual → error
            let unregistered = Address::new_virtual(MasterId::ZERO, UserTag::ZERO);
            assert!(Recipient::resolve(unregistered).is_err());

            Ok::<_, TempoPrecompileError>(())
        })?;

        // Pre-T3: virtual address passed through as literal
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T2);
        StorageCtx::enter(&mut storage, || {
            let virtual_addr = Address::new_virtual(MasterId::ZERO, UserTag::ZERO);
            let r = Recipient::resolve(virtual_addr)?;
            assert_eq!(
                r,
                Recipient {
                    target: virtual_addr,
                    virtual_addr: None
                }
            );
            Ok::<_, TempoPrecompileError>(())
        })?;
        Ok(())
    }

    #[test]
    fn test_validate() {
        assert!(Recipient::direct(Address::ZERO).validate().is_err());
        assert!(
            Recipient::direct(crate::PATH_USD_ADDRESS)
                .validate()
                .is_err()
        );
        assert!(
            Recipient::direct(Address::repeat_byte(0x11))
                .validate()
                .is_ok()
        );
    }

    #[test]
    fn test_build_events() {
        let from = Address::repeat_byte(0x01);
        let target = Address::repeat_byte(0x02);
        let vaddr = Address::repeat_byte(0x03);
        let amount = U256::from(42);

        let direct = Recipient::direct(target);
        let virt = Recipient {
            target,
            virtual_addr: Some(vaddr),
        };

        // transfer event uses virtual_addr when present, target otherwise
        assert!(matches!(direct.build_transfer_event(from, amount),
            TIP20Event::Transfer(ITIP20::Transfer { to, .. }) if to == target));
        assert!(matches!(virt.build_transfer_event(from, amount),
            TIP20Event::Transfer(ITIP20::Transfer { to, .. }) if to == vaddr));

        // virtual transfer event: None for direct, Some(virtual→master) for virtual
        assert!(direct.build_virtual_transfer_event(amount).is_none());
        let hop = virt.build_virtual_transfer_event(amount).unwrap();
        assert!(matches!(hop,
            TIP20Event::Transfer(ITIP20::Transfer { from, to, .. })
            if from == vaddr && to == target));
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use crate::{
        PATH_USD_ADDRESS,
        account_keychain::{
            AccountKeychain, KeyRestrictions, SignatureType, TokenLimit, getRemainingLimitCall,
        },
        address_registry::{AddressRegistry, MasterId, UserTag},
        error::TempoPrecompileError,
        receive_policy_guard::ReceivePolicyGuard,
        storage::{StorageCtx, hashmap::HashMapStorageProvider},
        test_util::{TIP20Setup, VIRTUAL_MASTER, register_virtual_master, setup_storage},
        tip403_registry::REJECT_ALL_POLICY_ID,
    };
    use alloy::primitives::{Address, FixedBytes, IntoLogData, U256, hex};
    use rand_08::{Rng, distributions::Alphanumeric, thread_rng};
    use tempo_chainspec::hardfork::TempoHardfork;
    use tempo_contracts::precompiles::{
        IReceivePolicyGuard, ReceivePolicyGuardEvent, createTokenCall,
    };

    #[test]
    fn test_mint_increases_balance_and_supply() -> eyre::Result<()> {
        let (mut storage, admin) = setup_storage();
        let addr = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .clear_events()
                .apply()?;

            token.mint(admin, ITIP20::mintCall { to: addr, amount })?;

            assert_eq!(token.get_balance(addr)?, amount);
            assert_eq!(token.total_supply()?, amount);

            token.assert_emitted_events(vec![
                TIP20Event::transfer(Address::ZERO, addr, amount),
                TIP20Event::mint(addr, amount),
            ]);

            Ok(())
        })
    }

    #[test]
    fn test_transfer_moves_balance() -> eyre::Result<()> {
        let (mut storage, admin) = setup_storage();
        let from = Address::random();
        let to = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(from, amount)
                .clear_events()
                .apply()?;

            token.transfer(from, ITIP20::transferCall { to, amount })?;

            assert_eq!(token.get_balance(from)?, U256::ZERO);
            assert_eq!(token.get_balance(to)?, amount);
            assert_eq!(token.total_supply()?, amount); // Supply unchanged

            token.assert_emitted_events(vec![TIP20Event::transfer(from, to, amount)]);

            Ok(())
        })
    }

    mod tip1028_tests {
        use super::*;
        use crate::{
            receive_policy_guard::BLOCKED_RECEIPT_VERSION, tip403_registry::ALLOW_ALL_POLICY_ID,
        };

        const BLOCKED_AT: u64 = 1_728_100;

        fn set_receive_policy(
            receiver: Address,
            sender_policy_id: u64,
            token_filter_id: u64,
            recovery_address: Address,
        ) -> Result<()> {
            TIP403Registry::new().set_receive_policy(
                receiver,
                ITIP403Registry::setReceivePolicyCall {
                    senderPolicyId: sender_policy_id,
                    tokenFilterId: token_filter_id,
                    recoveryAuthority: recovery_address,
                },
            )
        }

        #[test]
        fn test_transfer_blocked_by_receive_policy_guards_funds() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let sender = Address::random();
            let receiver = Address::random();
            let amount = U256::from(100u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount)
                    .clear_events()
                    .apply()?;
                set_receive_policy(
                    receiver,
                    REJECT_ALL_POLICY_ID,
                    ALLOW_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                token.transfer(
                    sender,
                    ITIP20::transferCall {
                        to: receiver,
                        amount,
                    },
                )?;

                assert_eq!(token.get_balance(sender)?, U256::ZERO);
                assert_eq!(token.get_balance(receiver)?, U256::ZERO);
                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, amount);
                token.assert_emitted_events(vec![TIP20Event::Transfer(ITIP20::Transfer {
                    from: sender,
                    to: RECEIVE_POLICY_GUARD_ADDRESS,
                    amount,
                })]);

                let receipt = IReceivePolicyGuard::ClaimReceiptV1::new(
                    token.address,
                    Address::ZERO,
                    sender,
                    receiver,
                    BLOCKED_AT,
                    1,
                    ITIP403Registry::BlockedReason::RECEIVE_POLICY as u8,
                    InboundKind::TRANSFER,
                    B256::ZERO,
                );
                let guard = ReceivePolicyGuard::new();
                assert_eq!(guard.balance_of(receipt.abi_encode().into())?, amount);
                guard.assert_emitted_events(vec![ReceivePolicyGuardEvent::TransferBlocked(
                    IReceivePolicyGuard::TransferBlocked {
                        token: token.address,
                        receiver,
                        blockedNonce: 1,
                        receiptVersion: BLOCKED_RECEIPT_VERSION,
                        amount,
                        receipt: receipt.abi_encode().into(),
                    },
                )]);

                Ok(())
            })
        }

        #[test]
        #[rustfmt::skip]
        fn test_release_blocked_funds_receive_policy_paths() -> eyre::Result<()> {
            let admin = Address::random();
            let originator = Address::random();
            let receiver = Address::random();
            let third_party = Address::random();
            let open_destination = Address::random();
            let blocked_destination = Address::random();
            let amount = U256::from(10u64);

            for (mode, recovery_auth, destination, destination_policy_blocks, should_succeed) in [
                // Receiver recovery back to the receiver is a resume: it skips receive-policy
                // validation, so the original blocking policy does not deadlock the claim.
                (RecoveryMode::Receiver, receiver, receiver, true, true),
                // Receiver and originator reroutes re-check the destination receive policy.
                (RecoveryMode::Receiver, receiver, blocked_destination, true, false),
                (RecoveryMode::Originator, originator, blocked_destination, true, false),
                (RecoveryMode::Originator, originator, originator, false, true),
                // Third-party recovery back to the receiver is also a resume: the receiver selected
                // that authority, so the claim skips receive-policy validation like receiver recovery.
                (RecoveryMode::ThirdParty, third_party, receiver, true, true),
                (RecoveryMode::ThirdParty, third_party, open_destination, false, true),
            ] {
                let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
                StorageCtx::enter(&mut storage, || {
                    let mut token = TIP20Setup::create("Test", "TST", admin)
                        .with_issuer(admin)
                        .apply()?;
                    token.set_balance(RECEIVE_POLICY_GUARD_ADDRESS, amount)?;

                    set_receive_policy(
                        receiver,
                        REJECT_ALL_POLICY_ID,
                        ALLOW_ALL_POLICY_ID,
                        Address::ZERO,
                    )?;
                    if destination_policy_blocks && destination != receiver {
                        set_receive_policy(
                            destination,
                            REJECT_ALL_POLICY_ID,
                            ALLOW_ALL_POLICY_ID,
                            Address::ZERO,
                        )?;
                    }

                    let result = token.release_blocked_funds(
                        originator,
                        receiver,
                        destination,
                        amount,
                        mode,
                        recovery_auth,
                    );

                    if should_succeed {
                        result?;
                        assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, U256::ZERO);
                        assert_eq!(token.get_balance(destination)?, amount);
                    } else {
                        assert_eq!(result.unwrap_err(), TIP20Error::policy_forbids().into());
                        assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, amount);
                        assert_eq!(token.get_balance(destination)?, U256::ZERO);
                    }

                    Ok::<(), TempoPrecompileError>(())
                })?;
            }

            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            StorageCtx::enter(&mut storage, || {
                let mut registry = TIP403Registry::new();
                let recipient_policy = registry.create_policy_with_accounts(
                    admin,
                    ITIP403Registry::createPolicyWithAccountsCall {
                        admin,
                        policyType: ITIP403Registry::PolicyType::WHITELIST,
                        accounts: vec![receiver],
                    },
                )?;
                let transfer_policy = registry.create_compound_policy(
                    admin,
                    ITIP403Registry::createCompoundPolicyCall {
                        senderPolicyId: REJECT_ALL_POLICY_ID,
                        recipientPolicyId: recipient_policy,
                        mintRecipientPolicyId: ALLOW_ALL_POLICY_ID,
                    },
                )?;

                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .apply()?;
                token.change_transfer_policy_id(
                    admin,
                    ITIP20::changeTransferPolicyIdCall {
                        newPolicyId: transfer_policy,
                    },
                )?;
                token.set_balance(RECEIVE_POLICY_GUARD_ADDRESS, amount)?;

                // A third-party claim back to the receiver is a resume. It requires the receiver
                // to be authorized as recipient, but must not require the receiver/policy subject
                // to be authorized as sender.
                token.release_blocked_funds(
                    originator,
                    receiver,
                    receiver,
                    amount,
                    RecoveryMode::ThirdParty,
                    third_party,
                )?;

                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, U256::ZERO);
                assert_eq!(token.get_balance(receiver)?, amount);

                Ok::<(), TempoPrecompileError>(())
            })?;

            Ok(())
        }

        #[test]
        fn test_transfer_blocked_by_token_filter_records_reason() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let sender = Address::random();
            let receiver = Address::random();
            let amount = U256::from(40u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount)
                    .apply()?;
                set_receive_policy(
                    receiver,
                    ALLOW_ALL_POLICY_ID,
                    REJECT_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                token.transfer(
                    sender,
                    ITIP20::transferCall {
                        to: receiver,
                        amount,
                    },
                )?;

                let receipt = IReceivePolicyGuard::ClaimReceiptV1::new(
                    token.address,
                    Address::ZERO,
                    sender,
                    receiver,
                    BLOCKED_AT,
                    1,
                    ITIP403Registry::BlockedReason::TOKEN_FILTER as u8,
                    InboundKind::TRANSFER,
                    B256::ZERO,
                );
                let guard = ReceivePolicyGuard::new();
                assert_eq!(guard.balance_of(receipt.abi_encode().into())?, amount);
                guard.assert_emitted_events(vec![ReceivePolicyGuardEvent::TransferBlocked(
                    IReceivePolicyGuard::TransferBlocked {
                        token: token.address,
                        receiver,
                        blockedNonce: 1,
                        receiptVersion: BLOCKED_RECEIPT_VERSION,
                        amount,
                        receipt: receipt.abi_encode().into(),
                    },
                )]);

                Ok(())
            })
        }

        #[test]
        fn test_transfer_to_guard_address_rejects() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            let admin = Address::random();
            let sender = Address::random();
            let amount = U256::from(10u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount)
                    .apply()?;

                let result = token.transfer(
                    sender,
                    ITIP20::transferCall {
                        to: RECEIVE_POLICY_GUARD_ADDRESS,
                        amount,
                    },
                );
                assert!(matches!(
                    result,
                    Err(e) if e == ReceivePolicyGuardError::address_reserved().into()
                ));
                assert_eq!(token.get_balance(sender)?, amount);
                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, U256::ZERO);

                Ok(())
            })
        }

        #[test]
        fn test_pre_t6_receive_policy_does_not_guard() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T5);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let sender = Address::random();
            let receiver = Address::random();
            let amount = U256::from(25u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount)
                    .clear_events()
                    .apply()?;
                set_receive_policy(
                    receiver,
                    REJECT_ALL_POLICY_ID,
                    ALLOW_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                token.transfer(
                    sender,
                    ITIP20::transferCall {
                        to: receiver,
                        amount,
                    },
                )?;

                assert_eq!(token.get_balance(sender)?, U256::ZERO);
                assert_eq!(token.get_balance(receiver)?, amount);
                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, U256::ZERO);
                token.assert_emitted_events(vec![TIP20Event::Transfer(ITIP20::Transfer {
                    from: sender,
                    to: receiver,
                    amount,
                })]);
                let receipt = IReceivePolicyGuard::ClaimReceiptV1::new(
                    token.address,
                    sender,
                    sender,
                    receiver,
                    BLOCKED_AT,
                    1,
                    ITIP403Registry::BlockedReason::RECEIVE_POLICY as u8,
                    InboundKind::TRANSFER,
                    B256::ZERO,
                );
                assert_eq!(
                    ReceivePolicyGuard::new().balance_of(receipt.abi_encode().into())?,
                    U256::ZERO
                );

                Ok(())
            })
        }

        #[test]
        fn test_transfer_from_blocked_consumes_allowance() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let owner = Address::random();
            let spender = Address::random();
            let receiver = Address::random();
            let amount = U256::from(30u64);
            let allowance = amount + U256::from(5u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(owner, amount)
                    .with_approval(owner, spender, allowance)
                    .apply()?;
                set_receive_policy(
                    receiver,
                    REJECT_ALL_POLICY_ID,
                    ALLOW_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                token.transfer_from(
                    spender,
                    ITIP20::transferFromCall {
                        from: owner,
                        to: receiver,
                        amount,
                    },
                )?;

                assert_eq!(
                    token.allowance(ITIP20::allowanceCall { owner, spender })?,
                    allowance - amount
                );
                assert_eq!(token.get_balance(owner)?, U256::ZERO);
                assert_eq!(token.get_balance(receiver)?, U256::ZERO);
                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, amount);

                Ok(())
            })
        }

        #[test]
        fn test_transfer_with_memo_blocked_preserves_memo() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let sender = Address::random();
            let receiver = Address::random();
            let amount = U256::from(55u64);
            let memo = B256::repeat_byte(0xab);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount)
                    .clear_events()
                    .apply()?;
                set_receive_policy(
                    receiver,
                    REJECT_ALL_POLICY_ID,
                    ALLOW_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                token.transfer_with_memo(
                    sender,
                    ITIP20::transferWithMemoCall {
                        to: receiver,
                        amount,
                        memo,
                    },
                )?;

                token.assert_emitted_events(vec![TIP20Event::Transfer(ITIP20::Transfer {
                    from: sender,
                    to: RECEIVE_POLICY_GUARD_ADDRESS,
                    amount,
                })]);
                let receipt = IReceivePolicyGuard::ClaimReceiptV1::new(
                    token.address,
                    Address::ZERO,
                    sender,
                    receiver,
                    BLOCKED_AT,
                    1,
                    ITIP403Registry::BlockedReason::RECEIVE_POLICY as u8,
                    InboundKind::TRANSFER,
                    memo,
                );
                assert_eq!(
                    ReceivePolicyGuard::new().balance_of(receipt.abi_encode().into())?,
                    amount
                );

                Ok(())
            })
        }

        #[test]
        fn test_mint_blocked_credits_guard() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
            storage.set_timestamp(U256::from(BLOCKED_AT));
            let admin = Address::random();
            let receiver = Address::random();
            let amount = U256::from(70u64);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .clear_events()
                    .apply()?;
                set_receive_policy(
                    receiver,
                    REJECT_ALL_POLICY_ID,
                    ALLOW_ALL_POLICY_ID,
                    Address::ZERO,
                )?;

                let mut guard = ReceivePolicyGuard::new();
                guard.clear_emitted_events();
                token.mint(
                    admin,
                    ITIP20::mintCall {
                        to: receiver,
                        amount,
                    },
                )?;

                assert_eq!(token.total_supply()?, amount);
                assert_eq!(token.get_balance(receiver)?, U256::ZERO);
                assert_eq!(token.get_balance(RECEIVE_POLICY_GUARD_ADDRESS)?, amount);
                token.assert_emitted_events(vec![
                    TIP20Event::transfer(Address::ZERO, RECEIVE_POLICY_GUARD_ADDRESS, amount),
                    TIP20Event::mint(RECEIVE_POLICY_GUARD_ADDRESS, amount),
                ]);
                let receipt = IReceivePolicyGuard::ClaimReceiptV1::new(
                    token.address,
                    Address::ZERO,
                    admin,
                    receiver,
                    BLOCKED_AT,
                    1,
                    ITIP403Registry::BlockedReason::RECEIVE_POLICY as u8,
                    InboundKind::MINT,
                    B256::ZERO,
                );
                guard.assert_emitted_events(vec![ReceivePolicyGuardEvent::TransferBlocked(
                    IReceivePolicyGuard::TransferBlocked {
                        token: token.address,
                        receiver,
                        blockedNonce: 1,
                        receiptVersion: BLOCKED_RECEIPT_VERSION,
                        amount,
                        receipt: receipt.abi_encode().into(),
                    },
                )]);
                assert_eq!(guard.balance_of(receipt.abi_encode().into())?, amount);

                Ok(())
            })
        }
    }

    #[test]
    fn test_transfer_insufficient_balance_fails() -> eyre::Result<()> {
        let (mut storage, admin) = setup_storage();
        let from = Address::random();
        let to = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            let result = token.transfer(from, ITIP20::transferCall { to, amount });
            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::InsufficientBalance(_)
                ))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_mint_with_memo() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);
        let to = Address::random();
        let memo = FixedBytes::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .clear_events()
                .apply()?;

            token.mint_with_memo(admin, ITIP20::mintWithMemoCall { to, amount, memo })?;

            // TransferWithMemo event should have Address::ZERO as from for mint
            token.assert_emitted_events(vec![
                TIP20Event::transfer(Address::ZERO, to, amount),
                TIP20Event::transfer_with_memo(Address::ZERO, to, amount, memo),
                TIP20Event::mint(to, amount),
            ]);

            Ok(())
        })
    }

    #[test]
    fn test_burn_with_memo() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);
        let memo = FixedBytes::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(admin, amount)
                .clear_events()
                .apply()?;

            token.burn_with_memo(admin, ITIP20::burnWithMemoCall { amount, memo })?;
            token.assert_emitted_events(vec![
                TIP20Event::transfer(admin, Address::ZERO, amount),
                TIP20Event::transfer_with_memo(admin, Address::ZERO, amount, memo),
                TIP20Event::burn(admin, amount),
            ]);

            Ok(())
        })
    }

    #[test]
    fn test_transfer_from_with_memo_from_address() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let owner = Address::random();
        let spender = Address::random();
        let to = Address::random();
        let memo = FixedBytes::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(owner, amount)
                .with_approval(owner, spender, amount)
                .clear_events()
                .apply()?;

            token.transfer_from_with_memo(
                spender,
                ITIP20::transferFromWithMemoCall {
                    from: owner,
                    to,
                    amount,
                    memo,
                },
            )?;

            // TransferWithMemo event should have use call.from in transfer event
            token.assert_emitted_events(vec![
                TIP20Event::transfer(owner, to, amount),
                TIP20Event::transfer_with_memo(owner, to, amount, memo),
            ]);

            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_pre_tx() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let amount = U256::from(100);
        let fee_amount = amount / U256::from(2);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(user, amount)
                .apply()?;

            token.transfer_fee_pre_tx(user, fee_amount)?;

            assert_eq!(token.get_balance(user)?, fee_amount);
            assert_eq!(token.get_balance(TIP_FEE_MANAGER_ADDRESS)?, fee_amount);

            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_pre_tx_insufficient_balance() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let amount = U256::from(100);
        let fee_amount = amount / U256::from(2);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .apply()?;

            assert_eq!(
                token.transfer_fee_pre_tx(user, fee_amount),
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::insufficient_balance(U256::ZERO, fee_amount, token.address)
                ))
            );
            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_pre_tx_fee_manager_overflow() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let fee_amount = U256::ONE;

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(user, fee_amount)
                .apply()?;
            token.set_balance(TIP_FEE_MANAGER_ADDRESS, U256::MAX)?;

            assert_eq!(
                token.transfer_fee_pre_tx(user, fee_amount),
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::supply_cap_exceeded()
                ))
            );
            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_pre_tx_paused() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let amount = U256::from(100);
        let fee_amount = amount / U256::from(2);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_role(admin, *PAUSE_ROLE)
                .with_mint(user, amount)
                .apply()?;

            // Pause the token
            token.pause(admin, ITIP20::pauseCall {})?;

            // transfer_fee_pre_tx should fail when paused
            assert_eq!(
                token.transfer_fee_pre_tx(user, fee_amount),
                Err(TempoPrecompileError::TIP20(TIP20Error::contract_paused()))
            );
            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_post_tx() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let initial_fee = U256::from(100);
        let refund_amount = U256::from(30);
        let gas_used = U256::from(10);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(TIP_FEE_MANAGER_ADDRESS, initial_fee)
                .apply()?;

            token.transfer_fee_post_tx(user, refund_amount, gas_used)?;

            assert_eq!(token.get_balance(user)?, refund_amount);
            assert_eq!(
                token.get_balance(TIP_FEE_MANAGER_ADDRESS)?,
                initial_fee - refund_amount
            );
            assert_eq!(
                token.emitted_events().last().unwrap(),
                &TIP20Event::transfer(user, TIP_FEE_MANAGER_ADDRESS, gas_used).into_log_data()
            );

            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_post_tx_insufficient_fee_manager_balance() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let initial_fee = U256::from(10);
        let refund_amount = U256::from(30);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(TIP_FEE_MANAGER_ADDRESS, initial_fee)
                .apply()?;

            assert_eq!(
                token.transfer_fee_post_tx(user, refund_amount, U256::ZERO),
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::insufficient_balance(initial_fee, refund_amount, token.address)
                ))
            );

            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_post_tx_recipient_overflow() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let user = Address::random();
        let refund_amount = U256::ONE;

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .apply()?;
            token.set_balance(TIP_FEE_MANAGER_ADDRESS, refund_amount)?;
            token.set_balance(user, U256::MAX)?;

            assert_eq!(
                token.transfer_fee_post_tx(user, refund_amount, U256::ZERO),
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::supply_cap_exceeded()
                ))
            );
            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_post_tx_refunds_spending_limit() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T1C);
        let admin = Address::random();
        let user = Address::random();
        let access_key = Address::random();
        let max_fee = U256::from(1000);
        let refund_amount = U256::from(300);
        let gas_used = U256::from(100);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(TIP_FEE_MANAGER_ADDRESS, max_fee)
                .apply()?;

            let token_address = token.address;
            let spending_limit = U256::from(2000);

            // Set up keychain: authorize an access key with a spending limit
            let mut keychain = AccountKeychain::new();
            keychain.initialize()?;
            keychain.set_transaction_key(Address::ZERO)?;

            keychain.authorize_key(
                user,
                access_key,
                SignatureType::Secp256k1,
                KeyRestrictions {
                    expiry: u64::MAX,
                    enforceLimits: true,
                    limits: vec![TokenLimit {
                        token: token_address,
                        amount: spending_limit,
                        period: 0,
                    }],
                    allowAnyCalls: true,
                    allowedCalls: vec![],
                },
                None,
            )?;

            // Simulate pre-tx: access key deducts max fee from spending limit
            keychain.set_transaction_key(access_key)?;
            keychain.set_tx_origin(user)?;
            keychain.authorize_transfer(user, token_address, max_fee)?;

            let remaining_after_deduction =
                keychain.get_remaining_limit(getRemainingLimitCall {
                    account: user,
                    keyId: access_key,
                    token: token_address,
                })?;
            assert_eq!(remaining_after_deduction, spending_limit - max_fee);

            // Call transfer_fee_post_tx — should refund the spending limit via is_t1c() gate
            token.transfer_fee_post_tx(user, refund_amount, gas_used)?;

            let remaining_after_refund = keychain.get_remaining_limit(getRemainingLimitCall {
                account: user,
                keyId: access_key,
                token: token_address,
            })?;
            assert_eq!(
                remaining_after_refund,
                spending_limit - max_fee + refund_amount,
                "spending limit should be restored by refund amount"
            );

            Ok(())
        })
    }

    #[test]
    fn test_transfer_fee_post_tx_pre_t1c() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T1B);
        let admin = Address::random();
        let user = Address::random();
        let access_key = Address::random();
        let max_fee = U256::from(1000);
        let refund_amount = U256::from(300);
        let gas_used = U256::from(100);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(TIP_FEE_MANAGER_ADDRESS, max_fee)
                .apply()?;

            let token_address = token.address;
            let spending_limit = U256::from(2000);

            let mut keychain = AccountKeychain::new();
            keychain.initialize()?;
            keychain.set_transaction_key(Address::ZERO)?;

            keychain.authorize_key(
                user,
                access_key,
                SignatureType::Secp256k1,
                KeyRestrictions {
                    expiry: u64::MAX,
                    enforceLimits: true,
                    limits: vec![TokenLimit {
                        token: token_address,
                        amount: spending_limit,
                        period: 0,
                    }],
                    allowAnyCalls: true,
                    allowedCalls: vec![],
                },
                None,
            )?;

            keychain.set_transaction_key(access_key)?;
            keychain.set_tx_origin(user)?;
            keychain.authorize_transfer(user, token_address, max_fee)?;

            let remaining_after_deduction =
                keychain.get_remaining_limit(getRemainingLimitCall {
                    account: user,
                    keyId: access_key,
                    token: token_address,
                })?;
            assert_eq!(remaining_after_deduction, spending_limit - max_fee);

            token.transfer_fee_post_tx(user, refund_amount, gas_used)?;

            // spending limit unchanged pre-t1c
            let remaining_after_refund = keychain.get_remaining_limit(getRemainingLimitCall {
                account: user,
                keyId: access_key,
                token: token_address,
            })?;
            assert_eq!(remaining_after_refund, spending_limit - max_fee);

            Ok(())
        })
    }

    #[test]
    fn test_transfer_from_insufficient_allowance() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let from = Address::random();
        let spender = Address::random();
        let to = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(from, amount)
                .apply()?;

            assert!(matches!(
                token.transfer_from(spender, ITIP20::transferFromCall { from, to, amount }),
                Err(TempoPrecompileError::TIP20(
                    TIP20Error::InsufficientAllowance(_)
                ))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_system_transfer_from() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let from = Address::random();
        let to = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(from, amount)
                .apply()?;

            // Pre-T5: caller is unchecked (preserves pre-TIP-1035 FeeAMM behavior).
            assert!(token.system_transfer_from(to, from, amount).is_ok());
            assert_eq!(
                token.emitted_events().last().unwrap(),
                &TIP20Event::transfer(from, to, amount).into_log_data()
            );

            Ok(())
        })
    }

    #[test]
    fn test_system_transfer_from_t5_authorized() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T5);
        let admin = Address::random();
        let from = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(from, amount)
                .apply()?;

            // Listed precompile is allowed to invoke `system_transfer_from`.
            assert!(
                token
                    .system_transfer_from(TIP_FEE_MANAGER_ADDRESS, from, amount)
                    .is_ok()
            );

            Ok(())
        })
    }

    #[test]
    fn test_system_transfer_from_t5_unauthorized_reverts() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T5);
        let admin = Address::random();
        let unlisted = Address::random();
        let from = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(from, amount)
                .apply()?;

            // Unlisted callers are rejected with `Unauthorized` at T5+.
            assert!(matches!(
                token.system_transfer_from(unlisted, from, amount),
                Err(TempoPrecompileError::TIP20(TIP20Error::Unauthorized(_)))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_initialize_sets_next_quote_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // Verify both quoteToken and nextQuoteToken are set to the same value
            assert_eq!(token.quote_token()?, PATH_USD_ADDRESS);
            assert_eq!(token.next_quote_token()?, PATH_USD_ADDRESS);

            Ok(())
        })
    }

    #[test]
    fn test_update_quote_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // Create a new USD token to use as the new quote token
            let new_quote_token = TIP20Setup::create("New Quote", "NQ", admin).apply()?;
            let new_quote_token_address = new_quote_token.address;

            // Verify initial quote token is PATH_USD
            assert_eq!(token.quote_token()?, PATH_USD_ADDRESS);

            // Set next quote token to the new token
            token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: new_quote_token_address,
                },
            )?;

            // Verify next quote token was set to the new token
            assert_eq!(token.next_quote_token()?, new_quote_token_address);

            // Verify event was emitted
            assert_eq!(
                token.emitted_events().last().unwrap(),
                &TIP20Event::next_quote_token_set(admin, new_quote_token_address).into_log_data()
            );

            Ok(())
        })
    }

    #[test]
    fn test_update_quote_token_requires_admin() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let non_admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // Use the token's own quote token for the test
            let quote_token_address = token.quote_token()?;

            // Try to set next quote token as non-admin
            let result = token.set_next_quote_token(
                non_admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: quote_token_address,
                },
            );

            assert!(matches!(
                result,
                Err(TempoPrecompileError::RolesAuthError(
                    RolesAuthError::Unauthorized(_)
                ))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_update_quote_token_rejects_non_tip20() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // Try to set a non-TIP20 address (random address that doesn't match TIP20 pattern)
            let non_tip20_address = Address::random();
            let result = token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: non_tip20_address,
                },
            );

            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::InvalidQuoteToken(
                    _
                )))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_update_quote_token_rejects_undeployed_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // Try to set a TIP20 address that hasn't been deployed yet
            // This has the correct TIP20 address pattern but hasn't been created
            let undeployed_token_address =
                Address::from(hex!("20C0000000000000000000000000000000000999"));
            let result = token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: undeployed_token_address,
                },
            );

            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::InvalidQuoteToken(
                    _
                )))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_finalize_quote_token_update() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
            let quote_token_address = token.quote_token()?;

            // Set next quote token
            token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: quote_token_address,
                },
            )?;

            // Complete the update
            token.complete_quote_token_update(admin, ITIP20::completeQuoteTokenUpdateCall {})?;

            // Verify quote token was updated
            assert_eq!(token.quote_token()?, quote_token_address);

            // Verify event was emitted
            assert_eq!(
                token.emitted_events().last().unwrap(),
                &TIP20Event::quote_token_update(admin, quote_token_address).into_log_data()
            );

            Ok(())
        })
    }

    #[test]
    fn test_finalize_quote_token_update_detects_loop() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            // Create token_b first (links to LINKING_USD)
            let mut token_b = TIP20Setup::create("Token B", "TKB", admin).apply()?;
            // Create token_a (links to token_b)
            let token_a = TIP20Setup::create("Token A", "TKA", admin)
                .quote_token(token_b.address)
                .apply()?;

            // Now try to set token_a as the next quote token for token_b (would create A -> B -> A loop)
            token_b.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: token_a.address,
                },
            )?;

            // Try to complete the update - should fail due to loop detection
            let result =
                token_b.complete_quote_token_update(admin, ITIP20::completeQuoteTokenUpdateCall {});

            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::InvalidQuoteToken(
                    _
                )))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_finalize_quote_token_update_requires_admin() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let non_admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
            let quote_token_address = token.quote_token()?;

            // Set next quote token as admin
            token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: quote_token_address,
                },
            )?;

            // Try to complete update as non-admin
            let result = token
                .complete_quote_token_update(non_admin, ITIP20::completeQuoteTokenUpdateCall {});

            assert!(matches!(
                result,
                Err(TempoPrecompileError::RolesAuthError(
                    RolesAuthError::Unauthorized(_)
                ))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_arbitrary_currency() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            for _ in 0..50 {
                let currency: String = thread_rng()
                    .sample_iter(&Alphanumeric)
                    .take(31)
                    .map(char::from)
                    .collect();

                // Initialize token with the random currency
                let token = TIP20Setup::create("Test", "TST", admin)
                    .currency(&currency)
                    .apply()?;

                // Verify the currency was stored and can be retrieved correctly
                let stored_currency = token.currency()?;
                assert_eq!(stored_currency, currency,);
            }

            Ok(())
        })
    }

    #[test]
    fn test_validate_logo_uri() {
        const MAX: usize = TIP20Token::MAX_LOGO_URI_BYTES;

        // Valid: empty, all allowlisted schemes (case-insensitive), and exactly at the 256-byte cap.
        let prefix = "https://example.com/";
        let at_cap = format!("{prefix}{}", "a".repeat(MAX - prefix.len()));
        assert_eq!(at_cap.len(), MAX);
        for ok in [
            "",
            "https://example.com/icon.svg",
            "http://example.com/icon.png",
            "ipfs://QmXfzKRvjZz3u5JRgC4v5mGVbm9ahrUiB4DgzHBsnWbTMM",
            "data:image/svg+xml;base64,PHN2Zy8+",
            "HTTPS://example.com/ICON.svg",
            "IPFS://Qm123",
            &at_cap,
        ] {
            assert!(
                TIP20Token::validate_logo_uri(ok).is_ok(),
                "expected Ok for {ok:?}"
            );
        }

        // 257 bytes — one over the limit. Use a syntactically valid URI so
        // we exercise the length check, not the URI/scheme check.
        let too_long = format!("{prefix}{}", "a".repeat(MAX + 1 - prefix.len()));
        assert_eq!(too_long.len(), MAX + 1);
        assert!(matches!(
            TIP20Token::validate_logo_uri(&too_long),
            Err(TempoPrecompileError::TIP20(TIP20Error::LogoURITooLong(_))),
        ));

        // Disallowed schemes and malformed URIs
        for bad in [
            "javascript:alert(1)",
            "file:///etc/passwd",
            "ftp://x.test/icon.png",
            "no-scheme-here",
            "://missing-scheme.test",
            "1https://digit-leading.test",
            ":empty-scheme",
            " https://leading-space.test",
        ] {
            assert!(
                matches!(
                    TIP20Token::validate_logo_uri(bad),
                    Err(TempoPrecompileError::TIP20(TIP20Error::InvalidLogoURI(_))),
                ),
                "expected InvalidLogoURI for {bad:?}"
            );
        }
    }

    #[test]
    fn test_set_logo_uri_non_admin_reverts() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let non_admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            let result = token.set_logo_uri(
                non_admin,
                ITIP20::setLogoURICall {
                    newLogoURI: "https://example.com/icon.svg".to_string(),
                },
            );

            assert!(matches!(
                result,
                Err(TempoPrecompileError::RolesAuthError(
                    RolesAuthError::Unauthorized(_)
                ))
            ));

            // logoURI should remain unchanged (empty)
            assert_eq!(token.logo_uri()?, "");

            Ok(())
        })
    }

    #[test]
    fn test_set_logo_uri_too_long_reverts() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            // 257 bytes — one over the limit. Use a syntactically valid URI
            // so we exercise the length check, not the URI/scheme check.
            let prefix = "https://example.com/";
            let too_long = format!("{prefix}{}", "a".repeat(257 - prefix.len()));
            assert_eq!(too_long.len(), 257);
            let result = token.set_logo_uri(
                admin,
                ITIP20::setLogoURICall {
                    newLogoURI: too_long,
                },
            );

            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::LogoURITooLong(_)))
            ));

            // 256 bytes — at the limit, should succeed
            let at_limit = format!("{prefix}{}", "a".repeat(256 - prefix.len()));
            assert_eq!(at_limit.len(), 256);
            token.set_logo_uri(
                admin,
                ITIP20::setLogoURICall {
                    newLogoURI: at_limit.clone(),
                },
            )?;
            assert_eq!(token.logo_uri()?, at_limit);

            Ok(())
        })
    }

    #[test]
    fn test_set_logo_uri_writes_and_emits() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .clear_events()
                .apply()?;

            // Default is empty for a freshly-created token.
            assert_eq!(token.logo_uri()?, "");

            let uri = "https://example.com/icon.svg".to_string();
            token.set_logo_uri(
                admin,
                ITIP20::setLogoURICall {
                    newLogoURI: uri.clone(),
                },
            )?;

            assert_eq!(token.logo_uri()?, uri);

            token.assert_emitted_events(vec![TIP20Event::LogoURIUpdated(ITIP20::LogoURIUpdated {
                updater: admin,
                newLogoURI: uri,
            })]);

            Ok(())
        })
    }

    #[test]
    fn test_set_logo_uri_empty_clears() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

            token.set_logo_uri(
                admin,
                ITIP20::setLogoURICall {
                    newLogoURI: "https://example.com/icon.svg".to_string(),
                },
            )?;
            assert_eq!(token.logo_uri()?, "https://example.com/icon.svg");

            // Empty string is still valid (clears the URI per spec).
            token.set_logo_uri(
                admin,
                ITIP20::setLogoURICall {
                    newLogoURI: String::new(),
                },
            )?;
            assert_eq!(token.logo_uri()?, "");

            Ok(())
        })
    }

    #[test]
    fn test_from_address() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            // Test with factory-created token (hash-derived address)
            let token = TIP20Setup::create("Test", "TST", admin).apply()?;
            let via_from_address = TIP20Token::from_address(token.address)?.address;

            assert_eq!(
                via_from_address, token.address,
                "from_address should use the provided address directly"
            );

            // Test with reserved token (pathUSD)
            let _path_usd = TIP20Setup::path_usd(admin).apply()?;
            let via_from_address_reserved = TIP20Token::from_address(PATH_USD_ADDRESS)?.address;

            assert_eq!(
                via_from_address_reserved, PATH_USD_ADDRESS,
                "from_address should work for reserved addresses too"
            );

            Ok(())
        })
    }

    #[test]
    fn test_new_invalid_quote_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let currency: String = thread_rng()
                .sample_iter(&Alphanumeric)
                .take(31)
                .map(char::from)
                .collect();

            let token = TIP20Setup::create("Token", "T", admin)
                .currency(&currency)
                .apply()?;

            // Try to create a new USD token with the arbitrary token as the quote token, this should fail
            TIP20Setup::create("USD Token", "USDT", admin)
                .currency(USD_CURRENCY)
                .quote_token(token.address)
                .expect_tip20_err(TIP20Error::invalid_quote_token());

            Ok(())
        })
    }

    #[test]
    fn test_new_valid_quote_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let usd_token1 = TIP20Setup::create("USD Token", "USDT", admin).apply()?;

            // USD token with USD token as quote
            let _usd_token2 = TIP20Setup::create("USD Token", "USDT", admin)
                .quote_token(usd_token1.address)
                .apply()?;

            // Create non USD token
            let currency_1: String = thread_rng()
                .sample_iter(&Alphanumeric)
                .take(31)
                .map(char::from)
                .collect();

            let token_1 = TIP20Setup::create("USD Token", "USDT", admin)
                .currency(currency_1)
                .apply()?;

            // Create a non USD token with non USD quote token
            let currency_2: String = thread_rng()
                .sample_iter(&Alphanumeric)
                .take(31)
                .map(char::from)
                .collect();

            let _token_2 = TIP20Setup::create("USD Token", "USDT", admin)
                .currency(currency_2)
                .quote_token(token_1.address)
                .apply()?;

            Ok(())
        })
    }

    #[test]
    fn test_update_quote_token_invalid_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let _path_usd = TIP20Setup::path_usd(admin).apply()?;

            let currency: String = thread_rng()
                .sample_iter(&Alphanumeric)
                .take(31)
                .map(char::from)
                .collect();

            let token_1 = TIP20Setup::create("Token 1", "TK1", admin)
                .currency(&currency)
                .apply()?;

            // Create a new USD token
            let mut usd_token = TIP20Setup::create("USD Token", "USDT", admin).apply()?;

            // Try to update the USD token's quote token to the arbitrary currency token, this should fail
            let result = usd_token.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: token_1.address,
                },
            );

            assert!(result.is_err_and(
                |err| err == TempoPrecompileError::TIP20(TIP20Error::invalid_quote_token())
            ));

            Ok(())
        })
    }

    #[test]
    fn test_is_tip20_prefix() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let sender = Address::random();

        StorageCtx::enter(&mut storage, || {
            let _path_usd = TIP20Setup::path_usd(sender).apply()?;

            let created_tip20 = TIP20Factory::new().create_token(
                sender,
                createTokenCall {
                    name: "Test Token".to_string(),
                    symbol: "TEST".to_string(),
                    currency: "USD".to_string(),
                    quoteToken: crate::PATH_USD_ADDRESS,
                    admin: sender,
                    salt: B256::random(),
                },
            )?;
            let non_tip20 = Address::random();

            assert!(PATH_USD_ADDRESS.is_tip20());
            assert!(created_tip20.is_tip20());
            assert!(!non_tip20.is_tip20());
            Ok(())
        })
    }

    #[test]
    fn test_initialize_supply_cap() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let token = TIP20Setup::create("Token", "TKN", admin).apply()?;

            let supply_cap = token.supply_cap()?;
            assert_eq!(supply_cap, U256::from(u128::MAX));

            Ok(())
        })
    }

    #[test]
    fn test_unable_to_burn_blocked_from_protected_address() -> eyre::Result<()> {
        let admin = Address::random();
        let burner = Address::random();
        let amount = (U256::random() % U256::from(u128::MAX)) / U256::from(8);
        let burn_amount = amount / U256::from(2);

        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T6);
        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Token", "TKN", admin)
                .with_issuer(admin)
                .with_role(burner, *BURN_BLOCKED_ROLE)
                .with_mint(TIP_FEE_MANAGER_ADDRESS, amount)
                .with_mint(STABLECOIN_DEX_ADDRESS, amount)
                .with_mint(TIP20_CHANNEL_RESERVE_ADDRESS, amount)
                .apply()?;

            for protected in [
                token.address,
                TIP_FEE_MANAGER_ADDRESS,
                STABLECOIN_DEX_ADDRESS,
                RECEIVE_POLICY_GUARD_ADDRESS,
                TIP20_CHANNEL_RESERVE_ADDRESS,
            ] {
                let result = token.burn_blocked(burner, protected, burn_amount, true);
                assert_eq!(result.unwrap_err(), TIP20Error::protected_address().into());
            }

            for minted in [TIP_FEE_MANAGER_ADDRESS, STABLECOIN_DEX_ADDRESS] {
                let balance = token.balance_of(ITIP20::balanceOfCall { account: minted })?;
                assert_eq!(balance, amount);
            }

            Ok::<_, TempoPrecompileError>(())
        })?;

        // Pre-T6: RECEIVE_POLICY_GUARD_ADDRESS is not yet in PROTECTED, so burn_blocked
        // actually burns from it (REJECT_ALL satisfies the sender-policy gate).
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T5);
        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Token", "TKN", admin)
                .with_issuer(admin)
                .with_role(burner, *BURN_BLOCKED_ROLE)
                .apply()?;

            for protected in [
                token.address,
                TIP_FEE_MANAGER_ADDRESS,
                STABLECOIN_DEX_ADDRESS,
                TIP20_CHANNEL_RESERVE_ADDRESS,
            ] {
                let result = token.burn_blocked(burner, protected, burn_amount, true);
                assert_eq!(result.unwrap_err(), TIP20Error::protected_address().into());
            }

            token.change_transfer_policy_id(
                admin,
                ITIP20::changeTransferPolicyIdCall {
                    newPolicyId: REJECT_ALL_POLICY_ID,
                },
            )?;
            token.set_balance(RECEIVE_POLICY_GUARD_ADDRESS, amount)?;
            token.set_total_supply(token.total_supply()? + amount)?;

            token.burn_blocked(burner, RECEIVE_POLICY_GUARD_ADDRESS, burn_amount, true)?;

            let balance = token.balance_of(ITIP20::balanceOfCall {
                account: RECEIVE_POLICY_GUARD_ADDRESS,
            })?;
            assert_eq!(balance, amount - burn_amount);

            Ok::<_, TempoPrecompileError>(())
        })?;

        // Pre-T5: TIP20_CHANNEL_RESERVE_ADDRESS and TIP20 address are not yet in PROTECTED,
        // so burn_blocked actually burns from it (REJECT_ALL satisfies the sender-policy gate).
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T4);
        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Token", "TKN", admin)
                .with_issuer(admin)
                .with_role(burner, *BURN_BLOCKED_ROLE)
                .with_mint(TIP20_CHANNEL_RESERVE_ADDRESS, amount)
                .apply()?;

            token.change_transfer_policy_id(
                admin,
                ITIP20::changeTransferPolicyIdCall {
                    newPolicyId: REJECT_ALL_POLICY_ID,
                },
            )?;

            // simulate a mint to TIP20 address.
            token.set_balance(token.address, amount)?;
            token.set_total_supply(token.total_supply()? + amount)?;

            for unprotected in [TIP20_CHANNEL_RESERVE_ADDRESS, token.address] {
                token.burn_blocked(burner, unprotected, burn_amount, true)?;

                let balance = token.balance_of(ITIP20::balanceOfCall {
                    account: unprotected,
                })?;
                assert_eq!(balance, amount - burn_amount);
            }

            Ok::<_, TempoPrecompileError>(())
        })?;

        Ok(())
    }

    #[test]
    fn test_initialize_usd_token() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            // USD token with zero quote token should succeed
            let _token = TIP20Setup::create("TestToken", "TEST", admin).apply()?;

            // Non-USD token with zero quote token should succeed
            let eur_token = TIP20Setup::create("EuroToken", "EUR", admin)
                .currency("EUR")
                .apply()?;

            // USD token with non-USD quote token should fail
            TIP20Setup::create("USDToken", "USD", admin)
                .quote_token(eur_token.address)
                .expect_tip20_err(TIP20Error::invalid_quote_token());

            Ok(())
        })
    }

    #[test]
    fn test_change_transfer_policy_id_invalid_policy() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::path_usd(admin).apply()?;

            // Initialize the TIP403 registry
            let mut registry = TIP403Registry::new();
            registry.initialize()?;

            // Try to change to a non-existent policy ID (should fail)
            let invalid_policy_id = 999u64;
            let result = token.change_transfer_policy_id(
                admin,
                ITIP20::changeTransferPolicyIdCall {
                    newPolicyId: invalid_policy_id,
                },
            );

            assert!(matches!(
                result.unwrap_err(),
                TempoPrecompileError::TIP20(TIP20Error::InvalidTransferPolicyId(_))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_transfer_invalid_recipient() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();
        let bob = Address::random();
        let amount = U256::random() % U256::from(u128::MAX);

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Token", "TKN", admin)
                .with_issuer(admin)
                .with_mint(admin, amount)
                .with_approval(admin, bob, amount)
                .apply()?;

            let result = token.transfer(
                admin,
                ITIP20::transferCall {
                    to: Address::ZERO,
                    amount,
                },
            );
            assert!(result.is_err_and(|err| err.to_string().contains("InvalidRecipient")));

            let result = token.transfer_from(
                bob,
                ITIP20::transferFromCall {
                    from: admin,
                    to: Address::ZERO,
                    amount,
                },
            );
            assert!(result.is_err_and(|err| err.to_string().contains("InvalidRecipient")));

            Ok(())
        })
    }

    #[test]
    fn test_change_transfer_policy_id() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::path_usd(admin).apply()?;

            // Initialize the TIP403 registry
            let mut registry = TIP403Registry::new();
            registry.initialize()?;

            // Test special policies 0 and 1 (should always work)
            token.change_transfer_policy_id(
                admin,
                ITIP20::changeTransferPolicyIdCall { newPolicyId: 0 },
            )?;
            assert_eq!(token.transfer_policy_id()?, 0);

            token.change_transfer_policy_id(
                admin,
                ITIP20::changeTransferPolicyIdCall { newPolicyId: 1 },
            )?;
            assert_eq!(token.transfer_policy_id()?, 1);

            // Test random invalid policy IDs should fail
            let mut rng = rand_08::thread_rng();
            for _ in 0..20 {
                let invalid_policy_id = rng.gen_range(2..u64::MAX);
                let result = token.change_transfer_policy_id(
                    admin,
                    ITIP20::changeTransferPolicyIdCall {
                        newPolicyId: invalid_policy_id,
                    },
                );
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::TIP20(TIP20Error::InvalidTransferPolicyId(_))
                ));
            }

            // Create some valid policies
            let mut valid_policy_ids = Vec::new();
            for i in 0..10 {
                let policy_id = registry.create_policy(
                    admin,
                    ITIP403Registry::createPolicyCall {
                        admin,
                        policyType: if i % 2 == 0 {
                            ITIP403Registry::PolicyType::WHITELIST
                        } else {
                            ITIP403Registry::PolicyType::BLACKLIST
                        },
                    },
                )?;
                valid_policy_ids.push(policy_id);
            }

            // Test that all created policies can be set
            for policy_id in valid_policy_ids {
                let result = token.change_transfer_policy_id(
                    admin,
                    ITIP20::changeTransferPolicyIdCall {
                        newPolicyId: policy_id,
                    },
                );
                assert!(result.is_ok());
                assert_eq!(token.transfer_policy_id()?, policy_id);
            }

            Ok(())
        })
    }

    #[test]
    fn test_is_transfer_authorized() -> eyre::Result<()> {
        use tempo_chainspec::hardfork::TempoHardfork;

        let admin = Address::random();
        let sender = Address::random();
        let recipient = Address::random();

        for hardfork in [TempoHardfork::T0, TempoHardfork::T1] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);

            StorageCtx::enter(&mut storage, || {
                let token = TIP20Setup::path_usd(admin).apply()?;

                // Initialize TIP403 registry and create a whitelist policy
                let mut registry = TIP403Registry::new();
                registry.initialize()?;

                let policy_id = registry.create_policy(
                    admin,
                    ITIP403Registry::createPolicyCall {
                        admin,
                        policyType: ITIP403Registry::PolicyType::WHITELIST,
                    },
                )?;

                // Assign token to use this policy
                let mut token = token;
                token.change_transfer_policy_id(
                    admin,
                    ITIP20::changeTransferPolicyIdCall {
                        newPolicyId: policy_id,
                    },
                )?;

                // Sender not whitelisted, recipient whitelisted
                registry.modify_policy_whitelist(
                    admin,
                    ITIP403Registry::modifyPolicyWhitelistCall {
                        policyId: policy_id,
                        account: recipient,
                        allowed: true,
                    },
                )?;
                assert!(!token.is_transfer_authorized(sender, recipient)?);

                // Sender whitelisted, recipient not whitelisted
                registry.modify_policy_whitelist(
                    admin,
                    ITIP403Registry::modifyPolicyWhitelistCall {
                        policyId: policy_id,
                        account: sender,
                        allowed: true,
                    },
                )?;
                registry.modify_policy_whitelist(
                    admin,
                    ITIP403Registry::modifyPolicyWhitelistCall {
                        policyId: policy_id,
                        account: recipient,
                        allowed: false,
                    },
                )?;
                assert!(!token.is_transfer_authorized(sender, recipient)?);

                // Both whitelisted
                registry.modify_policy_whitelist(
                    admin,
                    ITIP403Registry::modifyPolicyWhitelistCall {
                        policyId: policy_id,
                        account: recipient,
                        allowed: true,
                    },
                )?;
                assert!(token.is_transfer_authorized(sender, recipient)?);

                Ok::<_, TempoPrecompileError>(())
            })?;
        }

        Ok(())
    }

    #[test]
    fn test_set_next_quote_token_rejects_path_usd() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            let mut path_usd = TIP20Setup::path_usd(admin).apply()?;
            let other_token = TIP20Setup::create("Test", "T", admin).apply()?;

            // pathUSD cannot update its quote token
            let result = path_usd.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: other_token.address,
                },
            );
            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::InvalidQuoteToken(
                    _
                )))
            ));

            Ok(())
        })
    }

    #[test]
    fn test_non_path_usd_cycle_detection() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let admin = Address::random();

        StorageCtx::enter(&mut storage, || {
            TIP20Setup::path_usd(admin).apply()?;

            let mut token_b = TIP20Setup::create("TokenB", "TKNB", admin).apply()?;
            let token_a = TIP20Setup::create("TokenA", "TKNA", admin)
                .quote_token(token_b.address)
                .apply()?;

            // Verify chain where token_a -> token_b -> PATH_USD
            assert_eq!(token_a.quote_token()?, token_b.address);
            assert_eq!(token_b.quote_token()?, PATH_USD_ADDRESS);

            // Try to create cycle where token_b -> token_a
            token_b.set_next_quote_token(
                admin,
                ITIP20::setNextQuoteTokenCall {
                    newQuoteToken: token_a.address,
                },
            )?;

            let result =
                token_b.complete_quote_token_update(admin, ITIP20::completeQuoteTokenUpdateCall {});

            assert!(matches!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::InvalidQuoteToken(
                    _
                )))
            ));

            // assert that quote tokens are unchanged
            assert_eq!(token_a.quote_token()?, token_b.address);
            assert_eq!(token_b.quote_token()?, PATH_USD_ADDRESS);

            Ok(())
        })
    }

    // ═══════════════════════════════════════════════════════════
    //  TIP-1022 Virtual Address Tests
    // ═══════════════════════════════════════════════════════════

    #[test]
    fn test_mint_to_virtual_address_credits_master() -> eyre::Result<()> {
        let amount = U256::from(1000);

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();

            StorageCtx::enter(&mut storage, || {
                let mut registry = AddressRegistry::new();
                let (_, virtual_addr) = register_virtual_master(&mut registry)?;
                let credited = if hardfork.is_t3() {
                    VIRTUAL_MASTER
                } else {
                    virtual_addr
                };

                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .clear_events()
                    .apply()?;

                // mint
                token.mint(
                    admin,
                    ITIP20::mintCall {
                        to: virtual_addr,
                        amount,
                    },
                )?;

                if hardfork.is_t3() {
                    // T3: master is credited, virtual balance stays zero
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, amount);
                    assert_eq!(token.get_balance(virtual_addr)?, U256::ZERO);
                    assert_eq!(token.total_supply()?, amount);

                    // Events: Transfer(0→virtual) + Mint(virtual) + Transfer(virtual→master)
                    token.assert_emitted_events(vec![
                        TIP20Event::transfer(Address::ZERO, virtual_addr, amount),
                        TIP20Event::mint(virtual_addr, amount),
                        TIP20Event::transfer(virtual_addr, VIRTUAL_MASTER, amount),
                    ]);
                } else {
                    // Pre-T3: virtual address treated as literal, balance goes there
                    assert_eq!(token.get_balance(virtual_addr)?, amount);
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, U256::ZERO);
                }

                // mintWithMemo: same resolution behavior
                let pre = token.get_balance(credited)?;
                token.mint_with_memo(
                    admin,
                    ITIP20::mintWithMemoCall {
                        to: virtual_addr,
                        amount,
                        memo: FixedBytes::ZERO,
                    },
                )?;
                assert_eq!(token.get_balance(credited)? - pre, amount);

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }

    #[test]
    fn test_transfer_to_virtual_address_credits_master() -> eyre::Result<()> {
        let amount = U256::from(500);

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();
            let sender = Address::random();

            StorageCtx::enter(&mut storage, || {
                let mut registry = AddressRegistry::new();
                let (_, virtual_addr) = register_virtual_master(&mut registry)?;
                let credited = if hardfork.is_t3() {
                    VIRTUAL_MASTER
                } else {
                    virtual_addr
                };

                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(sender, amount * U256::from(2))
                    .clear_events()
                    .apply()?;

                // transfer
                token.transfer(
                    sender,
                    ITIP20::transferCall {
                        to: virtual_addr,
                        amount,
                    },
                )?;

                if hardfork.is_t3() {
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, amount);
                    assert_eq!(token.get_balance(virtual_addr)?, U256::ZERO);

                    // Events: Transfer(sender→virtual) + Transfer(virtual→master)
                    token.assert_emitted_events(vec![
                        TIP20Event::transfer(sender, virtual_addr, amount),
                        TIP20Event::transfer(virtual_addr, VIRTUAL_MASTER, amount),
                    ]);
                } else {
                    assert_eq!(token.get_balance(virtual_addr)?, amount);
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, U256::ZERO);
                }

                // transferWithMemo: same resolution behavior
                let pre = token.get_balance(credited)?;
                token.transfer_with_memo(
                    sender,
                    ITIP20::transferWithMemoCall {
                        to: virtual_addr,
                        amount,
                        memo: FixedBytes::ZERO,
                    },
                )?;
                assert_eq!(token.get_balance(credited)? - pre, amount);

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }

    #[test]
    fn test_transfer_from_to_virtual_address_credits_master() -> eyre::Result<()> {
        let amount = U256::from(300);

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();
            let owner = Address::random();
            let spender = Address::random();

            StorageCtx::enter(&mut storage, || {
                let mut registry = AddressRegistry::new();
                let (_, virtual_addr) = register_virtual_master(&mut registry)?;
                let credited = if hardfork.is_t3() {
                    VIRTUAL_MASTER
                } else {
                    virtual_addr
                };

                let total = amount * U256::from(2);
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_mint(owner, total)
                    .with_approval(owner, spender, total)
                    .clear_events()
                    .apply()?;

                // transferFrom
                token.transfer_from(
                    spender,
                    ITIP20::transferFromCall {
                        from: owner,
                        to: virtual_addr,
                        amount,
                    },
                )?;

                if hardfork.is_t3() {
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, amount);
                    assert_eq!(token.get_balance(virtual_addr)?, U256::ZERO);
                } else {
                    assert_eq!(token.get_balance(virtual_addr)?, amount);
                    assert_eq!(token.get_balance(VIRTUAL_MASTER)?, U256::ZERO);
                }

                // transferFromWithMemo: same resolution behavior
                let pre = token.get_balance(credited)?;
                token.transfer_from_with_memo(
                    spender,
                    ITIP20::transferFromWithMemoCall {
                        from: owner,
                        to: virtual_addr,
                        amount,
                        memo: FixedBytes::ZERO,
                    },
                )?;
                assert_eq!(token.get_balance(credited)? - pre, amount);

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }

    #[test]
    #[rustfmt::skip]
    fn test_unregistered_virtual_reverts_on_t3() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T3);
        let admin = Address::random();
        let sender = Address::random();
        let spender = Address::random();
        let to = Address::new_virtual(MasterId::ZERO, UserTag::ZERO);
        let amount = U256::from(100);
        let memo = FixedBytes::ZERO;

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_mint(sender, amount)
                .with_approval(sender, spender, amount)
                .apply()?;

            // All 6 entrypoints should revert for an unregistered virtual address
            assert!(token.mint(admin, ITIP20::mintCall { to, amount }).is_err());
            assert!(token.mint_with_memo(admin, ITIP20::mintWithMemoCall { to, amount, memo }).is_err());
            assert!(token.transfer(sender, ITIP20::transferCall { to, amount }).is_err());
            assert!(token.transfer_with_memo(sender, ITIP20::transferWithMemoCall { to, amount, memo }).is_err());
            assert!(token.transfer_from(spender, ITIP20::transferFromCall { from: sender, to, amount }).is_err());
            assert!(token.transfer_from_with_memo(spender, ITIP20::transferFromWithMemoCall { from: sender, to, amount, memo }).is_err());

            Ok(())
        })
    }

    // ═══════════════════════════════════════════════════════════
    //  EIP-2612 Permit Tests (TIP-1004)
    // ═══════════════════════════════════════════════════════════

    mod permit_tests {
        use super::*;
        use alloy::sol_types::SolValue;
        use alloy_signer::SignerSync;
        use alloy_signer_local::PrivateKeySigner;
        use tempo_chainspec::hardfork::TempoHardfork;

        const CHAIN_ID: u64 = 42;

        /// Create a T2 storage provider for permit tests
        fn setup_t2_storage() -> HashMapStorageProvider {
            HashMapStorageProvider::new_with_spec(CHAIN_ID, TempoHardfork::T2)
        }

        /// Helper to create a valid permit signature
        fn sign_permit(
            signer: &PrivateKeySigner,
            token_name: &str,
            token_address: Address,
            spender: Address,
            value: U256,
            nonce: U256,
            deadline: U256,
        ) -> (u8, B256, B256) {
            let domain_separator = compute_domain_separator(token_name, token_address);
            let struct_hash = keccak256(
                (
                    *PERMIT_TYPEHASH,
                    signer.address(),
                    spender,
                    value,
                    nonce,
                    deadline,
                )
                    .abi_encode(),
            );
            let digest = keccak256(
                [
                    &[0x19, 0x01],
                    domain_separator.as_slice(),
                    struct_hash.as_slice(),
                ]
                .concat(),
            );

            let sig = signer.sign_hash_sync(&digest).unwrap();
            let v = u8::from(sig.v()) + 27;
            let r: B256 = sig.r().into();
            let s: B256 = sig.s().into();
            (v, r, s)
        }

        fn compute_domain_separator(token_name: &str, token_address: Address) -> B256 {
            keccak256(
                (
                    *EIP712_DOMAIN_TYPEHASH,
                    keccak256(token_name.as_bytes()),
                    *VERSION_HASH,
                    U256::from(CHAIN_ID),
                    token_address,
                )
                    .abi_encode(),
            )
        }

        struct PermitFixture {
            storage: HashMapStorageProvider,
            admin: Address,
            signer: PrivateKeySigner,
            spender: Address,
        }

        impl PermitFixture {
            fn new() -> Self {
                Self {
                    storage: setup_t2_storage(),
                    admin: Address::random(),
                    signer: PrivateKeySigner::random(),
                    spender: Address::random(),
                }
            }
        }

        fn make_permit_call(
            signer: &PrivateKeySigner,
            spender: Address,
            token_address: Address,
            value: U256,
            nonce: U256,
            deadline: U256,
        ) -> ITIP20::permitCall {
            let (v, r, s) = sign_permit(
                signer,
                "Test",
                token_address,
                spender,
                value,
                nonce,
                deadline,
            );
            ITIP20::permitCall {
                owner: signer.address(),
                spender,
                value,
                deadline,
                v,
                r,
                s,
            }
        }

        #[test]
        fn test_permit_happy_path() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let owner = signer.address();
            let value = U256::from(1000);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
                let call =
                    make_permit_call(signer, spender, token.address, value, U256::ZERO, U256::MAX);
                token.permit(call)?;

                // Verify allowance was set
                let allowance = token.allowance(ITIP20::allowanceCall { owner, spender })?;
                assert_eq!(allowance, value);

                // Verify nonce was incremented
                let nonce = token.nonces(ITIP20::noncesCall { owner })?;
                assert_eq!(nonce, U256::from(1));

                Ok(())
            })
        }

        #[test]
        fn test_permit_expired() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let value = U256::from(1000);
            // Deadline in the past
            let deadline = U256::ZERO;

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
                let call =
                    make_permit_call(signer, spender, token.address, value, U256::ZERO, deadline);

                let result = token.permit(call);

                assert!(matches!(
                    result,
                    Err(TempoPrecompileError::TIP20(TIP20Error::PermitExpired(_)))
                ));

                Ok(())
            })
        }

        #[test]
        fn test_permit_invalid_signature() -> eyre::Result<()> {
            let mut storage = setup_t2_storage();
            let admin = Address::random();
            let owner = Address::random();
            let spender = Address::random();
            let value = U256::from(1000);
            let deadline = U256::MAX;

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                // Use garbage signature bytes
                let result = token.permit(ITIP20::permitCall {
                    owner,
                    spender,
                    value,
                    deadline,
                    v: 27,
                    r: B256::ZERO,
                    s: B256::ZERO,
                });

                assert!(matches!(
                    result,
                    Err(TempoPrecompileError::TIP20(TIP20Error::InvalidSignature(_)))
                ));

                Ok(())
            })
        }

        #[test]
        fn test_permit_wrong_signer() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let wrong_owner = Address::random(); // Not the signer's address
            let value = U256::from(1000);
            let deadline = U256::MAX;

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                // Sign with signer but claim wrong_owner
                let (v, r, s) = sign_permit(
                    signer,
                    "Test",
                    token.address,
                    spender,
                    value,
                    U256::ZERO,
                    deadline,
                );

                let result = token.permit(ITIP20::permitCall {
                    owner: wrong_owner, // Different from signer
                    spender,
                    value,
                    deadline,
                    v,
                    r,
                    s,
                });

                assert!(matches!(
                    result,
                    Err(TempoPrecompileError::TIP20(TIP20Error::InvalidSignature(_)))
                ));

                Ok(())
            })
        }

        #[test]
        fn test_permit_replay_protection() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let value = U256::from(1000);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
                let call =
                    make_permit_call(signer, spender, token.address, value, U256::ZERO, U256::MAX);

                // First use should succeed
                token.permit(call.clone())?;

                // Second use of same signature should fail (nonce incremented)
                let result = token.permit(call);

                assert!(matches!(
                    result,
                    Err(TempoPrecompileError::TIP20(TIP20Error::InvalidSignature(_)))
                ));

                Ok(())
            })
        }

        #[test]
        fn test_permit_nonce_tracking() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let owner = signer.address();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                // Initial nonce should be 0
                assert_eq!(token.nonces(ITIP20::noncesCall { owner })?, U256::ZERO);

                // Do 3 permits, each with correct nonce
                for i in 0u64..3 {
                    let nonce = U256::from(i);
                    let value = U256::from(100 * (i + 1));
                    let call =
                        make_permit_call(signer, spender, token.address, value, nonce, U256::MAX);
                    token.permit(call)?;

                    assert_eq!(
                        token.nonces(ITIP20::noncesCall { owner })?,
                        U256::from(i + 1)
                    );
                }

                Ok(())
            })
        }

        #[test]
        fn test_permit_works_when_paused() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let owner = signer.address();
            let value = U256::from(1000);

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_role(admin, *PAUSE_ROLE)
                    .apply()?;

                // Pause the token
                token.pause(admin, ITIP20::pauseCall {})?;
                assert!(token.paused()?);

                let call =
                    make_permit_call(signer, spender, token.address, value, U256::ZERO, U256::MAX);

                // Permit should work even when paused
                token.permit(call)?;

                assert_eq!(
                    token.allowance(ITIP20::allowanceCall { owner, spender })?,
                    value
                );

                Ok(())
            })
        }

        #[test]
        fn test_permit_domain_separator() -> eyre::Result<()> {
            let PermitFixture {
                mut storage, admin, ..
            } = PermitFixture::new();

            StorageCtx::enter(&mut storage, || {
                let token = TIP20Setup::create("Test", "TST", admin).apply()?;

                let ds = token.domain_separator()?;
                let expected = compute_domain_separator("Test", token.address);
                assert_eq!(ds, expected);

                Ok(())
            })
        }

        #[test]
        fn test_permit_max_allowance() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let owner = signer.address();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;
                let call = make_permit_call(
                    signer,
                    spender,
                    token.address,
                    U256::MAX,
                    U256::ZERO,
                    U256::MAX,
                );
                token.permit(call)?;

                assert_eq!(
                    token.allowance(ITIP20::allowanceCall { owner, spender })?,
                    U256::MAX
                );

                Ok(())
            })
        }

        #[test]
        fn test_permit_allowance_override() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                ref signer,
                spender,
            } = PermitFixture::new();
            let owner = signer.address();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                // First permit: set allowance to 1000
                let call = make_permit_call(
                    signer,
                    spender,
                    token.address,
                    U256::from(1000),
                    U256::ZERO,
                    U256::MAX,
                );
                token.permit(call)?;
                assert_eq!(
                    token.allowance(ITIP20::allowanceCall { owner, spender })?,
                    U256::from(1000)
                );

                // Second permit: override to 0
                let call = make_permit_call(
                    signer,
                    spender,
                    token.address,
                    U256::ZERO,
                    U256::from(1),
                    U256::MAX,
                );
                token.permit(call)?;
                assert_eq!(
                    token.allowance(ITIP20::allowanceCall { owner, spender })?,
                    U256::ZERO
                );

                Ok(())
            })
        }

        #[test]
        fn test_permit_invalid_v_values() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                spender,
                ..
            } = PermitFixture::new();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                for v in [0u8, 1] {
                    let result = token.permit(ITIP20::permitCall {
                        owner: admin,
                        spender,
                        value: U256::from(1000),
                        deadline: U256::MAX,
                        v,
                        r: B256::ZERO,
                        s: B256::ZERO,
                    });

                    assert!(
                        matches!(
                            result,
                            Err(TempoPrecompileError::TIP20(TIP20Error::InvalidSignature(_)))
                        ),
                        "v={v} should revert with InvalidSignature"
                    );
                }

                Ok(())
            })
        }

        #[test]
        fn test_permit_zero_address_recovery_reverts() -> eyre::Result<()> {
            let PermitFixture {
                mut storage,
                admin,
                spender,
                ..
            } = PermitFixture::new();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin).apply()?;

                let result = token.permit(ITIP20::permitCall {
                    owner: Address::ZERO,
                    spender,
                    value: U256::from(1000),
                    deadline: U256::MAX,
                    v: 27,
                    r: B256::ZERO,
                    s: B256::ZERO,
                });

                assert!(matches!(
                    result,
                    Err(TempoPrecompileError::TIP20(TIP20Error::InvalidSignature(_)))
                ));

                Ok(())
            })
        }

        #[test]
        fn test_permit_domain_separator_changes_with_chain_id() -> eyre::Result<()> {
            let PermitFixture { admin, .. } = PermitFixture::new();

            let mut storage_a = setup_t2_storage();
            let mut storage_b =
                HashMapStorageProvider::new_with_spec(CHAIN_ID + 1, TempoHardfork::T2);

            let ds_a = StorageCtx::enter(&mut storage_a, || {
                TIP20Setup::create("Test", "TST", admin)
                    .apply()?
                    .domain_separator()
            })?;

            let ds_b = StorageCtx::enter(&mut storage_b, || {
                TIP20Setup::create("Test", "TST", admin)
                    .apply()?
                    .domain_separator()
            })?;

            assert_ne!(
                ds_a, ds_b,
                "domain separator must change when chainId changes"
            );

            Ok(())
        }
    }

    #[test]
    fn test_mint_paused_pre_t6_short_circuits_before_policy_reads() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new_with_spec(1, TempoHardfork::T5);
        let (admin, amount) = (Address::random(), U256::random());

        StorageCtx::enter(&mut storage, || {
            let mut token = TIP20Setup::create("Test", "TST", admin)
                .with_issuer(admin)
                .with_role(admin, *PAUSE_ROLE)
                .apply()?;
            token.pause(admin, ITIP20::pauseCall {})?;

            token.storage.reset_counters();
            let result = token.mint(admin, ITIP20::mintCall { to: admin, amount });

            assert_eq!(
                result,
                Err(TempoPrecompileError::TIP20(TIP20Error::contract_paused()))
            );
            // Pre-T6 paused mint must stop after issuer-role, pause and total supply reads.
            assert_eq!(token.storage.counter_sload(), 3);

            Ok::<_, TempoPrecompileError>(())
        })?;

        Ok(())
    }

    #[test]
    fn test_mint_rejects_when_paused_on_t3() -> eyre::Result<()> {
        let to = Address::random();
        let amount = U256::from(1000);
        let memo = FixedBytes::random();

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_role(admin, *PAUSE_ROLE)
                    .apply()?;

                token.pause(admin, ITIP20::pauseCall {})?;

                let mint_result = token.mint(admin, ITIP20::mintCall { to, amount });
                let mint_memo_result =
                    token.mint_with_memo(admin, ITIP20::mintWithMemoCall { to, amount, memo });

                if hardfork.is_t3() {
                    let expected = TempoPrecompileError::TIP20(TIP20Error::contract_paused());
                    assert_eq!(mint_result, Err(expected.clone()));
                    assert_eq!(mint_memo_result, Err(expected));
                } else {
                    assert!(mint_result.is_ok());
                    assert!(mint_memo_result.is_ok());
                }

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }

    #[test]
    fn test_burn_rejects_when_paused_on_t3() -> eyre::Result<()> {
        let amount = U256::from(500);
        let memo = FixedBytes::random();

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();

            StorageCtx::enter(&mut storage, || {
                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_role(admin, *PAUSE_ROLE)
                    .with_mint(admin, amount * U256::from(2))
                    .apply()?;

                token.pause(admin, ITIP20::pauseCall {})?;

                let burn_result = token.burn(admin, ITIP20::burnCall { amount });
                let burn_memo_result =
                    token.burn_with_memo(admin, ITIP20::burnWithMemoCall { amount, memo });

                if hardfork.is_t3() {
                    let expected = TempoPrecompileError::TIP20(TIP20Error::contract_paused());
                    assert_eq!(burn_result, Err(expected.clone()));
                    assert_eq!(burn_memo_result, Err(expected));
                } else {
                    assert!(burn_result.is_ok());
                    assert!(burn_memo_result.is_ok());
                }

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }

    #[test]
    fn test_burn_blocked_rejects_when_paused_on_t3() -> eyre::Result<()> {
        let amount = U256::from(500);
        let blocked = Address::random();

        for hardfork in [TempoHardfork::T2, TempoHardfork::T3] {
            let mut storage = HashMapStorageProvider::new_with_spec(1, hardfork);
            let admin = Address::random();

            StorageCtx::enter(&mut storage, || {
                // Create a blacklist policy and block the address
                let mut registry = TIP403Registry::new();
                registry.initialize()?;
                let policy_id = registry.create_policy(
                    admin,
                    ITIP403Registry::createPolicyCall {
                        admin,
                        policyType: ITIP403Registry::PolicyType::BLACKLIST,
                    },
                )?;
                registry.modify_policy_blacklist(
                    admin,
                    ITIP403Registry::modifyPolicyBlacklistCall {
                        policyId: policy_id,
                        account: blocked,
                        restricted: true,
                    },
                )?;

                let mut token = TIP20Setup::create("Test", "TST", admin)
                    .with_issuer(admin)
                    .with_role(admin, *PAUSE_ROLE)
                    .with_role(admin, *BURN_BLOCKED_ROLE)
                    .with_mint(blocked, amount)
                    .apply()?;

                // Point the token's transfer policy at our blacklist
                token.change_transfer_policy_id(
                    admin,
                    ITIP20::changeTransferPolicyIdCall {
                        newPolicyId: policy_id,
                    },
                )?;

                // Pause the token
                token.pause(admin, ITIP20::pauseCall {})?;

                let result = token.burn_blocked(admin, blocked, amount, true);

                if hardfork.is_t3() {
                    assert_eq!(
                        result,
                        Err(TempoPrecompileError::TIP20(TIP20Error::contract_paused()))
                    );
                } else {
                    // T2: pause not enforced, burn succeeds
                    assert!(result.is_ok());
                    assert_eq!(token.get_balance(blocked)?, U256::ZERO);
                }

                Ok::<_, TempoPrecompileError>(())
            })?;
        }
        Ok(())
    }
}