tapimo 0.0.2 → 0.1.0

package/src/handlers/relay.ts

@@ -0,0 +1,1605 @@
+import { AbiEvent, Hex, RpcRequest, RpcResponse } from 'ox'
+import { Transaction as core_Transaction } from 'ox/tempo'
+import {
+  type Address,
+  type Call,
+  type Client,
+  createClient,
+  decodeFunctionData,
+  formatUnits,
+  http,
+  isAddress,
+  type Log,
+  parseEventLogs,
+  zeroAddress,
+} from 'viem'
+import type { LocalAccount } from 'viem/accounts'
+import { simulateCalls } from 'viem/actions'
+import { Abis, Actions, Addresses, Capabilities, Transaction, VirtualAddress } from 'viem/tempo'
+
+import * as ExecutionError from './internal/executionError.js'
+import type * as RpcSchema from '../internal/RpcSchema.js'
+import { type Handler, from } from '../Handler.js'
+import * as Store from '../internal/Store.js'
+import * as Multisig from './internal/multisig.js'
+import * as Sponsorship from './internal/sponsorship.js'
+import * as Utils from './internal/utils.js'
+
+/**
+ * Instantiates a relay handler that proxies `eth_fillTransaction`
+ * with wallet-aware enrichment (fee token resolution, simulation,
+ * sponsorship, AMM resolution).
+ *
+ * @example
+ * ```ts
+ * import { Handler } from 'tempo-api/server'
+ *
+ * const handler = Handler.relay({ getClient })
+ *
+ * // Plug handler into your server framework of choice:
+ * createServer(handler.listener)              // Node.js
+ * Bun.serve(handler)                          // Bun
+ * Deno.serve(handler)                         // Deno
+ * app.use(handler.listener)                   // Express
+ * app.all('*', c => handler.fetch(c.req.raw)) // Hono
+ * export const GET = handler.fetch            // Next.js
+ * export const POST = handler.fetch           // Next.js
+ * ```
+ *
+ * @example
+ * With sponsorship
+ *
+ * ```ts
+ * import { privateKeyToAccount } from 'viem/accounts'
+ * import { Handler } from 'tempo-api/server'
+ *
+ * const handler = Handler.relay({
+ *   getClient,
+ *   feePayer: {
+ *     account: privateKeyToAccount('0x...'),
+ *   },
+ * })
+ * ```
+ *
+ * @param options - Options.
+ * @returns Request handler.
+ */
+export function relay(options: relay.Options): Handler {
+  const {
+    getClient,
+    internal_allowUnsafeUrls = false,
+    onRequest,
+    path = '/',
+    resolveTokens,
+    ...rest
+  } = options
+  const feePayerOptions = options.feePayer
+  // Adapt the state store into the multisig operation store once, up front.
+  const multisigOptions = options.multisig
+    ? { ...options.multisig, store: Multisig.fromStore(options.multisig.store) }
+    : undefined
+
+  // Resolves the chain's fee-token candidates through the caller-provided
+  // resolver. An unconfigured resolver (or a chain it has no list for) yields
+  // an empty candidate set.
+  const getTokens = async (chainId: number | undefined): Promise<readonly Address[]> => {
+    if (!resolveTokens || chainId === undefined) return []
+    return await resolveTokens(chainId)
+  }
+
+  // Memoize cache for TIP-20 metadata and user fee-token preferences. Kept
+  // opt-in: an always-on cache would pin a raced null preference (set, then
+  // fill before the set mines) for the whole TTL.
+  const store = options.cache
+
+  const features = {
+    autoSwap: options.autoSwap ?? options.features === 'all',
+    feeTokenResolution: options.features === 'all' || Boolean(resolveTokens),
+    simulate: options.features === 'all',
+  }
+
+  const autoSwap = (() => {
+    if (!features.autoSwap) return undefined
+    if (options.autoSwap === false) return undefined
+    return {
+      slippage:
+        (typeof options.autoSwap === 'object' ? options.autoSwap?.slippage : undefined) ?? 0.05,
+    }
+  })()
+
+  async function handleRequest(
+    request: RpcRequest.RpcRequest<RpcSchema.Ox>,
+    options?: { chainId?: number | undefined },
+  ) {
+    await onRequest?.(request)
+
+    // Resolve chainId from: 1) explicit option (URL path), 2) first param object, 3) default chain.
+    const params = 'params' in request && Array.isArray(request.params) ? request.params : []
+    const first =
+      typeof params[0] === 'object' && params[0]
+        ? (params[0] as Record<string, unknown>)
+        : undefined
+    const chainId =
+      Utils.resolveChainId(first?.['chainId']) ?? options?.chainId ?? getClient().chain?.id
+    const client = getClient(chainId)
+
+    switch (request.method) {
+      case 'eth_fillTransaction': {
+        const parameters = params[0] as Record<string, unknown>
+        const capabilities = (parameters['capabilities'] ?? {}) as Record<string, unknown>
+
+        try {
+          const from =
+            typeof parameters['from'] === 'string' ? (parameters['from'] as Address) : undefined
+          const requestFeeToken =
+            typeof parameters['feeToken'] === 'string'
+              ? (parameters['feeToken'] as Address)
+              : undefined
+          const externalFeePayerUrl =
+            typeof parameters['feePayer'] === 'string'
+              ? normalizeExternalFeePayerUrl(parameters['feePayer'], {
+                  allowUnsafe: internal_allowUnsafeUrls,
+                })
+              : undefined
+          const requestsSponsorship =
+            (!!feePayerOptions || !!externalFeePayerUrl) && parameters['feePayer'] !== false
+          // Default to `true`. Dapps that don't render diffs can pass
+          // `capabilities.balanceDiffs: false` to skip the post-fill
+          // `tempo_simulateV1` round trip (~250-400ms).
+          const requireBalanceDiffs = capabilities['balanceDiffs'] !== false
+
+          const { feePayer: _feePayer, ...normalized } =
+            Utils.normalizeFillTransactionRequest(parameters)
+
+          // When sponsoring, the sponsor's preferred fee token (if set)
+          // overrides whatever the consumer asked for — the sponsor is
+          // paying, so the sponsor picks. Falls back to the request's
+          // feeToken otherwise.
+          const sponsoredFeeToken = requestsSponsorship
+            ? (feePayerOptions?.feeToken ?? requestFeeToken)
+            : requestFeeToken
+
+          const baseTx = {
+            ...normalized,
+            ...(typeof chainId !== 'undefined' ? { chainId } : {}),
+            ...(sponsoredFeeToken ? { feeToken: sponsoredFeeToken } : {}),
+          }
+
+          let filled: Awaited<ReturnType<typeof fill>>
+          let sponsored = false
+          let feeToken = sponsoredFeeToken
+
+          // Lazily resolve a swap source token when autoSwap needs one.
+          const resolveFeeTokenForSwap = from
+            ? async (insufficientToken: Address) =>
+                resolveFeeToken(client, {
+                  account: from,
+                  feeToken: undefined,
+                  store,
+                  tokens: (await getTokens(chainId)).filter(
+                    (t) => t.toLowerCase() !== insufficientToken.toLowerCase(),
+                  ),
+                })
+            : undefined
+
+          // When no sponsor will pay, prefer fee tokens the user actually
+          // holds. Extend the configured token list with any TIP20 token
+          // the transaction is calling — typically the token being
+          // transferred — so a user transferring USDC.e can pay gas in
+          // USDC.e even when the configured list defaults to pathUSD.
+          const configuredTokens = await getTokens(chainId)
+          const unsponsoredTokens = [
+            ...configuredTokens,
+            ...callTargetTokens(baseTx).filter(
+              (t) => !configuredTokens.some((rt) => rt.toLowerCase() === t.toLowerCase()),
+            ),
+          ]
+
+          // When the app provides its own fee payer URL, route the fill
+          // through that service so it can sign the transaction.
+          const fillClient = externalFeePayerUrl
+            ? createClient({
+                chain: client.chain,
+                batch: { multicall: { deployless: true } },
+                transport: http(externalFeePayerUrl),
+              })
+            : client
+
+          if (requestsSponsorship && (externalFeePayerUrl || !feePayerOptions?.validate)) {
+            // Path A: sponsorship guaranteed — skip fee token resolution,
+            // fill once with feePayer, then parallelize the rest. Taken when:
+            //   - no validate is configured (no gating), OR
+            //   - the app supplied its own external fee payer URL (that
+            //     relay is the sponsorship authority — the wallet's own
+            //     `validate` only governs the wallet's own fee payer).
+            // Default to the chain's first token so the broadcast envelope
+            // always carries a feeToken the chain can charge.
+            if (!feeToken) feeToken = (await getTokens(chainId))[0]
+            const transaction = {
+              ...baseTx,
+              feePayer: true,
+              ...(feeToken ? { feeToken } : {}),
+            }
+            if (Sponsorship.isPreparedTransaction(transaction)) {
+              filled = {
+                transaction: Utils.normalizeTempoTransaction(transaction),
+                sponsor: undefined,
+              }
+            } else {
+              filled = await fill(fillClient, {
+                autoSwap,
+                feeToken,
+                store,
+                resolveFeeToken: resolveFeeTokenForSwap,
+                transaction,
+              })
+              // The chain echoes feeToken: null for sponsored fills served
+              // by viem clients that strip feeToken pre-sign; re-inject
+              // before the spread in mergeCallsFromRequest drops it.
+              if (
+                feeToken &&
+                filled?.transaction &&
+                (filled.transaction as { feeToken?: Address | null }).feeToken == null
+              )
+                (filled.transaction as { feeToken?: Address }).feeToken = feeToken
+            }
+            sponsored = true
+          } else if (requestsSponsorship && feePayerOptions?.validate) {
+            // Path B: sponsorship possible but may be rejected.
+            // Speculatively fill the sponsored variant, validate, and only
+            // fall back to the unsponsored path on rejection. The accept
+            // case (common) avoids the upfront `resolveFeeToken` round
+            // trips and the second `eth_fillTransaction`.
+            const sponsoredTx = { ...baseTx, feePayer: true }
+
+            if (Sponsorship.isPreparedTransaction(sponsoredTx)) {
+              // Already prepared — skip fills, just validate sponsorship.
+              const prepared = {
+                transaction: Utils.normalizeTempoTransaction(sponsoredTx),
+                sponsor: undefined,
+              }
+              sponsored = await Sponsorship.shouldSponsor({
+                sender: from,
+                transaction: prepared.transaction,
+                validate: feePayerOptions!.validate,
+              })
+              filled = prepared
+            } else {
+              const options = {
+                autoSwap,
+                store,
+                resolveFeeToken: resolveFeeTokenForSwap,
+              }
+              const fill_sponsored = await fill(fillClient, {
+                ...options,
+                feeToken,
+                transaction: sponsoredTx,
+              })
+              sponsored = await Sponsorship.shouldSponsor({
+                sender: from,
+                transaction: fill_sponsored.transaction,
+                validate: feePayerOptions!.validate,
+              })
+              if (sponsored) {
+                filled = fill_sponsored
+              } else {
+                // Sponsor rejected — resolve fee token and fill unsponsored.
+                const feeToken_unsponsored = features.feeTokenResolution
+                  ? await resolveFeeToken(client, {
+                      account: from,
+                      feeToken: requestFeeToken,
+                      store,
+                      tokens: unsponsoredTokens,
+                    })
+                  : requestFeeToken
+                const tx_unsponsored = {
+                  ...baseTx,
+                  ...(feeToken_unsponsored ? { feeToken: feeToken_unsponsored } : {}),
+                }
+                filled = await fill(client, {
+                  ...options,
+                  feeToken: feeToken_unsponsored,
+                  transaction: tx_unsponsored,
+                })
+                feeToken = feeToken_unsponsored
+              }
+            }
+          } else {
+            // Path C: no sponsorship configured — resolve fee token, fill once.
+            feeToken = features.feeTokenResolution
+              ? await resolveFeeToken(client, {
+                  account: from,
+                  feeToken: requestFeeToken,
+                  store,
+                  tokens: unsponsoredTokens,
+                })
+              : requestFeeToken
+            const transaction = { ...baseTx, ...(feeToken ? { feeToken } : {}) }
+            filled = await fill(client, {
+              autoSwap,
+              feeToken,
+              store,
+              resolveFeeToken: resolveFeeTokenForSwap,
+              transaction,
+            })
+          }
+
+          const transaction_filled = filled.transaction
+          const swap = 'swap' in filled ? filled.swap : undefined
+          if (!feeToken)
+            feeToken =
+              (transaction_filled.feeToken as Address | undefined) ?? (await getTokens(chainId))[0]
+
+          // Parallelize: simulate, fee payer signing, and autoSwap metadata.
+          const alreadySigned =
+            'feePayerSignature' in transaction_filled &&
+            transaction_filled.feePayerSignature != null
+
+          const calls = extractCalls(transaction_filled)
+          const [simulation, transaction_final, autoSwap_, virtualAddresses] = await Promise.all([
+            // Simulate and compute balance diffs + fee.
+            // When `capabilities.balanceDiffs` is `false`, skip simulate
+            // and compute fee directly from cached metadata.
+            (async () => {
+              if (!features.simulate) return { balanceDiffs: undefined, fee: undefined }
+              if (requireBalanceDiffs)
+                return simulateAndParseDiffs(client, {
+                  account: from,
+                  calls,
+                  swap,
+                  feeToken,
+                  gas: transaction_filled.gas,
+                  store,
+                  maxFeePerGas: transaction_filled.maxFeePerGas,
+                })
+              const fee = await computeFee(client, {
+                feeToken,
+                gas: transaction_filled.gas,
+                store,
+                maxFeePerGas: transaction_filled.maxFeePerGas,
+              }).catch(() => undefined)
+              return { balanceDiffs: undefined, fee }
+            })(),
+            // Sign as fee payer (if sponsored and not already signed).
+            (async () => {
+              if (!(sponsored && feePayerOptions && !alreadySigned)) return transaction_filled
+              return Sponsorship.sign({
+                account: feePayerOptions.account,
+                sender: from,
+                transaction: transaction_filled,
+              })
+            })(),
+            // Resolve autoSwap metadata (when AMM path was taken).
+            resolveAutoSwapMetadata(client, { autoSwap, store, swap }),
+            // Resolve virtual-address recipients so wallets can show the
+            // eventual master address before signing.
+            resolveVirtualAddresses(client, { calls }),
+          ])
+          const { balanceDiffs, fee } = simulation
+
+          const sponsor = (() => {
+            if (!sponsored) return undefined
+            // App-provided fee payer: relay back the sponsor from the upstream response.
+            if (externalFeePayerUrl) return filled.sponsor
+            if (feePayerOptions) return Sponsorship.getSponsor(feePayerOptions)
+            return filled.sponsor
+          })()
+
+          return RpcResponse.from(
+            {
+              result: {
+                ...(sponsor ? { sponsor } : {}),
+                tx: core_Transaction.toRpc(transaction_final as core_Transaction.Transaction),
+                capabilities: {
+                  balanceDiffs,
+                  fee,
+                  sponsored: !!sponsor,
+                  ...(sponsor ? { sponsor } : {}),
+                  ...(autoSwap_ ? { autoSwap: autoSwap_ } : {}),
+                  ...(virtualAddresses ? { virtualAddresses } : {}),
+                },
+              },
+            },
+            { request },
+          )
+        } catch (error) {
+          if (!(error instanceof Error)) return Utils.rpcErrorJson(request, error)
+          if (capabilities['errors'] !== true) return Utils.rpcErrorJson(request, error)
+
+          const revert = ExecutionError.parse(error)
+
+          const parameters = request.params?.[0] as Record<string, unknown>
+          const stub = {
+            from: parameters['from'],
+            to: parameters['to'] ?? null,
+            gas: '0x0',
+            nonce: '0x0',
+            value: '0x0',
+            maxFeePerGas: '0x0',
+            maxPriorityFeePerGas: '0x0',
+          }
+
+          if (revert?.errorName === 'InsufficientBalance') {
+            const args = revert.args as [bigint, bigint, Address]
+            const [available, required, token] = args
+
+            const normalized = Utils.normalizeFillTransactionRequest(parameters)
+
+            // Simulate from zero address for optimistic balance diffs.
+            const optimisticCalls = normalized ? extractCalls(normalized) : undefined
+            const [{ balanceDiffs }, virtualAddresses] = optimisticCalls
+              ? await Promise.all([
+                  simulateAndParseDiffs(client, {
+                    account: zeroAddress,
+                    calls: optimisticCalls,
+                    store,
+                  }),
+                  resolveVirtualAddresses(client, { calls: optimisticCalls }),
+                ])
+              : [{ balanceDiffs: undefined }, undefined]
+
+            // Re-key balance diffs from zero address to the real sender.
+            const senderDiffs =
+              parameters['from'] && balanceDiffs
+                ? { [parameters['from'] as Address]: balanceDiffs[zeroAddress] ?? [] }
+                : balanceDiffs
+
+            const metadata = await resolveTokenMetadata(client, { token, store }).catch(
+              () => undefined,
+            )
+            const deficit = required - available
+            return RpcResponse.from(
+              {
+                result: {
+                  tx: stub,
+                  capabilities: {
+                    balanceDiffs: senderDiffs,
+                    error: ExecutionError.serialize(revert),
+                    requireFunds: metadata
+                      ? {
+                          amount: Hex.fromNumber(deficit) as `0x${string}`,
+                          decimals: metadata.decimals,
+                          formatted: formatUnits(deficit, metadata.decimals),
+                          token,
+                          symbol: metadata.symbol,
+                        }
+                      : undefined,
+                    sponsored: false,
+                    ...(virtualAddresses ? { virtualAddresses } : {}),
+                  },
+                },
+              },
+              { request },
+            )
+          }
+
+          const normalized = Utils.normalizeFillTransactionRequest(parameters)
+          const virtualAddresses = normalized
+            ? await resolveVirtualAddresses(client, { calls: extractCalls(normalized) }).catch(
+                () => undefined,
+              )
+            : undefined
+
+          return RpcResponse.from(
+            {
+              result: {
+                tx: stub,
+                capabilities: {
+                  error: ExecutionError.serialize(revert),
+                  sponsored: false,
+                  ...(virtualAddresses ? { virtualAddresses } : {}),
+                },
+              },
+            },
+            { request },
+          )
+        }
+      }
+
+      case 'eth_signRawTransaction':
+      case 'eth_sendRawTransaction':
+      case 'eth_sendRawTransactionSync': {
+        try {
+          const serialized = params[0]
+          if (
+            multisigOptions &&
+            (request.method === 'eth_sendRawTransaction' ||
+              request.method === 'eth_sendRawTransactionSync') &&
+            typeof serialized === 'string' &&
+            Multisig.isMultisigTransaction(serialized as Hex.Hex)
+          ) {
+            const result = await Multisig.handleRawTransaction({
+              claimTtl: multisigOptions.claimTtl,
+              finalize: multisigOptions.finalize,
+              getClient,
+              method: request.method,
+              request: { params: 'params' in request ? request.params : undefined },
+              resolveConfig: multisigOptions.resolveConfig,
+              sponsor: feePayerOptions
+                ? {
+                    account: feePayerOptions.account,
+                    feeToken: feePayerOptions.feeToken,
+                    resolveFeeToken: async (chainId) => (await getTokens(chainId))[0],
+                    validate: feePayerOptions.validate,
+                  }
+                : undefined,
+              store: multisigOptions.store,
+            })
+            return RpcResponse.from({ result } as never, { request } as never)
+          }
+
+          if (!feePayerOptions) {
+            // eth_signRawTransaction is a signing method that only the
+            // relay can fulfill — forwarding it to the RPC node returns
+            // an opaque "Method not found". Return an actionable error.
+            if ((request as { method: string }).method === 'eth_signRawTransaction') {
+              return RpcResponse.from(
+                {
+                  error: {
+                    code: -32601,
+                    message:
+                      'eth_signRawTransaction requires a fee payer to be configured on the relay. ' +
+                      'Set the `feePayer` option in `Handler.relay()` to enable transaction sponsorship.',
+                  },
+                } as never,
+                { request } as never,
+              )
+            }
+            const result = await client.request(request as never)
+            return RpcResponse.from({ result }, { request })
+          }
+
+          if (
+            typeof serialized !== 'string' ||
+            !Sponsorship.requestsRawSponsorship(serialized as `0x${string}`)
+          ) {
+            const result = await client.request(request as never)
+            return RpcResponse.from({ result }, { request })
+          }
+
+          const result = await Sponsorship.handleRawTransaction({
+            account: feePayerOptions.account,
+            feeToken: feePayerOptions.feeToken,
+            getFeeToken: async (chainId) => (await getTokens(chainId))[0],
+            getClient,
+            method: request.method as Sponsorship.handleRawTransaction.Options['method'],
+            request: { params: 'params' in request ? request.params : undefined },
+            validate: feePayerOptions.validate,
+          })
+          return RpcResponse.from({ result } as never, { request } as never)
+        } catch (error) {
+          return Utils.rpcErrorJson(request, error)
+        }
+      }
+
+      case 'eth_getTransactionByHash':
+      case 'eth_getTransactionReceipt': {
+        try {
+          if (multisigOptions) {
+            const aliased = await Multisig.handleGetTransaction({
+              getClient,
+              method: request.method,
+              request: { params: 'params' in request ? request.params : undefined },
+              store: multisigOptions.store,
+            })
+            if (aliased)
+              return RpcResponse.from({ result: aliased.result } as never, { request } as never)
+          }
+
+          const result = await client.request(request as never)
+          return RpcResponse.from({ result }, { request })
+        } catch (error) {
+          return Utils.rpcErrorJson(request, error)
+        }
+      }
+
+      default: {
+        try {
+          const result = await client.request(request as never)
+          return RpcResponse.from({ result }, { request })
+        } catch (error) {
+          return Utils.rpcErrorJson(request, error)
+        }
+      }
+    }
+  }
+
+  const router = from(rest)
+
+  async function handlePost(c: { req: { raw: Request; param: (key: string) => string } }) {
+    const chainId = Utils.resolveChainId(c.req.param('chainId'))
+    const body = await c.req.raw.json()
+    const isBatch = Array.isArray(body)
+
+    if (!isBatch) {
+      const request = RpcRequest.from(body as never) as RpcRequest.RpcRequest<RpcSchema.Ox>
+      return Response.json(await handleRequest(request, { chainId }))
+    }
+
+    const responses = await Promise.all(
+      (body as unknown[]).map((item) =>
+        handleRequest(RpcRequest.from(item as never) as RpcRequest.RpcRequest<RpcSchema.Ox>, {
+          chainId,
+        }),
+      ),
+    )
+    return Response.json(responses)
+  }
+
+  router.post(path, handlePost as never)
+  router.post(`${path === '/' ? '' : path}/:chainId`, handlePost as never)
+
+  return router
+}
+
+export namespace relay {
+  export type Options = from.Options & {
+    /**
+     * Auto-swap options.
+     */
+    autoSwap?:
+      | false
+      | {
+          /** Slippage tolerance (e.g. 0.05 = 5%). @default 0.05 */
+          slippage?: number | undefined
+        }
+      | undefined
+    /**
+     * Resolves a viem client for a chain id. The handler resolves the client
+     * from the `chainId` in the incoming transaction (falling back to the
+     * client's default chain). Called with no argument for the default client.
+     */
+    getClient: (chainId?: number) => Client
+    /**
+     * Fee payer / sponsor configuration. When provided, the relay will
+     * sign `feePayerSignature` on the filled transaction.
+     */
+    feePayer?:
+      | {
+          /** Account to use as the fee payer. */
+          account: LocalAccount
+          /** Preferred fee token the sponsor wants to pay fees in. */
+          feeToken?: Address | undefined
+          /**
+           * Validates whether to sponsor the transaction. When omitted, all
+           * transactions are sponsored. Return `false` to reject sponsorship.
+           */
+          validate?:
+            | ((request: Transaction.TransactionRequest) => boolean | Promise<boolean>)
+            | undefined
+          /** Sponsor display name returned from `eth_fillTransaction`. */
+          name?: string | undefined
+          /** Sponsor URL returned from `eth_fillTransaction`. */
+          url?: string | undefined
+        }
+      | undefined
+    /**
+     * Native multisig configuration. When provided, the relay collects owner
+     * approvals from multisig raw transaction submissions and broadcasts once
+     * collected owner weight meets the configured threshold.
+     */
+    multisig?: Multisig.Options | undefined
+    /**
+     * Relay features.
+     *
+     * - `'all'` — enables fee token resolution, auto-swap,
+     *   fee payer, and simulation (balance diffs + fee breakdown).
+     * - `undefined` (default) — only fee payers.
+     */
+    features?: 'all' | undefined
+    /**
+     * Allows app-provided external fee payer URLs to use non-HTTPS protocols
+     * or local/private hosts. Intended only for trusted development setups.
+     * @default false
+     */
+    internal_allowUnsafeUrls?: boolean | undefined
+    /**
+     * In-process cache backing TIP-20 metadata and user fee-token preference
+     * memoization. Omit to read upstream on every fill.
+     */
+    cache?: Store.Store | undefined
+    /** Function to call before handling the request. */
+    onRequest?: ((request: RpcRequest.RpcRequest) => Promise<void>) | undefined
+    /** Path to use for the handler. @default "/" */
+    path?: string | undefined
+    /**
+     * Resolves the known fee-token candidates for a chain. The relay checks
+     * the caller's balance for each candidate and picks the highest during
+     * fee-token resolution. Omit to disable fee-token resolution.
+     */
+    resolveTokens?:
+      | ((chainId: number) => readonly Address[] | Promise<readonly Address[]>)
+      | undefined
+  }
+}
+
+// TODO: cleanup
+async function fill(client: Client, options: fill.Options) {
+  const { autoSwap, feeToken, store, transaction: request } = options
+
+  // Skip re-formatting if already in RPC format (e.g. from viem's fillTransaction).
+  const format = (value: Record<string, unknown>) =>
+    value['type'] === '0x76' ? value : Utils.formatFillTransactionRequest(client, value)
+
+  // Re-fill the transaction with prepended swap calls so the user can
+  // mint the missing `insufficientToken` (typically the fee token) from
+  // a token they already hold. Returns null if no source token is
+  // available or autoSwap is disabled.
+  async function fillWithSwap(insufficientToken: Address, deficit: bigint) {
+    if (!autoSwap) return null
+    const sourceToken =
+      feeToken && feeToken.toLowerCase() !== insufficientToken.toLowerCase()
+        ? feeToken
+        : await options.resolveFeeToken?.(insufficientToken)
+    if (!sourceToken || sourceToken.toLowerCase() === insufficientToken.toLowerCase()) return null
+
+    const maxAmountIn = deficit + (deficit * BigInt(Math.round(autoSwap.slippage * 1000))) / 1000n
+    const originalCalls = (request['calls'] as Call[] | undefined) ?? []
+    const swapCalls = buildSwapCalls(client, sourceToken, insufficientToken, deficit, maxAmountIn)
+
+    const result = await client.request({
+      method: 'eth_fillTransaction',
+      params: [
+        format({
+          ...request,
+          calls: [...swapCalls, ...originalCalls],
+        }) as never,
+      ],
+    })
+    const sponsor = (result as Record<string, any>)['capabilities']?.sponsor as
+      | { address: Address; name?: string; url?: string }
+      | undefined
+    const mergedTx = mergeCallsFromRequest(result.tx as Record<string, unknown>, {
+      ...request,
+      calls: [...swapCalls, ...originalCalls],
+    })
+    return {
+      transaction: Utils.normalizeTempoTransaction(mergedTx),
+      sponsor,
+      swap: {
+        calls: swapCalls,
+        tokenIn: sourceToken,
+        tokenOut: insufficientToken,
+        amountOut: deficit,
+        maxAmountIn,
+      },
+    }
+  }
+
+  try {
+    const formatted = format(request)
+    const result = await client.request({
+      method: 'eth_fillTransaction',
+      params: [formatted as never],
+    })
+    // FIXME: node estimates gas with secp256k1 dummy sig + null feePayerSignature.
+    // Actual tx has larger keychain/webAuthn sigs + real fee payer sig, costing
+    // more intrinsic gas. Mirror the bump from viem's tempo chainConfig.
+    // Skip if another relay already bumped (indicated by feePayerSignature).
+    // @ts-expect-error
+    if (result.tx.gas && request.feePayer && !result.tx.feePayerSignature)
+      result.tx.gas = Hex.fromNumber(BigInt(result.tx.gas) + 20_000n)
+    const upstreamCapabilities = (result as { capabilities?: Record<string, unknown> }).capabilities
+    const sponsor = upstreamCapabilities?.['sponsor'] as
+      | { address: Address; name?: string; url?: string }
+      | undefined
+    // External fee-payer relays surface chain reverts (e.g. InsufficientBalance,
+    // InsufficientAllowance) inside `capabilities.error` with a stub `tx`
+    // instead of throwing. Re-throw all upstream errors so the outer handler
+    // either recovers via autoSwap (InsufficientBalance) or propagates the
+    // error to the caller. Without this, the wallet would otherwise sign the
+    // zero-stub tx with its own fee payer and broadcast garbage.
+    const upstreamError = upstreamCapabilities?.['error'] as
+      | { errorName?: string; message?: string; data?: `0x${string}` }
+      | undefined
+    if (upstreamError) {
+      const synthetic = new Error(
+        upstreamError.message ?? upstreamError.errorName ?? 'UpstreamRevert',
+      )
+      synthetic.name = 'UpstreamRevertError'
+      ;(synthetic as { data?: `0x${string}` | undefined }).data = upstreamError.data
+      throw synthetic
+    }
+    // Reconstruct a `swap` shape from upstream's `capabilities.autoSwap` so the
+    // wallet relay's outer code can re-resolve autoSwap metadata locally —
+    // otherwise upstream-driven swaps are silently dropped from the response.
+    const swap = extractSwapFromCapabilities(upstreamCapabilities?.['autoSwap'])
+    // The chain's `eth_fillTransaction` doesn't echo back `calls`, so merge
+    // them in from the original request before normalizing — otherwise the
+    // typed envelope built for sponsorship signing throws CallsEmptyError.
+    const mergedTx = mergeCallsFromRequest(result.tx as Record<string, unknown>, request)
+
+    // The node's `eth_fillTransaction` may pick a fee token the user
+    // doesn't yet hold (e.g. one this transaction will mint via a
+    // swap). Tempo's gas check runs before the calls execute, so the
+    // tx would revert at broadcast with `have 0 want N`. Validate the
+    // sender's pre-tx balance against the computed gas cost and, if
+    // short, autoSwap a token they do hold into the fee token.
+    if (autoSwap && !swap) {
+      const fromAddress = request['from'] as Address | undefined
+      const resolvedFeeToken = ((mergedTx['feeToken'] as Address | undefined) ?? feeToken) as
+        | Address
+        | undefined
+      const gas = mergedTx['gas'] ? BigInt(mergedTx['gas'] as `0x${string}`) : 0n
+      const maxFeePerGas = mergedTx['maxFeePerGas']
+        ? BigInt(mergedTx['maxFeePerGas'] as `0x${string}`)
+        : 0n
+      if (fromAddress && resolvedFeeToken && gas > 0n && maxFeePerGas > 0n) {
+        const [balance, metadata] = await Promise.all([
+          Actions.token
+            .getBalance(client, { account: fromAddress, token: resolvedFeeToken })
+            .then((balance) => balance.amount)
+            .catch(() => 0n),
+          resolveTokenMetadata(client, { token: resolvedFeeToken, store }).catch(() => undefined),
+        ])
+        if (metadata) {
+          const requiredFee =
+            (gas * maxFeePerGas) / 10n ** BigInt(Math.max(0, 18 - metadata.decimals))
+          if (balance < requiredFee) {
+            // Best-effort: if the swap itself can't be filled (e.g. the
+            // source token also has insufficient balance), fall through
+            // and return the original tx with the resolved feeToken
+            // rather than failing the whole request.
+            const swapResult = await fillWithSwap(resolvedFeeToken, requiredFee - balance).catch(
+              () => null,
+            )
+            if (swapResult) return swapResult
+          }
+        }
+      }
+    }
+
+    return {
+      transaction: Utils.normalizeTempoTransaction(mergedTx),
+      sponsor,
+      ...(swap ? { swap } : {}),
+    }
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    if (!autoSwap) throw error
+
+    const revert = ExecutionError.parse(error)
+    if (revert?.errorName !== 'InsufficientBalance') throw error
+
+    const [available, required, token] = revert.args
+    if (typeof available === 'undefined' || typeof required === 'undefined' || !token) throw error
+
+    const swapResult = await fillWithSwap(token as Address, required - available)
+    if (!swapResult) throw error
+    return swapResult
+  }
+}
+
+declare namespace fill {
+  type Options = {
+    autoSwap?: { slippage: number } | undefined
+    feeToken?: Address | undefined
+    store?: Store.Store | undefined
+    resolveFeeToken?: ((insufficientToken: Address) => Promise<Address | undefined>) | undefined
+    transaction: Record<string, unknown>
+  }
+}
+
+async function resolveFeeToken(
+  client: Client,
+  options: resolveFeeToken.Options,
+): Promise<Address | undefined> {
+  const { feeToken, account, store, tokens } = options
+  if (feeToken) return feeToken
+  if (!account) return undefined
+
+  // Cache the user's preferred fee token for `userTokenCacheTtl` seconds.
+  // The on-chain preference rarely changes; a short TTL avoids the
+  // ~150-250ms `userTokens` multicall on every unsponsored fill while
+  // still picking up updates within a minute. The cached value is just a
+  // hint — if the user's balance is 0 we fall back to the highest-balance
+  // token from the configured list.
+  const getUserToken = () => Actions.fee.getUserToken(client, { account }).catch(() => null)
+  const userTokenPromise = store
+    ? Store.memoize(
+        async () => {
+          const result = await getUserToken()
+          return result ? { address: result.address } : null
+        },
+        {
+          key: `fee.userToken:${client.chain?.id ?? 0}:${account.toLowerCase()}`,
+          store,
+          ttl: (options.userTokenCacheTtl ?? 60) * 1000,
+        },
+      )
+    : getUserToken()
+
+  const [userToken, balances] = await Promise.all([
+    userTokenPromise,
+    tokens
+      ? Promise.all(
+          tokens.map(async (token) => ({
+            address: token,
+            balance: await Actions.token
+              .getBalance(client, { account, token })
+              .then((balance) => balance.amount)
+              .catch(() => 0n),
+          })),
+        )
+      : [],
+  ])
+
+  // If on-chain preference is set and user has balance, use it.
+  if (userToken) {
+    const match = balances.find(
+      (b: { address: Address; balance: bigint }) =>
+        b.address.toLowerCase() === userToken.address.toLowerCase() && b.balance > 0n,
+    )
+    if (match) return userToken.address
+
+    // Token list may not include the preference — check on-chain directly.
+    if (!match) {
+      try {
+        const { amount: balance } = await Actions.token.getBalance(client, {
+          account,
+          token: userToken.address,
+        })
+        if (balance > 0n) return userToken.address
+      } catch {}
+    }
+  }
+
+  // Pick the token with the highest balance.
+  let best: { address: Address; balance: bigint } | undefined
+  for (const asset of balances) {
+    if (asset.balance <= 0n) continue
+    if (!best || asset.balance > best.balance) best = asset
+  }
+  if (best) return best.address
+  return undefined
+}
+
+declare namespace resolveFeeToken {
+  type Options = {
+    feeToken?: Address | undefined
+    account?: Address | undefined
+    store?: Store.Store | undefined
+    tokens?: readonly Address[] | undefined
+    /** TTL in seconds for the cached `userTokens` lookup. @default 60 */
+    userTokenCacheTtl?: number | undefined
+  }
+}
+
+/**
+ * Extracts unique TIP20 token addresses (Tempo `0x20c0…` prefix) that the
+ * transaction's calls target. Used as fallback fee-token candidates so a
+ * user transferring a token they hold can pay gas in that token even when
+ * the configured fee-token list defaults to one they don't hold.
+ */
+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)
+  }
+  return out
+}
+
+// TODO: Replace with viem's Tempo fillTransaction capability type once released.
+type VirtualAddresses = Record<Address, Address | null>
+
+async function resolveVirtualAddresses(
+  client: Client,
+  options: { calls: readonly Call[] },
+): Promise<VirtualAddresses | undefined> {
+  const targets = getVirtualAddressTargets(options.calls)
+  if (targets.length === 0) return undefined
+
+  const masters = new Map<string, { addresses: Address[]; masterId: Hex.Hex }>()
+  for (const address of targets) {
+    const { masterId } = VirtualAddress.parse(address)
+    const lower = masterId.toLowerCase()
+    const entry = masters.get(lower) ?? { addresses: [], masterId }
+    entry.addresses.push(address)
+    masters.set(lower, entry)
+  }
+
+  const entries = await Promise.all(
+    [...masters.values()].map(async ({ addresses, masterId }) => {
+      const master = await Actions.virtualAddress.getMasterAddress(client, { masterId })
+      return addresses.map((address) => [address, master] as const)
+    }),
+  )
+  return Object.fromEntries(entries.flat()) as VirtualAddresses
+}
+
+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)
+    }
+  }
+  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'])
+
+// TODO: cleanup/remove
+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[]
+}
+
+// TODO: cleanup/remove
+async function simulate(client: Client, options: simulate.Options) {
+  const { account, calls } = options
+  try {
+    return await Actions.simulate.simulateCalls(client, {
+      ...(account ? { account } : {}),
+      calls: calls as Call[],
+      traceTransfers: true,
+    })
+  } catch (error) {
+    // TODO: Remove fallback once all nodes support tempo_simulateV1.
+    // Fall back to viem's simulateCalls (eth_simulateV1) if the Tempo
+    // method (tempo_simulateV1) is not supported.
+    const code =
+      (error as { code?: number | undefined }).code ??
+      (error as { cause?: { code?: number | undefined } | undefined }).cause?.code
+    if (code !== -32601) throw error
+    const { results } = await simulateCalls(client, {
+      ...(account ? { account } : {}),
+      calls: calls as Call[],
+    })
+    return { results, tokenMetadata: undefined }
+  }
+}
+
+declare namespace simulate {
+  type Options = {
+    account?: Address | undefined
+    calls: readonly Call[]
+  }
+}
+
+async function simulateAndParseDiffs(client: Client, options: simulateAndParseDiffs.Options) {
+  const { account, calls, swap, feeToken, gas, store, maxFeePerGas } = options
+
+  try {
+    const { results, tokenMetadata } = await simulate(client, {
+      account: account === zeroAddress ? undefined : account,
+      calls,
+    })
+
+    // 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,
+          logs,
+          swap,
+          tokenMetadata: tokenMetadata as never,
+        })
+      : {}
+
+    // Compute fee breakdown.
+    const fee = await computeFee(client, {
+      feeToken,
+      gas,
+      store,
+      maxFeePerGas,
+      tokenMetadata: tokenMetadata as never,
+    }).catch(() => undefined)
+
+    return { balanceDiffs, fee }
+  } catch {
+    // 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 })
+    return { balanceDiffs: undefined, fee }
+  }
+}
+
+declare namespace simulateAndParseDiffs {
+  type Options = {
+    account?: Address | undefined
+    calls: readonly Call[]
+    swap?: { tokenIn: Address; tokenOut: Address } | undefined
+    feeToken?: Address | undefined
+    gas?: bigint | undefined
+    store?: Store.Store | undefined
+    maxFeePerGas?: bigint | undefined
+  }
+}
+
+async function buildBalanceDiffs(client: Client, options: buildBalanceDiffs.Options) {
+  const { account, store, logs, swap, tokenMetadata } = options
+  const accountLower = account.toLowerCase()
+  const dexLower = Addresses.stablecoinDex.toLowerCase()
+  const swapTokenIn = swap?.tokenIn.toLowerCase()
+  const swapTokenOut = swap?.tokenOut.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; recipients: Set<Address>; token: Address }
+  >()
+
+  // Track total transferred per (token, spender) so we can suppress covered approvals.
+  const transferredBySpender = new Map<string, bigint>()
+
+  for (const log of transferLogs) {
+    const token = log.address.toLowerCase()
+    const fromLower = log.args.from.toLowerCase()
+    const toLower = log.args.to.toLowerCase()
+
+    // Skip swap-related transfers (reported in capabilities.autoSwap instead).
+    if (swap) {
+      if (token === swapTokenIn && fromLower === accountLower && toLower === dexLower) continue
+      if (token === swapTokenOut && fromLower === dexLower && toLower === accountLower) continue
+    }
+
+    const entry = tokenMap.get(token) ?? {
+      incoming: 0n,
+      outgoing: 0n,
+      recipients: new Set<Address>(),
+      token: log.address,
+    }
+    if (fromLower === accountLower) {
+      entry.outgoing += log.args.amount
+      entry.recipients.add(log.args.to)
+      const key = `${token}:${toLower}`
+      transferredBySpender.set(key, (transferredBySpender.get(key) ?? 0n) + log.args.amount)
+    }
+    if (toLower === accountLower) entry.incoming += log.args.amount
+    tokenMap.set(token, entry)
+  }
+
+  // Treat approvals as outgoing unless the spender already transferred >= approval amount.
+  for (const log of approvalLogs) {
+    if (log.args.owner.toLowerCase() !== accountLower) continue
+    const token = log.address.toLowerCase()
+
+    // Skip swap-related approvals (reported in capabilities.autoSwap instead).
+    if (swap && token === swapTokenIn && log.args.spender.toLowerCase() === dexLower) continue
+
+    const spenderKey = `${token}:${log.args.spender.toLowerCase()}`
+    const transferred = transferredBySpender.get(spenderKey) ?? 0n
+    if (log.args.amount <= transferred) continue
+
+    const entry = tokenMap.get(token) ?? {
+      incoming: 0n,
+      outgoing: 0n,
+      recipients: new Set<Address>(),
+      token: log.address,
+    }
+    entry.outgoing += log.args.amount - transferred
+    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
+  })
+  if (entries.length === 0) return {}
+
+  // Resolve metadata for all tokens in parallel (simulation metadata first, RPC fallback).
+  const metadataMap = new Map<string, { decimals: number; symbol: string; name: string }>()
+  await Promise.all(
+    entries.map(async (entry) => {
+      try {
+        const metadata = await resolveTokenMetadata(client, {
+          token: entry.token,
+          tokenMetadata,
+          store,
+        })
+        metadataMap.set(entry.token.toLowerCase(), metadata)
+      } catch {}
+    }),
+  )
+
+  // Build the diff array for this account.
+  const diffs: Capabilities.BalanceDiff[] = []
+  for (const entry of entries) {
+    const net =
+      entry.outgoing > entry.incoming
+        ? entry.outgoing - entry.incoming
+        : entry.incoming - entry.outgoing
+
+    const direction = entry.outgoing > entry.incoming ? 'outgoing' : 'incoming'
+    const meta = metadataMap.get(entry.token.toLowerCase())
+    const decimals = meta?.decimals ?? 0
+    diffs.push({
+      address: entry.token,
+      decimals,
+      direction,
+      formatted: formatUnits(net, decimals),
+      name: meta?.name ?? '',
+      symbol: meta?.symbol ?? '',
+      recipients: [...entry.recipients] as Address[],
+      value: Hex.fromNumber(net) as `0x${string}`,
+    })
+  }
+
+  return { [account]: diffs }
+}
+
+declare namespace buildBalanceDiffs {
+  type Options = {
+    account: Address
+    store?: Store.Store | undefined
+    logs: Log[]
+    swap?: { tokenIn: Address; tokenOut: Address } | undefined
+    tokenMetadata: Record<Address, { name: string; symbol: string; currency: string }>
+  }
+}
+
+async function resolveTokenMetadata(client: Client, options: resolveTokenMetadata.Options) {
+  const { token, tokenMetadata, store } = options
+  const meta = tokenMetadata?.[token] ?? tokenMetadata?.[token.toLowerCase() as Address]
+  // 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,
+  }
+}
+
+declare namespace resolveTokenMetadata {
+  type Options = {
+    token: Address
+    tokenMetadata?: Record<Address, { name: string; symbol: string; currency: string }> | undefined
+    store?: Store.Store | undefined
+  }
+}
+
+async function resolveAutoSwapMetadata(client: Client, options: resolveAutoSwapMetadata.Options) {
+  const { autoSwap, store, swap } = options
+  if (!autoSwap || !swap) return undefined
+  const [inMeta, outMeta] = await Promise.all([
+    resolveTokenMetadata(client, { token: swap.tokenIn, store }).catch(() => undefined),
+    resolveTokenMetadata(client, { token: swap.tokenOut, store }).catch(() => undefined),
+  ])
+  if (!inMeta || !outMeta) return undefined
+  return {
+    calls: swap.calls.map((c) => ({ to: c.to, data: c.data })),
+    slippage: autoSwap.slippage,
+    maxIn: {
+      token: swap.tokenIn,
+      value: Hex.fromNumber(swap.maxAmountIn) as `0x${string}`,
+      formatted: formatUnits(swap.maxAmountIn, inMeta.decimals),
+      decimals: inMeta.decimals,
+      symbol: inMeta.symbol,
+      name: inMeta.name,
+    },
+    minOut: {
+      token: swap.tokenOut,
+      value: Hex.fromNumber(swap.amountOut) as `0x${string}`,
+      formatted: formatUnits(swap.amountOut, outMeta.decimals),
+      decimals: outMeta.decimals,
+      symbol: outMeta.symbol,
+      name: outMeta.name,
+    },
+  }
+}
+
+declare namespace resolveAutoSwapMetadata {
+  type Options = {
+    autoSwap?: { slippage: number } | undefined
+    store?: Store.Store | undefined
+    swap?:
+      | {
+          calls: readonly { to: Address; data: `0x${string}` }[]
+          tokenIn: Address
+          tokenOut: Address
+          amountOut: bigint
+          maxAmountIn: bigint
+        }
+      | undefined
+  }
+}
+
+async function computeFee(client: Client, options: computeFee.Options) {
+  const { feeToken, gas, store, maxFeePerGas, tokenMetadata } = options
+  if (!feeToken || !gas || !maxFeePerGas) return undefined
+
+  try {
+    const metadata = await resolveTokenMetadata(client, { token: feeToken, tokenMetadata, store })
+    const raw = gas * maxFeePerGas
+    const amount = raw / 10n ** BigInt(18 - metadata.decimals)
+    return {
+      amount: Hex.fromNumber(amount) as `0x${string}`,
+      decimals: metadata.decimals,
+      formatted: formatUnits(amount, metadata.decimals),
+      symbol: metadata.symbol,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+declare namespace computeFee {
+  type Options = {
+    feeToken?: Address | undefined
+    gas?: bigint | undefined
+    store?: Store.Store | undefined
+    maxFeePerGas?: bigint | undefined
+    tokenMetadata?: Record<Address, { name: string; symbol: string; currency: string }> | undefined
+  }
+}
+
+function buildSwapCalls(
+  client: Client,
+  sourceToken: Address,
+  targetToken: Address,
+  deficit: bigint,
+  maxAmountIn: bigint,
+) {
+  const approve = Actions.token.approve.call(client, {
+    token: sourceToken,
+    spender: Addresses.stablecoinDex,
+    amount: maxAmountIn,
+  })
+  const buy = Actions.dex.buy.call({
+    tokenIn: sourceToken,
+    tokenOut: targetToken,
+    amountOut: deficit,
+    maxAmountIn,
+  })
+  return [
+    { to: approve.to, data: approve.data, value: 0n },
+    { to: buy.to, data: buy.data, value: 0n },
+  ] as const
+}
+
+/**
+ * Merges the original fill request into the result tx. The chain's
+ * `eth_fillTransaction` returns only the "filled" gas/nonce/fee fields and
+ * omits envelope inputs like `calls`, `chainId`, `validBefore`, `nonceKey`,
+ * `keyData`, `keyType`, `feePayer`. Without these the typed Tempo envelope
+ * built for sponsorship signing throws `CallsEmptyError` or
+ * `Cannot convert undefined to a BigInt` when serializing.
+ *
+ * Result fields take precedence (they are the chain's authoritative filled
+ * values); request fields fill in everything else. Calls are normalized
+ * separately so legacy `to`/`data`/`value` requests are also supported.
+ */
+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) && reqCalls.length > 0) {
+    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
+}
+
+/** Normalizes external fee-payer relay URLs before forwarding fill payloads. */
+function normalizeExternalFeePayerUrl(
+  value: string,
+  options: normalizeExternalFeePayerUrl.Options = {},
+): string {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL.' })
+  }
+
+  const allowUnsafe = options.allowUnsafe === true
+  if (url.protocol !== 'http:' && url.protocol !== 'https:')
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+  if (!allowUnsafe && url.protocol !== 'https:')
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+  if (!allowUnsafe && isUnsafeHostname(url.hostname))
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL host.' })
+
+  url.username = ''
+  url.password = ''
+  url.hash = ''
+  return url.href
+}
+
+declare namespace normalizeExternalFeePayerUrl {
+  type Options = {
+    /** Whether to allow non-HTTPS or local/private external fee payer URLs. */
+    allowUnsafe?: boolean | undefined
+  }
+}
+
+function isUnsafeHostname(hostname: string): boolean {
+  const host = normalizeHostname(hostname)
+  if (host === 'localhost' || host.endsWith('.localhost')) return true
+  const ipv4 = parseIpv4(host)
+  if (ipv4) return isUnsafeIpv4(ipv4)
+  if (!host.includes(':')) return false
+  const ipv6 = parseIpv6(host)
+  if (!ipv6) return true
+  return isUnsafeIpv6(ipv6)
+}
+
+function normalizeHostname(hostname: string): string {
+  return hostname
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '')
+    .split('%')[0]!
+}
+
+function parseIpv4(value: string): [number, number, number, number] | undefined {
+  const parts = value.split('.')
+  if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined
+  const numbers = parts.map((part) => Number(part))
+  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined
+  return numbers as [number, number, number, number]
+}
+
+function isUnsafeIpv4(parts: [number, number, number, number]): boolean {
+  const [a, b] = parts
+  if (a === 0 || a === 10 || a === 127) return true
+  if (a === 100 && b >= 64 && b <= 127) return true
+  if (a === 169 && b === 254) return true
+  if (a === 172 && b >= 16 && b <= 31) return true
+  if (a === 192 && b === 168) return true
+  if (a >= 224) return true
+  return false
+}
+
+function parseIpv6(
+  value: string,
+): [number, number, number, number, number, number, number, number] | undefined {
+  const halves = value.split('::')
+  if (halves.length > 2) return undefined
+
+  const left = halves[0] ? halves[0].split(':') : []
+  const right = halves[1] ? halves[1].split(':') : []
+  const missing = halves.length === 2 ? 8 - left.length - right.length : 0
+  if (missing < 0) return undefined
+
+  const parts = [...left, ...Array(missing).fill('0'), ...right]
+  if (parts.length !== 8) return undefined
+
+  const numbers = parts.map((part) =>
+    /^[\da-f]{1,4}$/i.test(part) ? Number.parseInt(part, 16) : NaN,
+  )
+  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff)) return undefined
+  return numbers as [number, number, number, number, number, number, number, number]
+}
+
+function isUnsafeIpv6(parts: [number, number, number, number, number, number, number, number]) {
+  const [a] = parts
+  if (parts.every((part) => part === 0)) return true
+  if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return true
+  if ((a & 0xfe00) === 0xfc00) return true
+  if ((a & 0xffc0) === 0xfe80) return true
+  if ((a & 0xffc0) === 0xfec0) return true
+  if ((a & 0xff00) === 0xff00) return true
+
+  const ipv4 = ipv4FromIpv6(parts)
+  if (ipv4) return isUnsafeIpv4(ipv4)
+  return false
+}
+
+function ipv4FromIpv6(
+  parts: [number, number, number, number, number, number, number, number],
+): [number, number, number, number] | undefined {
+  const mapped = parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff
+  const compatible = parts.slice(0, 6).every((part) => part === 0)
+  if (!mapped && !compatible) return undefined
+  return [parts[6]! >> 8, parts[6]! & 0xff, parts[7]! >> 8, parts[7]! & 0xff]
+}
+
+/**
+ * Reconstructs a `swap` shape (matching the inner autoSwap branch's return
+ * value) from an upstream relay's `capabilities.autoSwap`. Used so a wallet
+ * relay forwarding to an external feePayer URL can re-emit autoSwap metadata
+ * locally without losing track of the upstream's swap.
+ */
+function extractSwapFromCapabilities(autoSwap: unknown):
+  | {
+      calls: readonly { to: Address; data: `0x${string}` }[]
+      tokenIn: Address
+      tokenOut: Address
+      amountOut: bigint
+      maxAmountIn: bigint
+    }
+  | undefined {
+  if (!autoSwap || typeof autoSwap !== 'object') return undefined
+  const a = autoSwap as {
+    calls?: readonly { to: Address; data: `0x${string}` }[]
+    maxIn?: { token?: Address; value?: `0x${string}` }
+    minOut?: { token?: Address; value?: `0x${string}` }
+  }
+  if (!a.calls || !a.maxIn?.token || !a.maxIn.value || !a.minOut?.token || !a.minOut.value)
+    return undefined
+  return {
+    calls: a.calls,
+    tokenIn: a.maxIn.token,
+    tokenOut: a.minOut.token,
+    amountOut: BigInt(a.minOut.value),
+    maxAmountIn: BigInt(a.maxIn.value),
+  }
+}