Struct AccountKeychain 

pub struct AccountKeychain {
    pub keys: <Mapping<Address, Mapping<Address, AuthorizedKey>> as StorableType>::Handler,
    pub spending_limits: <Mapping<B256, Mapping<Address, SpendingLimitState>> as StorableType>::Handler,
    pub key_scopes: <Mapping<B256, KeyScope> as StorableType>::Handler,
    pub transaction_key: <Address as StorableType>::Handler,
    pub tx_origin: <Address as StorableType>::Handler,
    address: Address,
    storage: StorageCtx,
}

Fields

keys: <Mapping<Address, Mapping<Address, AuthorizedKey>> as StorableType>::Handler

spending_limits: <Mapping<B256, Mapping<Address, SpendingLimitState>> as StorableType>::Handler

key_scopes: <Mapping<B256, KeyScope> as StorableType>::Handler

transaction_key: <Address as StorableType>::Handler

tx_origin: <Address as StorableType>::Handler

address: Address

storage: StorageCtx

Implementations

impl AccountKeychain

pub fn new() -> Self

Creates an instance of the precompile.

Caution: This does not initialize the account, see Self::initialize.

fn __new(address: Address) -> Self

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

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

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

Available on crate features test-utils only.

pub fn clear_emitted_events(&mut self)

Available on crate features test-utils only.

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

Available on crate features test-utils only.

impl AccountKeychain

pub fn spending_limit_key(account: Address, key_id: Address) -> B256

Create a hash key for account+key scoped storage rows.

This is used to access account-key rows like spending_limits[key][token] and key_scopes[key]. The hash combines account and key_id to avoid triple nesting.

fn t3_spending_limit_cap(limit: U256) -> Result<u128>

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

Initializes the account keychain precompile.

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

Registers a new access key with signature type, expiry, and optional per-token spending limits. Only callable with the account’s main key (not a session key).

Errors

• UnauthorizedCaller — only the main key can authorize/revoke and, for contract callers on T2+, msg.sender must match tx.origin
• ZeroPublicKey — keyId cannot be the zero address
• ExpiryInPast — expiry must be in the future (enforced since T0)
• KeyAlreadyExists — a key with this ID is already registered
• KeyAlreadyRevoked — revoked keys cannot be re-authorized
• InvalidSignatureType — must be Secp256k1, P256, or WebAuthn

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

Permanently revokes an access key. Once revoked, a key ID can never be re-authorized for this account, preventing replay of old KeyAuthorization signatures.

Errors

• UnauthorizedCaller — only the main key can authorize/revoke and, for contract callers on T2+, msg.sender must match tx.origin
• KeyNotFound — no key registered with this ID

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

Updates the spending limit for a key-token pair. Can also convert an unlimited key into a limited one. Delegates to load_active_key for existence/revocation/expiry checks.

Errors

• UnauthorizedCaller — the transaction wasn’t signed by the main key, or on T2+ contract callers where msg.sender != tx.origin
• KeyAlreadyRevoked — the target key has been permanently revoked
• KeyNotFound — no key is registered under the given keyId
• KeyExpired — the key’s expiry is at or before the current block timestamp

pub fn get_key(&self, call: getKeyCall) -> Result<KeyInfo>

Returns key info for the given account-key pair, or a blank entry if inexistent or revoked.

pub fn get_remaining_limit(&self, call: getRemainingLimitCall) -> Result<U256>

Returns the remaining spending limit for a key-token pair.

T2+ returns zero for missing, revoked, or expired keys. Pre-T2 preserves the historical behavior of reading the raw stored remaining amount so old blocks reexecute identically.

pub fn get_remaining_limit_with_period( &self, call: getRemainingLimitWithPeriodCall, ) -> Result<getRemainingLimitReturn>

Returns the remaining spending limit together with the active period end timestamp.

Missing, revoked, or expired keys report zeroed values instead of erroring.

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

Root-only create-or-replace updates for one or more target call scopes.

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

Root-only removal of one target call scope.

