viem 2.56.9 → 2.57.0

package/tempo/internal/relay/feeToken.ts

@@ -0,0 +1,190 @@
+import type { Address } from 'abitype'
+import { RpcResponse } from 'ox'
+import type { Client } from '../../../clients/createClient.js'
+import { tokens as tokenSets } from '../../../tokens/sets.js'
+import * as Actions from '../../actions/index.js'
+import type * as Relay from '../../Relay.js'
+import * as Store from './cache.js'
+import * as Preflight from './preflight.js'
+import * as Utils from './utils.js'
+import { extractCalls, getVirtualAddressTargets } from './virtualAddress.js'
+
+export function create(): Relay.Plugin {
+  return {
+    async handleRequest(context, next) {
+      const { request } = context
+      if (request.method !== 'eth_fillTransaction') return next()
+      const parameters = request.params![0] as Record<string, unknown>
+      const transaction = Utils.normalizeFillTransactionRequest(parameters)
+
+      if (transaction.feeToken) {
+        context.request = {
+          ...request,
+          params: [
+            Utils.formatFillTransactionRequest(context.client, transaction),
+          ],
+        }
+        return next()
+      }
+
+      const tokens = await context.resolveTokens()
+      const candidates = [
+        ...tokens,
+        ...callTargetTokens(transaction).filter(
+          (token) =>
+            !tokens.some(
+              (candidate) => candidate.toLowerCase() === token.toLowerCase(),
+            ),
+        ),
+      ]
+
+      const resolved = transaction.feePayer
+        ? { feeToken: tokens[0], virtualAddresses: undefined }
+        : await resolveFeeToken(context.client, {
+            account: transaction.from as Address | undefined,
+            feeToken: transaction.feeToken as Address | undefined,
+            targets: getVirtualAddressTargets(extractCalls(transaction)),
+            tokens: candidates,
+          })
+
+      const { feeToken, virtualAddresses } = resolved
+      const selected = { ...transaction, ...(feeToken ? { feeToken } : {}) }
+      context.request = {
+        ...request,
+        params: [Utils.formatFillTransactionRequest(context.client, selected)],
+      }
+      await next()
+      const result = context.result as Relay.Plugin.FillResult
+      context.result = {
+        ...result,
+        // Unsigned sponsored estimates can omit the fee token selected by this plugin.
+        tx: {
+          ...result.tx,
+          ...(!result.tx.feeToken && feeToken ? { feeToken } : {}),
+        },
+        ...(virtualAddresses
+          ? { capabilities: { ...result.capabilities, virtualAddresses } }
+          : {}),
+      }
+    },
+  }
+}
+
+export async function getDefaultTokens(
+  chainId: number,
+): Promise<readonly Address[]> {
+  return tokenSets.tempo.flatMap((token) => {
+    const address = (token.addresses as Record<number, Address>)[chainId]
+    return address ? [address] : []
+  })
+}
+
+/** Resolves a funded fee-token candidate. @internal */
+export async function resolveFeeToken(
+  client: Client,
+  options: resolveFeeToken.Options,
+) {
+  const { feeToken, account, exclude, tokens } = options
+  if (feeToken || !account) return { feeToken, virtualAddresses: undefined }
+  const candidates = [
+    ...new Set(tokens?.map((token) => token.toLowerCase() as Address)),
+  ]
+  if (candidates.length > 100)
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Fee-token candidates exceed the limit of 100 tokens.',
+    })
+  const { preferredToken, preferredBalance, balances, virtualAddresses } =
+    await Preflight.read(client, {
+      account,
+      tokens: candidates,
+      targets: options.targets,
+    })
+  const minimumBalance = options.minimumBalance ?? 1n
+  if (
+    preferredToken.toLowerCase() !== exclude?.toLowerCase() &&
+    preferredBalance >= minimumBalance
+  )
+    return { feeToken: preferredToken, virtualAddresses }
+
+  let best: { address: Address; balance: bigint } | undefined
+  for (const asset of balances) {
+    if (
+      asset.balance < minimumBalance ||
+      asset.address.toLowerCase() === exclude?.toLowerCase()
+    )
+      continue
+    if (!best || asset.balance > best.balance) best = asset
+  }
+  return { feeToken: best?.address, virtualAddresses }
+}
+
+export declare namespace resolveFeeToken {
+  type Options = {
+    minimumBalance?: bigint | undefined
+    exclude?: Address | undefined
+    feeToken?: Address | undefined
+    account?: Address | undefined
+    tokens?: readonly Address[] | undefined
+    targets?: readonly Address[] | undefined
+  }
+}
+
+/** Includes call-target TIP20 tokens as fee candidates, allowing transfers to pay fees with the transferred token. */
+function callTargetTokens(
+  transaction: Record<string, unknown>,
+): readonly Address[] {
+  const calls = transaction.calls as readonly { to?: Address }[] | undefined
+  if (!calls) return []
+  const out: Address[] = []
+  const seen = new Set<string>()
+  for (const c of calls) {
+    if (!c.to) continue
+    const lower = c.to.toLowerCase()
+    if (!lower.startsWith('0x20c0')) continue
+    if (seen.has(lower)) continue
+    seen.add(lower)
+    out.push(c.to)
+    if (out.length > 100)
+      throw new RpcResponse.InvalidParamsError({
+        message: 'Fee-token candidates exceed the limit of 100 tokens.',
+      })
+  }
+  return out
+}
+
+export async function resolveTokenMetadata(
+  client: Client,
+  options: resolveTokenMetadata.Options,
+) {
+  const { token, tokenMetadata, store } = options
+  const meta =
+    tokenMetadata?.[token] ?? tokenMetadata?.[token.toLowerCase() as Address]
+  // Tempo simulation metadata covers TIP-20 tokens, whose decimals are always six.
+  if (token.toLowerCase().startsWith('0x20c0') && meta)
+    return { decimals: 6, symbol: meta.symbol, name: meta.name }
+  // TIP-20 metadata (decimals/symbol/name) is immutable per token, so cache
+  // long-term. Skips the multicall RPC on cache hits.
+  const fetcher = () => Actions.token.getMetadata(client, { token })
+  const fallback = store
+    ? await Store.memoize(fetcher, {
+        key: `tokenMetadata:${client.chain?.id ?? 0}:${token.toLowerCase()}`,
+        store,
+        ttl: 24 * 60 * 60 * 1000,
+      })
+    : await fetcher()
+  return {
+    decimals: fallback.decimals ?? 6,
+    symbol: meta?.symbol || fallback.symbol,
+    name: meta?.name || fallback.name,
+  }
+}
+
+export declare namespace resolveTokenMetadata {
+  type Options = {
+    token: Address
+    tokenMetadata?:
+      | Record<Address, { name: string; symbol: string; currency: string }>
+      | undefined
+    store?: Store.Store | undefined
+  }
+}

