mppx 0.8.17 → 0.8.18

package/src/tempo/internal/fee-payer.ts

@@ -1,808 +0,0 @@
-import { Secp256k1 } from 'ox'
-import type { TempoAddress } from 'ox/tempo'
-import { TxEnvelopeTempo } from 'ox/tempo'
-import type { Hex } from 'viem'
-import type { Account } from 'viem'
-import { decodeFunctionData, encodeFunctionData, maxUint256, toHex } from 'viem'
-import { Abis, Addresses, Transaction } from 'viem/tempo'
-
-import * as TempoAddress_internal from './address.js'
-import * as defaults from './defaults.js'
-import * as Selectors from './selectors.js'
-
-/** Returns true if the serialized transaction has a Tempo envelope prefix. */
-export function isTempoTransaction(serialized: string | undefined): boolean {
-  return (
-    serialized?.startsWith(TxEnvelopeTempo.serializedType) === true ||
-    serialized?.startsWith(TxEnvelopeTempo.feePayerMagic) === true
-  )
-}
-
-/**
- * Allowed call patterns for fee-payer sponsored transactions.
- * Each inner array is an ordered list of function selectors.
- */
-export const callScopes = [
-  [Selectors.transfer],
-  [Selectors.transferWithMemo],
-  [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transfer],
-  [Selectors.approve, Selectors.swapExactAmountOut, Selectors.transferWithMemo],
-]
-
-export type Policy = {
-  maxGas: bigint
-  maxFeePerGas: bigint
-  maxPriorityFeePerGas: bigint
-  maxTotalFee: bigint
-  maxValidityWindowSeconds: number
-}
-
-// Reuse the exact object shape returned by `Transaction.deserialize()`.
-// `typeof Transaction` gets the module value type, `['deserialize']` picks the
-// deserialize function off that module, and `ReturnType<...>` asks TypeScript
-// for that function's return type so this helper stays aligned with upstream
-// Tempo transaction fields.
-type SponsoredTransaction = ReturnType<(typeof Transaction)['deserialize']>
-
-type HostedFeePayerFillResponse = {
-  error?: { message?: string | undefined } | undefined
-  result?: {
-    tx?: {
-      feePayerSignature?: unknown
-      feeToken?: unknown
-    }
-  }
-}
-
-type ExpectedTransfer = {
-  amount: string
-  allowAnyMemo?: boolean | undefined
-  memo?: Hex | undefined
-  recipient: TempoAddress.Address
-}
-
-const preservedTransactionKeys = [
-  'accessList',
-  'calls',
-  'chainId',
-  'feeToken',
-  'from',
-  'gas',
-  'keyAuthorization',
-  'maxFeePerGas',
-  'maxPriorityFeePerGas',
-  'nonce',
-  'nonceKey',
-  'signature',
-  'validAfter',
-  'validBefore',
-] as const satisfies readonly (keyof SponsoredTransaction)[]
-
-const rejectedTransactionKeys = [
-  'blobVersionedHashes',
-  'blobs',
-  'data',
-  'feePayerSignature',
-  'gasPrice',
-  'kzg',
-  'maxFeePerBlobGas',
-  'r',
-  's',
-  'sidecars',
-  'to',
-  'v',
-  'value',
-  'yParity',
-] as const
-
-const rewrittenTransactionKeys = ['type'] as const
-
-const supportedTransactionKeys = new Set<string>([
-  ...preservedTransactionKeys,
-  ...rejectedTransactionKeys,
-  ...rewrittenTransactionKeys,
-])
-
-function pushAllowedFeeToken(tokens: TempoAddress.Address[], token: string | undefined) {
-  if (!token) return
-  const normalized = token as TempoAddress.Address
-  if (tokens.some((existing) => TempoAddress_internal.isEqual(existing, normalized))) return
-  tokens.push(normalized)
-}
-
-/** Returns fee tokens that mppx allows sponsored transactions to charge. */
-export function defaultAllowedFeeTokens(chainId: number | undefined) {
-  const tokens: TempoAddress.Address[] = []
-  pushAllowedFeeToken(tokens, defaults.tokens.pathUsd)
-  pushAllowedFeeToken(tokens, defaults.currency[chainId as keyof typeof defaults.currency])
-  return tokens
-}
-
-/** Rejects a sponsored fee token outside the server's allowlist. */
-export function assertAllowedFeeToken(
-  transaction: { feeToken?: unknown },
-  allowedFeeTokens: readonly TempoAddress.Address[],
-) {
-  const { feeToken } = transaction
-  if (feeToken === undefined) return
-  if (typeof feeToken !== 'string')
-    throw new FeePayerValidationError('fee-sponsored transaction feeToken is invalid', {})
-  const normalized = feeToken as TempoAddress.Address
-  if (!allowedFeeTokens.some((allowed) => TempoAddress_internal.isEqual(allowed, normalized)))
-    throw new FeePayerValidationError('fee-sponsored transaction feeToken is not allowed', {
-      feeToken,
-    })
-}
-
-function hostedFeePayerRequest(transaction: SponsoredTransaction) {
-  return {
-    ...(transaction.accessList?.length ? { accessList: transaction.accessList } : {}),
-    calls: transaction.calls.map(
-      (call: {
-        data?: `0x${string}` | undefined
-        to?: TempoAddress.Address | undefined
-        value?: bigint | undefined
-      }) => ({
-        ...(call.to ? { to: call.to } : {}),
-        ...(call.data ? { data: call.data } : {}),
-        value: call.value === undefined ? '0x' : toHex(call.value),
-      }),
-    ),
-    feePayer: true,
-    from: transaction.from,
-    ...(transaction.gas !== undefined ? { gas: toHex(transaction.gas) } : {}),
-    ...(transaction.keyAuthorization !== undefined
-      ? { keyAuthorization: transaction.keyAuthorization }
-      : {}),
-    ...(transaction.maxFeePerGas !== undefined
-      ? { maxFeePerGas: toHex(transaction.maxFeePerGas) }
-      : {}),
-    ...(transaction.maxPriorityFeePerGas !== undefined
-      ? { maxPriorityFeePerGas: toHex(transaction.maxPriorityFeePerGas) }
-      : {}),
-    nonce: toHex(transaction.nonce ?? 0),
-    ...(transaction.nonceKey !== undefined ? { nonceKey: toHex(transaction.nonceKey) } : {}),
-    type: '0x76',
-    ...(transaction.validAfter !== undefined ? { validAfter: toHex(transaction.validAfter) } : {}),
-    ...(transaction.validBefore !== undefined
-      ? { validBefore: toHex(transaction.validBefore) }
-      : {}),
-  }
-}
-
-/**
- * Co-signs a sender-signed partial sponsorship envelope using a hosted
- * fee-payer endpoint without letting the endpoint mutate sender-committed
- * transaction fields.
- *
- * @returns The serialized co-signed transaction plus the sponsor's recovered
- *   `feePayer` address and chosen `feeToken`, so callers can pre-broadcast
- *   simulate the exact transaction the sponsor broadcasts.
- */
-export async function fillHostedFeePayerTransaction(parameters: {
-  allowedFeeTokens: readonly TempoAddress.Address[]
-  challengeExpires?: string | undefined
-  chainId: number
-  details: Record<string, string>
-  policy?: Partial<Policy> | undefined
-  transaction: SponsoredTransaction
-  url: string
-}) {
-  const { allowedFeeTokens, challengeExpires, chainId, details, policy, transaction, url } =
-    parameters
-  assertTransactionPolicy({
-    challengeExpires,
-    chainId,
-    details,
-    policy,
-    transaction,
-  })
-  const response = await fetch(url, {
-    body: JSON.stringify(
-      {
-        id: 1,
-        jsonrpc: '2.0',
-        method: 'eth_fillTransaction',
-        params: [hostedFeePayerRequest(transaction)],
-      },
-      (_key, value) => (typeof value === 'bigint' ? toHex(value) : value),
-    ),
-    headers: { 'content-type': 'application/json' },
-    method: 'POST',
-  })
-  const payload = (await response.json().catch(async () => ({
-    error: { message: await response.text() },
-  }))) as HostedFeePayerFillResponse
-  const filled = payload.result?.tx
-  if (!response.ok || payload.error || !filled?.feePayerSignature)
-    throw new FeePayerValidationError(
-      payload.error?.message ?? 'hosted fee payer failed to sponsor transaction',
-      {},
-    )
-  if (typeof filled.feeToken !== 'string')
-    throw new FeePayerValidationError('hosted fee payer did not return a feeToken', {})
-
-  assertAllowedFeeToken({ feeToken: filled.feeToken }, allowedFeeTokens)
-
-  const feePayerSignature = {
-    ...(filled.feePayerSignature as Record<string, unknown>),
-    yParity: Number((filled.feePayerSignature as { yParity?: unknown }).yParity),
-  }
-  const feeToken = filled.feeToken as TempoAddress.Address
-
-  // Recover the concrete sponsor address so the simulation can use a concrete
-  // `feePayer` (the node rejects `eth_call` with `feePayer: true`).
-  const feePayer = (() => {
-    try {
-      return Secp256k1.recoverAddress({
-        payload: TxEnvelopeTempo.getFeePayerSignPayload(
-          TxEnvelopeTempo.from({
-            ...transaction,
-            feePayerSignature: undefined,
-            feeToken,
-            signature: undefined,
-          } as never),
-          { sender: transaction.from as never },
-        ),
-        signature: feePayerSignature as never,
-      })
-    } catch {
-      throw new FeePayerValidationError(
-        'hosted fee payer returned an invalid feePayerSignature',
-        {},
-      )
-    }
-  })()
-
-  return {
-    feePayer,
-    feeToken,
-    serializedTransaction: await Transaction.serialize({
-      ...transaction,
-      feePayer: true,
-      feePayerSignature,
-      feeToken,
-    } as never),
-  }
-}
-
-/**
- * Returns a transaction shape suitable for pre-broadcast simulation.
- *
- * Sponsored transactions are first simulated as calls from the sender with no
- * fee fields or signatures. This checks call execution without requiring the
- * sender to hold the fee token; transferred value and call-level balances are
- * still checked by the RPC.
- */
-export function simulationTransaction(
-  transaction: SponsoredTransaction,
-  options: { feePayer: boolean },
-) {
-  if (options.feePayer)
-    return {
-      account: transaction.from,
-      calls: transaction.calls,
-    }
-  return {
-    ...transaction,
-    account: transaction.from,
-    calls: transaction.calls,
-    feePayerSignature: undefined,
-  }
-}
-
-/**
- * Returns the final fee-sponsored transaction shape for pre-broadcast
- * simulation. RPC `eth_call` does not carry either transaction signature.
- */
-export function sponsoredSimulationTransaction(
-  transaction: SponsoredTransaction,
-  options: { feePayer: TempoAddress.Address; feeToken?: TempoAddress.Address | undefined },
-) {
-  const { feePayer, feeToken } = options
-  return {
-    ...transaction,
-    account: transaction.from,
-    calls: transaction.calls,
-    feePayer,
-    feePayerSignature: undefined,
-    ...(feeToken !== undefined ? { feeToken } : {}),
-    signature: undefined,
-  }
-}
-
-/** A completed sponsorship envelope that can be simulated before signing or broadcast. */
-export type PreflightSponsorship = {
-  feePayer: TempoAddress.Address
-  feeToken?: TempoAddress.Address | undefined
-  transaction: SponsoredTransaction
-}
-
-/**
- * Runs execution-only sender and final-envelope simulations around sponsorship.
- *
- * First, it simulates the calls with the sender as `from`, omitting fee fields
- * and signatures so the sender's fee balance is irrelevant. Next, `complete`
- * resolves the sponsor and produces the co-signed transaction. Finally, it
- * simulates that transaction with its concrete fee payer and fee token.
- *
- * `complete` runs only after sender-context execution succeeds, so a reverting
- * transaction never reaches a local signer or hosted fee-payer.
- */
-export async function preflightSponsorship<sponsorship extends PreflightSponsorship>(parameters: {
-  complete: () => Promise<sponsorship>
-  simulate: (request: Record<string, unknown>) => Promise<unknown>
-  transaction: SponsoredTransaction
-}): Promise<sponsorship> {
-  const { complete, simulate, transaction } = parameters
-  await simulate(simulationTransaction(transaction, { feePayer: true }))
-  const completed = await complete()
-  await simulate(
-    sponsoredSimulationTransaction(completed.transaction, {
-      feePayer: completed.feePayer,
-      feeToken: completed.feeToken,
-    }),
-  )
-  return completed
-}
-
-/**
- * maxTotalFee must be high enough to cover `transferWithMemo` and
- * swap transactions at peak gas prices. Bumped from 0.01 ETH in #327.
- */
-const defaultPolicy: Policy = {
-  maxGas: 2_000_000n,
-  maxFeePerGas: 100_000_000_000n,
-  maxPriorityFeePerGas: 10_000_000_000n,
-  maxTotalFee: 50_000_000_000_000_000n,
-  maxValidityWindowSeconds: 15 * 60,
-}
-
-const policyByChainId = {
-  [defaults.chainId.mainnet]: defaultPolicy,
-  // Moderato regularly needs a higher priority fee than mainnet.
-  [defaults.chainId.testnet]: {
-    ...defaultPolicy,
-    maxPriorityFeePerGas: 50_000_000_000n,
-  },
-} as const satisfies Record<defaults.ChainId, Policy>
-
-function getPolicy(chainId: number, overrides: Partial<Policy> | undefined): Policy {
-  const base = policyByChainId[chainId as defaults.ChainId] ?? defaultPolicy
-  if (!overrides) return base
-
-  return {
-    maxGas: overrides.maxGas ?? base.maxGas,
-    maxFeePerGas: overrides.maxFeePerGas ?? base.maxFeePerGas,
-    maxPriorityFeePerGas: overrides.maxPriorityFeePerGas ?? base.maxPriorityFeePerGas,
-    maxTotalFee: overrides.maxTotalFee ?? base.maxTotalFee,
-    maxValidityWindowSeconds: overrides.maxValidityWindowSeconds ?? base.maxValidityWindowSeconds,
-  }
-}
-
-function isExpiringNonceKey(nonceKey: SponsoredTransaction['nonceKey']): boolean {
-  return nonceKey === 'expiring' || nonceKey === maxUint256
-}
-
-const sponsoredCallAbi = [...Abis.tip20, ...Abis.stablecoinDex] as const
-const sponsoredCallSelectors = new Set([
-  Selectors.approve,
-  Selectors.transfer,
-  Selectors.transferWithMemo,
-  Selectors.swapExactAmountOut,
-])
-
-function canonicalSponsoredCallData(
-  data: Hex,
-  call: string,
-  fail: (reason: string, extra?: Record<string, string>) => never,
-) {
-  if (!sponsoredCallSelectors.has(data.slice(0, 10) as Hex)) return undefined
-
-  let decoded: ReturnType<typeof decodeFunctionData<typeof sponsoredCallAbi>>
-  try {
-    decoded = decodeFunctionData({ abi: sponsoredCallAbi, data })
-  } catch {
-    fail('fee-sponsored transaction call calldata is invalid', { call })
-  }
-  return encodeFunctionData({
-    abi: sponsoredCallAbi,
-    functionName: decoded.functionName,
-    args: decoded.args,
-  })
-}
-
-/**
- * Rejects sponsored transaction fields that increase intrinsic gas without
- * changing the decoded payment intent.
- */
-function assertCanonicalSponsoredTransaction(
-  transaction: SponsoredTransaction,
-  fail: (reason: string, extra?: Record<string, string>) => never,
-) {
-  if (transaction.accessList !== undefined && transaction.accessList.length > 0)
-    fail('fee-sponsored transaction accessList is not allowed', {
-      accessListEntries: String(transaction.accessList.length),
-    })
-
-  const calls = transaction.calls
-  if (!Array.isArray(calls) || calls.length === 0)
-    fail('fee-sponsored transaction must declare calls')
-
-  for (const [index, call] of calls.entries()) {
-    const callIndex = String(index)
-    const value = call.value
-    if (value !== undefined && value !== 0n)
-      fail('fee-sponsored transaction call value is not allowed', {
-        call: callIndex,
-        value: value.toString(),
-      })
-
-    const data = call.data
-    if (!data)
-      fail('fee-sponsored transaction call is missing calldata', {
-        call: callIndex,
-      })
-
-    const canonical = canonicalSponsoredCallData(data, callIndex, fail)
-    if (canonical && data.toLowerCase() !== canonical.toLowerCase())
-      fail('fee-sponsored transaction call calldata is not canonical', {
-        call: callIndex,
-      })
-  }
-}
-
-/** Validates that a set of transaction calls matches an allowed fee-payer pattern. */
-export function validateCalls(
-  calls: readonly { data?: `0x${string}` | undefined; to?: TempoAddress.Address | undefined }[],
-  details: Record<string, string>,
-  options?: {
-    currency?: TempoAddress.Address | undefined
-    expectedTransfers?: readonly ExpectedTransfer[] | undefined
-  },
-) {
-  if (calls.length === 0)
-    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
-
-  const callSelectors = calls.map((c) => c.data?.slice(0, 10))
-  const hasSwapPrefix = callSelectors[0] === Selectors.approve
-
-  if (hasSwapPrefix) {
-    if (callSelectors[1] !== Selectors.swapExactAmountOut)
-      throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
-  } else if (callSelectors[0] === Selectors.swapExactAmountOut) {
-    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
-  }
-
-  const transferSelectors = callSelectors.slice(hasSwapPrefix ? 2 : 0)
-  if (transferSelectors.length === 0)
-    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
-
-  const expectedTransfers = options?.expectedTransfers
-  const transferLimit = expectedTransfers?.length ?? 11
-  if (
-    transferSelectors.length > transferLimit ||
-    transferSelectors.some(
-      (selector) => selector !== Selectors.transfer && selector !== Selectors.transferWithMemo,
-    ) ||
-    (expectedTransfers && transferSelectors.length !== expectedTransfers.length)
-  )
-    throw new FeePayerValidationError('disallowed call pattern in fee-payer transaction', details)
-
-  // Bind the swap approval to the token the DEX call will actually spend.
-  const buyCall = calls.find((c) => c.data?.slice(0, 10) === Selectors.swapExactAmountOut)
-  const buyArgs = buyCall
-    ? (decodeFunctionData({ abi: Abis.stablecoinDex, data: buyCall.data! }).args as [
-        `0x${string}`,
-        `0x${string}`,
-        bigint,
-        bigint,
-      ])
-    : undefined
-
-  const approveCall = calls.find((c) => c.data?.slice(0, 10) === Selectors.approve)
-  if (approveCall) {
-    const { args } = decodeFunctionData({ abi: Abis.tip20, data: approveCall.data! })
-    const [spender, amount] = args as [`0x${string}`, bigint]
-    if (!approveCall.to || (buyArgs && !TempoAddress_internal.isEqual(approveCall.to, buyArgs[0])))
-      throw new FeePayerValidationError('approve target does not match swap tokenIn', details)
-    if (!TempoAddress_internal.isEqual(spender, Addresses.stablecoinDex))
-      throw new FeePayerValidationError('approve spender is not the DEX', details)
-    if (buyArgs && amount !== buyArgs[3])
-      throw new FeePayerValidationError('approve amount does not match swap max input', details)
-  }
-  if (
-    buyCall &&
-    (!buyCall.to || !TempoAddress_internal.isEqual(buyCall.to, Addresses.stablecoinDex))
-  )
-    throw new FeePayerValidationError('buy target is not the DEX', details)
-
-  if (!expectedTransfers) return
-
-  const currency = options?.currency ?? (details.currency as TempoAddress.Address | undefined)
-  if (!currency) throw new FeePayerValidationError('missing payment currency', details)
-
-  if (buyArgs) {
-    const [, tokenOut, amountOut] = buyArgs
-    const expectedAmountOut = expectedTransfers.reduce(
-      (sum, transfer) => sum + BigInt(transfer.amount),
-      0n,
-    )
-    if (!TempoAddress_internal.isEqual(tokenOut, currency))
-      throw new FeePayerValidationError('swap tokenOut does not match payment currency', details)
-    if (amountOut !== expectedAmountOut)
-      throw new FeePayerValidationError('swap output does not match payment amount', details)
-  }
-
-  const transferCalls = calls.slice(hasSwapPrefix ? 2 : 0)
-  const sorted = [...expectedTransfers].sort((a, b) => {
-    if (a.memo && !b.memo) return -1
-    if (!a.memo && b.memo) return 1
-    return 0
-  })
-
-  const used = new Set<number>()
-  for (const expected of sorted) {
-    const matchIndex = transferCalls.findIndex((call, index) => {
-      if (used.has(index)) return false
-      if (!call.to || !TempoAddress_internal.isEqual(call.to, currency) || !call.data) return false
-
-      try {
-        const selector = call.data.slice(0, 10)
-        const { args } = decodeFunctionData({ abi: Abis.tip20, data: call.data })
-        if (selector === Selectors.transfer) {
-          const [recipient, amount] = args as [`0x${string}`, bigint]
-          if (!TempoAddress_internal.isEqual(recipient, expected.recipient)) return false
-          if (amount.toString() !== expected.amount) return false
-          return expected.memo === undefined
-        }
-
-        if (selector === Selectors.transferWithMemo) {
-          const [recipient, amount, memo] = args as [`0x${string}`, bigint, Hex]
-          if (!TempoAddress_internal.isEqual(recipient, expected.recipient)) return false
-          if (amount.toString() !== expected.amount) return false
-          if (expected.memo) return memo.toLowerCase() === expected.memo.toLowerCase()
-          return expected.allowAnyMemo === true
-        }
-      } catch {
-        return false
-      }
-
-      return false
-    })
-
-    if (matchIndex === -1)
-      throw new FeePayerValidationError('payment transfer does not match challenge', details)
-
-    used.add(matchIndex)
-  }
-}
-
-/** Validates sponsor fee policy limits for a fee-payer transaction. */
-export function assertTransactionPolicy(parameters: {
-  challengeExpires?: string | undefined
-  chainId: number
-  details: Record<string, string>
-  now?: Date | undefined
-  policy?: Partial<Policy> | undefined
-  transaction: SponsoredTransaction
-}) {
-  const {
-    challengeExpires,
-    chainId,
-    details,
-    now = new Date(),
-    policy: policyOverrides,
-    transaction,
-  } = parameters
-  const policy = getPolicy(chainId, policyOverrides)
-  const {
-    chainId: transactionChainId,
-    gas,
-    maxFeePerGas,
-    maxPriorityFeePerGas,
-    nonceKey,
-    validBefore,
-  } = transaction
-
-  const fail = (reason: string, extra: Record<string, string> = {}) => {
-    throw new FeePayerValidationError(reason, { ...details, ...extra })
-  }
-
-  if (transaction.type !== undefined && transaction.type !== 'tempo')
-    fail('fee-sponsored transaction type is invalid', {
-      type: String(transaction.type),
-    })
-
-  if (transactionChainId !== chainId)
-    fail('fee-sponsored transaction chainId does not match challenge', {
-      chainId: String(transactionChainId),
-    })
-
-  assertCanonicalSponsoredTransaction(transaction, fail)
-
-  if (gas === undefined || gas <= 0n) fail('fee-sponsored transaction must declare gas')
-  const gasLimit = gas
-  if (gasLimit > policy.maxGas)
-    fail('fee-sponsored transaction gas exceeds sponsor policy', {
-      gas: gasLimit.toString(),
-    })
-
-  if (maxFeePerGas === undefined || maxFeePerGas <= 0n)
-    fail('fee-sponsored transaction must declare maxFeePerGas')
-  const maxFeePerGasValue = maxFeePerGas
-  if (maxFeePerGasValue > policy.maxFeePerGas)
-    fail('fee-sponsored transaction maxFeePerGas exceeds sponsor policy', {
-      maxFeePerGas: maxFeePerGasValue.toString(),
-    })
-
-  const maxTotalFee = BigInt(gasLimit) * BigInt(maxFeePerGasValue)
-  if (maxTotalFee > policy.maxTotalFee)
-    fail('fee-sponsored transaction total fee budget exceeds sponsor policy', {
-      gas: gasLimit.toString(),
-      maxFeePerGas: maxFeePerGasValue.toString(),
-      totalFee: maxTotalFee.toString(),
-    })
-  if (maxPriorityFeePerGas !== undefined && maxPriorityFeePerGas > maxFeePerGasValue)
-    fail('fee-sponsored transaction maxPriorityFeePerGas exceeds maxFeePerGas', {
-      maxFeePerGas: maxFeePerGasValue.toString(),
-      maxPriorityFeePerGas: maxPriorityFeePerGas.toString(),
-    })
-  if (maxPriorityFeePerGas !== undefined && maxPriorityFeePerGas > policy.maxPriorityFeePerGas)
-    fail('fee-sponsored transaction maxPriorityFeePerGas exceeds sponsor policy', {
-      maxPriorityFeePerGas: maxPriorityFeePerGas.toString(),
-    })
-
-  if (!isExpiringNonceKey(nonceKey)) fail('fee-sponsored transaction must use an expiring nonce')
-  if (validBefore === undefined)
-    fail('fee-sponsored transaction must declare validBefore for the expiring nonce')
-  const validBeforeValue = validBefore
-
-  const nowSeconds = Math.floor(now.getTime() / 1_000)
-  if (validBeforeValue <= nowSeconds)
-    fail('fee-sponsored transaction has already expired', {
-      validBefore: String(validBeforeValue),
-    })
-
-  const challengeExpirySeconds = challengeExpires
-    ? Math.floor(new Date(challengeExpires).getTime() / 1_000)
-    : undefined
-  const maxValidBefore = Math.min(
-    nowSeconds + policy.maxValidityWindowSeconds,
-    challengeExpirySeconds ? challengeExpirySeconds + 60 : Number.MAX_SAFE_INTEGER,
-  )
-  if (validBeforeValue > maxValidBefore)
-    fail('fee-sponsored transaction validity window exceeds sponsor policy', {
-      validBefore: String(validBeforeValue),
-    })
-
-  return {
-    gasLimit,
-    maxFeePerGasValue,
-    totalFee: maxTotalFee,
-    validBeforeValue,
-  }
-}
-
-export function prepareSponsoredTransaction(parameters: {
-  account: Account
-  allowedFeeTokens?: readonly TempoAddress.Address[] | undefined
-  challengeExpires?: string | undefined
-  chainId: number
-  details: Record<string, string>
-  now?: Date | undefined
-  policy?: Partial<Policy> | undefined
-  transaction: SponsoredTransaction
-}) {
-  const {
-    account,
-    allowedFeeTokens,
-    challengeExpires,
-    chainId,
-    details,
-    now = new Date(),
-    policy: policyOverrides,
-    transaction,
-  } = parameters
-  const transactionRecord = transaction as Record<string, unknown>
-
-  const {
-    accessList,
-    calls,
-    chainId: transactionChainId,
-    feeToken,
-    from,
-    keyAuthorization,
-    maxPriorityFeePerGas,
-    nonce,
-    nonceKey,
-    signature,
-    validAfter,
-  } = transaction
-
-  const fail = (reason: string, extra: Record<string, string> = {}) => {
-    throw new FeePayerValidationError(reason, { ...details, ...extra })
-  }
-
-  const unsupportedKeys = Object.entries(transaction).flatMap(([key, value]) => {
-    if (value === undefined) return []
-    if (supportedTransactionKeys.has(key)) return []
-    return [key]
-  })
-  if (unsupportedKeys.length > 0)
-    fail('fee-sponsored transaction contains unsupported fields', {
-      unsupportedFields: unsupportedKeys.join(', '),
-    })
-
-  const rejectedKeys = rejectedTransactionKeys.filter((key) => {
-    const value = transactionRecord[key]
-    return value !== undefined && value !== null
-  })
-  if (rejectedKeys.length > 0)
-    fail('fee-sponsored transaction contains rejected fields', {
-      rejectedFields: rejectedKeys.join(', '),
-    })
-
-  const { gasLimit, maxFeePerGasValue, validBeforeValue } = assertTransactionPolicy({
-    challengeExpires,
-    chainId,
-    details,
-    now,
-    policy: policyOverrides,
-    transaction,
-  })
-
-  const normalizedFeeToken = (() => {
-    if (feeToken === undefined) return undefined
-    if (typeof feeToken !== 'string') fail('fee-sponsored transaction feeToken is invalid')
-    return feeToken
-  })()
-
-  if (normalizedFeeToken !== undefined) {
-    if (
-      allowedFeeTokens &&
-      !allowedFeeTokens.some((allowed) =>
-        TempoAddress_internal.isEqual(normalizedFeeToken, allowed),
-      )
-    )
-      fail('fee-sponsored transaction feeToken is not allowed', {
-        feeToken: normalizedFeeToken,
-      })
-  }
-
-  return {
-    accessList,
-    account,
-    calls,
-    chainId: transactionChainId,
-    feePayer: account,
-    ...(normalizedFeeToken ? { feeToken: normalizedFeeToken } : {}),
-    ...(from ? { from } : {}),
-    gas: gasLimit,
-    ...(keyAuthorization !== undefined ? { keyAuthorization } : {}),
-    ...(nonce !== undefined ? { nonce } : {}),
-    maxFeePerGas: maxFeePerGasValue,
-    ...(maxPriorityFeePerGas !== undefined ? { maxPriorityFeePerGas } : {}),
-    nonceKey,
-    ...(signature ? { signature } : {}),
-    type: 'tempo' as const,
-    ...(validAfter !== undefined ? { validAfter } : {}),
-    validBefore: validBeforeValue,
-  } satisfies ReturnType<(typeof Transaction)['deserialize']> & {
-    account: Account
-    feePayer: Account
-  }
-}
-
-export class FeePayerValidationError extends Error {
-  override readonly name = 'FeePayerValidationError'
-
-  constructor(reason: string, details: Record<string, string>) {
-    super(
-      [
-        `Invalid transaction: ${reason}`,
-        ...Object.entries(details).map(([k, v]) => `  - ${k}: ${v}`),
-      ].join('\n'),
-    )
-  }
-}