mppx 0.8.4 → 0.8.6

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

@@ -51,6 +51,7 @@ function createMockClient(
     channel?: { descriptor: Channel.ChannelDescriptor; state: Chain.ChannelState } | undefined
     receipt?: Record<string, unknown> | null | undefined
     rpcMethods?: string[] | undefined
+    onRequest?: ((method: string, params: unknown) => void) | undefined
   } = {},
 ) {
   return createClient({
@@ -59,6 +60,7 @@ function createMockClient(
     transport: custom({
       async request(args) {
         parameters.rpcMethods?.push(args.method)
+        parameters.onRequest?.(args.method, args.params)
         if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
         if (args.method === 'eth_sendRawTransaction') return txHash
         if (args.method === 'eth_sendRawTransactionSync') return parameters.receipt ?? receipt([])
@@ -91,7 +93,7 @@ function createMockClient(
   })
 }
 
-function receipt(logs: readonly Record<string, unknown>[]) {
+function receipt(logs: readonly Record<string, unknown>[], transactionHash: Hex = txHash) {
   return {
     blockHash: `0x${'01'.repeat(32)}`,
     blockNumber: '0x1',
@@ -104,7 +106,7 @@ function receipt(logs: readonly Record<string, unknown>[]) {
     logsBloom: `0x${'00'.repeat(256)}`,
     status: '0x1',
     to: tip20ChannelEscrow,
-    transactionHash: txHash,
+    transactionHash,
     transactionIndex: '0x0',
     type: '0x76',
   }
@@ -253,6 +255,41 @@ function expectedExpiringNonceHash(serializedTransaction: `0x${string}`) {
   )
 }
 
+describe('precompile receipt wait', () => {
+  test('does not run replacement detection while waiting for Tempo receipts', async () => {
+    const requestedHash = `0x${'12'.repeat(32)}` as Hex
+    const rpcMethods: string[] = []
+    let receiptReads = 0
+    let blockNumber = 0n
+    const client = createClient({
+      chain: { id: chainId } as never,
+      pollingInterval: 1,
+      transport: custom({
+        async request(args) {
+          rpcMethods.push(args.method)
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_blockNumber') {
+            blockNumber += 1n
+            return `0x${blockNumber.toString(16)}`
+          }
+          if (args.method === 'eth_getTransactionReceipt') {
+            receiptReads += 1
+            if (receiptReads === 1) return null
+            return receipt([], requestedHash)
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+
+    const result = await Chain.waitForSuccessfulReceipt(client, requestedHash)
+
+    expect(result.transactionHash).toBe(requestedHash)
+    expect(rpcMethods).not.toContain('eth_getTransactionByHash')
+    expect(rpcMethods).not.toContain('eth_getBlockByNumber')
+  })
+})
+
 describe('precompile open calldata parsing', () => {
   test('parseOpenCall accepts TIP-1034 open calldata', () => {
     const data = encodeFunctionData({
@@ -641,6 +678,44 @@ describe('precompile broadcastOpenTransaction', () => {
     })
   })
 
+  test('pins the read-back to the block that included the open transaction', async () => {
+    const serializedTransaction = await createOpenTransaction()
+    const expiringNonceHash = expectedExpiringNonceHash(serializedTransaction)
+    const expectedDescriptor = { ...descriptor, expiringNonceHash }
+    const channelId = Channel.computeId({
+      ...expectedDescriptor,
+      chainId,
+      escrow: tip20ChannelEscrow,
+    })
+    const state = { settled: 0n, deposit, closeRequestedAt: 0 }
+    // The open tx is mined in block 0x1 (see `receipt`). The read-back must be
+    // pinned to that block, not `latest`, so a lagging RPC replica cannot
+    // answer with stale/empty state.
+    const ethCallBlockTags: unknown[] = []
+
+    await Chain.broadcastOpenTransaction({
+      chainId,
+      client: createMockClient({
+        channel: { descriptor: expectedDescriptor, state },
+        receipt: receipt([openedLog({ channelId, expiringNonceHash })]),
+        onRequest: (method, params) => {
+          if (method === 'eth_call') ethCallBlockTags.push((params as unknown[])[1])
+        },
+      }),
+      escrowContract: tip20ChannelEscrow,
+      expectedAuthorizedSigner: descriptor.authorizedSigner,
+      expectedChannelId: channelId,
+      expectedCurrency: descriptor.token,
+      expectedExpiringNonceHash: expiringNonceHash,
+      expectedOperator: descriptor.operator,
+      expectedPayee: descriptor.payee,
+      expectedPayer: descriptor.payer,
+      serializedTransaction,
+    })
+
+    expect(ethCallBlockTags).toEqual(['0x1'])
+  })
+
   test('rejects ChannelOpened receipt deposit mismatches', async () => {
     const serializedTransaction = await createOpenTransaction()
     const expiringNonceHash = expectedExpiringNonceHash(serializedTransaction)
@@ -1256,3 +1331,47 @@ describe('Chain.assertPrecompileFeePayerPolicy', () => {
     }
   })
 })
+
+describe('Chain.readbackWithRetry', () => {
+  test('returns immediately when the read succeeds on the first attempt', async () => {
+    let calls = 0
+    const result = await Chain.readbackWithRetry(
+      async () => {
+        calls++
+        return 'ok'
+      },
+      { delayMs: 0 },
+    )
+    expect(result).toBe('ok')
+    expect(calls).toBe(1)
+  })
+
+  test('retries a lagging read until it resolves', async () => {
+    let calls = 0
+    const result = await Chain.readbackWithRetry(
+      async () => {
+        calls++
+        if (calls < 3) throw new Error('header not found')
+        return 'ok'
+      },
+      { retries: 5, delayMs: 0 },
+    )
+    expect(result).toBe('ok')
+    expect(calls).toBe(3)
+  })
+
+  test('rethrows the last error after exhausting retries', async () => {
+    let calls = 0
+    await expect(
+      Chain.readbackWithRetry(
+        async () => {
+          calls++
+          throw new Error(`attempt ${calls}`)
+        },
+        { retries: 2, delayMs: 0 },
+      ),
+    ).rejects.toThrow('attempt 3')
+    // 1 initial attempt + 2 retries.
+    expect(calls).toBe(3)
+  })
+})

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

@@ -293,12 +293,14 @@ 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,
@@ -313,12 +315,14 @@ 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)
 }
@@ -340,6 +344,47 @@ export async function getChannelStatesBatch(
   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. */
@@ -586,7 +631,7 @@ export async function sendTransaction(client: TransactionClient, transaction: He
 
 /** Wait for a receipt and reject reverted precompile transactions. */
 export async function waitForSuccessfulReceipt(client: TransactionClient, hash: Hex) {
-  const receipt = await waitForTransactionReceipt(client, { hash })
+  const receipt = await waitForTransactionReceipt(client, { hash, checkReplacement: false })
   if (receipt.status !== 'success')
     throw new VerificationFailedError({ reason: 'precompile transaction reverted' })
   return receipt
@@ -808,7 +853,9 @@ export async function broadcastOpenTransaction(
     expectedChannelId: parameters.expectedChannelId,
     openDeposit: open.deposit,
   })
-  const chainChannel = await getChannel(parameters.client, descriptor, parameters.escrowContract)
+  const chainChannel = await readbackWithRetry(() =>
+    getChannel(parameters.client, descriptor, parameters.escrowContract, receipt.blockNumber),
+  )
   const state = chainChannel.state
   validateOpenReadbackState({ emittedDeposit: opened.deposit, state })
   return {
@@ -896,10 +943,13 @@ export async function broadcastTopUpTransaction(
     emittedChannelId: toppedUp.channelId,
     expectedChannelId: parameters.expectedChannelId,
   })
-  const state = await getChannelState(
-    parameters.client,
-    toppedUp.channelId,
-    parameters.escrowContract,
+  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 }

package/src/x402/Assets.test.ts

@@ -0,0 +1,211 @@
+import { usdc } from 'viem/tokens'
+import { describe, expect, test } from 'vp/test'
+
+import * as Assets from './Assets.js'
+
+describe('x402 assets', () => {
+  test('defines branded asset metadata', () => {
+    const asset = Assets.define({
+      address: '0x1111111111111111111111111111111111111111',
+      decimals: 18,
+      network: 'eip155:1',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+
+    expect(Assets.isAsset(asset)).toBe(true)
+    expect(asset).toMatchObject({
+      address: '0x1111111111111111111111111111111111111111',
+      decimals: 18,
+      network: 'eip155:1',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('rejects unbranded values', () => {
+    expect(Assets.isAsset(null)).toBe(false)
+    expect(Assets.isAsset('0x1111111111111111111111111111111111111111')).toBe(false)
+    expect(
+      Assets.isAsset({
+        address: '0x1111111111111111111111111111111111111111',
+        decimals: 18,
+        network: 'eip155:1',
+        transfer: {
+          name: 'USD Coin',
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toBe(false)
+  })
+
+  test('defines asset metadata from viem tokens', () => {
+    const asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+
+    expect(Assets.isAsset(asset)).toBe(true)
+    expect(asset).toMatchObject({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      network: 'eip155:84532',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('allows viem token transfer metadata overrides', () => {
+    const eip3009Asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+    const permit2Asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        type: 'permit2',
+      },
+    })
+
+    expect(eip3009Asset.transfer).toEqual({
+      name: 'USDC',
+      type: 'eip3009',
+      version: '2',
+    })
+    expect(permit2Asset.transfer).toEqual({
+      type: 'permit2',
+    })
+  })
+
+  test('requires token names for EIP-3009 viem token assets', () => {
+    const tokenWithoutName = Object.assign(
+      () => ({
+        address: '0x1111111111111111111111111111111111111111',
+        decimals: 6,
+        symbol: 'TEST',
+      }),
+      {
+        addresses: { 1: '0x1111111111111111111111111111111111111111' },
+        decimals: 6,
+      },
+    ) as unknown as Assets.ViemToken
+
+    expect(() =>
+      Assets.fromToken(tokenWithoutName, {
+        chainId: 1,
+        transfer: {
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toThrow('EIP-3009 token assets require a token name.')
+  })
+
+  test('identifies currency kinds and converts networks', () => {
+    expect(Assets.isToken(usdc)).toBe(true)
+    expect(Assets.isToken(Assets.baseSepolia.USDC)).toBe(false)
+    expect(Assets.isRawAddress('0x1111111111111111111111111111111111111111')).toBe(true)
+    expect(Assets.isRawAddress(Assets.baseSepolia.USDC)).toBe(false)
+    expect(Assets.toNetwork(84532)).toBe('eip155:84532')
+    expect(Assets.toChainId('eip155:84532')).toBe(84532)
+  })
+
+  test('resolves and matches raw addresses, known assets, and viem tokens', () => {
+    expect(Assets.resolve('0x1111111111111111111111111111111111111111', 'eip155:84532')).toEqual({
+      address: '0x1111111111111111111111111111111111111111',
+    })
+    expect(Assets.resolve(Assets.baseSepolia.USDC, 'eip155:84532')).toEqual({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+    expect(Assets.resolve(Assets.baseSepolia.USDC, 'eip155:8453')).toBeUndefined()
+    expect(Assets.resolve(usdc, 'eip155:84532')).toEqual({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      name: 'USD Coin',
+    })
+    expect(Assets.resolve(usdc, 'eip155:999999')).toBeUndefined()
+    expect(Assets.matches(usdc, '0x036CbD53842c5426634e7929541eC2318f3dCF7e', 'eip155:84532')).toBe(
+      true,
+    )
+    expect(Assets.matches(usdc, '0x036cbd53842c5426634e7929541ec2318f3dcf7e', 'eip155:84532')).toBe(
+      true,
+    )
+    expect(
+      Assets.matches(
+        '0x1111111111111111111111111111111111111111',
+        '0x1111111111111111111111111111111111111111',
+        'eip155:84532',
+      ),
+    ).toBe(true)
+    expect(
+      Assets.matches(
+        Assets.baseSepolia.USDC,
+        '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        'eip155:84532',
+      ),
+    ).toBe(false)
+  })
+
+  test('throws when creating assets from tokens unavailable on a chain', () => {
+    expect(() =>
+      Assets.fromToken(usdc, {
+        chainId: 999_999,
+        transfer: {
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toThrow('Token has no address for chain id "999999".')
+  })
+
+  test('exports Base USDC metadata', () => {
+    expect(Assets.isAsset(Assets.base.USDC)).toBe(true)
+    expect(Assets.base.USDC).toMatchObject({
+      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+      decimals: 6,
+      network: 'eip155:8453',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('exports Base Sepolia USDC metadata', () => {
+    expect(Assets.isAsset(Assets.baseSepolia.USDC)).toBe(true)
+    expect(Assets.baseSepolia.USDC).toMatchObject({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      network: 'eip155:84532',
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+})

package/src/x402/Assets.ts

@@ -1,3 +1,6 @@
+import { getAddress } from 'viem'
+import type { Token } from 'viem/tokens'
+
 import type { Asset, EvmNetwork, ExactTransfer } from './Types.js'
 
 const knownAsset = Symbol('mppx.x402.asset')
@@ -8,6 +11,12 @@ export type KnownAsset = Asset & {
   network: EvmNetwork
 }
 
+/** Viem token metadata from `viem/tokens`. */
+export type ViemToken = Token
+
+/** Currency metadata accepted by EVM and x402 payment config. */
+export type Currency = `0x${string}` | KnownAsset | ViemToken
+
 /** Creates typed x402 asset metadata for custom tokens. */
 export function define(parameters: define.Parameters): KnownAsset {
   return {
@@ -28,6 +37,30 @@ export declare namespace define {
   }
 }
 
+/** Creates x402 asset metadata from a `viem/tokens` token definition. */
+export function fromToken(token: ViemToken, parameters: fromToken.Parameters): KnownAsset {
+  const resolved = token(parameters.chainId)
+  return define({
+    address: resolved.address,
+    decimals: resolved.decimals,
+    network: toNetwork(parameters.chainId),
+    transfer: withTokenDefaults(parameters.transfer, resolved),
+  })
+}
+
+export declare namespace fromToken {
+  type Parameters = {
+    chainId: number
+    transfer: Transfer
+  }
+
+  type Transfer =
+    | (Omit<Extract<ExactTransfer, { type: 'eip3009' }>, 'name'> & {
+        name?: string | undefined
+      })
+    | Extract<ExactTransfer, { type: 'permit2' }>
+}
+
 /** Base network known assets. */
 export const base = {
   USDC: define({
@@ -63,3 +96,86 @@ export function isAsset(value: unknown): value is KnownAsset {
   if (typeof value !== 'object' || value === null) return false
   return (value as Partial<KnownAsset>)[knownAsset] === true
 }
+
+/** Returns true when a value is a `viem/tokens` token definition. */
+export function isToken(value: unknown): value is ViemToken {
+  return (
+    typeof value === 'function' &&
+    typeof (value as Partial<ViemToken>).addresses === 'object' &&
+    typeof (value as Partial<ViemToken>).decimals === 'number'
+  )
+}
+
+/** Returns true when a currency is a raw address without chain metadata. */
+export function isRawAddress(currency: Currency): currency is `0x${string}` {
+  return typeof currency === 'string'
+}
+
+/** Resolves currency metadata for an EVM network. */
+export function resolve(currency: Currency, network: EvmNetwork): resolve.Result | undefined {
+  if (isAsset(currency)) {
+    if (currency.network !== network) return undefined
+    return {
+      address: currency.address,
+      decimals: currency.decimals,
+      transfer: currency.transfer,
+    }
+  }
+
+  if (isToken(currency)) {
+    const address = currency.addresses[toChainId(network)]
+    if (!address) return undefined
+    return {
+      address,
+      decimals: currency.decimals,
+      name: currency.name,
+    }
+  }
+
+  return {
+    address: currency,
+  }
+}
+
+export declare namespace resolve {
+  type Result = {
+    address: `0x${string}`
+    decimals?: number | undefined
+    name?: string | undefined
+    transfer?: ExactTransfer | undefined
+  }
+}
+
+/** Returns true when a currency resolves to the accepted address on the network. */
+export function matches(
+  currency: Currency,
+  acceptedCurrency: `0x${string}`,
+  network: EvmNetwork,
+): boolean {
+  const resolved = resolve(currency, network)
+  if (!resolved) return false
+  return getAddress(resolved.address) === getAddress(acceptedCurrency)
+}
+
+/** Converts an EVM chain ID to a CAIP-2 network identifier. */
+export function toNetwork(chainId: number): EvmNetwork {
+  return `eip155:${chainId}`
+}
+
+/** Converts a CAIP-2 EVM network identifier to a chain ID. */
+export function toChainId(network: EvmNetwork): number {
+  return Number(network.slice('eip155:'.length))
+}
+
+function withTokenDefaults(
+  transfer: fromToken.Transfer,
+  token: ReturnType<ViemToken>,
+): ExactTransfer {
+  if (transfer.type !== 'eip3009') return transfer
+  if (transfer.name) return { ...transfer, name: transfer.name }
+  if (!token.name) throw new Error('EIP-3009 token assets require a token name.')
+  return {
+    ...transfer,
+    name: token.name,
+  }
+}