package/tempo/{Multisig.ts → internal/relay/multisig.ts}

@@ -11,232 +11,201 @@ import {
   SignatureEnvelope,
   TxEnvelopeTempo,
 } from 'ox/tempo'
-import { getBlockNumber } from '../actions/public/getBlockNumber.js'
-import { createClient } from '../clients/createClient.js'
-import { custom } from '../clients/transports/custom.js'
-import type { EIP1193RequestOptions } from '../types/eip1193.js'
-import { decodeFunctionData } from '../utils/abi/decodeFunctionData.js'
-import { isAddressEqual } from '../utils/address/isAddressEqual.js'
-import * as Abis from './Abis.js'
-import * as Addresses from './Addresses.js'
-import { getConfigCommitment } from './actions/multisig.js'
-import * as ConfigStore from './multisig/Config.js'
-import * as OperationStore from './multisig/Operation.js'
-import type * as Store from './Store.js'
-import * as Transaction from './Transaction.js'
+import { getBlockNumber } from '../../../actions/public/getBlockNumber.js'
+import { createClient } from '../../../clients/createClient.js'
+import { custom } from '../../../clients/transports/custom.js'
+import { decodeFunctionData } from '../../../utils/abi/decodeFunctionData.js'
+import { isAddressEqual } from '../../../utils/address/isAddressEqual.js'
+import * as Abis from '../../Abis.js'
+import * as Addresses from '../../Addresses.js'
+import { getConfigCommitment } from '../../actions/multisig.js'
+import * as ConfigStore from '../../multisig/Config.js'
+import * as OperationStore from '../../multisig/Operation.js'
+import type * as Relay from '../../Relay.js'
+import type * as Store from '../../Store.js'
+import * as Transaction from '../../Transaction.js'
+import * as Plugin from './plugin.js'
 
 const submissionTtl = 30_000
 const pollingInterval = 100
 
