viem 2.56.8 → 2.57.0

package/tempo/internal/relay/simulate.ts

@@ -0,0 +1,367 @@
+import type { Address } from 'abitype'
+import { AbiEvent, Hex } from 'ox'
+import type { Client } from '../../../clients/createClient.js'
+import { zeroAddress } from '../../../constants/address.js'
+import type { Call } from '../../../types/calls.js'
+import type { Log } from '../../../types/log.js'
+import { parseEventLogs } from '../../../utils/abi/parseEventLogs.js'
+import { formatUnits } from '../../../utils/unit/formatUnits.js'
+import * as Abis from '../../Abis.js'
+import * as Actions from '../../actions/index.js'
+import type * as Capabilities from '../../Capabilities.js'
+import type * as Relay from '../../Relay.js'
+import type * as Store from './cache.js'
+import { formatError, isExecutionError } from './error.js'
+import { resolveTokenMetadata } from './feeToken.js'
+import * as Utils from './utils.js'
+import { extractCalls } from './virtualAddress.js'
+
+export function create(options: Relay.simulate.Options): Relay.Plugin {
+  return {
+    async handleRequest(context, next) {
+      if (context.request.method !== 'eth_fillTransaction') return next()
+      try {
+        await next()
+      } catch (error) {
+        const parameters = context.request.params![0] as Record<string, unknown>
+        if (
+          isExecutionError(error) &&
+          (parameters.capabilities as Record<string, unknown> | undefined)
+            ?.errors === true
+        )
+          return formatError(
+            error,
+            parameters,
+            context.client,
+            context.getStore(options.store),
+          )
+        throw error
+      }
+    },
+    async afterFill(result, context) {
+      const parameters = context.request.params![0] as Record<string, unknown>
+      const store = context.getStore(options.store)
+      const signal = context.options.signal
+      const transaction = Utils.normalizeTempoTransaction(result.tx)
+      const feeToken = transaction.feeToken as Address | undefined
+      const simulation =
+        (parameters.capabilities as Record<string, unknown> | undefined)
+          ?.balanceDiffs !== false
+          ? await simulateAndParseDiffs(context.client, {
+              account: parameters.from as Address | undefined,
+              calls: extractCalls(transaction),
+              feeToken,
+              gas: transaction.gas,
+              maxFeePerGas: transaction.maxFeePerGas,
+              store,
+              signal,
+            })
+          : await computeFee(context.client, {
+              feeToken,
+              gas: transaction.gas,
+              maxFeePerGas: transaction.maxFeePerGas,
+              store,
+              signal,
+            }).then((fee) => ({ balanceDiffs: undefined, fee }))
+      return {
+        capabilities: {
+          balanceDiffs: simulation.balanceDiffs,
+          fee: simulation.fee,
+        },
+      }
+    },
+  }
+}
+
+export async function simulateAndParseDiffs(
+  client: Client,
+  options: simulateAndParseDiffs.Options,
+) {
+  const { account, calls, feeToken, gas, store, maxFeePerGas, signal } = options
+  signal?.throwIfAborted()
+
+  try {
+    // Including the fee token as a read target asks the node to return its metadata too.
+    const probe =
+      feeToken &&
+      !calls.some((call) => call.to?.toLowerCase() === feeToken.toLowerCase())
+        ? [
+            Actions.token.getBalance.call(client, {
+              account: account ?? zeroAddress,
+              token: feeToken,
+            }),
+          ]
+        : []
+    const simulation = await Actions.simulate.simulateCalls(client, {
+      account: account === zeroAddress ? undefined : account,
+      calls: [...calls, ...probe] as Call[],
+      traceTransfers: true,
+    })
+    const results = simulation.results.slice(0, calls.length)
+    const { tokenMetadata } = simulation
+
+    signal?.throwIfAborted()
+
+    // Collect all logs across all call results.
+    const logs: (typeof results)[number]['logs'] = []
+    for (const result of results as {
+      logs?: (typeof logs)[number][] | undefined
+    }[])
+      if (result.logs) logs.push(...result.logs)
+
+    // Build per-token balance diffs relative to the sender.
+    const balanceDiffs = account
+      ? await buildBalanceDiffs(client, {
+          account,
+          store,
+          signal,
+          logs,
+          tokenMetadata: tokenMetadata as never,
+        })
+      : {}
+
+    // Compute fee breakdown.
+    const fee = await computeFee(client, {
+      feeToken,
+      gas,
+      store,
+      signal,
+      maxFeePerGas,
+      tokenMetadata: tokenMetadata as never,
+    })
+
+    return { balanceDiffs, fee, tokenMetadata }
+  } catch {
+    signal?.throwIfAborted()
+    // Simulation failures should not block the fill response —
+    // return empty diffs with fee computed from transaction fields.
+    const fee = await computeFee(client, {
+      feeToken,
+      gas,
+      store,
+      maxFeePerGas,
+      signal,
+    })
+    return { balanceDiffs: undefined, fee, tokenMetadata: undefined }
+  }
+}
+
+export declare namespace simulateAndParseDiffs {
+  type Options = {
+    account?: Address | undefined
+    calls: readonly Call[]
+    feeToken?: Address | undefined
+    gas?: bigint | undefined
+    store?: Store.Store | undefined
+    signal?: AbortSignal | undefined
+    maxFeePerGas?: bigint | undefined
+  }
+}
+
+/** Builds a complete preview within the metadata lookup budget. @internal */
+export async function buildBalanceDiffs(
+  client: Client,
+  options: buildBalanceDiffs.Options,
+) {
+  const { account, store, logs, tokenMetadata, signal } = options
+  signal?.throwIfAborted()
+  const accountLower = account.toLowerCase()
+
+  const transferLogs = parseEventLogs({
+    abi: [AbiEvent.fromAbi(Abis.tip20, 'Transfer')],
+    eventName: 'Transfer',
+    logs,
+  })
+  const approvalLogs = parseEventLogs({
+    abi: [AbiEvent.fromAbi(Abis.tip20, 'Approval')],
+    eventName: 'Approval',
+    logs,
+  })
+
+  // Track net movement per token: incoming vs outgoing.
+  const tokenMap = new Map<
+    string,
+    {
+      incoming: bigint
+      outgoing: bigint
+      approved: bigint
+      recipients: Set<Address>
+      token: Address
+    }
+  >()
+
+  for (const log of transferLogs) {
+    const token = log.address.toLowerCase()
+    const fromLower = log.args.from.toLowerCase()
+    const toLower = log.args.to.toLowerCase()
+
+    const entry = tokenMap.get(token) ?? {
+      incoming: 0n,
+      outgoing: 0n,
+      approved: 0n,
+      recipients: new Set<Address>(),
+      token: log.address,
+    }
+    if (fromLower === accountLower) {
+      entry.outgoing += log.args.amount
+      entry.recipients.add(log.args.to)
+    }
+    if (toLower === accountLower) entry.incoming += log.args.amount
+    tokenMap.set(token, entry)
+  }
+
+  // Approvals replace allowances; retain the last event for each token and spender.
+  const approvals = new Map<string, (typeof approvalLogs)[number]>()
+  for (const log of approvalLogs) {
+    if (log.args.owner.toLowerCase() !== accountLower) continue
+    approvals.set(
+      `${log.address.toLowerCase()}:${log.args.spender.toLowerCase()}`,
+      log,
+    )
+  }
+
+  // Transfers do not identify allowance consumption, so retain final approval exposure.
+  for (const log of approvals.values()) {
+    if (log.args.amount === 0n) continue
+    const token = log.address.toLowerCase()
+
+    const entry = tokenMap.get(token) ?? {
+      incoming: 0n,
+      outgoing: 0n,
+      approved: 0n,
+      recipients: new Set<Address>(),
+      token: log.address,
+    }
+    entry.approved += log.args.amount
+    entry.recipients.add(log.args.spender)
+    tokenMap.set(token, entry)
+  }
+
+  // Collect unique tokens that need decimals.
+  const entries = [...tokenMap.values()].filter((e) => {
+    const net =
+      e.outgoing > e.incoming
+        ? e.outgoing - e.incoming
+        : e.incoming - e.outgoing
+    return net > 0n || e.approved > 0n
+  })
+  if (entries.length === 0) return {}
+  // Omit an unavailable preview rather than returning a partial set of movements.
+  if (entries.length > 100) return undefined
+
+  // Bound metadata work for a single fill independently of the RPC batch limit.
+  const metadataMap = new Map<
+    string,
+    { decimals: number; symbol: string; name: string }
+  >()
+  let index = 0
+  await Promise.all(
+    Array.from({ length: Math.min(10, entries.length) }, async () => {
+      while (index < entries.length) {
+        const entry = entries[index++]!
+        try {
+          const metadata = await resolveTokenMetadata(client, {
+            token: entry.token,
+            tokenMetadata,
+            store,
+          })
+          metadataMap.set(entry.token.toLowerCase(), metadata)
+        } catch {
+          signal?.throwIfAborted()
+        }
+      }
+    }),
+  )
+  signal?.throwIfAborted()
+  if (metadataMap.size !== entries.length) return undefined
+
+  // Build the diff array for this account.
+  const diffs: Capabilities.BalanceDiff[] = []
+  for (const entry of entries) {
+    const incoming =
+      entry.incoming > entry.outgoing ? entry.incoming - entry.outgoing : 0n
+    const outgoing =
+      (entry.outgoing > entry.incoming ? entry.outgoing - entry.incoming : 0n) +
+      entry.approved
+    const meta = metadataMap.get(entry.token.toLowerCase())!
+    const decimals = meta.decimals
+    const metadata = {
+      address: entry.token,
+      decimals,
+      name: meta.name,
+      symbol: meta.symbol,
+    }
+    if (incoming > 0n)
+      diffs.push({
+        ...metadata,
+        direction: 'incoming',
+        formatted: formatUnits(incoming, decimals),
+        recipients: [],
+        value: Hex.fromNumber(incoming),
+      })
+    if (outgoing > 0n)
+      diffs.push({
+        ...metadata,
+        direction: 'outgoing',
+        formatted: formatUnits(outgoing, decimals),
+        recipients: [...entry.recipients],
+        value: Hex.fromNumber(outgoing),
+      })
+  }
+
+  return { [account]: diffs }
+}
+
+export declare namespace buildBalanceDiffs {
+  type Options = {
+    account: Address
+    store?: Store.Store | undefined
+    signal?: AbortSignal | undefined
+    logs: Log[]
+    tokenMetadata: Record<
+      Address,
+      { name: string; symbol: string; currency: string }
+    >
+  }
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: declaration merge
+async function computeFee(client: Client, options: computeFee.Options) {
+  const { feeToken, gas, store, maxFeePerGas, tokenMetadata, signal } = options
+  signal?.throwIfAborted()
+  if (!feeToken || !gas || !maxFeePerGas) return undefined
+
+  try {
+    const metadata = await resolveTokenMetadata(client, {
+      token: feeToken,
+      tokenMetadata,
+      store,
+    })
+    signal?.throwIfAborted()
+    const raw = gas * maxFeePerGas
+    const scale = 10n ** BigInt(Math.max(0, 18 - metadata.decimals))
+    const amount = (raw + scale - 1n) / scale
+    return {
+      amount: Hex.fromNumber(amount) as `0x${string}`,
+      decimals: metadata.decimals,
+      formatted: formatUnits(amount, metadata.decimals),
+      symbol: metadata.symbol,
+    }
+  } catch {
+    signal?.throwIfAborted()
+    return undefined
+  }
+}
+
+declare namespace computeFee {
+  type Options = {
+    feeToken?: Address | undefined
+    gas?: bigint | undefined
+    store?: Store.Store | undefined
+    signal?: AbortSignal | undefined
+    maxFeePerGas?: bigint | undefined
+    tokenMetadata?:
+      | Record<Address, { name: string; symbol: string; currency: string }>
+      | undefined
+  }
+}

package/tempo/internal/relay/utils.ts

@@ -0,0 +1,202 @@
+import { Address, Hex, RpcResponse } from 'ox'
+import {
+  Transaction as core_Transaction,
+  KeyAuthorization,
+  TxEnvelopeTempo,
+} from 'ox/tempo'
+import type { Client } from '../../../clients/createClient.js'
+import { UnknownRpcError } from '../../../errors/rpc.js'
+
+export function resolveChainId(value: unknown) {
+  if (typeof value === 'number') return value
+  if (typeof value === 'bigint') return Number(value)
+  if (typeof value === 'string') {
+    if (!/^(?:0x[0-9a-f]+|[0-9]+)$/i.test(value)) return undefined
+    const n = Number(value)
+    if (Number.isFinite(n)) return n
+  }
+  return undefined
+}
+
+export function formatFillTransactionRequest(
+  client: Client,
+  value: Record<string, unknown>,
+) {
+  if (value.type === '0x76') return { ...value }
+  const format = client.chain?.formatters?.transactionRequest?.format
+  if (!format) return value
+  return {
+    ...format({ ...value } as never, 'fillTransaction'),
+    // Keep the selected token until the request leaves the plugin pipeline.
+    ...(value.feeToken !== undefined ? { feeToken: value.feeToken } : {}),
+  } as Record<string, unknown>
+}
+
+export function normalizeFillTransactionRequest(
+  tx: Record<string, unknown>,
+): Record<string, unknown> & { calls: unknown[] } {
+  const { to, data, value, ...rest } = tx
+  const keyAuthorization = normalizeKeyAuthorization(tx.keyAuthorization)
+  const withKeyAuthorization = keyAuthorization ? { keyAuthorization } : {}
+  if (Array.isArray(tx.calls))
+    return {
+      ...tx,
+      ...withKeyAuthorization,
+      calls: tx.calls.map((call) => {
+        if (!call || typeof call !== 'object' || Array.isArray(call))
+          throw new RpcResponse.InvalidParamsError({
+            message: 'Expected a transaction call object.',
+          })
+        assertCallTarget(call.to)
+        return { ...call, value: normalizeFillValue(call.value) }
+      }),
+    }
+  assertCallTarget(to)
+  const call = {
+    ...(typeof to !== 'undefined' ? { to } : {}),
+    ...(typeof data !== 'undefined' ? { data } : {}),
+    ...(typeof value !== 'undefined'
+      ? { value: normalizeFillValue(value) }
+      : {}),
+  }
+  return { ...rest, ...withKeyAuthorization, calls: [call] }
+}
+
+/**
+ * Forwards `keyAuthorization` to the chain in RPC shape. Pass-through
+ * when already RPC; convert via `KeyAuthorization.toRpc` when internal.
+ */
+function normalizeKeyAuthorization(value: unknown) {
+  if (!value || typeof value !== 'object') return undefined
+  const ka = value as Record<string, unknown>
+  const signature = ka.signature as Record<string, unknown> | undefined
+  if (!signature || typeof signature !== 'object') return undefined
+  const isInternal =
+    typeof signature.signature === 'object' && signature.signature !== null
+  return isInternal ? KeyAuthorization.toRpc(value as never) : value
+}
+
+function assertCallTarget(to: unknown) {
+  if (to === undefined || to === null) return
+  if (typeof to !== 'string' || !Address.validate(to, { strict: false }))
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Invalid transaction call target.',
+    })
+}
+
+function normalizeFillValue(value: unknown) {
+  if (typeof value !== 'string' || !value.startsWith('0x')) return value
+  if (!/^0x[\da-f]*$/i.test(value))
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Invalid transaction value.',
+    })
+  return BigInt(value === '0x' ? '0x0' : value)
+}
+
+/** Returns whether a raw transaction uses a Tempo sender or fee-payer wire prefix. */
+export function isSerializedTempoTransaction(
+  value: unknown,
+): value is `0x76${string}` | `0x78${string}` {
+  if (typeof value !== 'string') return false
+  // `0x78` is Tempo's fee-payer handoff magic, not a separate EIP-2718 type.
+  return (
+    value.startsWith(TxEnvelopeTempo.serializedType) ||
+    value.startsWith(TxEnvelopeTempo.feePayerMagic)
+  )
+}
+
+export function normalizeTempoTransaction(
+  value: Record<string, unknown> | undefined,
+) {
+  if (!value) throw new Error('Expected `tx` in eth_fillTransaction response.')
+  return core_Transaction.fromRpc({
+    type: '0x76',
+    ...value,
+  } as core_Transaction.Rpc)!
+}
+
+/** Preserves the nonce domain when serializing filled Tempo transactions. */
+export function formatTempoTransaction(
+  transaction: core_Transaction.Transaction,
+) {
+  return {
+    ...core_Transaction.toRpc(transaction),
+    ...('nonceKey' in transaction && transaction.nonceKey !== undefined
+      ? { nonceKey: Hex.fromNumber(transaction.nonceKey) }
+      : {}),
+  }
+}
+
+/** Preserves upstream RPC errors and the relay's expired-transaction contract. */
+export function toRpcError(error: unknown): RpcResponse.BaseError {
+  let current: unknown = error
+  let deepest: { code: number; message: string; data?: unknown } | undefined
+  const seen = new Set<unknown>()
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current)
+    const candidate = current as Record<string, unknown>
+    if (
+      !(current instanceof UnknownRpcError) &&
+      typeof candidate.code === 'number' &&
+      typeof candidate.message === 'string'
+    )
+      deepest =
+        current instanceof RpcResponse.BaseError
+          ? current
+          : {
+              code: candidate.code,
+              message: candidate.message,
+              data: candidate.data,
+            }
+    current = candidate.cause
+  }
+  if (!deepest)
+    return new RpcResponse.InternalError({
+      message: 'Internal error',
+      data: { code: 'internal_error' },
+    })
+  if (
+    deepest.code === -32603 &&
+    /^Revm error: transaction expired(?:\.|: .+)?$/.test(deepest.message)
+  )
+    return new RpcResponse.TransactionRejectedError({
+      message: 'Transaction expired.',
+      data: { code: 'transaction_expired' },
+    })
+  return deepest instanceof RpcResponse.BaseError
+    ? deepest
+    : new RpcResponse.BaseError(deepest)
+}
+
+/** Preserves envelope inputs omitted by the node, including calls and chain ID. Filled fields take precedence; legacy calls are normalized separately. */
+export function mergeCallsFromRequest(
+  resultTx: Record<string, unknown>,
+  request: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...request, ...resultTx }
+  const resultCalls = resultTx.calls
+  if (Array.isArray(resultCalls) && resultCalls.length > 0) return merged
+
+  const reqCalls = request.calls
+  if (Array.isArray(reqCalls)) {
+    merged.calls = reqCalls
+    return merged
+  }
+
+  const { to, data, value } = request
+  if (
+    typeof to === 'undefined' &&
+    typeof data === 'undefined' &&
+    typeof value === 'undefined'
+  )
+    return merged
+
+  merged.calls = [
+    {
+      ...(typeof to !== 'undefined' ? { to } : {}),
+      ...(typeof data !== 'undefined' ? { data } : {}),
+      ...(typeof value !== 'undefined' ? { value } : {}),
+    },
+  ]
+  return merged
+}

