viem 2.57.4 → 2.57.6

package/tempo/chainConfig.ts

@@ -1,9 +1,9 @@
 import type { Address } from 'abitype'
 import * as Hex from 'ox/Hex'
 import {
-  MultisigConfig,
-  MultisigOperation,
-  type MultisigSimulation,
+  AccountConfig,
+  AccountOperation,
+  type AccountSimulation,
   SignatureEnvelope,
   type TokenId,
 } from 'ox/tempo'
@@ -20,9 +20,9 @@ import { defineTransactionRequest } from '../utils/formatters/transactionRequest
 import { getAction } from '../utils/getAction.js'
 import { keccak256 } from '../utils/hash/keccak256.js'
 import type { SerializeTransactionFn } from '../utils/transaction/serializeTransaction.js'
-import type { Account, MultisigAccount } from './Account.js'
+import type { Account, ConfigurableAccount } from './Account.js'
 import { getMetadata } from './actions/accessKey.js'
-import { getConfig } from './actions/multisig.js'
+import { getConfig } from './actions/accounts.js'
 import * as Formatters from './Formatters.js'
 import type { Hardfork } from './Hardfork.js'
 import * as Concurrent from './internal/concurrent.js'
@@ -55,7 +55,7 @@ export const chainConfig = {
   prepareTransactionRequest: [
     async (r, { client, phase }) => {
       const request = r as Transaction.TransactionRequest & {
-        account?: Account | MultisigAccount | undefined
+        account?: Account | ConfigurableAccount | undefined
         chainId?: number | undefined
         chain?:
           | (Chain & {
@@ -67,8 +67,8 @@ export const chainConfig = {
         hash?: Hex.Hex | undefined
         keyData?: Hex.Hex | undefined
         keyType?: 'p256' | 'secp256k1' | 'webAuthn' | undefined
-        multisigSimulation?: MultisigSimulation.Spec | undefined
-        owner?: Account | MultisigAccount | Address | undefined
+        accountSimulation?: AccountSimulation.Spec | undefined
+        owner?: Account | ConfigurableAccount | Address | undefined
         signatures?: readonly unknown[] | undefined
       }
 
@@ -76,18 +76,18 @@ export const chainConfig = {
         if (
           !request.account ||
           typeof request.account === 'string' ||
-          request.account.source !== 'multisig'
+          request.account.source !== 'configurable'
         )
           throw new Error(
-            'A local multisig account is required to approve a stored multisig transaction.',
+            'A local configurable account is required to approve a stored configurable account transaction.',
           )
         if (!request.owner || typeof request.owner === 'string')
           throw new Error(
-            'A local owner account is required to approve a stored multisig transaction.',
+            'A local owner account is required to approve a stored configurable account transaction.',
           )
         if (request.owner.source !== 'root')
           throw new Error(
-            'A Tempo owner account is required to approve a stored multisig transaction.',
+            'A Tempo owner account is required to approve a stored configurable account transaction.',
           )
         const transaction = await getAction(
           client,
@@ -95,28 +95,28 @@ export const chainConfig = {
           'getTransaction',
         )({ hash: request.hash })
         const operation =
-          'multisig' in transaction
-            ? (transaction.multisig as
-                | MultisigOperation.TransactionOperation
+          'operation' in transaction
+            ? (transaction.operation as
+                | AccountOperation.TransactionOperation
                 | undefined)
             : undefined
         if (!operation)
-          throw new Error('Expected a multisig operation transaction.')
+          throw new Error('Expected an account operation transaction.')
         if (!isAddressEqual(operation.account, request.account.address))
           throw new Error(
-            'Multisig operation account does not match the requested account.',
+            'Account operation account does not match the requested account.',
           )
         const storedTransaction = Transaction.deserialize(
           operation.transaction as Transaction.TransactionSerializedTempo,
         )
-        const hash = MultisigOperation.getHash({
+        const hash = AccountOperation.getHash({
           account: operation.account,
           config: operation.config,
           transaction: operation.transaction,
           type: 'transaction',
         })
         if (hash.toLowerCase() !== request.hash.toLowerCase())
-          throw new Error('Multisig operation hash does not match transaction.')
+          throw new Error('Account operation hash does not match transaction.')
         return {
           ...storedTransaction,
           // Serialized zero values must not trigger a new fill of an approved transaction.
@@ -125,7 +125,7 @@ export const chainConfig = {
           maxPriorityFeePerGas: storedTransaction.maxPriorityFeePerGas ?? 0n,
           account: request.account,
           from: operation.account,
-          multisigSimulation: getMultisigSimulation({
+          accountSimulation: getAccountSimulation({
             config: operation.config,
             local: request.account,
           }),
@@ -151,40 +151,40 @@ export const chainConfig = {
         return request as unknown as typeof r
       }
 
-      const multisigIdentity = (() => {
-        if (request.account?.source === 'multisig')
+      const configurableIdentity = (() => {
+        if (request.account?.source === 'configurable')
           return {
             account: request.account.address,
-            config: (request.account as MultisigAccount).config,
-            local: request.account as MultisigAccount,
+            config: (request.account as ConfigurableAccount).config,
+            local: request.account as ConfigurableAccount,
           }
         return undefined
       })()
-      if (request.owner && !multisigIdentity)
+      if (request.owner && !configurableIdentity)
         throw new Error(
-          'A multisig account is required when an owner is provided.',
+          'A configurable account is required when an owner is provided.',
         )
       if (request.owner && typeof request.owner === 'string')
         throw new Error(
-          'A local owner account is required to approve a multisig transaction.',
+          'A local owner account is required to approve a configurable account transaction.',
         )
       if (request.owner && request.owner.source !== 'root')
         throw new Error(
-          'A Tempo owner account is required to approve a multisig transaction.',
+          'A Tempo owner account is required to approve a configurable account transaction.',
         )
-      const coordinatedMultisig =
-        !!multisigIdentity &&
+      const coordinated =
+        !!configurableIdentity &&
         !!request.owner &&
-        (client.transport as { multisig?: boolean }).multisig === true
-      if (multisigIdentity) {
-        const { account, local } = multisigIdentity
+        (client.transport as { accounts?: boolean }).accounts === true
+      if (configurableIdentity) {
+        const { account, local } = configurableIdentity
         if (!account)
           throw new Error(
-            'A multisig account address is required with a current config.',
+            'A configurable account address is required with a current config.',
           )
         const config = await (async () => {
-          if (multisigIdentity.config) return multisigIdentity.config
-          if (!coordinatedMultisig) return undefined
+          if (configurableIdentity.config) return configurableIdentity.config
+          if (!coordinated) return undefined
           const cachedConfig = await getAction(
             client,
             getConfig,
@@ -192,16 +192,16 @@ export const chainConfig = {
           )({ address: account })
           if (!cachedConfig)
             throw new Error(
-              `No current multisig config is cached for account ${account}. Provide the current config.`,
+              `No current account config is cached for account ${account}. Provide the current config.`,
             )
           return cachedConfig
         })()
         if (!config)
           throw new Error(
-            'A multisig config is required to prepare a transaction.',
+            'An account config is required to prepare a transaction.',
           )
         request.from = account
-        request.multisigSimulation = getMultisigSimulation({
+        request.accountSimulation = getAccountSimulation({
           config,
           local,
         })
@@ -213,12 +213,12 @@ export const chainConfig = {
         if (request.nonceKey === 'expiring' || request.nonceKey === maxUint256)
           return true
         if (typeof request.nonceKey !== 'undefined') return false
-        if (multisigIdentity) return false
+        if (configurableIdentity) return false
         if (request.feePayer && typeof request.nonceKey === 'undefined')
           return true
         const account = request.account as
           | Account
-          | MultisigAccount
+          | ConfigurableAccount
           | Address
           | undefined
         const address = typeof account === 'string' ? account : account?.address
@@ -227,7 +227,7 @@ export const chainConfig = {
         return false
       })()
 
-      if (coordinatedMultisig && typeof request.nonceKey === 'undefined') {
+      if (coordinated && typeof request.nonceKey === 'undefined') {
         // A random nonce lane lets a stored approval ceremony remain valid
         // indefinitely without blocking other pending operations.
         request.nonceKey = Hex.toBigInt(Hex.random(31)) + 1n
@@ -294,17 +294,17 @@ export const chainConfig = {
     transaction: serializeTransaction,
     async transactionEnvelope({ serializedTransaction, transaction }) {
       const request = transaction as Transaction.TransactionSerializableTempo
-      if (!request.multisigSimulation) return serializedTransaction
+      if (!request.accountSimulation) return serializedTransaction
       try {
         SignatureEnvelope.deserialize(serializedTransaction)
       } catch {
         const transaction = Transaction.deserialize(
           serializedTransaction as Transaction.TransactionSerializedTempo,
         )
-        if (transaction.signature?.type === 'multisig')
+        if (transaction.signature?.type === 'configurable')
           return serializedTransaction
         throw new Error(
-          'A Tempo owner account is required to approve a multisig transaction.',
+          'A Tempo owner account is required to approve a configurable account transaction.',
         )
       }
       return await serializeTransaction({
@@ -402,11 +402,11 @@ export const chainConfig = {
 
 export type ChainConfig = typeof chainConfig
 
-/** Builds a bounded multisig spec for gas simulation. */
-function getMultisigSimulation(options: {
-  config: MultisigConfig.Config
-  local?: MultisigAccount | undefined
-}): MultisigSimulation.Spec {
+/** Builds a bounded account spec for gas simulation. */
+function getAccountSimulation(options: {
+  config: AccountConfig.Config
+  local?: ConfigurableAccount | undefined
+}): AccountSimulation.Spec {
   const { config, local } = options
   return {
     approvals: selectOwners(config).map((owner) => {
@@ -453,7 +453,7 @@ function randomValidAfter(): number {
 }
 
 /** Selects a deterministic minimum-cardinality owner quorum. */
-function selectOwners(config: MultisigConfig.Config) {
+function selectOwners(config: AccountConfig.Config) {
   const owners = [...config.owners].sort(
     (a, b) =>
       Number(b.weight) - Number(a.weight) ||
@@ -461,7 +461,7 @@ function selectOwners(config: MultisigConfig.Config) {
   )
   const selected: typeof owners = []
   let weight = 0
-  for (const owner of owners.slice(0, MultisigConfig.maxSignatures)) {
+  for (const owner of owners.slice(0, AccountConfig.maxSignatures)) {
     if (weight >= Number(config.threshold)) break
     selected.push(owner)
     weight += Number(owner.weight)

package/tempo/errors.ts

@@ -1,6 +1,16 @@
-import type { Address } from 'abitype'
+import type { AbiError, Address } from 'abitype'
 import type { Hex } from 'ox'
 import { BaseError } from '../errors/base.js'
+import { prettyPrint } from '../errors/transaction.js'
+import type * as accessKey from './actions/accessKey.js'
+import type * as amm from './actions/amm.js'
+import type * as channel from './actions/channel.js'
+import type * as dex from './actions/dex.js'
+import type * as fee from './actions/fee.js'
+import type * as nonce from './actions/nonce.js'
+import type * as policy from './actions/policy.js'
+import type * as token from './actions/token.js'
+import type * as ExecutionError from './ExecutionError.js'
 
 export type GetVaultEngineChangedErrorType = GetVaultEngineChangedError & {
   name: 'GetVaultEngineChangedError'
@@ -138,3 +148,106 @@ export class FeeTokenPausedError extends BaseError {
     })
   }
 }
+
+/**
+ * Errors thrown by Tempo actions for decoded Tempo precompile errors. Narrow with `error.name`,
+ * then `error.errorName` for the base `TempoExecutionError`.
+ */
+export type ExecutionErrorType =
+  | TempoExecutionErrorType
+  | accessKey.ExecutionErrorType
+  | amm.ExecutionErrorType
+  | channel.ExecutionErrorType
+  | dex.ExecutionErrorType
+  | fee.ExecutionErrorType
+  | nonce.ExecutionErrorType
+  | policy.ExecutionErrorType
+  | token.ExecutionErrorType
+
+/** Union of `TempoExecutionError` per decoded error, so `errorName` narrows `args`. */
+export type TempoExecutionErrorType<
+  decoded extends TempoExecutionError.Decoded = TempoExecutionError.Decoded,
+> = decoded extends TempoExecutionError.Decoded
+  ? TempoExecutionError<decoded> & { name: 'TempoExecutionError' }
+  : never
+
+/** Thrown when a Tempo action fails with a decoded Tempo precompile error. */
+export class TempoExecutionError<
+  decoded extends TempoExecutionError.Decoded = TempoExecutionError.Decoded,
+> extends BaseError {
+  /** ABI item of the error. */
+  abiItem: AbiError
+  /** Decoded error arguments, when the revert data carried them. */
+  args: decoded['args']
+  /** Revert data, or the error selector when only the name is known. */
+  data: Hex.Hex
+  /** Error name from `Abis.coreErrors`. */
+  errorName: decoded['errorName']
+  /** Steps to resolve the error. */
+  hints: readonly string[]
+
+  constructor(
+    { cause, error, hints }: TempoExecutionError.Parameters,
+    {
+      details,
+      docsPath,
+      name = 'TempoExecutionError',
+      shortMessage = error.message,
+    }: TempoExecutionError.Options = {},
+  ) {
+    // Keep the call or request summary from the original error.
+    const summary = cause.metaMessages?.findIndex((message) =>
+      /^(Contract Call|Request Arguments):/.test(message),
+    )
+    super(shortMessage, {
+      cause,
+      docsPath,
+      metaMessages: [
+        ...(details ? [prettyPrint(details), ' '] : []),
+        ...(hints.length
+          ? ['How to fix:', ...hints.map((hint) => `- ${hint}`), ' ']
+          : []),
+        ...(summary !== undefined && summary >= 0
+          ? cause.metaMessages!.slice(summary)
+          : []),
+      ],
+      name,
+    })
+    this.abiItem = error.abiItem as AbiError
+    // Subclasses narrow `decoded` to the error they are built for.
+    this.args = error.args as decoded['args']
+    this.data = error.data
+    this.errorName = error.errorName as decoded['errorName']
+    this.hints = hints
+  }
+}
+
+export declare namespace TempoExecutionError {
+  /** Decoded Tempo error, optionally narrowed to `name`. */
+  type Decoded<name extends string = string> = Extract<
+    Exclude<ExecutionError.ExecutionError, { errorName: 'unknown' }>,
+    { errorName: name }
+  >
+  /** Name of any decoded Tempo error. */
+  type ErrorName = Decoded['errorName']
+  /** Message options for subclasses. */
+  type Options = {
+    /** Rows printed below the short message. Empty values are omitted. */
+    details?: Record<string, unknown> | undefined
+    /** Documentation path. */
+    docsPath?: string | undefined
+    /** Error name. Defaults to `TempoExecutionError`. */
+    name?: string | undefined
+    /** Short message. Defaults to the decoded error message. */
+    shortMessage?: string | undefined
+  }
+  /** Constructor parameters. */
+  type Parameters = {
+    /** Original error. */
+    cause: BaseError
+    /** Decoded Tempo error. */
+    error: Decoded
+    /** Steps to resolve the error. */
+    hints: readonly string[]
+  }
+}

package/tempo/index.ts

@@ -12,10 +12,10 @@ export type {
   TxEnvelopeTempo as z_TxEnvelopeTempo,
 } from 'ox/tempo'
 export {
+  AccountConfig,
+  AccountOperation,
   Channel,
   EarnShares,
-  MultisigConfig,
-  MultisigOperation,
   Period,
   ReceivePolicyReceipt,
   TempoAddress,
@@ -26,8 +26,8 @@ export {
 } from 'ox/tempo'
 export type {
   /** @deprecated */
-  Owner as z_MultisigConfigOwner,
-} from 'ox/tempo/MultisigConfig'
+  Owner as z_AccountConfigOwner,
+} from 'ox/tempo/AccountConfig'
 export {
   type CustomTransport,
   type CustomTransportConfig,
@@ -73,6 +73,7 @@ export * as Expiry from './Expiry.js'
 export * from './errors.js'
 export * as Formatters from './Formatters.js'
 export * as Hardfork from './Hardfork.js'
+/** Client-side storage for pending key authorizations, backed by a `Store`. */
 export * as KeyAuthorizationManager from './KeyAuthorizationManager.js'
 export * as P256 from './P256.js'
 /**

package/tempo/internal/errors.ts

@@ -0,0 +1,110 @@
+import type { Address } from 'abitype'
+import { TokenId } from 'ox/tempo'
+import type {
+  MulticallParameters,
+  MulticallReturnType,
+} from '../../actions/public/multicall.js'
+import type { Client } from '../../clients/createClient.js'
+import { formatUnits } from '../../utils/unit/formatUnits.js'
+import type * as ExecutionError from '../ExecutionError.js'
+import type { TempoExecutionError } from '../errors.js'
+
+/** Action-specific steps to resolve errors, keyed by error name. Listed before the default steps. */
+export type Hints = {
+  [name in TempoExecutionError.ErrorName]?: readonly string[]
+}
+
+/** Builds a specific error for a decoded Tempo error, or returns `undefined` when it does not apply. */
+type Resolver = (
+  context: Context,
+) => Promise<TempoExecutionError | undefined> | TempoExecutionError | undefined
+
+/** Resolvers keyed by error signature. */
+export type Resolvers = {
+  [signature in keyof typeof ExecutionError.messages]?: Resolver
+}
+
+export type Context = {
+  /** Parameters for the base `TempoExecutionError`. */
+  base: TempoExecutionError.Parameters
+  client: Client
+  /** Signer, with its access key when signing with one. */
+  signer: { address: Address; accessKey: Address | undefined } | undefined
+  /** Contract call that failed, when the action made one. */
+  call:
+    | {
+        address: Address
+        args: readonly unknown[]
+        functionName: string
+        /** Reads an argument by its ABI input name. */
+        arg: <type = unknown>(name: string) => type | undefined
+      }
+    | undefined
+  /** Whether the error came from transaction validation or fee payment rather than a revert. */
+  validation: boolean
+  /** Raw node message. */
+  details: string
+  parameters: Record<string, any>
+  /** Multicall with `allowFailure: true`. Resolves an empty array when the request fails. */
+  read: <const contracts extends readonly unknown[]>(
+    contracts: MulticallParameters<contracts>['contracts'],
+  ) => Promise<Partial<MulticallReturnType<contracts, true>>>
+}
+
+/**
+ * Wraps an action so failures with a decoded Tempo error throw a {@link TempoExecutionError}.
+ * Other errors are rethrown unchanged.
+ *
+ * @internal
+ */
+export function withExecutionError<
+  action extends (client: any, parameters: any) => Promise<any>,
+>(action: action, options: { hints?: Hints | undefined } = {}): action {
+  return (async (client: Client, parameters: Record<string, any>) => {
+    try {
+      return await action(client, parameters)
+    } catch (error) {
+      // Loaded on failure only, so resolvers and error tables stay out of the success path.
+      const { toExecutionError } = await import('./resolveError.js')
+      throw await toExecutionError(error, { ...options, client, parameters })
+    }
+  }) as action
+}
+
+/** Fee token from the action parameters or chain, when set. */
+export function getFeeToken(context: Context) {
+  const feeToken =
+    context.parameters.feeToken ??
+    (
+      context.client.chain as
+        | { feeToken?: TokenId.TokenIdOrAddress }
+        | undefined
+    )?.feeToken
+  return feeToken === undefined || feeToken === null
+    ? undefined
+    : TokenId.toAddress(feeToken)
+}
+
+/** Whether `address` is a TIP-20 token. */
+export function isTip20(address: Address | undefined): address is Address {
+  return !!address?.toLowerCase().startsWith('0x20c0')
+}
+
+/** Formats an amount as `formatted (raw)` when decimals are known. */
+export function formatAmount(
+  value: bigint | undefined,
+  decimals: number | undefined,
+) {
+  if (value === undefined) return undefined
+  if (decimals === undefined) return value.toString()
+  return `${formatUnits(value, decimals)} (${value})`
+}
+
+/** Formats Unix seconds as an ISO 8601 string. */
+export function formatTime(seconds: bigint | number | undefined) {
+  if (!seconds) return undefined
+  const milliseconds = Number(seconds) * 1000
+  // `Date` cannot represent times past ±8.64e15 milliseconds.
+  if (!(Math.abs(milliseconds) <= 8.64e15)) return seconds.toString()
+  return new Date(milliseconds).toISOString()
+}