mppx 0.8.15 → 0.8.18

package/src/tempo/session/precompile/Chain.ts

@@ -1,1149 +0,0 @@
-import type { Account, Address, Client, Hex } from 'viem'
-import { decodeFunctionData, encodeFunctionData, isAddressEqual, parseEventLogs } from 'viem'
-import {
-  call,
-  prepareTransactionRequest,
-  readContract,
-  sendRawTransaction,
-  sendRawTransactionSync,
-  sendTransaction as sendViemTransaction,
-  signTransaction,
-  waitForTransactionReceipt,
-} from 'viem/actions'
-import { Abis, Addresses, Transaction } from 'viem/tempo'
-
-import { BadRequestError, VerificationFailedError } from '../../../Errors.js'
-import * as FeePayer from '../../internal/fee-payer.js'
-import { resolveFeeToken } from '../../internal/fee-token.js'
-import * as ChannelOps from '../server/ChannelOps.js'
-import * as ChannelUtils from './Channel.js'
-import type { ChannelDescriptor } from './Channel.js'
-import { escrowAbi } from './escrow.abi.js'
-import { tip20ChannelEscrow } from './Protocol.js'
-
-/** Minimal on-chain state read back after precompile transaction receipts. */
-export type ReceiptValidationChannelState = {
-  /** Cumulative amount settled on-chain. */
-  settled: bigint
-  /** Current on-chain channel deposit. */
-  deposit: bigint
-  /** Close-request timestamp, or zero when open. */
-  closeRequestedAt: number
-}
-
-/** Inputs used to validate a ChannelOpened event against the verified open calldata. */
-export type ValidateChannelOpenedReceiptParameters = {
-  /** Chain ID used in descriptor-derived channel ID. */
-  chainId: number
-  /** Descriptor reconstructed from the open calldata. */
-  descriptor: ChannelDescriptor
-  /** Channel ID emitted by the ChannelOpened event. */
-  emittedChannelId: Hex
-  /** Deposit emitted by the ChannelOpened event. */
-  emittedDeposit: bigint
-  /** Expiring nonce hash emitted by the ChannelOpened event. */
-  emittedExpiringNonceHash: Hex
-  /** Escrow precompile address used in descriptor-derived channel ID. */
-  escrow: Address
-  /** Channel ID expected from the credential. */
-  expectedChannelId: Hex
-  /** Deposit parsed from open calldata. */
-  openDeposit: bigint
-}
-
-/** Inputs used to validate open read-back state after ChannelOpened. */
-export type ValidateOpenReadbackStateParameters = {
-  /** Deposit emitted by the ChannelOpened event. */
-  emittedDeposit: bigint
-  /** State read back from the precompile. */
-  state: ReceiptValidationChannelState
-}
-
-/** Inputs used to validate a TopUp event against the credential channel ID. */
-export type ValidateTopUpReceiptParameters = {
-  /** Channel ID emitted by the TopUp event. */
-  emittedChannelId: Hex
-  /** Channel ID expected from the credential. */
-  expectedChannelId: Hex
-}
-
-/** Inputs used to validate top-up read-back state after TopUp. */
-export type ValidateTopUpReadbackStateParameters = {
-  /** New deposit emitted by the TopUp event. */
-  newDeposit: bigint
-  /** State read back from the precompile. */
-  state: ReceiptValidationChannelState
-}
-
-/** Typed fields decoded from a ChannelOpened receipt event. */
-export type ChannelOpenedReceiptFields = {
-  /** Channel ID emitted by the precompile. */
-  channelId: Hex
-  /** Deposit emitted by the precompile. */
-  deposit: bigint
-  /** Expiring nonce hash emitted by the precompile. */
-  expiringNonceHash: Hex
-}
-
-/** Typed fields decoded from a TopUp receipt event. */
-export type TopUpReceiptFields = {
-  /** Channel ID emitted by the precompile. */
-  channelId: Hex
-  /** New total deposit emitted by the precompile. */
-  newDeposit: bigint
-}
-
-/** Typed fields decoded from a Settled receipt event. */
-export type SettledReceiptFields = {
-  /** New cumulative amount settled on-chain. */
-  newSettled: bigint
-}
-
-/** Typed fields decoded from a ChannelClosed receipt event. */
-export type ChannelClosedReceiptFields = {
-  /** Amount captured by the payee. */
-  settledToPayee: bigint
-  /** Amount refunded to the payer. */
-  refundedToPayer: bigint
-}
-
-type ReceiptEventWithArgs = {
-  args: Record<string, unknown>
-}
-
-const uint96Max = 2n ** 96n - 1n
-
-function readBytes32(value: unknown, label: string): Hex {
-  if (typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value)) return value as Hex
-  throw new VerificationFailedError({ reason: `${label} missing from receipt event` })
-}
-
-function readUint96(value: unknown, label: string): bigint {
-  if (typeof value !== 'bigint')
-    throw new VerificationFailedError({ reason: `${label} missing from receipt event` })
-  if (value < 0n || value > uint96Max)
-    throw new VerificationFailedError({ reason: `${label} exceeds uint96 range` })
-  return value
-}
-
-/** Reads and validates typed fields from a ChannelOpened receipt event. */
-export function readChannelOpenedReceiptFields(
-  event: ReceiptEventWithArgs,
-): ChannelOpenedReceiptFields {
-  return {
-    channelId: readBytes32(event.args.channelId, 'ChannelOpened channelId'),
-    deposit: readUint96(event.args.deposit, 'ChannelOpened deposit'),
-    expiringNonceHash: readBytes32(event.args.expiringNonceHash, 'ChannelOpened expiringNonceHash'),
-  }
-}
-
-/** Reads and validates typed fields from a TopUp receipt event. */
-export function readTopUpReceiptFields(event: ReceiptEventWithArgs): TopUpReceiptFields {
-  return {
-    channelId: readBytes32(event.args.channelId, 'TopUp channelId'),
-    newDeposit: readUint96(event.args.newDeposit, 'TopUp newDeposit'),
-  }
-}
-
-/** Reads and validates typed fields from a Settled receipt event. */
-export function readSettledReceiptFields(event: ReceiptEventWithArgs): SettledReceiptFields {
-  return {
-    newSettled: readUint96(event.args.newSettled, 'Settled newSettled'),
-  }
-}
-
-/** Reads and validates typed fields from a ChannelClosed receipt event. */
-export function readChannelClosedReceiptFields(
-  event: ReceiptEventWithArgs,
-): ChannelClosedReceiptFields {
-  return {
-    settledToPayee: readUint96(event.args.settledToPayee, 'ChannelClosed settledToPayee'),
-    refundedToPayer: readUint96(event.args.refundedToPayer, 'ChannelClosed refundedToPayer'),
-  }
-}
-
-/** Validates that ChannelOpened receipt fields match calldata, descriptor, and credential. */
-export function validateChannelOpenedReceipt(
-  parameters: ValidateChannelOpenedReceiptParameters,
-): void {
-  const {
-    chainId,
-    descriptor,
-    emittedChannelId,
-    emittedDeposit,
-    emittedExpiringNonceHash,
-    escrow,
-    expectedChannelId,
-    openDeposit,
-  } = parameters
-
-  if (emittedChannelId.toLowerCase() !== expectedChannelId.toLowerCase())
-    throw new VerificationFailedError({
-      reason: 'ChannelOpened channelId does not match credential',
-    })
-  if (emittedExpiringNonceHash.toLowerCase() !== descriptor.expiringNonceHash.toLowerCase())
-    throw new VerificationFailedError({
-      reason: 'ChannelOpened expiringNonceHash does not match descriptor',
-    })
-  if (emittedDeposit !== openDeposit)
-    throw new VerificationFailedError({ reason: 'ChannelOpened deposit does not match calldata' })
-
-  const confirmedChannelId = ChannelUtils.computeId({ ...descriptor, chainId, escrow })
-  if (confirmedChannelId.toLowerCase() !== emittedChannelId.toLowerCase())
-    throw new VerificationFailedError({
-      reason: 'descriptor does not match ChannelOpened channelId',
-    })
-}
-
-/** Validates the state read back after a successful open transaction. */
-export function validateOpenReadbackState(parameters: ValidateOpenReadbackStateParameters): void {
-  const { emittedDeposit, state } = parameters
-  if (state.deposit !== emittedDeposit || state.settled !== 0n || state.closeRequestedAt !== 0)
-    throw new VerificationFailedError({
-      reason: 'on-chain channel state does not match open receipt',
-    })
-}
-
-/** Validates that a TopUp receipt belongs to the credential channel. */
-export function validateTopUpReceipt(parameters: ValidateTopUpReceiptParameters): void {
-  if (parameters.emittedChannelId.toLowerCase() !== parameters.expectedChannelId.toLowerCase())
-    throw new VerificationFailedError({ reason: 'TopUp channelId does not match credential' })
-}
-
-/** Validates the state read back after a successful top-up transaction. */
-export function validateTopUpReadbackState(parameters: ValidateTopUpReadbackStateParameters): void {
-  if (parameters.state.deposit !== parameters.newDeposit)
-    throw new VerificationFailedError({
-      reason: 'on-chain channel state does not match topUp receipt',
-    })
-}
-
-/** Fee fields produced by viem transaction preparation for direct precompile calls. */
-export type PreparedPrecompileFeePayerTransaction = {
-  /** Estimated gas units for the transaction. */
-  gas?: bigint | undefined
-  /** Maximum fee per gas unit. */
-  maxFeePerGas?: bigint | undefined
-  /** Maximum priority fee per gas unit. */
-  maxPriorityFeePerGas?: bigint | undefined
-}
-
-/** Parameters for checking a direct precompile transaction against sponsor limits. */
-export type AssertPrecompileFeePayerPolicyParameters = {
-  /** Prepared transaction fee fields to validate. */
-  prepared: PreparedPrecompileFeePayerTransaction
-  /** Optional sponsor policy overrides. Missing fields are not enforced here. */
-  policy?: Partial<FeePayer.Policy> | undefined
-}
-
-/** Enforces sponsor gas and fee limits before co-signing a direct precompile call. */
-export function assertPrecompileFeePayerPolicy(
-  parameters: AssertPrecompileFeePayerPolicyParameters,
-) {
-  const { policy, prepared } = parameters
-  if (!policy) return
-  if (policy.maxGas !== undefined && (prepared.gas ?? 0n) > policy.maxGas)
-    throw new BadRequestError({ reason: 'fee-payer policy maxGas exceeded' })
-  if (policy.maxFeePerGas !== undefined && (prepared.maxFeePerGas ?? 0n) > policy.maxFeePerGas)
-    throw new BadRequestError({ reason: 'fee-payer policy maxFeePerGas exceeded' })
-  if (
-    policy.maxPriorityFeePerGas !== undefined &&
-    (prepared.maxPriorityFeePerGas ?? 0n) > policy.maxPriorityFeePerGas
-  )
-    throw new BadRequestError({ reason: 'fee-payer policy maxPriorityFeePerGas exceeded' })
-  if (
-    policy.maxTotalFee !== undefined &&
-    (prepared.gas ?? 0n) * (prepared.maxFeePerGas ?? 0n) > policy.maxTotalFee
-  )
-    throw new BadRequestError({ reason: 'fee-payer policy maxTotalFee exceeded' })
-}
-
-const UINT96_MAX = 2n ** 96n - 1n
-
-/** viem client shape accepted by raw Tempo transaction actions. */
-export type TransactionClient = Parameters<typeof sendRawTransaction>[0]
-
-function assertUint96(amount: bigint): void {
-  if (amount < 0n || amount > UINT96_MAX) {
-    throw new VerificationFailedError({ reason: 'amount exceeds uint96 range' })
-  }
-}
-
-/**
- * On-chain channel state from the TIP20EscrowChannel precompile.
- */
-export type ChannelState = {
-  settled: bigint
-  deposit: bigint
-  closeRequestedAt: number
-}
-
-/**
- * On-chain channel descriptor and state from the TIP20EscrowChannel precompile.
- */
-export type Channel = {
-  descriptor: ChannelDescriptor
-  state: ChannelState
-}
-
-/**
- * Read channel descriptor and state from the TIP20EscrowChannel precompile.
- */
-export async function getChannel(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  escrow: Address = tip20ChannelEscrow,
-  blockNumber?: bigint,
-): Promise<Channel> {
-  const channel = await readContract(client, {
-    address: escrow,
-    abi: escrowAbi,
-    functionName: 'getChannel',
-    args: [descriptorTuple(descriptor)],
-    ...(blockNumber !== undefined ? { blockNumber } : {}),
-  })
-  return {
-    descriptor: channel.descriptor,
-    state: stateFromTuple(channel.state),
-  }
-}
-
-/**
- * Read channel state from the TIP20EscrowChannel precompile.
- */
-export async function getChannelState(
-  client: Client,
-  channelId: Hex,
-  escrow: Address = tip20ChannelEscrow,
-  blockNumber?: bigint,
-): Promise<ChannelState> {
-  const state = await readContract(client, {
-    address: escrow,
-    abi: escrowAbi,
-    functionName: 'getChannelState',
-    args: [channelId],
-    ...(blockNumber !== undefined ? { blockNumber } : {}),
-  })
-  return stateFromTuple(state)
-}
-
-/**
- * Read channel states from the TIP20EscrowChannel precompile.
- */
-export async function getChannelStatesBatch(
-  client: Client,
-  channelIds: readonly Hex[],
-  escrow: Address = tip20ChannelEscrow,
-): Promise<ChannelState[]> {
-  const states = await readContract(client, {
-    address: escrow,
-    abi: escrowAbi,
-    functionName: 'getChannelStatesBatch',
-    args: [channelIds],
-  })
-  return states.map(stateFromTuple)
-}
-
-/** Tuning for {@link readbackWithRetry}. */
-export type ReadbackRetryOptions = {
-  /** Additional attempts after the first, before giving up. @default 5 */
-  retries?: number | undefined
-  /** Delay between attempts, in milliseconds. @default 250 */
-  delayMs?: number | undefined
-}
-
-/**
- * Retry an on-chain readback that is pinned to the block containing a just-sent
- * transaction.
- *
- * The escrow state read is served by a load-balanced RPC whose replicas can lag
- * behind the block that produced the transaction receipt. Callers pin the read
- * to that block number (via the `blockNumber` arg on {@link getChannel} /
- * {@link getChannelState}) so a node that has imported the block returns
- * authoritative state; replicas that have not yet imported it throw (e.g.
- * "header not found"), so we retry with a short backoff until one catches up.
- *
- * This closes the read-after-write race behind
- * `on-chain channel state does not match open receipt` — without it, a stale
- * `latest` read on a lagging replica returns an empty channel and fails
- * verification even though the open transaction succeeded.
- */
-export async function readbackWithRetry<T>(
-  read: () => Promise<T>,
-  options: ReadbackRetryOptions = {},
-): Promise<T> {
-  const { retries = 5, delayMs = 250 } = options
-  let lastError: unknown
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      return await read()
-    } catch (error) {
-      lastError = error
-      if (attempt < retries) await new Promise((resolve) => setTimeout(resolve, delayMs))
-    }
-  }
-  throw lastError
-}
-
-/** Options accepted by low-level TIP-1034 on-chain management helpers. */
-export type ChannelTransactionOptions = {
-  /** Account used to send the transaction when the viem client has no default account. */
-  account?: Account | undefined
-  /** Candidate fee tokens used when resolving a fee token for fee-sponsored transactions. */
-  candidateFeeTokens?: readonly Address[] | undefined
-  /** Fee-payer account used to co-sign Tempo fee-sponsored transactions. */
-  feePayer?: Account | undefined
-  /** Optional fee-payer gas and total-fee limits enforced before co-signing. */
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  /** Explicit fee token for the transaction. */
-  feeToken?: Address | undefined
-}
-
-type ParsedPrecompileCredentialTransaction = {
-  call: Transaction.TransactionTempo['calls'][number] & { data: Hex; to: Address }
-  prefixCalls: readonly Transaction.TransactionTempo['calls'][number][]
-  transaction: ReturnType<(typeof Transaction)['deserialize']>
-}
-
-function parsePrecompileCredentialTransaction(parameters: {
-  escrowContract: Address
-  feePayer?: Account | true | undefined
-  label: 'open' | 'topUp'
-  serializedTransaction: Hex
-}): ParsedPrecompileCredentialTransaction {
-  const { escrowContract, feePayer, label, serializedTransaction } = parameters
-  if (feePayer && !FeePayer.isTempoTransaction(serializedTransaction))
-    throw new BadRequestError({ reason: 'Only Tempo (0x76/0x78) transactions are supported' })
-
-  const transaction = Transaction.deserialize(
-    serializedTransaction as Transaction.TransactionSerializedTempo,
-  )
-  const calls = transaction.calls
-  if (calls.length !== 1 && calls.length !== 3)
-    throw new VerificationFailedError({
-      reason: `TIP-1034 ${label} transaction must contain one management call, optionally preceded by an auto-swap`,
-    })
-  const call = calls[calls.length - 1]!
-  if (!call.to || !isAddressEqual(call.to, escrowContract))
-    throw new VerificationFailedError({
-      reason: `TIP-1034 ${label} transaction targets the wrong address`,
-    })
-  if (!call.data)
-    throw new VerificationFailedError({
-      reason: `TIP-1034 ${label} transaction is missing calldata`,
-    })
-  return {
-    transaction,
-    call: { ...call, data: call.data, to: call.to },
-    prefixCalls: calls.slice(0, -1),
-  }
-}
-
-function validateAutoSwapPrefix(parameters: {
-  amountOut: bigint
-  currency: Address
-  label: 'open' | 'topUp'
-  prefixCalls: readonly Transaction.TransactionTempo['calls'][number][]
-}) {
-  const { amountOut, currency, label, prefixCalls } = parameters
-  if (prefixCalls.length === 0) return
-
-  const fail = (reason: string): never => {
-    throw new VerificationFailedError({ reason: `TIP-1034 ${label} auto-swap ${reason}` })
-  }
-  if (prefixCalls.length !== 2) fail('must contain exactly approve and swap calls')
-
-  const approveCall = prefixCalls[0]!
-  const swapCall = prefixCalls[1]!
-  const approveTo = approveCall.to
-  const approveData = approveCall.data
-  const swapTo = swapCall.to
-  const swapData = swapCall.data
-  if (!approveTo || !approveData || !swapTo || !swapData)
-    fail('call is missing a target or calldata')
-  const checkedApproveTo = approveTo as Address
-  const checkedApproveData = approveData as Hex
-  const checkedSwapTo = swapTo as Address
-  const checkedSwapData = swapData as Hex
-  if ((approveCall.value ?? 0n) !== 0n || (swapCall.value ?? 0n) !== 0n)
-    fail('calls must not transfer native value')
-  if (!isAddressEqual(checkedSwapTo, Addresses.stablecoinDex)) fail('targets the wrong DEX')
-
-  const approve = (() => {
-    try {
-      return decodeFunctionData({ abi: Abis.tip20, data: checkedApproveData })
-    } catch {
-      return fail('approval calldata is invalid')
-    }
-  })()
-  const swap = (() => {
-    try {
-      return decodeFunctionData({ abi: Abis.stablecoinDex, data: checkedSwapData })
-    } catch {
-      return fail('swap calldata is invalid')
-    }
-  })()
-  if (approve.functionName !== 'approve' || swap.functionName !== 'swapExactAmountOut')
-    fail('must contain approve followed by swapExactAmountOut')
-
-  const [spender, approvedAmount] = approve.args as readonly [Address, bigint]
-  const [tokenIn, tokenOut, swapAmountOut, maxAmountIn] = swap.args as readonly [
-    Address,
-    Address,
-    bigint,
-    bigint,
-  ]
-  if (!isAddressEqual(checkedApproveTo, tokenIn)) fail('approval token does not match swap input')
-  if (!isAddressEqual(spender, Addresses.stablecoinDex)) fail('approval spender is not the DEX')
-  if (approvedAmount !== maxAmountIn) fail('approval amount does not match swap maximum input')
-  if (!isAddressEqual(tokenOut, currency)) fail('output token does not match channel currency')
-  if (swapAmountOut !== amountOut) fail('output amount does not match channel deposit')
-  if (isAddressEqual(tokenIn, tokenOut)) fail('input and output tokens must differ')
-
-  const canonicalApprove = encodeFunctionData({
-    abi: Abis.tip20,
-    functionName: 'approve',
-    args: [spender, approvedAmount],
-  })
-  const canonicalSwap = encodeFunctionData({
-    abi: Abis.stablecoinDex,
-    functionName: 'swapExactAmountOut',
-    args: [tokenIn, tokenOut, swapAmountOut, maxAmountIn],
-  })
-  if (checkedApproveData.toLowerCase() !== canonicalApprove.toLowerCase())
-    fail('approval calldata is not canonical')
-  if (checkedSwapData.toLowerCase() !== canonicalSwap.toLowerCase())
-    fail('swap calldata is not canonical')
-}
-
-async function simulateTempoTransaction(client: Client, request: unknown) {
-  // viem's public `call` type does not yet model Tempo's multi-call and
-  // fee-payer fields together. Keep that compatibility cast in one place.
-  await call(client, request as never)
-}
-
-async function signTempoTransaction(client: Client, transaction: unknown): Promise<Hex> {
-  return (await signTransaction(client, transaction as never)) as Hex
-}
-
-async function prepareFeePayerCallTransaction(
-  client: Client,
-  parameters: {
-    account: Account
-    data: Hex
-    feeToken?: Address | undefined
-    to: Address
-  },
-) {
-  const { account, data, feeToken, to } = parameters
-  // viem's stable request type does not expose Tempo fee-payer transaction
-  // fields for this call shape. Keep the cast at the boundary.
-  return prepareTransactionRequest(client, {
-    account,
-    calls: [{ to, data }],
-    feePayer: true,
-    ...(feeToken ? { feeToken } : {}),
-  } as never)
-}
-
-function sendPrecompileContractCall(
-  client: Client,
-  parameters: {
-    account?: Account | undefined
-    data: Hex
-    feeToken?: Address | undefined
-    to: Address
-  },
-): Promise<Hex> {
-  const { account, data, feeToken, to } = parameters
-  // `feeToken` is Tempo-specific and not represented on viem's base
-  // transaction request type.
-  return sendViemTransaction(client, {
-    ...(account ? { account } : {}),
-    to,
-    data,
-    ...(feeToken ? { feeToken } : {}),
-  } as never)
-}
-
-/**
- * Submit a settle transaction on-chain.
- */
-export async function settleOnChain(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  cumulativeAmount: bigint,
-  signature: Hex,
-  escrow: Address = tip20ChannelEscrow,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  assertUint96(cumulativeAmount)
-  const args = [descriptorTuple(descriptor), cumulativeAmount, signature] as const
-  return sendPrecompileTransaction(
-    client,
-    escrow,
-    encodeFunctionData({ abi: escrowAbi, functionName: 'settle', args }),
-    'settle',
-    options,
-  )
-}
-
-/**
- * Submit a top-up transaction on-chain.
- */
-export async function topUpOnChain(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  additionalDeposit: bigint,
-  escrow: Address = tip20ChannelEscrow,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  assertUint96(additionalDeposit)
-  const args = [descriptorTuple(descriptor), additionalDeposit] as const
-  return sendPrecompileTransaction(
-    client,
-    escrow,
-    encodeFunctionData({ abi: escrowAbi, functionName: 'topUp', args }),
-    'topUp',
-    options,
-  )
-}
-
-/**
- * Submit a request-close transaction on-chain.
- */
-export async function requestCloseOnChain(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  escrow: Address = tip20ChannelEscrow,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  const args = [descriptorTuple(descriptor)] as const
-  return sendPrecompileTransaction(
-    client,
-    escrow,
-    encodeFunctionData({ abi: escrowAbi, functionName: 'requestClose', args }),
-    'requestClose',
-    options,
-  )
-}
-
-/**
- * Submit a withdraw transaction on-chain.
- */
-export async function withdrawOnChain(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  escrow: Address = tip20ChannelEscrow,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  const args = [descriptorTuple(descriptor)] as const
-  return sendPrecompileTransaction(
-    client,
-    escrow,
-    encodeFunctionData({ abi: escrowAbi, functionName: 'withdraw', args }),
-    'withdraw',
-    options,
-  )
-}
-
-/**
- * Submit a close transaction on-chain.
- */
-export async function closeOnChain(
-  client: Client,
-  descriptor: ChannelDescriptor,
-  cumulativeAmount: bigint,
-  captureAmount: bigint,
-  signature: Hex,
-  escrow: Address = tip20ChannelEscrow,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  assertUint96(cumulativeAmount)
-  assertUint96(captureAmount)
-  const args = [descriptorTuple(descriptor), cumulativeAmount, captureAmount, signature] as const
-  return sendPrecompileTransaction(
-    client,
-    escrow,
-    encodeFunctionData({ abi: escrowAbi, functionName: 'close', args }),
-    'close',
-    options,
-  )
-}
-
-/** Receipt event shape emitted by TIP20EscrowChannel precompile management calls. */
-export type ChannelReceiptEvent = {
-  args: {
-    channelId: Hex
-    expiringNonceHash?: Hex | undefined
-    deposit?: bigint | undefined
-    newDeposit?: bigint | undefined
-    newSettled?: bigint | undefined
-    settledToPayee?: bigint | undefined
-    refundedToPayer?: bigint | undefined
-  }
-}
-
-/** Receipt-like input used when extracting channel events from transaction logs. */
-export type ChannelEventReceipt = {
-  logs: Parameters<typeof parseEventLogs>[0]['logs']
-}
-
-/**
- * Asserts that a deserialized transaction has an existing sender signature.
- */
-export function assertSenderSigned(
-  transaction: ReturnType<(typeof Transaction)['deserialize']>,
-): void {
-  if (!transaction.signature || !transaction.from)
-    throw new BadRequestError({
-      reason: 'Transaction must be signed by the sender before fee payer co-signing',
-    })
-}
-
-/** Broadcast a raw serialized transaction. */
-export async function sendTransaction(client: TransactionClient, transaction: Hex) {
-  return sendRawTransaction(client, { serializedTransaction: transaction })
-}
-
-/** Wait for a receipt and reject reverted precompile transactions. */
-export async function waitForSuccessfulReceipt(client: TransactionClient, hash: Hex) {
-  const receipt = await waitForTransactionReceipt(client, { hash, checkReplacement: false })
-  if (receipt.status !== 'success')
-    throw new VerificationFailedError({ reason: 'precompile transaction reverted' })
-  return receipt
-}
-
-/** Extract exactly one channel event for a channel ID from a receipt. */
-export function getChannelEvent(
-  receipt: ChannelEventReceipt,
-  name: 'ChannelOpened' | 'TopUp' | 'Settled' | 'ChannelClosed',
-  channelId: Hex,
-): ChannelReceiptEvent {
-  const logs = parseEventLogs({
-    abi: escrowAbi,
-    eventName: name,
-    logs: receipt.logs,
-  }) as ChannelReceiptEvent[]
-  const matches = logs.filter((log) => log.args.channelId.toLowerCase() === channelId.toLowerCase())
-  if (matches.length !== 1)
-    throw new VerificationFailedError({
-      reason: `expected one ${name} event for credential channelId in receipt`,
-    })
-  return matches[0]!
-}
-
-/** Inputs for broadcasting a client-signed precompile management transaction. */
-export type SendCredentialTransactionParameters = {
-  /** Challenge expiration propagated into fee-payer policy checks. */
-  challengeExpires?: string | undefined
-  /** Chain ID used for fee-payer transaction signing. */
-  chainId: number
-  /** viem client used to submit the transaction. */
-  client: TransactionClient
-  /** Fee tokens allowed by the server for sponsored transactions. */
-  allowedFeeTokens?: readonly Address[] | undefined
-  /** Human-readable transaction details used by fee-payer policy hooks. */
-  details: Record<string, string>
-  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
-  feePayer?: Account | true | undefined
-  /** Optional fee-payer policy enforced before co-signing. */
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  /** Management transaction kind, used for validation errors. */
-  label: 'open' | 'topUp'
-  /** Client-signed serialized transaction. */
-  serializedTransaction: Hex
-  /** Deserialized transaction corresponding to `serializedTransaction`. */
-  transaction: ReturnType<(typeof Transaction)['deserialize']>
-}
-
-/** Broadcasts a client-signed management transaction, adding a fee-payer co-signature when requested. */
-export async function sendCredentialTransaction(parameters: SendCredentialTransactionParameters) {
-  const {
-    challengeExpires,
-    chainId,
-    client,
-    allowedFeeTokens,
-    details,
-    feePayer,
-    feePayerPolicy,
-    label,
-    serializedTransaction,
-    transaction,
-  } = parameters
-
-  if (!feePayer) {
-    const txHash = await sendTransaction(client, serializedTransaction)
-    return waitForSuccessfulReceipt(client, txHash)
-  }
-
-  if (!FeePayer.isTempoTransaction(serializedTransaction))
-    throw new BadRequestError({ reason: 'Only Tempo (0x76/0x78) transactions are supported' })
-  assertSenderSigned(transaction)
-
-  if (feePayer === true) {
-    // The transport owns hosted completion, so mppx can only preflight call
-    // execution as the sender. It intentionally omits fee fields here; the
-    // transport is responsible for validating its final sponsored envelope.
-    await simulateTempoTransaction(
-      client,
-      FeePayer.simulationTransaction(transaction, { feePayer: true }),
-    )
-    const txHash = await sendTransaction(client, serializedTransaction)
-    return waitForSuccessfulReceipt(client, txHash)
-  }
-
-  const sponsorshipTransaction = {
-    ...transaction,
-    ...(allowedFeeTokens?.[0] ? { feeToken: transaction.feeToken ?? allowedFeeTokens[0] } : {}),
-  }
-  const completed = await FeePayer.preflightSponsorship({
-    transaction: sponsorshipTransaction,
-    simulate: (request) => simulateTempoTransaction(client, request),
-    async complete() {
-      const sponsored = FeePayer.prepareSponsoredTransaction({
-        account: feePayer,
-        allowedFeeTokens,
-        challengeExpires,
-        chainId,
-        details,
-        policy: feePayerPolicy,
-        transaction: sponsorshipTransaction,
-      })
-      return { feePayer: feePayer.address, transaction: sponsored }
-    },
-  })
-  const serialized = await signTempoTransaction(client, completed.transaction)
-  const receipt = await sendRawTransactionSync(client, {
-    serializedTransaction: serialized as Transaction.TransactionSerializedTempo,
-  })
-  if (receipt.status !== 'success')
-    throw new VerificationFailedError({
-      reason: `${label} precompile transaction reverted: ${receipt.transactionHash}`,
-    })
-  return receipt
-}
-
-/** Result returned after a TIP-1034 open transaction is broadcast and verified. */
-export type BroadcastOpenTransactionResult = {
-  /** Broadcast transaction hash. */
-  txHash: Hex
-  /** Descriptor recovered from the verified open transaction. */
-  descriptor: ChannelDescriptor
-  /** Latest on-chain channel state after open. */
-  state: ChannelState
-  /** Expiring nonce hash emitted by the open receipt. */
-  expiringNonceHash: Hex
-  /** Deposit amount encoded in the open calldata. */
-  openDeposit: bigint
-}
-
-/** Inputs for broadcasting and verifying a client-signed TIP-1034 open transaction. */
-export type BroadcastOpenTransactionParameters = {
-  /** Hook invoked after calldata validation but before broadcasting. */
-  beforeBroadcast?:
-    | ((result: Omit<BroadcastOpenTransactionResult, 'txHash' | 'state'>) => Promise<void> | void)
-    | undefined
-  /** Challenge expiration propagated into fee-payer policy checks. */
-  challengeExpires?: string | undefined
-  /** Chain ID used for channel ID and voucher domain separation. */
-  chainId: number
-  /** viem client used for transaction submission and readback. */
-  client: TransactionClient
-  /** TIP20EscrowChannel precompile address. */
-  escrowContract: Address
-  /** Authorized voucher signer expected in the open calldata. */
-  expectedAuthorizedSigner: Address
-  /** Channel ID expected from descriptor, escrow, and chain ID. */
-  expectedChannelId: Hex
-  /** Payment token expected in the open calldata. */
-  expectedCurrency: Address
-  /** Transaction-bound nonce hash expected in the descriptor. */
-  expectedExpiringNonceHash: Hex
-  /** Payee-side operator expected in the open calldata. */
-  expectedOperator: Address
-  /** Payment recipient expected in the open calldata. */
-  expectedPayee: Address
-  /** Payer expected to have signed the open transaction. */
-  expectedPayer: Address
-  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
-  feePayer?: Account | true | undefined
-  /** Optional fee-payer policy enforced before co-signing. */
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  /** Client-signed serialized open transaction. */
-  serializedTransaction: Hex
-}
-
-/** Broadcast and validate a client-signed TIP-1034 open transaction. */
-export async function broadcastOpenTransaction(
-  parameters: BroadcastOpenTransactionParameters,
-): Promise<BroadcastOpenTransactionResult> {
-  const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
-    escrowContract: parameters.escrowContract,
-    feePayer: parameters.feePayer,
-    label: 'open',
-    serializedTransaction: parameters.serializedTransaction,
-  })
-  const payer = transaction.from ?? parameters.expectedPayer
-  const open = ChannelOps.parseOpenCall({
-    data: call.data,
-    expected: {
-      payee: parameters.expectedPayee,
-      token: parameters.expectedCurrency,
-      operator: parameters.expectedOperator,
-      authorizedSigner: parameters.expectedAuthorizedSigner,
-    },
-  })
-  validateAutoSwapPrefix({
-    amountOut: open.deposit,
-    currency: parameters.expectedCurrency,
-    label: 'open',
-    prefixCalls,
-  })
-  const descriptor = ChannelOps.descriptorFromOpen({
-    chainId: parameters.chainId,
-    escrow: parameters.escrowContract,
-    payer,
-    open,
-    expiringNonceHash: parameters.expectedExpiringNonceHash,
-    channelId: parameters.expectedChannelId,
-  })
-  if (parameters.feePayer) assertSenderSigned(transaction)
-  const expiringNonceHash = ChannelUtils.computeExpiringNonceHash(
-    ChannelUtils.transactionForExpiringNonceHash({
-      feePayer: parameters.feePayer,
-      transaction,
-    }),
-    { sender: payer },
-  )
-  if (expiringNonceHash.toLowerCase() !== descriptor.expiringNonceHash.toLowerCase())
-    throw new VerificationFailedError({
-      reason: 'credential expiringNonceHash does not match transaction',
-    })
-  await parameters.beforeBroadcast?.({
-    descriptor,
-    expiringNonceHash,
-    openDeposit: open.deposit,
-  })
-  const receipt = await sendCredentialTransaction({
-    challengeExpires: parameters.challengeExpires,
-    chainId: parameters.chainId,
-    client: parameters.client,
-    allowedFeeTokens: [parameters.expectedCurrency],
-    details: {
-      channelId: parameters.expectedChannelId,
-      currency: parameters.expectedCurrency,
-      recipient: parameters.expectedPayee,
-    },
-    feePayer: parameters.feePayer,
-    feePayerPolicy: parameters.feePayerPolicy,
-    label: 'open',
-    serializedTransaction: parameters.serializedTransaction,
-    transaction,
-  })
-  const opened = readChannelOpenedReceiptFields(
-    getChannelEvent(receipt, 'ChannelOpened', parameters.expectedChannelId),
-  )
-  validateChannelOpenedReceipt({
-    chainId: parameters.chainId,
-    descriptor,
-    emittedChannelId: opened.channelId,
-    emittedDeposit: opened.deposit,
-    emittedExpiringNonceHash: opened.expiringNonceHash,
-    escrow: parameters.escrowContract,
-    expectedChannelId: parameters.expectedChannelId,
-    openDeposit: open.deposit,
-  })
-  const chainChannel = await readbackWithRetry(() =>
-    getChannel(parameters.client, descriptor, parameters.escrowContract, receipt.blockNumber),
-  )
-  const state = chainChannel.state
-  validateOpenReadbackState({ emittedDeposit: opened.deposit, state })
-  return {
-    txHash: receipt.transactionHash,
-    descriptor,
-    state,
-    expiringNonceHash: opened.expiringNonceHash,
-    openDeposit: open.deposit,
-  }
-}
-
-/** Result returned after a TIP-1034 top-up transaction is broadcast and verified. */
-export type BroadcastTopUpTransactionResult = {
-  /** Broadcast transaction hash. */
-  txHash: Hex
-  /** New on-chain deposit emitted by the top-up receipt. */
-  newDeposit: bigint
-  /** Latest on-chain channel state after top-up. */
-  state: ChannelState
-}
-
-/** Inputs for broadcasting and verifying a client-signed TIP-1034 top-up transaction. */
-export type BroadcastTopUpTransactionParameters = {
-  /** Additional deposit amount expected in the top-up calldata. */
-  additionalDeposit: bigint
-  /** Challenge expiration propagated into fee-payer policy checks. */
-  challengeExpires?: string | undefined
-  /** Chain ID used for fee-payer transaction signing. */
-  chainId: number
-  /** viem client used for transaction submission and readback. */
-  client: TransactionClient
-  /** Descriptor expected in the top-up calldata. */
-  descriptor: ChannelDescriptor
-  /** TIP20EscrowChannel precompile address. */
-  escrowContract: Address
-  /** Channel ID expected in the top-up receipt. */
-  expectedChannelId: Hex
-  /** Payment token expected for sponsored transaction fee token checks. */
-  expectedCurrency: Address
-  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
-  feePayer?: Account | true | undefined
-  /** Optional fee-payer policy enforced before co-signing. */
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  /** Client-signed serialized top-up transaction. */
-  serializedTransaction: Hex
-}
-
-/** Broadcast and validate a client-signed TIP-1034 top-up transaction. */
-export async function broadcastTopUpTransaction(
-  parameters: BroadcastTopUpTransactionParameters,
-): Promise<BroadcastTopUpTransactionResult> {
-  const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
-    escrowContract: parameters.escrowContract,
-    feePayer: parameters.feePayer,
-    label: 'topUp',
-    serializedTransaction: parameters.serializedTransaction,
-  })
-  ChannelOps.parseTopUpCall({
-    data: call.data,
-    expected: {
-      descriptor: parameters.descriptor,
-      additionalDeposit: parameters.additionalDeposit,
-    },
-  })
-  validateAutoSwapPrefix({
-    amountOut: parameters.additionalDeposit,
-    currency: parameters.expectedCurrency,
-    label: 'topUp',
-    prefixCalls,
-  })
-  const receipt = await sendCredentialTransaction({
-    challengeExpires: parameters.challengeExpires,
-    chainId: parameters.chainId,
-    client: parameters.client,
-    allowedFeeTokens: [parameters.expectedCurrency],
-    details: {
-      additionalDeposit: parameters.additionalDeposit.toString(),
-      channelId: parameters.expectedChannelId,
-      currency: parameters.expectedCurrency,
-    },
-    feePayer: parameters.feePayer,
-    feePayerPolicy: parameters.feePayerPolicy,
-    label: 'topUp',
-    serializedTransaction: parameters.serializedTransaction,
-    transaction,
-  })
-  const toppedUp = readTopUpReceiptFields(
-    getChannelEvent(receipt, 'TopUp', parameters.expectedChannelId),
-  )
-  validateTopUpReceipt({
-    emittedChannelId: toppedUp.channelId,
-    expectedChannelId: parameters.expectedChannelId,
-  })
-  const state = await readbackWithRetry(() =>
-    getChannelState(
-      parameters.client,
-      toppedUp.channelId,
-      parameters.escrowContract,
-      receipt.blockNumber,
-    ),
-  )
-  validateTopUpReadbackState({ newDeposit: toppedUp.newDeposit, state })
-  return { txHash: receipt.transactionHash, newDeposit: toppedUp.newDeposit, state }
-}
-
-function stateFromTuple(state: {
-  settled: bigint
-  deposit: bigint
-  closeRequestedAt: number
-}): ChannelState {
-  assertUint96(state.settled)
-  assertUint96(state.deposit)
-  return {
-    settled: state.settled,
-    deposit: state.deposit,
-    closeRequestedAt: state.closeRequestedAt,
-  }
-}
-
-function descriptorTuple(descriptor: ChannelDescriptor) {
-  return {
-    payer: descriptor.payer,
-    payee: descriptor.payee,
-    operator: descriptor.operator,
-    token: descriptor.token,
-    salt: descriptor.salt,
-    authorizedSigner: descriptor.authorizedSigner,
-    expiringNonceHash: descriptor.expiringNonceHash,
-  } as const
-}
-
-async function sendPrecompileTransaction(
-  client: Client,
-  to: Address,
-  data: Hex,
-  label: string,
-  options?: ChannelTransactionOptions,
-): Promise<Hex> {
-  const account = options?.account ?? client.account
-  const selfSponsored =
-    account && options?.feePayer && isAddressEqual(account.address, options.feePayer.address)
-
-  if (options?.feePayer && !selfSponsored) {
-    if (!account) throw new Error(`Cannot ${label} precompile channel: no account available.`)
-    const feeToken =
-      options.feeToken ??
-      (await resolveFeeToken({
-        account: options.feePayer.address,
-        candidateTokens: options.candidateFeeTokens,
-        client,
-      }))
-    const prepared = await prepareFeePayerCallTransaction(client, {
-      account,
-      data,
-      feeToken,
-      to,
-    })
-    assertPrecompileFeePayerPolicy({ prepared, policy: options.feePayerPolicy })
-    const serialized = await signTempoTransaction(client, {
-      ...prepared,
-      account,
-      feePayer: options.feePayer,
-    })
-    const receipt = await sendRawTransactionSync(client, {
-      serializedTransaction: serialized as Transaction.TransactionSerializedTempo,
-    })
-    if (receipt.status !== 'success')
-      throw new VerificationFailedError({
-        reason: `${label} precompile transaction reverted: ${receipt.transactionHash}`,
-      })
-    return receipt.transactionHash
-  }
-
-  const feeToken =
-    options?.feeToken ??
-    (selfSponsored
-      ? await resolveFeeToken({
-          account: account.address,
-          candidateTokens: options?.candidateFeeTokens,
-          client,
-        })
-      : undefined)
-
-  return sendPrecompileContractCall(client, {
-    account,
-    to,
-    data,
-    feeToken,
-  })
-}