pub fn get_allowed_calls( &self, call: getAllowedCallsCall, ) -> Result<getAllowedCallsReturn>

Returns whether an account key is call-scoped together with its configured call scopes.

isScoped = false means unrestricted. isScoped = true with an empty scopes vec means the key is scoped but currently allows no targets. Missing, revoked, or expired access keys also report scoped deny-all so this getter never exposes stale persisted scope state.

pub fn get_transaction_key( &self, _call: getTransactionKeyCall, _msg_sender: Address, ) -> Result<Address>

Returns the access key used to authorize the current transaction (Address::ZERO = root key).

pub fn set_transaction_key(&mut self, key_id: Address) -> Result<()>

Internal: Set the transaction key (called during transaction validation)

SECURITY CRITICAL: This must be called by the transaction validation logic BEFORE the transaction is executed, to store which key authorized the transaction.

• If key_id is Address::ZERO (main key), this should store Address::ZERO
• If key_id is a specific key address, this should store that key

This creates a secure channel between validation and the precompile to ensure only the main key can authorize/revoke other keys. Uses transient storage, so the key is automatically cleared after the transaction.

pub fn set_tx_origin(&mut self, origin: Address) -> Result<()>

Sets the transaction origin (tx.origin) for the current transaction.

Called by the handler before transaction execution. Uses transient storage, so it’s automatically cleared after the transaction.

fn apply_key_authorization_restrictions<'a>( &mut self, account: Address, key_id: Address, limits: impl IntoIterator<Item = &'a TokenLimit>, allowed_calls: Option<&[CallScope]>, ) -> Result<()>

Persists the authorization-time restrictions for a freshly created key.

T0-T2 only store raw spending limits. T3 additionally seeds periodic metadata and replaces the key’s call-scope tree in one pass.

pub fn validate_call_scope_for_transaction( &self, account: Address, key_id: Address, to: &TxKind, input: &[u8], ) -> Result<()>

Validates a top-level call against scoped permissions for this key.

Validation walks the scope tree from coarse to fine:

• is_scoped = false => unrestricted key
• target missing from targets => target denied
• target present with selectors = [] => allow any selector on that target
• selector missing from selectors => selector denied
• selector present with recipients = [] => allow any recipient for that selector

fn replace_allowed_calls( &mut self, account_key: B256, allowed_calls: Option<&[CallScope]>, ) -> Result<()>

Replaces the full call-scope tree for an account key.

None switches the key back to unrestricted mode, while Some([]) preserves scoped mode with no targets so reads can distinguish scoped deny-all from unrestricted mode. This is the only place where an empty top-level list means deny-all; below the key level, empty child sets mean “no further restriction”.

fn clear_all_target_scopes(&mut self, account_key: B256) -> Result<()>

Deletes every persisted target scope under an account key.

fn remove_target_scope( &mut self, account_key: B256, target: Address, ) -> Result<()>

Deletes one target scope and all nested selector/recipient rows beneath it.

fn clear_target_selectors( &mut self, account_key: B256, target: Address, ) -> Result<()>

Clears every selector scope stored under one target.

fn upsert_target_scope( &mut self, account_key: B256, scope: &CallScope, ) -> Result<()>

Creates or replaces one target scope, including all nested selector rules.

fn validate_call_scopes(&self, scopes: &[CallScope]) -> Result<()>

Validates a list of CallScopes.

fn validate_call_scope(&self, scope: &CallScope) -> Result<()>

Validates a single CallScope.

fn validate_selector_rules( &self, target: Address, rules: &[SelectorRule], ) -> Result<()>

Validates per-selector scope rules for one target before they are persisted.

recipients = [] is an explicit allow-all sentinel at the selector level. To deny a selector entirely, omit it from selectorRules or remove the target scope instead of leaving behind an empty child set via incremental mutation.

fn ensure_admin_caller(&self, msg_sender: Address) -> Result<()>

Ensures admin operations are authorized for this caller.

Rules:

• transaction must be signed by the main key (transaction_key == Address::ZERO)
• T2+: caller must match tx.origin

Errors

