# Account Keychain Precompile **Address:** `0xAAAAAAAA00000000000000000000000000000000` ## Overview The Account Keychain precompile manages authorized Access Keys for accounts, enabling Root Keys (e.g., passkeys) to provision scoped "secondary" Access Keys with expiry timestamps, recurring or one-time per-TIP20 token spending limits, and explicit call scopes that restrict which targets, selectors, and recipients an Access Key may invoke. `authorizeKey(...)` takes a `KeyRestrictions` tuple that bundles expiry, spending limits, and call scopes. Access-key-signed transactions cannot create contracts; use a Root Key for deployment flows. ## Motivation The Tempo Transaction type unlocks a number of new signature schemes, including WebAuthn (Passkeys). However, for an Account using a Passkey as its Root Key, the sender will subsequently be prompted with passkey prompts for every signature request. This can be a poor user experience for highly interactive or multi-step flows. Additionally, users would also see "Sign In" copy in prompts for signing transactions which is confusing. This proposal introduces the concept of the Root Key being able to provision a (scoped) Access Key that can be used for subsequent transactions, without the need for repetitive end-user prompting. Recurring spending budgets and explicit call scoping make these keys suitable for subscriptions, connected apps, and session-key-style flows. ## Concepts ### Access Keys Access Keys are secondary signing keys authorized by an account's Root Key. They can sign transactions on behalf of the account with the following restrictions: * **Expiry**: Unix timestamp when the key becomes invalid. A non-expiring `key_authorization` omits `expiry` at the transaction RLP layer; the protocol translates that omission to `u64::MAX` before calling the precompile. Direct precompile callers should pass `u64::MAX` for a non-expiring key. Literal `0` is treated as past expiry and rejected. * **Spending Limits**: Per-TIP20 token limits that deplete as tokens are spent * Limits are one-time (`period = 0`) or recurring (`period > 0`, in seconds). Recurring limits roll over to `max` when `current_timestamp >= periodEnd`. * Limits can be updated by the Root Key via `updateSpendingLimit()`. An update resets `remaining` and `max` to `newLimit` but preserves the configured `period` and current `periodEnd`. * Spending limits only apply to TIP20 `transfer()`, `transferWithMemo()`, and `approve()` calls * Spending limits only apply when `msg.sender == tx.origin` (direct EOA calls, not contract calls) * Native value transfers and `transferFrom()` are NOT limited * **Call Scopes**: An Access Key is either unrestricted (`allowAnyCalls = true`) or restricted to an explicit allowlist of `(target, selector, recipients)` tuples. An empty allowlist with `allowAnyCalls = false` means scoped deny-all. * **No Contract Creation**: Access-key-signed transactions cannot perform `CREATE` or `CREATE2`, including via factory contracts. Use a Root Key for deployments. * **Privilege Restrictions**: Cannot authorize new keys or modify their own limits or scopes. ### Authorization Hierarchy The protocol enforces a strict hierarchy at validation time: 1. **Root Key**: The account's main key (derived from the account address) * Can call all precompile functions, including the Root-Key-only mutators (`authorizeKey`, `revokeKey`, `updateSpendingLimit`, `setAllowedCalls`, `removeAllowedCalls`) * Has no spending limits or call-scope restrictions 2. **Access Keys**: Secondary authorized keys * Cannot call mutable precompile functions (only view functions are allowed) * Subject to per-TIP20 token spending limits * Subject to call-scope checks during execution * Cannot create contracts * Can have expiry timestamps ## Storage The precompile uses a `keyId` (address) to uniquely identify each access key for an account. **Storage Mappings:** * `keys[account][keyId]` → Packed `AuthorizedKey` struct (signature type, expiry, enforce\_limits, is\_revoked) * `spendingLimits[keccak256(account || keyId)][token]` → `SpendingLimitState { remaining, max, period, periodEnd }` * `keyScopes[keccak256(account || keyId)]` → Tree of `(target, selector, recipients)` allowlists used during call-scope checks * `transactionKey` → Transient storage for the key ID that signed the current transaction (slot 0) **AuthorizedKey Storage Layout (packed into single slot):** * byte 0: signature\_type (u8) * bytes 1-8: expiry (u64, little-endian) * byte 9: enforce\_limits (bool) * byte 10: is\_revoked (bool) ## Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.13; interface IAccountKeychain { enum SignatureType { Secp256k1, P256, WebAuthn } struct TokenLimit { address token; uint256 amount; uint64 period; } struct SelectorRule { bytes4 selector; address[] recipients; } struct CallScope { address target; SelectorRule[] selectorRules; } struct KeyRestrictions { uint64 expiry; bool enforceLimits; TokenLimit[] limits; bool allowAnyCalls; CallScope[] allowedCalls; } struct KeyInfo { SignatureType signatureType; address keyId; uint64 expiry; bool enforceLimits; bool isRevoked; } event KeyAuthorized(address indexed account, address indexed publicKey, uint8 signatureType, uint64 expiry); event KeyRevoked(address indexed account, address indexed publicKey); event SpendingLimitUpdated(address indexed account, address indexed publicKey, address indexed token, uint256 newLimit); event AccessKeySpend(address indexed account, address indexed publicKey, address indexed token, uint256 amount, uint256 remainingLimit); error UnauthorizedCaller(); error KeyAlreadyExists(); error KeyNotFound(); error KeyExpired(); error SpendingLimitExceeded(); error InvalidSpendingLimit(); error InvalidSignatureType(); error ZeroPublicKey(); error ExpiryInPast(); error KeyAlreadyRevoked(); error SignatureTypeMismatch(uint8 expected, uint8 actual); error CallNotAllowed(); error InvalidCallScope(); error LegacyAuthorizeKeySelectorChanged(bytes4 newSelector); function authorizeKey( address keyId, SignatureType signatureType, KeyRestrictions calldata config ) external; function revokeKey(address keyId) external; function updateSpendingLimit( address keyId, address token, uint256 newLimit ) external; function setAllowedCalls( address keyId, CallScope[] calldata scopes ) external; function removeAllowedCalls(address keyId, address target) external; function getKey(address account, address keyId) external view returns (KeyInfo memory); function getRemainingLimitWithPeriod( address account, address keyId, address token ) external view returns (uint256 remaining, uint64 periodEnd); function getAllowedCalls( address account, address keyId ) external view returns (bool isScoped, CallScope[] memory scopes); function getTransactionKey() external view returns (address); } ``` ## Behavior ### Key Authorization * Creates a new key entry with the specified `signatureType`, `config.expiry`, `config.enforceLimits`, and `isRevoked` set to `false` * If `enforceLimits` is `true`, initializes spending limits for each specified token. Each `TokenLimit` carries a `period` (0 = one-time, non-zero = recurring in seconds). * If `allowAnyCalls` is `false`, stores the `allowedCalls` allowlist in `keyScopes`. `allowAnyCalls = false` with `allowedCalls = []` means scoped deny-all. * Recipient-constrained selector rules are validated before any state is written. * Emits `KeyAuthorized` event **Requirements:** * MUST be called by Root Key only (verified by checking `transactionKey[msg.sender] == 0`) * MUST be invoked via the canonical selector `0x980a6025` (the `(address,uint8,(uint64,bool,(address,uint256,uint64)[],bool,(address,(bytes4,address[])[])[]))` shape). Other selectors revert. * `keyId` MUST NOT be `address(0)` (reverts with `ZeroPublicKey`) * `keyId` MUST NOT already be authorized with `expiry > 0` (reverts with `KeyAlreadyExists`) * `keyId` MUST NOT have been previously revoked (reverts with `KeyAlreadyRevoked` - prevents replay attacks) * `signatureType` MUST be `0` (Secp256k1), `1` (P256), or `2` (WebAuthn) (reverts with `InvalidSignatureType`) * `config.expiry` MUST be strictly greater than the current block timestamp (reverts with `ExpiryInPast`) * To authorize a non-expiring key, omit `key_authorization.expiry` in the transaction RLP or pass `u64::MAX` when calling the precompile ABI directly. Do not pass `0`. * `enforceLimits` determines whether spending limits are enforced for this key * `limits` are only processed if `enforceLimits` is `true`. Duplicate token entries revert with `InvalidSpendingLimit`. * Invalid call-scope shapes (zero targets, duplicate targets, duplicate selectors, duplicate recipients, malformed recipient-bound rules) revert with `InvalidCallScope`. ### Key Revocation * Marks the key as revoked by setting `isRevoked` to `true` and `expiry` to `0` * Once revoked, a `keyId` can NEVER be re-authorized for this account (prevents replay attacks) * Any stored call-scope and periodic-limit state becomes inaccessible. `getAllowedCalls(...)` returns scoped deny-all (`isScoped = true, scopes = []`) for revoked keys. * Key can no longer be used for transactions * Emits `KeyRevoked` event **Requirements:** * MUST be called by Root Key only (verified by checking `transactionKey[msg.sender] == 0`) * `keyId` MUST exist (key with `expiry > 0`) (reverts with `KeyNotFound` if not found) ### Spending Limit Update * Updates the spending limit for a specific token on an authorized key * Allows Root Key to modify limits without revoking and re-authorizing the key * If the key had unlimited spending (`enforceLimits == false`), enables limits * Sets both `remaining` and `max` to `newLimit`. The configured `period` and current `periodEnd` are preserved. * `newLimit` MUST fit within TIP20's `u128` supply range. * Emits `SpendingLimitUpdated` event **Requirements:** * MUST be called by Root Key only (verified by checking `transactionKey[msg.sender] == 0`) * `keyId` MUST exist and not be revoked (reverts with `KeyNotFound` or `KeyAlreadyRevoked`) * `keyId` MUST not be expired (reverts with `KeyExpired`) ### Allowed Call Updates * `setAllowedCalls(...)` creates or replaces one or more target scopes for an existing key. * `removeAllowedCalls(...)` removes one stored target scope. * An empty `selectorRules` array means any selector on that target is allowed. * `setAllowedCalls(...)` rejects an empty scope batch, zero targets, duplicate targets, duplicate selectors, duplicate recipients, and invalid recipient-constrained rules (reverts with `InvalidCallScope`). **Requirements:** * MUST be called by Root Key only (verified by checking `transactionKey[msg.sender] == 0`) * `keyId` MUST exist and not be revoked ### View Behavior * `getKey(...)` returns key metadata. * `getRemainingLimitWithPeriod(...)` returns the effective `remaining` amount and current `periodEnd` for a key-token pair, accounting for periodic rollover. * `getAllowedCalls(...)` returns `(isScoped, scopes)`. Unrestricted keys return `isScoped = false`. Scoped keys return `isScoped = true` with their `CallScope[]`. Missing, revoked, or expired access keys return `isScoped = true, scopes = []` (scoped deny-all). * `getTransactionKey()` returns the key used in the current transaction. `address(0)` means the Root Key. * Missing, revoked, or expired keys return zeroed limit values. ## Security Considerations ### Access Key Storage Access Keys should be securely stored to prevent unauthorized access. Call scopes make per-app and per-device key isolation more important, because a mis-scoped key may have a broader allowlist than intended. * **Device and Application Scoping**: Access Keys SHOULD be scoped to a specific client device AND application combination. Access Keys SHOULD NOT be shared between devices or applications, even if they belong to the same user. * **Non-Extractable Keys**: Access Keys SHOULD be generated and stored in a non-extractable format to prevent theft. For example, use WebCrypto API with `extractable: false` when generating Keys in web browsers. * **Secure Storage**: Private Keys MUST never be stored in plaintext. Private Keys SHOULD be encrypted and stored in a secure manner. For web applications, use browser-native secure storage mechanisms like IndexedDB with non-extractable WebCrypto keys rather than storing raw key material. ### Privilege Escalation Prevention Access Keys cannot escalate their own privileges because: 1. Management functions (`authorizeKey`, `revokeKey`, `updateSpendingLimit`, `setAllowedCalls`, `removeAllowedCalls`) are restricted to Root Key transactions 2. The protocol sets `transactionKey[account]` during transaction validation to indicate which key signed the transaction 3. These management functions check that `transactionKey[msg.sender] == 0` (Root Key) before executing 4. Mutable precompile calls also require `msg.sender == tx.origin`, which prevents contract-mediated confused-deputy patterns 5. Access Keys cannot bypass these checks - transactions will revert with `UnauthorizedCaller` ### Spending Limit Enforcement * Spending limits are only enforced if `enforceLimits == true` for the key * Keys with `enforceLimits == false` have unlimited spending (no limits checked) * Spending limits are enforced by the protocol internally calling `verify_and_update_spending()` during execution * Limits are per-TIP20 token and deplete as TIP20 tokens are spent * Recurring limits (`period > 0`) roll over to `max` when `current_timestamp >= periodEnd`. Callers can observe rollover state via `getRemainingLimitWithPeriod(...)`. * Spending limits only track TIP20 token transfers (via `transfer` and `transferWithMemo`) and approvals (via `approve`) * For approvals: only increases in approval amount count against the spending limit. This means approvals indirectly control `transferFrom` spending, since `transferFrom` requires a prior approval * Non-TIP20 asset movements (ETH, NFTs) are not subject to spending limits * Root keys (`keyId == address(0)`) have no spending limits - the function returns immediately * Missing, revoked, or expired keys have an effective remaining limit of zero * Failed limit checks revert the entire transaction with `SpendingLimitExceeded` ### Call Scope Enforcement * Call-scope checks run on top-level calls signed by an Access Key. * If a key is scoped and a call does not match the stored target, selector, and recipient rules, execution reverts with `CallNotAllowed`. * Access-key-signed transactions cannot create contracts in any configuration — including direct `CREATE`, factory `CREATE`, and internal `CREATE2`. Only Root-Key-signed transactions may perform contract creation. ### Key Expiry * Keys with `expiry > 0` are checked against the current timestamp during validation * Expired keys cause transaction rejection with `KeyExpired` error (checked via `validate_keychain_authorization()`) * New authorizations require a future expiry timestamp * Expiry is checked as: `current_timestamp >= expiry` (key is expired when current time reaches or exceeds expiry) * Expired keys return zeroed limit and call-scope reads. ## Usage Patterns ### First-Time Access Key Authorization 1. User signs Passkey prompt → signs over `key_authorization` for a new Access Key (e.g., WebCrypto P256 key). The signed authorization carries `KeyRestrictions`, allowing the same first-use flow to provision recurring limits and call scopes. 2. User's Access Key signs the transaction 3. Transaction includes the `key_authorization` AND the Access Key `signature` 4. Protocol validates Passkey signature on `key_authorization`, sets `transactionKey[account] = 0`, calls `AccountKeychain.authorizeKey()`, then validates Access Key signature 5. Transaction executes with Access Key's spending limits enforced via internal `verify_and_update_spending()`, plus call-scope checks if the key is scoped ### Subsequent Access Key Usage 1. User's Access Key signs the transaction (no `key_authorization` needed) 2. Protocol validates the Access Key via `validate_keychain_authorization()`, sets `transactionKey[account] = keyId` 3. Transaction executes with spending limit enforcement via internal `verify_and_update_spending()` and call-scope enforcement. Contract creation is rejected. ### Root Key Revoking or Updating an Access Key 1. User signs Passkey prompt → signs transaction calling `revokeKey(keyId)`, `updateSpendingLimit(...)`, `setAllowedCalls(...)`, or `removeAllowedCalls(...)` 2. Transaction executes, marking the Access Key as inactive or updating its restrictions 3. Future transactions signed by that Access Key are rejected (after revocation) or evaluated against the updated restrictions ## T2 → T3 migration :::info\[Migration appendix] This section captures changes introduced by the [T3 network upgrade](/protocol/upgrades/t3) for integrators migrating from T2. The spec above is the canonical post-T3 specification; this appendix exists for reference and will be removed in a future docs revision. ::: ### Migration summary * The legacy `authorizeKey(address,uint8,uint64,bool,(address,uint256)[])` entrypoint (selector `0x54063a55`) is no longer accepted. Calls revert with `LegacyAuthorizeKeySelectorChanged(0x980a6025)`. * `authorizeKey(...)` now takes a `KeyRestrictions` tuple that bundles expiry, spending limits, and call scopes. The flattened seven-argument form (which hashes to `0x203e2736` in Foundry) is rejected as an unknown selector — the call must use the canonical tuple-form selector `0x980a6025`. * A non-expiring key is no longer represented by `expiry = 0`. Omit `key_authorization.expiry` in the transaction RLP, or pass `u64::MAX` when calling `authorizeKey(...)` directly. Literal `0` reverts with `ExpiryInPast`. * `TokenLimit` gains a `period` field, so limits can be one-time (`period = 0`) or recurring. * Access keys can be scoped to specific targets, selectors, and recipients via `KeyRestrictions.allowAnyCalls` and `KeyRestrictions.allowedCalls`. * The precompile adds `setAllowedCalls(...)`, `removeAllowedCalls(...)`, `getAllowedCalls(...)`, and `getRemainingLimitWithPeriod(...)`. * The legacy `getRemainingLimit(...)` selector is dropped. Callers must switch to `getRemainingLimitWithPeriod(...)`, which returns both `remaining` and `periodEnd`. * Access-key-signed transactions can no longer create contracts. Use a Root Key for deployment flows. * New errors: `InvalidSpendingLimit()`, `ExpiryInPast()`, `SignatureTypeMismatch(uint8,uint8)`, `CallNotAllowed()`, `InvalidCallScope()`, `LegacyAuthorizeKeySelectorChanged(bytes4)`. ### Before and after `authorizeKey(...)` ```text T2 authorizeKey(address,uint8,uint64,bool,(address,uint256)[]) selector: 0x54063a55 T3 authorizeKey(address,uint8,(uint64,bool,(address,uint256,uint64)[],bool,(address,(bytes4,address[])[])[])) selector: 0x980a6025 ``` ### Legacy T2 interface (reference only) ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.13; interface IAccountKeychainT2 { enum SignatureType { Secp256k1, P256, WebAuthn, } struct TokenLimit { address token; uint256 amount; } struct KeyInfo { SignatureType signatureType; address keyId; uint64 expiry; bool enforceLimits; bool isRevoked; } event KeyAuthorized( address indexed account, address indexed publicKey, uint8 signatureType, uint64 expiry ); event KeyRevoked(address indexed account, address indexed publicKey); event SpendingLimitUpdated( address indexed account, address indexed publicKey, address indexed token, uint256 newLimit ); error KeyAlreadyExists(); error KeyNotFound(); error KeyInactive(); error KeyExpired(); error KeyAlreadyRevoked(); error SpendingLimitExceeded(); error InvalidSignatureType(); error ZeroPublicKey(); error UnauthorizedCaller(); function authorizeKey( address keyId, SignatureType signatureType, uint64 expiry, bool enforceLimits, TokenLimit[] calldata limits ) external; function revokeKey(address keyId) external; function updateSpendingLimit( address keyId, address token, uint256 newLimit ) external; function getKey( address account, address keyId ) external view returns (KeyInfo memory); function getRemainingLimit( address account, address keyId, address token ) external view returns (uint256); function getTransactionKey() external view returns (address); } ```