viem 2.57.4 → 2.57.6

package/tempo/actions/accessKey.ts

@@ -1,9 +1,9 @@
 import type { Address } from 'abitype'
 import type * as RpcSchema from 'ox/RpcSchema'
 import {
+  AccountConfig,
+  AccountOperation,
   KeyAuthorization,
-  MultisigConfig,
-  MultisigOperation,
   type RpcSchemaTempo,
   SignatureEnvelope,
 } from 'ox/tempo'
@@ -21,36 +21,52 @@ import { writeContractSync } from '../../actions/wallet/writeContractSync.js'
 import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
 import type { BaseErrorType } from '../../errors/base.js'
+import {
+  MethodNotFoundRpcError,
+  MethodNotSupportedRpcError,
+} from '../../errors/rpc.js'
 import type { Chain } from '../../types/chain.js'
 import type { ExtractAbiItem, GetEventArgs } from '../../types/contract.js'
 import type { Log, Log as viem_Log } from '../../types/log.js'
 import type { Hex } from '../../types/misc.js'
 import type { Compute, OneOf, UnionOmit } from '../../types/utils.js'
+import { formatAbiItem } from '../../utils/abi/formatAbiItem.js'
 import { parseEventLogs } from '../../utils/abi/parseEventLogs.js'
 import { isAddressEqual } from '../../utils/address/isAddressEqual.js'
 import * as Abis from '../Abis.js'
 import type {
   AccessKeyAccount,
-  MultisigAccount,
+  ConfigurableAccount,
   RootAccount,
 } from '../Account.js'
 import {
-  fromMultisig,
+  fromConfig,
   getKeyAuthorizationSignPayload,
   resolveAccessKey,
   signKeyAuthorization,
 } from '../Account.js'
 import * as Addresses from '../Addresses.js'
+import { parseApproval } from '../accounts/Signature.js'
+import type * as Errors from '../errors.js'
+import { TempoExecutionError } from '../errors.js'
 import * as Hardfork from '../Hardfork.js'
+import {
+  type Context,
+  formatAmount,
+  formatTime,
+  getFeeToken,
+  isTip20,
+  type Resolvers,
+  withExecutionError,
+} from '../internal/errors.js'
 import type {
   GetAccountParameter,
   ReadParameters,
   WriteParameters,
 } from '../internal/types.js'
 import { defineCall } from '../internal/utils.js'
-import { parseApproval } from '../multisig/Signature.js'
 import type { TransactionReceipt } from '../Transaction.js'