package/tempo/internal/relay/virtualAddress.ts

@@ -0,0 +1,95 @@
+import type { Address } from 'abitype'
+import { type Hex, RpcResponse } from 'ox'
+import * as VirtualAddress from 'ox/tempo/VirtualAddress'
+import type { Client } from '../../../clients/createClient.js'
+import type { Call } from '../../../types/calls.js'
+import { decodeFunctionData } from '../../../utils/abi/decodeFunctionData.js'
+import { isAddress } from '../../../utils/address/isAddress.js'
+import * as Abis from '../../Abis.js'
+import * as Preflight from './preflight.js'
+
+export async function resolveVirtualAddresses(
+  client: Client,
+  options: { calls: readonly Call[] },
+): Promise<Record<Address, Address | null> | undefined> {
+  const targets = getVirtualAddressTargets(options.calls)
+  if (targets.length === 0) return undefined
+
+  const result = await Preflight.read(client, { targets })
+  return result.virtualAddresses
+}
+
+export function getVirtualAddressTargets(
+  calls: readonly Call[],
+): readonly Address[] {
+  const targets = new Set<Address>()
+  for (const call of calls) {
+    for (const address of [call.to, decodeTransferRecipient(call.data)]) {
+      if (!address || !isAddress(address) || !VirtualAddress.isVirtual(address))
+        continue
+      targets.add(address.toLowerCase() as Address)
+      if (targets.size > 100)
+        throw new RpcResponse.InvalidParamsError({
+          message: 'Virtual-address targets exceed the limit of 100 addresses.',
+        })
+    }
+  }
+
+  return [...targets]
+}
+
+function decodeTransferRecipient(data?: string): Address | undefined {
+  if (!data) return undefined
+
+  const selector = data.slice(0, 10).toLowerCase()
+  if (!transferSelectors.has(selector)) return undefined
+
+  try {
+    const { args, functionName } = decodeFunctionData({
+      abi: Abis.tip20,
+      data: data as Hex.Hex,
+    })
+
+    if (
+      (functionName === 'transfer' || functionName === 'transferWithMemo') &&
+      typeof args[0] === 'string'
+    )
+      return args[0]
+
+    if (
+      (functionName === 'transferFrom' ||
+        functionName === 'transferFromWithMemo') &&
+      typeof args[1] === 'string'
+    )
+      return args[1]
+  } catch {}
+
+  return undefined
+}
+
+const transferSelectors = new Set([
+  '0xa9059cbb',
+  '0x95777d59',
+  '0x23b872dd',
+  '0x929c2539',
+])
+
+export function extractCalls(
+  transaction: Record<string, unknown>,
+): readonly Call[] {
+  const calls = transaction.calls as readonly Call[] | undefined
+  if (calls && calls.length > 0)
+    return calls.map((c) => ({
+      ...(c.to ? { to: c.to } : {}),
+      ...(c.data ? { data: c.data } : {}),
+      ...(c.value ? { value: c.value } : {}),
+    })) as readonly Call[]
+
+  return [
+    {
+      ...(transaction.to ? { to: transaction.to as Address } : {}),
+      ...(transaction.data ? { data: transaction.data as `0x${string}` } : {}),
+      ...(transaction.value ? { value: transaction.value as bigint } : {}),
+    },
+  ] as readonly Call[]
+}