• UnauthorizedCaller when called via an access key
• UnauthorizedCaller on T2+ when msg.sender != tx.origin
• storage read errors from transient key/origin or account metadata lookups

The T2 check prevents transaction-global root-key status from being reused by intermediate contracts (confused-deputy self-administration).

tx_origin is seeded by the handler before validation/execution. If origin is not seeded (zero), admin ops are rejected.

fn load_active_key( &self, account: Address, key_id: Address, current_timestamp: u64, ) -> Result<AuthorizedKey>

Load and validate a key exists, is not revoked, and is not expired.

Returns the key if valid, or an error if:

• Key doesn’t exist (expiry == 0)
• Key has been revoked
• Key has expired at or before current_timestamp

pub fn validate_keychain_authorization( &self, account: Address, key_id: Address, current_timestamp: u64, expected_sig_type: Option<u8>, ) -> Result<AuthorizedKey>

Validate keychain authorization (existence, revocation, expiry, and optionally signature type).

Arguments

• account - The account that owns the key
• key_id - The key identifier to validate
• current_timestamp - Current block timestamp for expiry check
• expected_sig_type - The signature type from the actual signature (0=Secp256k1, 1=P256, 2=WebAuthn). Pass None to skip validation (for backward compatibility pre-T1).

Errors

• KeyAlreadyRevoked — the key has been permanently revoked
• KeyNotFound — no key is registered under the given key_id
• KeyExpired — current_timestamp is at or past the key’s expiry
• SignatureTypeMismatch — the key’s stored type differs from expected_sig_type

pub fn effective_remaining_limit( &self, account: Address, key_id: Address, token: Address, current_timestamp: u64, ) -> Result<U256>

Computes the effective remaining limit at current_timestamp without mutating storage.

fn effective_limit_state( &self, account: Address, key_id: Address, token: Address, current_timestamp: u64, ) -> Result<(U256, u64)>

Computes the effective remaining limit and period end at current_timestamp without mutating storage.

pub fn verify_and_update_spending( &mut self, account: Address, key_id: Address, token: Address, amount: U256, ) -> Result<()>

Deducts amount from the key’s remaining spending limit for token, failing if exceeded.

Errors

• KeyAlreadyRevoked — the key has been permanently revoked
• KeyNotFound — no key is registered under the given key_id
• SpendingLimitExceeded — amount exceeds the key’s remaining limit for token

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

Refund spending limit after a fee refund.

Restores the spending limit by the refunded amount. Should be called after a fee refund to avoid permanently reducing the spending limit. On T3, this should never restore more than the configured max in the current fee flow, but we still clamp as defense in depth in case a future caller violates that invariant.

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

Authorize a token transfer with access key spending limits.

This method checks if the transaction is using an access key, and if so, verifies and updates the spending limits for that key. Should be called before executing a transfer.

Errors

• KeyAlreadyRevoked — the session key has been permanently revoked
• KeyNotFound — no key is registered for the current transaction key
• SpendingLimitExceeded — amount exceeds the key’s remaining limit for token

pub fn authorize_approve( &mut self, account: Address, token: Address, old_approval: U256, new_approval: U256, ) -> Result<()>

Authorize a token approval with access key spending limits.

This method checks if the transaction is using an access key, and if so, verifies and updates the spending limits for that key. Should be called before executing an approval.

Errors

• KeyAlreadyRevoked — the session key has been permanently revoked
• KeyNotFound — no key is registered for the current transaction key
• SpendingLimitExceeded — the approval increase exceeds the remaining limit for token

impl AccountKeychain

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

Creates the EVM precompile for this type.

Trait Implementations

impl ContractStorage for AccountKeychain

fn address(&self) -> Address

Contract address.

fn storage(&self) -> &StorageCtx

Contract storage accessor.

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

Contract storage mutable accessor.

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

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

impl Default for AccountKeychain

fn default() -> Self

Returns the “default value” for a type.

impl Precompile for AccountKeychain

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

Dispatches an EVM call to this precompile.

Layout

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

Size: 488 bytes