-import { getConfig } from './multisig.js'
+import { getConfig } from './accounts.js'
 
 /** @internal */
 const signatureTypes = {
@@ -149,7 +165,7 @@ export namespace authorize {
   export type ReturnValue = WriteContractReturnType
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 
   /** @internal */
   export async function inner<
@@ -174,7 +190,7 @@ export namespace authorize {
     const account_ = rest.account ?? client.account
     if (!account_) throw new Error('account is required.')
     if (!chainId) throw new Error('chainId is required.')
-    const keyAuthorization = await signAuthorization(client, {
+    const keyAuthorization = await signLocal(client, {
       account: account_,
       accessKey,
       chainId,
@@ -184,7 +200,13 @@ export namespace authorize {
       scopes,
       witness,
     })
-    return (await action(client, {
+    return (await withExecutionError(action, {
+      hints: {
+        KeyAlreadyExists: [
+          'This access key is already authorized. Update its spending limits instead.',
+        ],
+      },
+    })(client, {
       ...rest,
       keyAuthorization,
     } as never)) as never
@@ -273,7 +295,7 @@ export namespace authorizeSync {
   >
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -332,7 +354,7 @@ export namespace burnWitness {
   export type ReturnValue = WriteContractReturnType
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 
   /** @internal */
   export async function inner<
@@ -346,7 +368,7 @@ export namespace burnWitness {
   ): Promise<ReturnType<action>> {
     const { witness, ...rest } = parameters
     const call = burnWitness.call({ witness })
-    return (await action(client, {
+    return (await withExecutionError(action)(client, {
       ...rest,
       ...call,
     } as never)) as never
@@ -469,7 +491,7 @@ export namespace burnWitnessSync {
   >
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -506,7 +528,7 @@ export async function getMetadata<
   const { account: account_ = client.account, accessKey, ...rest } = parameters
   if (!account_) throw new Error('account is required.')
   const account = parseAccount(account_)
-  const result = await readContract(client, {
+  const result = await withExecutionError(readContract)(client, {
     ...rest,
     account: null as never,
     ...getMetadata.call({ account: account.address, accessKey }),
@@ -562,6 +584,8 @@ export namespace getMetadata {
       args: [account, resolveAccessKeyAddress(accessKey)],
     })
   }
+
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -610,21 +634,24 @@ export async function getRemainingLimit<
   // TODO: remove pre-t3 branch once mainnet is on t3.
   const hardfork = (client.chain as { hardfork?: string } | undefined)?.hardfork
   if (hardfork && Hardfork.lt(hardfork, 't3')) {
-    const remaining = await readContract(client, {
+    const remaining = await withExecutionError(readContract)(client, {
       ...rest,
       ...getRemainingLimit.call({ account: account.address, accessKey, token }),
     })
     return { remaining, periodEnd: undefined }
   }
 
-  const [remaining, periodEnd] = await readContract(client, {
-    ...rest,
-    ...getRemainingLimit.callWithPeriod({
-      account: account.address,
-      accessKey,
-      token,
-    }),
-  })
+  const [remaining, periodEnd] = await withExecutionError(readContract)(
+    client,
+    {
+      ...rest,
+      ...getRemainingLimit.callWithPeriod({
+        account: account.address,
+        accessKey,
+        token,
+      }),
+    },
+  )
   return { remaining, periodEnd }
 }
 
@@ -680,6 +707,8 @@ export namespace getRemainingLimit {
       args: [account, resolveAccessKeyAddress(accessKey), token],
     })
   }
+
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -721,7 +750,7 @@ export async function isAdmin<
   const { account: account_ = client.account, accessKey, ...rest } = parameters
   if (!account_) throw new Error('account is required.')
   const account = parseAccount(account_)
-  return readContract(client, {
+  return withExecutionError(readContract)(client, {
     ...rest,
     account: null as never,
     ...isAdmin.call({ account: account.address, accessKey }),
@@ -761,6 +790,8 @@ export namespace isAdmin {
       args: [account, resolveAccessKeyAddress(accessKey)],
     })
   }
+
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -797,7 +828,7 @@ export async function isWitnessBurned<
   const { account: account_ = client.account, witness, ...rest } = parameters
   if (!account_) throw new Error('account is required.')
   const account = parseAccount(account_)
-  return readContract(client, {
+  return withExecutionError(readContract)(client, {
     ...rest,
     account: null as never,
     ...isWitnessBurned.call({ account: account.address, witness }),
@@ -837,6 +868,8 @@ export namespace isWitnessBurned {
       args: [account, witness],
     })
   }
+
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -888,7 +921,7 @@ export namespace revoke {
   export type ReturnValue = WriteContractReturnType
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 
   /** @internal */
   export async function inner<
@@ -902,7 +935,7 @@ export namespace revoke {
   ): Promise<ReturnType<action>> {
     const { accessKey, ...rest } = parameters
     const call = revoke.call({ accessKey })
-    return (await action(client, {
+    return (await withExecutionError(action)(client, {
       ...rest,
       ...call,
     } as never)) as never
@@ -1024,7 +1057,7 @@ export namespace revokeSync {
   >
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -1058,13 +1091,13 @@ export async function prepareAuthorization<
   if (!account_) throw new Error('account is required.')
   if (!chainId) throw new Error('chainId is required.')
   const parsed = parseAccount(account_)
-  const multisigState = await (async () => {
-    if ('multisig' in parameters) return parameters.multisig
-    if (parsed.source !== 'multisig') return undefined
-    const account = parsed as MultisigAccount
+  const configurableState = await (async () => {
+    if ('configurable' in parameters) return parameters.configurable
+    if (parsed.source !== 'configurable') return undefined
+    const account = parsed as ConfigurableAccount
     if (!account.config)
       throw new Error(
-        'A multisig config is required to prepare a key authorization.',
+        'An account config is required to prepare a key authorization.',
       )
     return { config: account.config }
   })()
@@ -1077,10 +1110,10 @@ export async function prepareAuthorization<
     },
   )
   const signPayload =
-    parsed.source === 'multisig' && multisigState
-      ? MultisigConfig.getSignPayload({
+    parsed.source === 'configurable' && configurableState
+      ? AccountConfig.getSignPayload({
           account: parsed.address,
-          config: multisigState.config,
+          config: configurableState.config,
           payload: authorizationSignPayload,
         })
       : authorizationSignPayload
@@ -1088,7 +1121,7 @@ export async function prepareAuthorization<
     ...parameters,
     account: parsed,
     chainId,
-    multisig: multisigState,
+    configurable: configurableState,
     signPayload,
   } as never
 }
@@ -1115,8 +1148,8 @@ export namespace prepareAuthorization {
     limits?:
       | { token: Address; limit: bigint; period?: number | undefined }[]
       | undefined
-    /** @internal Prepared multisig state. */
-    multisig?: signKeyAuthorization.Parameters['multisig']
+    /** @internal Prepared configurable account state. */
+    configurable?: signKeyAuthorization.Parameters['configurable']
     /** Call scopes restricting which contracts/selectors this key can call. */
     scopes?: KeyAuthorization.Scope[] | undefined
     /**
@@ -1136,22 +1169,81 @@ export namespace prepareAuthorization {
     Omit<Parameters<Account | undefined>, 'account' | 'chainId'> & {
       account: Account
       chainId: number
-      multisig: signKeyAuthorization.Parameters['multisig']
-      /** Payload that the authorizing account or multisig owners sign. */
+      configurable: signKeyAuthorization.Parameters['configurable']
+      /** Payload that the authorizing account or owners sign. */
       signPayload: Hex
     }
   >
 }
 
+/**
+ * Saves a signed key authorization to a relay with key authorization storage.
+ *
+ * The relay attaches the authorization to the access key's next transaction until
+ * the key is active onchain. Use this for authorizations signed outside
+ * {@link signAuthorization}, such as on another device. Requires a relay running the
+ * `Relay.keyAuthorization` plugin.
+ *
+ * @example
+ * ```ts
+ * import { createClient, http } from 'viem'
+ * import { tempo } from 'viem/chains'
+ * import { Actions, withRelay } from 'viem/tempo'
+ *
+ * const client = createClient({
+ *   chain: tempo,
+ *   transport: withRelay(http(), http('https://relay.example.com'), {
+ *     keyAuthorization: true,
+ *   }),
+ * })
+ *
+ * await Actions.accessKey.saveAuthorization(client, {
+ *   keyAuthorization,
+ * })
+ * ```
+ *
+ * @param client - Client.
+ * @param parameters - Parameters.
+ */
+export async function saveAuthorization<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: saveAuthorization.Parameters,
+): Promise<saveAuthorization.ReturnValue> {
+  const { keyAuthorization } = parameters
+  await client.request<relay_saveKeyAuthorization>({
+    method: 'relay_saveKeyAuthorization',
+    params: [KeyAuthorization.toRpc(keyAuthorization)],
+  })
+}
+
+export namespace saveAuthorization {
+  export type Parameters = {
+    /** Signed key authorization to save. */
+    keyAuthorization: KeyAuthorization.Signed
+  }
+
+  export type ReturnValue = void
+
+  // TODO: exhaustive error type
+  export type ErrorType = BaseErrorType
+}
+
 /**
  * Signs a key authorization for an access key.
  *
  * Use {@link prepareAuthorization} before this action when signing requires
  * transient user activation.
  *
+ * When the client transport is a relay with the `Relay.keyAuthorization` plugin,
+ * an authorization signed by the account is saved to the relay, which attaches it
+ * to the access key's next transaction.
+ *
  * @param client - Client.
  * @param parameters - Authorization fields, or a stored operation hash.
- * @returns A signed key authorization with multisig operation metadata when coordinated.
+ * @returns A signed key authorization with account operation metadata when coordinated.
  */
 export function signAuthorization<
   chain extends Chain | undefined,
@@ -1185,13 +1277,13 @@ export async function signAuthorization<
     const owner_ = parameters_.owner
     if (!owner_ || typeof owner_ === 'string')
       throw new Error(
-        'A local owner account is required to approve a multisig key authorization.',
+        'A local owner account is required to approve a configurable account key authorization.',
       )
     const owner = parseAccount(owner_)
     const sign = owner.sign
     if (!sign)
       throw new Error(
-        'A local owner account is required to approve a multisig key authorization.',
+        'A local owner account is required to approve a configurable account key authorization.',
       )
 
     const request = await (async () => {
@@ -1214,16 +1306,16 @@ export async function signAuthorization<
         const config = await getConfig(client, { address })
         if (config) return config
         throw new Error(
-          `No current multisig config is cached for account ${address}. Provide the current config.`,
+          `No current account config is cached for account ${address}. Provide the current config.`,
         )
       })()
       const account = (() => {
-        if (config.version !== 0n) return fromMultisig({ address, ...config })
+        if (config.version !== 0n) return fromConfig({ address, ...config })
         const { version: _, ...initialConfig } = config
-        return fromMultisig({ address: 'infer', ...initialConfig })
+        return fromConfig({ address: 'infer', ...initialConfig })
       })()
       if (!isAddressEqual(account.address, address))
-        throw new Error('Initial multisig config does not match the account.')
+        throw new Error('Initial account config does not match the account.')
       const prepared = await prepareAuthorization(client, {
         ...authorization,
         account,
@@ -1250,79 +1342,81 @@ export async function signAuthorization<
       return { keyAuthorization: KeyAuthorization.toRpc(keyAuthorization) }
     })()
 
-    type multisig_approveKeyAuthorization = Extract<
-      RpcSchema.ToViem<RpcSchemaTempo.Multisig>[number],
-      { Method: 'multisig_approveKeyAuthorization' }
+    type account_approveKeyAuthorization = Extract<
+      RpcSchema.ToViem<RpcSchemaTempo.Account>[number],
+      { Method: 'account_approveKeyAuthorization' }
     >
-    const operation = await client.request<multisig_approveKeyAuthorization>({
-      method: 'multisig_approveKeyAuthorization',
+    const operation = await client.request<account_approveKeyAuthorization>({
+      method: 'account_approveKeyAuthorization',
       params: [request],
     })
-    const multisig = MultisigOperation.fromRpc(operation)
+    const operation_ = AccountOperation.fromRpc(operation)
     const keyAuthorization = KeyAuthorization.deserialize(
       await (async () => {
-        if (multisig.status === 'success') return multisig.keyAuthorization
-        const approvals = await MultisigOperation.selectApprovals({
-          account: multisig.account,
-          approvals: multisig.approvals,
-          config: multisig.config,
-          hash: multisig.hash,
+        if (operation_.status === 'success') return operation_.keyAuthorization
+        const approvals = await AccountOperation.selectApprovals({
+          account: operation_.account,
+          approvals: operation_.approvals,
+          config: operation_.config,
+          hash: operation_.hash,
         })
-        return MultisigOperation.serializeKeyAuthorization(
-          multisig.keyAuthorization,
+        return AccountOperation.serializeKeyAuthorization(
+          operation_.keyAuthorization,
           {
-            account: multisig.account,
+            account: operation_.account,
             approvals:
               approvals.selectedApprovals.length > 0
                 ? approvals.selectedApprovals
                 : approvals.approvals.slice(0, 1),
-            config: multisig.config,
+            config: operation_.config,
           },
         )
       })(),
     )
     if (!keyAuthorization.signature)
-      throw new Error('Expected a signed multisig key authorization.')
+      throw new Error(
+        'Expected a signed configurable account key authorization.',
+      )
     return {
       ...keyAuthorization,
-      hash: multisig.hash,
-      multisig,
-      status: multisig.status,
+      hash: operation_.hash,
+      operation: operation_,
+      status: operation_.status,
     } as never
   }
 
-  const prepared = (
-    'signPayload' in parameters
-      ? parameters
-      : await prepareAuthorization(
-          client,
-          parameters as signAuthorization.LocalParameters<account>,
-        )
-  ) as prepareAuthorization.ReturnValue
-  const {
-    accessKey,
-    account: account_,
-    chainId,
-    multisig: multisigState,
-    signPayload: _,
-    ...rest
-  } = prepared
-  return signKeyAuthorization(account_ as never, {
-    chainId: BigInt(chainId),
-    key: accessKey,
-    multisig: multisigState,
-    ...rest,
-  }) as never
+  const keyAuthorization = await signLocal(
+    client,
+    parameters as signAuthorization.LocalParameters<account>,
+  )
+  const signer = parameters.account ?? client.account
+  // Relays with key authorization storage attach it to the access key's next
+  // transaction. Admin-signed authorizations can only be submitted by the admin key.
+  if (
+    (client.transport as { keyAuthorization?: boolean }).keyAuthorization &&
+    signer &&
+    parseAccount(signer).source !== 'accessKey'
+  )
+    await saveAuthorization(client, { keyAuthorization }).catch((error) => {
+      // Remote relays without key authorization storage do not expose this method.
+      if (
+        error instanceof MethodNotFoundRpcError ||
+        error instanceof MethodNotSupportedRpcError
+      )
+        return
+      throw error
+    })
+  return keyAuthorization
 }
 
 export namespace signAuthorization {
   /** Initial coordinated key authorization parameters. */
   export type CoordinatedInitialParameters = Omit<
     prepareAuthorization.Parameters<Account>,
-    'account' | 'multisig'
+    'account' | 'configurable'
   > & {
-    /** Multisig account being authorized. */
-    account: Address | MultisigAccount
+    /** Configurable account being authorized. */
+    account: Address | ConfigurableAccount
     /** Local owner that approves the authorization. */
     owner: RootAccount
   }
@@ -1331,7 +1425,7 @@ export namespace signAuthorization {
   export type CoordinatedParameters = OneOf<
     | CoordinatedInitialParameters
     | {
-        /** Stored multisig operation hash. */
+        /** Stored account operation hash. */
         hash: Hex
         /** Local owner that approves the authorization. */
         owner: RootAccount
@@ -1342,7 +1436,7 @@ export namespace signAuthorization {
   export type LocalParameters<
     account extends Account | undefined = Account | undefined,
   > = prepareAuthorization.Parameters<account> & {
-    /** Serialized approvals from external multisig owners. */
+    /** Serialized approvals from external owners. */
     signatures?: readonly SignatureEnvelope.Serialized[] | undefined
   }
 
@@ -1357,12 +1451,12 @@ export namespace signAuthorization {
   /** Coordinated return value for {@link signAuthorization}. */
   export type CoordinatedReturnValue = Compute<
     ReturnValue & {
-      /** Deterministic multisig operation hash. */
+      /** Deterministic account operation hash. */
       hash: Hex
-      /** Current multisig operation. */
-      multisig: MultisigOperation.KeyAuthorizationOperation
-      /** Current multisig operation status. */
-      status: MultisigOperation.KeyAuthorizationOperation['status']
+      /** Current account operation. */
+      operation: AccountOperation.KeyAuthorizationOperation
+      /** Current account operation status. */
+      status: AccountOperation.KeyAuthorizationOperation['status']
     }
   >
 
@@ -1370,6 +1464,41 @@ export namespace signAuthorization {
   export type ErrorType = BaseErrorType
 }
 
+/** Signs a key authorization locally without saving it to a relay. */
+async function signLocal<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: signAuthorization.LocalParameters<account>,
+): Promise<signAuthorization.ReturnValue> {
+  const prepared = (
+    'signPayload' in parameters
+      ? parameters
+      : await prepareAuthorization(client, parameters)
+  ) as prepareAuthorization.ReturnValue
+  const {
+    accessKey,
+    account: account_,
+    chainId,
+    configurable: configurableState,
+    signPayload: _,
+    ...rest
+  } = prepared
+  return signKeyAuthorization(account_ as never, {
+    chainId: BigInt(chainId),
+    key: accessKey,
+    configurable: configurableState,
+    ...rest,
+  })
+}
+
+type relay_saveKeyAuthorization = {
+  Method: 'relay_saveKeyAuthorization'
+  Parameters: [KeyAuthorization.Rpc]
+  ReturnType: null
+}
+
 /**
  * Updates the spending limit for a specific token on an authorized access key.
  *
@@ -1425,7 +1554,7 @@ export namespace updateLimit {
   export type ReturnValue = WriteContractReturnType
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 
   /** @internal */
   export async function inner<
@@ -1439,7 +1568,7 @@ export namespace updateLimit {
   ): Promise<ReturnType<action>> {
     const { accessKey, token, limit, ...rest } = parameters
     const call = updateLimit.call({ accessKey, token, limit })
-    return (await action(client, {
+    return (await withExecutionError(action)(client, {
       ...rest,
       ...call,
     } as never)) as never
@@ -1573,7 +1702,7 @@ export namespace updateLimitSync {
   }
 
   // TODO: exhaustive error type
-  export type ErrorType = BaseErrorType
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /**
@@ -1854,7 +1983,7 @@ export async function verifyHash<
   parameters: verifyHash.Parameters,
 ): Promise<verifyHash.ReturnValue> {
   const { account, admin, hash, signature, ...rest } = parameters
-  return readContract(client, {
+  return withExecutionError(readContract)(client, {
     ...rest,
     ...verifyHash.call({ account, admin, hash, signature }),
   })
@@ -1900,6 +2029,8 @@ export namespace verifyHash {
       args: [account, hash, signature],
     })
   }
+
+  export type ErrorType = Errors.ExecutionErrorType | BaseErrorType
 }
 
 /** @internal */
@@ -1909,3 +2040,443 @@ function resolveAccessKeyAddress(
   if (typeof accessKey === 'string') return accessKey
   return accessKey.accessKeyAddress
 }
+
+// Errors
+
+/** Errors this module throws for decoded Tempo errors. Narrow with `error.name`. */
+export type ExecutionErrorType =
+  | AccessKeyAlreadyExistsErrorType
+  | AccessKeyCallNotAllowedErrorType
+  | AccessKeyErrorType
+  | AccessKeyExpiredErrorType
+  | AccessKeyExpiryInPastErrorType
+  | AccessKeySignatureTypeMismatchErrorType
+  | AccessKeySpendingLimitExceededErrorType
+
+/** `AccessKeyError` with a literal `name`, for narrowing. */
+export type AccessKeyErrorType = AccessKeyError & { name: 'AccessKeyError' }
+
+/** Thrown when an access key fails an `AccountKeychain` check. */
+export class AccessKeyError<
+  decoded extends
+    Errors.TempoExecutionError.Decoded = Errors.TempoExecutionError.Decoded,
+> extends TempoExecutionError<decoded> {
+  /** Root account that owns the access key. */
+  account: Address
+  /** Access key address. */
+  accessKey: Address
+
+  constructor(
+    parameters: AccessKeyError.Parameters,
+    options: Errors.TempoExecutionError.Options = {},
+  ) {
+    const { account, accessKey } = parameters
+    super(parameters, {
+      shortMessage: `Access key "${accessKey}" failed: ${parameters.error.message}`,
+      ...options,
+      details: { account, 'access key': accessKey, ...options.details },
+      docsPath: '/tempo/guides/access-keys/manage',
+      name: options.name ?? 'AccessKeyError',
+    })
+    this.account = account
+    this.accessKey = accessKey
+  }
+}
+
+export declare namespace AccessKeyError {
+  /** Constructor parameters. */
+  type Parameters = Errors.TempoExecutionError.Parameters & {
+    /** Root account that owns the access key. */
+    account: Address
+    /** Access key address. */
+    accessKey: Address
+  }
+}
+
+/** `AccessKeySpendingLimitExceededError` with a literal `name`, for narrowing. */
+export type AccessKeySpendingLimitExceededErrorType =
+  AccessKeySpendingLimitExceededError & {
+    name: 'AccessKeySpendingLimitExceededError'
+  }
+
+/** Thrown when a transfer, approval, or fee payment exceeds an access key's spending limit. */
+export class AccessKeySpendingLimitExceededError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'SpendingLimitExceeded'>
+> {
+  /** Amount the call tried to spend, when known. */
+  amount: bigint | undefined
+  /** Token decimals, when known. */
+  decimals: number | undefined
+  /** Whether the fee payment, rather than the call, exceeded the limit. */
+  fee: boolean
+  /** End of the current period (Unix seconds) for periodic limits, when known. */
+  periodEnd: bigint | undefined
+  /** Remaining limit for `token`, when known. */
+  remaining: bigint | undefined
+  /** Token the limit applies to, when known. */
+  token: Address | undefined
+
+  constructor(parameters: AccessKeySpendingLimitExceededError.Parameters) {
+    const { amount, decimals, fee, periodEnd, remaining, token } = parameters
+    super(parameters, {
+      details: {
+        token,
+        amount: formatAmount(amount, decimals),
+        remaining: formatAmount(remaining, decimals),
+        'exceeded by':
+          amount !== undefined && remaining !== undefined
+            ? formatAmount(amount - remaining, decimals)
+            : undefined,
+        'resets at': formatTime(periodEnd),
+      },
+      name: 'AccessKeySpendingLimitExceededError',
+      shortMessage: `Access key "${parameters.accessKey}" exceeded its spending limit${token ? ` for token "${token}"` : ''}${fee ? ' while paying fees' : ''}.`,
+    })
+    this.amount = amount
+    this.decimals = decimals
+    this.fee = fee
+    this.periodEnd = periodEnd
+    this.remaining = remaining
+    this.token = token
+  }
+}
+
+export declare namespace AccessKeySpendingLimitExceededError {
+  /** Constructor parameters. */
+  type Parameters = AccessKeyError.Parameters & {
+    /** Amount the call tried to spend, when known. */
+    amount?: bigint | undefined
+    /** Token decimals, when known. */
+    decimals?: number | undefined
+    /** Whether the fee payment, rather than the call, exceeded the limit. */
+    fee: boolean
+    /** End of the current period (Unix seconds) for periodic limits, when known. */
+    periodEnd?: bigint | undefined
+    /** Remaining limit for `token`, when known. */
+    remaining?: bigint | undefined
+    /** Token the limit applies to, when known. */
+    token?: Address | undefined
+  }
+}
+
+/** `AccessKeyExpiredError` with a literal `name`, for narrowing. */
+export type AccessKeyExpiredErrorType = AccessKeyExpiredError & {
+  name: 'AccessKeyExpiredError'
+}
+
+/** Thrown when a transaction is signed with an expired access key. */
+export class AccessKeyExpiredError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'KeyExpired'>
+> {
+  /** Expiry (Unix seconds), when known. */
+  expiry: bigint | undefined
+
+  constructor(
+    parameters: AccessKeyError.Parameters & { expiry?: bigint | undefined },
+  ) {
+    super(parameters, {
+      details: { 'expired at': formatTime(parameters.expiry) },
+      name: 'AccessKeyExpiredError',
+      shortMessage: `Access key "${parameters.accessKey}" has expired.`,
+    })
+    this.expiry = parameters.expiry
+  }
+}
+
+/** `AccessKeyCallNotAllowedError` with a literal `name`, for narrowing. */
+export type AccessKeyCallNotAllowedErrorType = AccessKeyCallNotAllowedError & {
+  name: 'AccessKeyCallNotAllowedError'
+}
+
+/** Thrown when an access key's scopes do not allow a call. */
+export class AccessKeyCallNotAllowedError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'CallNotAllowed'>
+> {
+  /** Function selector of the rejected call, when known. */
+  selector: Hex | undefined
+  /** Target of the rejected call, when known. */
+  target: Address | undefined
+
+  constructor(
+    parameters: AccessKeyError.Parameters & {
+      selector?: Hex | undefined
+      target?: Address | undefined
+    },
+  ) {
+    const { selector, target } = parameters
+    super(parameters, {
+      details: { target, selector },
+      name: 'AccessKeyCallNotAllowedError',
+      shortMessage: `Access key "${parameters.accessKey}" is not allowed to make this call.`,
+    })
+    this.selector = selector
+    this.target = target
+  }
+}
+
+/** `AccessKeyAlreadyExistsError` with a literal `name`, for narrowing. */
+export type AccessKeyAlreadyExistsErrorType = AccessKeyAlreadyExistsError & {
+  name: 'AccessKeyAlreadyExistsError'
+}
+
+/** Thrown when authorizing an access key that is already authorized. */
+export class AccessKeyAlreadyExistsError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'KeyAlreadyExists'>
+> {
+  /** Expiry (Unix seconds) of the existing key, when known. */
+  expiry: bigint | undefined
+  /** Whether the existing key enforces spending limits, when known. */
+  limited: boolean | undefined
+
+  constructor(
+    parameters: AccessKeyError.Parameters & {
+      expiry?: bigint | undefined
+      limited?: boolean | undefined
+    },
+  ) {
+    const { expiry, limited } = parameters
+    super(parameters, {
+      details: {
+        expires: formatTime(expiry),
+        'spending limits':
+          limited === undefined ? undefined : limited ? 'enforced' : 'none',
+      },
+      name: 'AccessKeyAlreadyExistsError',
+      shortMessage: `Access key "${parameters.accessKey}" is already authorized on account "${parameters.account}".`,
+    })
+    this.expiry = expiry
+    this.limited = limited
+  }
+}
+
+/** `AccessKeySignatureTypeMismatchError` with a literal `name`, for narrowing. */
+export type AccessKeySignatureTypeMismatchErrorType =
+  AccessKeySignatureTypeMismatchError & {
+    name: 'AccessKeySignatureTypeMismatchError'
+  }
+
+/** Thrown when an access key signs with a different key type than it was authorized with. */
+export class AccessKeySignatureTypeMismatchError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'SignatureTypeMismatch'>
+> {
+  /** Key type the access key was authorized with. */
+  expected: KeyType | undefined
+  /** Key type of the signature. */
+  actual: KeyType | undefined
+
+  constructor(parameters: AccessKeyError.Parameters) {
+    const [expected, actual] = (parameters.error.args ?? []).map(
+      (type) => signatureTypes[Number(type) as keyof typeof signatureTypes],
+    )
+    super(parameters, {
+      details: { expected, actual },
+      name: 'AccessKeySignatureTypeMismatchError',
+      shortMessage: `Access key "${parameters.accessKey}" signed with a ${actual ?? 'different'} key, but was authorized as a ${expected ?? 'different'} key.`,
+    })
+    this.expected = expected
+    this.actual = actual
+  }
+}
+
+/** `AccessKeyExpiryInPastError` with a literal `name`, for narrowing. */
+export type AccessKeyExpiryInPastErrorType = AccessKeyExpiryInPastError & {
+  name: 'AccessKeyExpiryInPastError'
+}
+
+/** Thrown when authorizing an access key with an expiry that has passed or is too soon. */
+export class AccessKeyExpiryInPastError extends AccessKeyError<
+  Errors.TempoExecutionError.Decoded<'ExpiryInPast'>
+> {
+  /** Requested expiry (Unix seconds), when known. */
+  expiry: bigint | undefined
+  /** Earliest allowed expiry (Unix seconds), when known. */
+  minimum: bigint | undefined
+
+  constructor(
+    parameters: AccessKeyError.Parameters & {
+      expiry?: bigint | undefined
+      minimum?: bigint | undefined
+    },
+  ) {
+    const { expiry, minimum } = parameters
+    super(parameters, {
+      details: { expiry: formatTime(expiry), minimum: formatTime(minimum) },
+      name: 'AccessKeyExpiryInPastError',
+      shortMessage: `Access key "${parameters.accessKey}" expiry must be later${minimum ? ` than ${formatTime(minimum)}` : ''}.`,
+    })
+    this.expiry = expiry
+    this.minimum = minimum
+  }
+}
+
+type KeyType = (typeof signatureTypes)[keyof typeof signatureTypes]
+
+const keychain = {
+  address: Addresses.accountKeychain,
+  abi: Abis.accountKeychain,
+} as const
+
+/** Signer and key for errors raised while validating the signing access key. */
+function getSigner(context: Context) {
+  const { call, parameters, signer } = context
+  if (!signer?.accessKey) return undefined
+  // Key management calls and authorizations of another key fail about that key, not the signer.
+  if (call && isAddressEqual(call.address, Addresses.accountKeychain))
+    return undefined
+  const authorized = parameters.keyAuthorization?.address as Address | undefined
+  if (authorized && !isAddressEqual(authorized, signer.accessKey))
+    return undefined
+  return {
+    ...context.base,
+    account: signer.address,
+    accessKey: signer.accessKey,
+  }
+}
+
+/** Fee payer and key for fee payment errors. External fee payers cannot be resolved. */
+function getFeePayer(context: Context) {
+  const { feePayer } = context.parameters
+  if (typeof feePayer !== 'object') return undefined
+  const account = parseAccount(feePayer)
+  if (account.source !== 'accessKey' || !('accessKeyAddress' in account))
+    return undefined
+  return {
+    ...context.base,
+    account: account.address,
+    accessKey: account.accessKeyAddress as Address,
+  }
+}
+
+/** Account and key for errors raised while authorizing a key. */
+function getAuthorization(context: Context) {
+  const { call, parameters, signer } = context
+  const accessKey =
+    (parameters.keyAuthorization?.address as Address | undefined) ??
+    call?.arg<Address>('keyId')
+  if (!signer || !accessKey) return undefined
+  return { ...context.base, account: signer.address, accessKey }
+}
+
+/** @internal */
+export const errorResolvers: Resolvers = {
+  // Fallback for `AccountKeychain` errors without a specific resolver below.
+  ...Object.fromEntries(
+    Abis.accountKeychain.flatMap((item) =>
+      item.type === 'error'
+        ? [
+            [
+              formatAbiItem(item),
+              (context: Context) => {
+                const parameters = getSigner(context)
+                return parameters && new AccessKeyError(parameters)
+              },
+            ],
+          ]
+        : [],
+    ),
+  ),
+  'CallNotAllowed()': (context) => {
+    const parameters = getSigner(context)
+    if (!parameters) return undefined
+    return new AccessKeyCallNotAllowedError({
+      ...parameters,
+      selector: (context.parameters.data as Hex | undefined)?.slice(
+        0,
+        10,
+      ) as Hex,
+      target: context.call?.address ?? context.parameters.to,
+    })
+  },
+  'ExpiryInPast()': (context) => {
+    const parameters = getAuthorization(context)
+    if (!parameters) return undefined
+    const [, expiry, minimum] =
+      /expiry (\d+) <= min allowed (\d+)/.exec(context.details) ?? []
+    const requested =
+      context.parameters.keyAuthorization?.expiry ??
+      context.call?.arg<bigint>('expiry') ??
+      context.call?.arg<{ expiry: bigint }>('config')?.expiry
+    return new AccessKeyExpiryInPastError({
+      ...parameters,
+      expiry: expiry
+        ? BigInt(expiry)
+        : requested === undefined || requested === null
+          ? undefined
+          : BigInt(requested),
+      minimum: minimum ? BigInt(minimum) : undefined,
+    })
+  },
+  'KeyAlreadyExists()': async (context) => {
+    const parameters = getAuthorization(context)
+    if (!parameters) return undefined
+    const [key] = await context.read([
+      {
+        ...keychain,
+        functionName: 'getKey',
+        args: [parameters.account, parameters.accessKey],
+      },
+    ])
+    return new AccessKeyAlreadyExistsError({
+      ...parameters,
+      expiry: key?.result?.expiry,
+      limited: key?.result?.enforceLimits,
+    })
+  },
+  'KeyExpired()': async (context) => {
+    const parameters = getSigner(context)
+    if (!parameters) return undefined
+    const [key] = await context.read([
+      {
+        ...keychain,
+        functionName: 'getKey',
+        args: [parameters.account, parameters.accessKey],
+      },
+    ])
+    return new AccessKeyExpiredError({
+      ...parameters,
+      expiry: key?.result?.expiry,
+    })
+  },
+  'SignatureTypeMismatch(uint8,uint8)': (context) => {
+    const parameters = getSigner(context) ?? getAuthorization(context)
+    return parameters && new AccessKeySignatureTypeMismatchError(parameters)
+  },
+  'SpendingLimitExceeded()': async (context) => {
+    // Without revert data, the fee payment exceeded the limit.
+    const fee = context.validation
+    const parameters =
+      fee && context.parameters.feePayer
+        ? getFeePayer(context)
+        : getSigner(context)
+    if (!parameters) return undefined
+    const token = fee
+      ? getFeeToken(context)
+      : isTip20(context.call?.address)
+        ? context.call.address
+        : undefined
+    if (!token)
+      return new AccessKeySpendingLimitExceededError({
+        ...parameters,
+        fee,
+        hints: fee
+          ? [...parameters.hints, 'Pay fees with another token.']
+          : parameters.hints,
+      })
+    const args = [parameters.account, parameters.accessKey, token] as const
+    const [withPeriod, legacy, decimals] = await context.read([
+      // `getRemainingLimitWithPeriod` is T3+; `getRemainingLimit` covers earlier hardforks.
+      { ...keychain, functionName: 'getRemainingLimitWithPeriod', args },
+      { ...keychain, functionName: 'getRemainingLimit', args },
+      { address: token, abi: Abis.tip20, functionName: 'decimals' },
+    ])
+    return new AccessKeySpendingLimitExceededError({
+      ...parameters,
+      amount: fee ? undefined : context.call?.arg<bigint>('amount'),
+      decimals: decimals?.result,
+      fee,
+      periodEnd: withPeriod?.result?.[1] || undefined,
+      remaining: withPeriod?.result?.[0] ?? legacy?.result,
+      token,
+    })
+  },
+}