-/**
- * Creates an RPC request handler that coordinates native multisig approvals.
- *
- * @param next - Downstream RPC request handler.
- * @param parameters - Handler parameters.
- * @returns The multisig-aware RPC request handler.
- */
-export function handleRequest(
-  next: handleRequest.Handler,
-  parameters: handleRequest.Parameters,
-): handleRequest.Handler {
-  if (!parameters.store.compareAndSet)
+/** Creates middleware for multisig approval coordination. @internal */
+export function create(
+  options: Relay.multisig.Options,
+): Relay.multisig.ReturnType {
+  if (!options.store.compareAndSet)
     throw new RpcResponse.InvalidParamsError({
       message:
         'Multisig coordination requires a store with atomic `compareAndSet`.',
     })
-  return async (request, requestOptions_) => {
-    const requestOptions = await resolveRequestOptions({
-      request,
-      requestOptions: requestOptions_,
-      store: parameters.store,
-    })
-    const client = createClient({
-      transport: custom({
-        request: ({ method, params }, options) =>
-          next({ method, params }, { ...requestOptions, ...options }),
-      }),
-    })
-
-    if (request.method === 'multisig_getConfig') {
-      const value = request.params?.[0]
-      const address =
-        value && typeof value === 'object' && 'address' in value
-          ? value.address
-          : undefined
-      if (
-        typeof address !== 'string' ||
-        !Address_.validate(address) ||
-        Hex.toBigInt(address) === 0n
-      )
-        throw new RpcResponse.InvalidParamsError({
-          message: 'Expected a multisig account address.',
-        })
-      const blockNumber = await getBlockNumber(client, { cacheTime: 0 })
-      const commitment = await getConfigCommitment(client, {
-        account: address,
-        blockNumber,
+  return Plugin.multisig({
+    async handleRequest(context, forward) {
+      const { request, options: requestOptions_ } = context
+      const requestOptions = await resolveRequestOptions({
+        request,
+        requestOptions: requestOptions_,
+        store: options.store,
       })
-      const config = await ConfigStore.read(parameters.store, {
-        address,
-        commitment,
+      context.options = requestOptions ?? {}
+      const next: Relay.handleRequest.Handler = async (request, options) => {
+        return context
+          .getClient(options?.chainId)
+          .request(request as never, options)
+      }
+      const client = createClient({
+        transport: custom(
+          {
+            request: (request, options) =>
+              next(request, { ...requestOptions, ...options }),
+          },
+          { retryCount: 0 },
+        ),
       })
-      if (!config) return null
-      return MultisigConfig.toRpc(config)
-    }
 
-    if (request.method === 'multisig_getOperation') {
-      const hash = request.params?.[0]
-      if (typeof hash !== 'string' || !Hash.validate(hash))
-        throw new RpcResponse.InvalidParamsError({
-          message: 'Expected a multisig operation hash.',
+      if (request.method === 'multisig_getConfig') {
+        const value = request.params?.[0]
+        const address =
+          value && typeof value === 'object' && 'address' in value
+            ? value.address
+            : undefined
+        if (
+          typeof address !== 'string' ||
+          !Address_.validate(address) ||
+          Hex.toBigInt(address) === 0n
+        )
+          throw new RpcResponse.InvalidParamsError({
+            message: 'Expected a multisig account address.',
+          })
+        const blockNumber = await getBlockNumber(client, { cacheTime: 0 })
+        const commitment = await getConfigCommitment(client, {
+          account: address,
+          blockNumber,
         })
-      const operation = await OperationStore.read(parameters.store, hash)
-      return operation ? MultisigOperation.toRpc(operation) : null
-    }
+        const config = await ConfigStore.read(options.store, {
+          address,
+          commitment,
+        })
+        if (!config) return null
+        return MultisigConfig.toRpc(config)
+      }
 
-    if (request.method === 'multisig_approveKeyAuthorization')
-      return await approveKeyAuthorization({
-        client,
-        request,
-        store: parameters.store,
-      })
+      if (request.method === 'multisig_getOperation') {
+        const hash = request.params?.[0]
+        if (typeof hash !== 'string' || !Hash.validate(hash))
+          throw new RpcResponse.InvalidParamsError({
+            message: 'Expected a multisig operation hash.',
+          })
+        const operation = await OperationStore.read(options.store, hash)
+        return operation ? MultisigOperation.toRpc(operation) : null
+      }
 
-    if (
-      request.method === 'eth_getTransactionByHash' ||
-      request.method === 'eth_getTransactionReceipt'
-    ) {
-      const hash = request.params?.[0]
-      if (typeof hash !== 'string' || !Hash.validate(hash))
-        return await next(request, requestOptions)
-      const operation = await OperationStore.read(parameters.store, hash)
-      if (!operation || operation.type !== 'transaction')
-        return await next(request, requestOptions)
-      if (request.method === 'eth_getTransactionReceipt') {
-        if (operation.status === 'pending') return null
+      if (request.method === 'multisig_approveKeyAuthorization')
+        return await approveKeyAuthorization({
+          client,
+          request,
+          store: options.store,
+        })
+
+      if (
+        request.method === 'eth_getTransactionByHash' ||
+        request.method === 'eth_getTransactionReceipt'
+      ) {
+        const hash = request.params?.[0]
+        if (typeof hash !== 'string' || !Hash.validate(hash)) return forward()
+        const operation = await OperationStore.read(options.store, hash)
+        if (!operation || operation.type !== 'transaction') return forward()
+        if (request.method === 'eth_getTransactionReceipt') {
+          if (operation.status === 'pending') return null
+          const transactionHash = await getSubmittedTransactionHash(
+            options.store,
+            operation,
+          )
+          if (!transactionHash) return null
+          const receipt = await next(
+            {
+              ...request,
+              params: [transactionHash],
+            },
+            requestOptions,
+          )
+          if (!receipt || typeof receipt !== 'object') return receipt
+          const success =
+            operation.status === 'submitting'
+              ? await completeSubmission(
+                  options.store,
+                  operation,
+                  transactionHash,
+                )
+              : operation
+          return {
+            ...receipt,
+            multisig: MultisigOperation.toRpc(success),
+          }
+        }
+        if (operation.status === 'pending')
+          return await toTransaction(client, operation)
         const transactionHash = await getSubmittedTransactionHash(
-          parameters.store,
+          options.store,
           operation,
         )
-        if (!transactionHash) return null
-        const receipt = await next(
+        if (!transactionHash) return await toTransaction(client, operation)
+        const transaction = await next(
           {
             ...request,
             params: [transactionHash],
           },
           requestOptions,
         )
-        if (!receipt || typeof receipt !== 'object') return receipt
+        if (!transaction || typeof transaction !== 'object')
+          return await toTransaction(client, operation)
         const success =
           operation.status === 'submitting'
             ? await completeSubmission(
-                parameters.store,
+                options.store,
                 operation,
                 transactionHash,
               )
             : operation
         return {
-          ...receipt,
+          ...transaction,
           multisig: MultisigOperation.toRpc(success),
         }
       }
-      if (operation.status === 'pending')
-        return await toTransaction(client, operation)
-      const transactionHash = await getSubmittedTransactionHash(
-        parameters.store,
-        operation,
-      )
-      if (!transactionHash) return await toTransaction(client, operation)
-      const transaction = await next(
-        {
-          ...request,
-          params: [transactionHash],
-        },
-        requestOptions,
+
+      if (
+        request.method !== 'eth_sendRawTransaction' &&
+        request.method !== 'eth_sendRawTransactionSync' &&
+        request.method !== 'multisig_approveRawTransaction' &&
+        request.method !== 'multisig_approveRawTransactionSync'
       )
-      if (!transaction || typeof transaction !== 'object')
-        return await toTransaction(client, operation)
-      const success =
-        operation.status === 'submitting'
-          ? await completeSubmission(
-              parameters.store,
-              operation,
-              transactionHash,
-            )
-          : operation
-      return {
-        ...transaction,
-        multisig: MultisigOperation.toRpc(success),
-      }
-    }
+        return forward()
 
-    if (
-      request.method !== 'eth_sendRawTransaction' &&
-      request.method !== 'eth_sendRawTransactionSync' &&
-      request.method !== 'multisig_approveRawTransaction' &&
-      request.method !== 'multisig_approveRawTransactionSync'
-    )
-      return await next(request, requestOptions)
+      const standard =
+        request.method === 'eth_sendRawTransaction' ||
+        request.method === 'eth_sendRawTransactionSync'
+      const serialized = request.params?.[0]
+      if (!isSerializedTempoTransaction(serialized)) {
+        if (standard) return forward()
+        throw new RpcResponse.InvalidParamsError({
+          message: 'Expected a serialized Tempo multisig transaction.',
+        })
+      }
 
-    const standard =
-      request.method === 'eth_sendRawTransaction' ||
-      request.method === 'eth_sendRawTransactionSync'
-    const serialized = request.params?.[0]
-    if (!isSerializedTempoTransaction(serialized)) {
-      if (standard) return await next(request, requestOptions)
-      throw new RpcResponse.InvalidParamsError({
-        message: 'Expected a serialized Tempo multisig transaction.',
+      return await submit({
+        client,
+        method: request.method,
+        next,
+        request,
+        requestOptions,
+        serialized,
+        store: options.store,
       })
-    }
-
-    return await submit({
-      client,
-      method: request.method,
-      next,
-      request,
-      requestOptions,
-      serialized,
-      store: parameters.store,
-    })
-  }
-}
-
-export declare namespace handleRequest {
-  /** RPC request handler. */
-  export type Handler = (
-    request: Request,
-    options?: RequestOptions | undefined,
-  ) => Promise<unknown>
-
-  /** RPC request passed to a handler. */
-  export type Request = {
-    /** RPC method name. */
-    method: string
-    /** RPC method parameters. */
-    params?: readonly unknown[] | undefined
-  }
-
-  /** Options for one handled request. */
-  export type RequestOptions = EIP1193RequestOptions & {
-    /** Chain selected by the caller or inferred from the multisig request. */
-    chainId?: number | undefined
-  }
-
-  /** Parameters for {@link handleRequest}. */
-  export type Parameters = {
-    /** Store shared by multisig coordinators. */
-    store: Store.Atomic
-  }
-
-  /** Error type for {@link handleRequest}. */
-  export type ErrorType =
-    | ConfigStore.InvalidStoreValueError
-    | OperationStore.InvalidStoreValueError
-    | OperationStore.StoreConflictError
-    | RpcResponse.InvalidParamsError
+    },
+  })
 }
 
 /** Collects approvals and submits a transaction after quorum. @internal */
-// biome-ignore lint/correctness/noUnusedVariables: _
+// biome-ignore lint/correctness/noUnusedVariables: declaration merge
 async function submit(options: submit.Options) {
   const transaction = (() => {
     try {
@@ -551,11 +520,11 @@ declare namespace submit {
       | 'multisig_approveRawTransaction'
       | 'multisig_approveRawTransactionSync'
     /** Downstream RPC request handler. */
-    next: handleRequest.Handler
+    next: Relay.handleRequest.Handler
     /** Original RPC request. */
-    request: handleRequest.Request
+    request: Relay.handleRequest.Request
     /** Original request overrides. */
-    requestOptions?: handleRequest.RequestOptions | undefined
+    requestOptions?: Relay.handleRequest.RequestOptions | undefined
     /** Serialized Tempo transaction. */
     serialized: Hex.Hex
     /** Shared multisig store. */
@@ -758,7 +727,7 @@ declare namespace approveKeyAuthorization {
     /** Client used to validate configs. */
     client: ReturnType<typeof createClient>
     /** Original RPC request. */
-    request: handleRequest.Request
+    request: Relay.handleRequest.Request
     /** Shared multisig store. */
     store: Store.Atomic
   }
@@ -1240,10 +1209,10 @@ function getTransactionHash(result: unknown): Hex.Hex {
 
 /** Resolves and validates the chain used by a handled request. */
 async function resolveRequestOptions(options: {
-  request: handleRequest.Request
-  requestOptions?: handleRequest.RequestOptions | undefined
+  request: Relay.handleRequest.Request
+  requestOptions?: Relay.handleRequest.RequestOptions | undefined
   store: Store.Store
-}): Promise<handleRequest.RequestOptions | undefined> {
+}): Promise<Relay.handleRequest.RequestOptions | undefined> {
   const { request, requestOptions, store } = options
   const chainId_explicit = requestOptions?.chainId
   if (
@@ -1269,7 +1238,7 @@ async function resolveRequestOptions(options: {
 
 /** Resolves a chain from request fields, envelopes, or stored operations. */
 async function resolveRequestChainId(
-  request: handleRequest.Request,
+  request: Relay.handleRequest.Request,
   store: Store.Store,
 ) {
   const value = request.params?.[0]

package/tempo/internal/relay/plugin.ts

@@ -0,0 +1,13 @@
+import type * as Relay from '../../Relay.js'
+
+const multisigPlugins = new WeakSet<Relay.Plugin>()
+
+/** Registers the built-in multisig plugin for transport capability detection. */
+export function multisig(plugin: Relay.Plugin): Relay.multisig.ReturnType {
+  multisigPlugins.add(plugin)
+  return plugin as Relay.multisig.ReturnType
+}
+
+export function isMultisig(plugin: Relay.Plugin): boolean {
+  return multisigPlugins.has(plugin)
+}