mppx 0.8.15 → 0.8.17

package/src/mcp/client/McpClient.integration.test.ts

@@ -6,20 +6,22 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-import { sessionLegacy as tempo_session_client, tempo as tempo_client } from 'mppx/client'
+import { session as tempo_session_client, tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { readContract } from 'viem/actions'
 import { Actions, Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import { tempoNetwork } from '~test/config.js'
-import { deployEscrow, signTopUpChannel } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client as testClient, fundAccount } from '~test/tempo/viem.js'
 
 import * as Credential from '../../Credential.js'
 import * as core_Mcp from '../../Mcp.js'
 import * as Store from '../../Store.js'
-import type { SessionReceipt } from '../../tempo/session/precompile/Protocol.js'
+import type {
+  SessionCredentialPayload,
+  SessionReceipt,
+} from '../../tempo/session/precompile/Protocol.js'
 import * as ChannelStore from '../../tempo/session/server/ChannelStore.js'
 import * as McpServer_transport from '../server/Transport.js'
 import * as McpClient from './McpClient.js'
@@ -31,21 +33,11 @@ const doubleSessionAmountRaw = chargeAmountRaw * 2n
 const topUpAmountRaw = chargeAmountRaw * 3n
 const isLocalnet = tempoNetwork === 'localnet'
 
-let escrowContract: Address
-
-// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
 function tokenGetBalanceCall(parameters: { account: Address; token: Address }) {
-  const call = Actions.token.getBalance.call as unknown as {
-    length: number
-    (parameters: { account: Address; token: Address }): unknown
-    (client: unknown, parameters: { account: Address; token: Address }): unknown
-  }
-  if (call.length >= 2) return call(testClient, parameters)
-  return call(parameters)
+  return Actions.token.getBalance.call(testClient, parameters)
 }
 
 beforeAll(async () => {
-  escrowContract = await deployEscrow()
   await fundAccount({ address: accounts[4].address, token: Addresses.pathUsd })
   await fundAccount({ address: accounts[4].address, token: asset })
   await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })
@@ -171,6 +163,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
             action: 'voucher',
             channelId: openReceipt!.channelId,
             cumulativeAmountRaw: replayedCumulativeRaw,
+            descriptor: credentialDescriptor(openCredential),
           },
         })
         const firstVoucher = await callToolWithCredential(
@@ -236,7 +229,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
     {
       name: 'session intent can top up a live MCP channel and continue metering on the same channel',
       sessionFeePayer: true,
-      sessionMaxDeposit: '2',
+      sessionMaxDeposit: '5',
       async run(harness: Harness) {
         const openChallenge = await getPaymentChallenge(harness.sdkClient, 'session_tool')
         const openCredential = await harness.sessionMethod.createCredential({
@@ -269,14 +262,6 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
         expect(meteredReceipt?.channelId).toBe(openReceipt?.channelId)
         expect(meteredReceipt?.acceptedCumulative).toBe((chargeAmountRaw * 2n).toString())
 
-        const { serializedTransaction } = await signTopUpChannel({
-          escrow: escrowContract,
-          feePayer: true,
-          payer: accounts[2],
-          channelId: openReceipt!.channelId,
-          token: asset,
-          amount: topUpAmountRaw,
-        })
         const topUpChallenge = await getPaymentChallenge(harness.sdkClient, 'session_tool')
         const topUpCredential = await harness.sessionMethod.createCredential({
           challenge: topUpChallenge,
@@ -284,7 +269,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
             action: 'topUp',
             additionalDepositRaw: topUpAmountRaw.toString(),
             channelId: openReceipt!.channelId,
-            transaction: serializedTransaction,
+            descriptor: credentialDescriptor(openCredential),
           },
         })
         const toppedUp = await callToolWithCredential(
@@ -317,7 +302,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
         expect(resumedReceipt?.acceptedCumulative).toBe((chargeAmountRaw * 3n).toString())
 
         const channel = await harness.sessionStore.getChannel(openReceipt!.channelId)
-        expect(channel?.deposit).toBe(chargeAmountRaw * 2n + topUpAmountRaw)
+        expect(channel?.deposit).toBe(chargeAmountRaw * 5n + topUpAmountRaw)
         expect(channel?.highestVoucherAmount).toBe(chargeAmountRaw * 3n)
         expect(channel?.spent).toBeGreaterThanOrEqual(BigInt(topUpReceipt!.spent))
         expect(channel?.units).toBeGreaterThanOrEqual(topUpReceipt?.units ?? 0)
@@ -362,6 +347,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
             action: 'close',
             channelId: openReceipt!.channelId,
             cumulativeAmountRaw: (chargeAmountRaw * 2n).toString(),
+            descriptor: credentialDescriptor(openCredential),
           },
         })
         const closed = await callToolWithCredential(
@@ -452,7 +438,6 @@ type Harness = {
 
 async function createHarness(options?: {
   sessionFeePayer?: boolean | undefined
-  sessionDeposit?: string | undefined
   sessionMaxDeposit?: string | undefined
 }): Promise<Harness> {
   const sessionBackingStore = Store.memory()
@@ -463,11 +448,8 @@ async function createHarness(options?: {
   })
   const sessionMethod = tempo_session_client({
     account: accounts[2],
-    escrowContract,
     getClient: () => testClient,
-    ...(options?.sessionMaxDeposit
-      ? { maxDeposit: options.sessionMaxDeposit }
-      : { deposit: options?.sessionDeposit ?? '5' }),
+    ...(options?.sessionMaxDeposit ? { maxDeposit: options.sessionMaxDeposit } : {}),
   })
 
   const payment = Mppx_server.create({
@@ -477,10 +459,9 @@ async function createHarness(options?: {
         currency: asset,
         getClient: () => testClient,
       }),
-      tempo_server.sessionLegacy({
+      tempo_server.session({
         account: accounts[0],
         currency: asset,
-        escrowContract,
         getClient: () => testClient,
         store: sessionBackingStore,
         ...(options?.sessionFeePayer ? { feePayer: accounts[4] } : {}),
@@ -578,6 +559,12 @@ async function createHarness(options?: {
   }
 }
 
+function credentialDescriptor(serializedCredential: string) {
+  const payload = Credential.deserialize<SessionCredentialPayload>(serializedCredential).payload
+  if (!payload.descriptor) throw new Error('Session credential is missing its channel descriptor.')
+  return payload.descriptor
+}
+
 async function getPaymentChallenge(client: Client, toolName: string): Promise<SessionChallenge> {
   try {
     await client.callTool({ name: toolName, arguments: {} })

package/src/middlewares/elysia.test.ts

@@ -2,18 +2,12 @@ import * as http from 'node:http'
 
 import { Elysia } from 'elysia'
 import { Receipt } from 'mppx'
-import {
-  Mppx as Mppx_client,
-  sessionLegacy as sessionIntent,
-  tempo as tempo_client,
-} from 'mppx/client'
+import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/elysia'
 import { tempo as tempo_server } from 'mppx/server'
-import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as TestHttp from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Elysia<any, any, any, any, any, any, any>) {
@@ -201,16 +195,13 @@ describe('charge', () => {
 })
 
 describe('session', () => {
-  let escrowContract: Address
-
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           ...(feePayer ? { feePayer: accounts[1] } : {}),
         } as any),
       ],
@@ -232,7 +223,6 @@ describe('session', () => {
   }
 
   beforeAll(async () => {
-    escrowContract = await deployEscrow()
     await fundAccount({ address: accounts[1].address, token: Addresses.pathUsd })
     await fundAccount({ address: accounts[1].address, token: asset })
     await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })

package/src/middlewares/express.test.ts

@@ -1,17 +1,11 @@
 import express from 'express'
 import { Receipt } from 'mppx'
-import {
-  Mppx as Mppx_client,
-  sessionLegacy as sessionIntent,
-  tempo as tempo_client,
-} from 'mppx/client'
+import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/express'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
-import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: express.Express) {
@@ -195,16 +189,13 @@ describe('payment', () => {
 })
 
 describe('session', () => {
-  let escrowContract: Address
-
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           ...(feePayer ? { feePayer: accounts[1] } : {}),
         } as any),
       ],
@@ -226,7 +217,6 @@ describe('session', () => {
   }
 
   beforeAll(async () => {
-    escrowContract = await deployEscrow()
     await fundAccount({ address: accounts[1].address, token: Addresses.pathUsd })
     await fundAccount({ address: accounts[1].address, token: asset })
     await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })

package/src/middlewares/hono.test.ts

@@ -4,7 +4,7 @@ import { Challenge, Credential, Method, Receipt, z } from 'mppx'
 import {
   evm as evm_client,
   Mppx as Mppx_client,
-  sessionLegacy as sessionIntent,
+  session as sessionIntent,
   tempo as tempo_client,
 } from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/hono'
@@ -15,11 +15,9 @@ import {
   paymentSignatureHeader,
   type PaymentPayload,
 } from 'mppx/x402'
-import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Hono) {
@@ -203,7 +201,9 @@ describe('charge', () => {
     const { mppx } = createChargeHarness(false)
 
     const app = new Hono()
-    app.get('/', mppx.charge({ amount: '1' }), (c) => c.json({ fortune: 'You will be rich' }))
+    app.get('/', mppx.charge({ amount: '1', description: 'Daily fortune' }), (c) =>
+      c.json({ fortune: 'You will be rich' }),
+    )
     discovery(app, mppx, { auto: true, info: { title: 'Auto API', version: '2.0.0' } })
 
     const server = await createServer(app)
@@ -216,6 +216,7 @@ describe('charge', () => {
     expect(body.paths['/'].get['x-payment-info'].offers[0]).toMatchObject({
       amount: '1000000',
       currency: asset,
+      description: 'Daily fortune',
       intent: 'charge',
       method: 'tempo',
     })
@@ -386,16 +387,13 @@ describe('scope binding', () => {
 })
 
 describe('session', () => {
-  let escrowContract: Address
-
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           ...(feePayer ? { feePayer: accounts[1] } : {}),
         } as any),
       ],
@@ -417,7 +415,6 @@ describe('session', () => {
   }
 
   beforeAll(async () => {
-    escrowContract = await deployEscrow()
     await fundAccount({ address: accounts[1].address, token: Addresses.pathUsd })
     await fundAccount({ address: accounts[1].address, token: asset })
     await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })

package/src/middlewares/nextjs.test.ts

@@ -1,18 +1,12 @@
 import * as http from 'node:http'
 
 import { Challenge, Credential, Receipt } from 'mppx'
-import {
-  Mppx as Mppx_client,
-  sessionLegacy as sessionIntent,
-  tempo as tempo_client,
-} from 'mppx/client'
+import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/nextjs'
 import { tempo as tempo_server } from 'mppx/server'
-import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as TestHttp from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(handler: (request: Request) => Promise<Response> | Response) {
@@ -278,16 +272,13 @@ describe('charge', () => {
 })
 
 describe('session', () => {
-  let escrowContract: Address
-
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           ...(feePayer ? { feePayer: accounts[1] } : {}),
         } as any),
       ],
@@ -309,7 +300,6 @@ describe('session', () => {
   }
 
   beforeAll(async () => {
-    escrowContract = await deployEscrow()
     await fundAccount({ address: accounts[1].address, token: Addresses.pathUsd })
     await fundAccount({ address: accounts[1].address, token: asset })
     await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })

package/src/proxy/Proxy.test.ts

@@ -1,14 +1,12 @@
 import { Challenge, Credential, Method, Receipt, z } from 'mppx'
 import { Mppx as Mppx_client, tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
-import type { Address } from 'viem'
-import { afterEach, beforeAll, describe, expect, test } from 'vp/test'
+import { afterEach, describe, expect, test } from 'vp/test'
 import { tempoNetwork } from '~test/config.js'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client } from '~test/tempo/viem.js'
 
-import { sessionManager } from '../tempo/legacy/client/index.js'
+import { sessionManager } from '../tempo/session/client/SessionManager.js'
 import { deserializeSessionReceipt } from '../tempo/session/precompile/Protocol.js'
 import * as ApiProxy from './Proxy.js'
 import * as Service from './Service.js'
@@ -76,13 +74,6 @@ const mppx_client = Mppx_client.create({
 
 let upstream: Awaited<ReturnType<typeof Http.createServer>> | undefined
 let proxyServer: Awaited<ReturnType<typeof Http.createServer>> | undefined
-let sessionEscrow: Address
-
-beforeAll(async () => {
-  if (!isLocalnet) return
-  sessionEscrow = await deployEscrow()
-})
-
 afterEach(() => {
   upstream?.close()
   proxyServer?.close()
@@ -181,6 +172,7 @@ describe('create', () => {
   })
 
   test('behavior: GET /openapi.json returns discovery JSON', async () => {
+    const alternateAsset = '0x20c0000000000000000000000000000000000002'
     const proxy = ApiProxy.create({
       categories: ['gateway'],
       docs: {
@@ -196,6 +188,10 @@ describe('create', () => {
           routes: {
             'GET /v1/models': true,
             'POST /v1/generate': mppx_server.charge({ amount: '1', description: 'Generate text' }),
+            'POST /v1/multi': mppx_server.compose(
+              ['tempo/charge', { amount: '1', currency: asset, decimals: 6 }],
+              ['tempo/charge', { amount: '2', currency: alternateAsset, decimals: 6 }],
+            ),
             'POST /v1/stream': mppx_server.session({
               amount: '1',
               description: 'Stream text',
@@ -231,6 +227,20 @@ describe('create', () => {
       intent: 'charge',
       method: 'tempo',
     })
+    expect(body.paths['/api/v1/multi'].post['x-payment-info'].offers).toEqual([
+      expect.objectContaining({
+        amount: '1000000',
+        currency: asset,
+        intent: 'charge',
+        method: 'tempo',
+      }),
+      expect.objectContaining({
+        amount: '2000000',
+        currency: alternateAsset,
+        intent: 'charge',
+        method: 'tempo',
+      }),
+    ])
     expect(body.paths['/api/v1/stream'].post['x-payment-info'].offers[0]).toMatchObject({
       amount: '1000000',
       currency: asset,
@@ -576,7 +586,7 @@ describe('create', () => {
     expect(res.status).toBe(402)
   })
 
-  test('behavior: management POST uses credential method binding to disambiguate same-path paid routes', async () => {
+  test('behavior: management POST uses composed credential binding to disambiguate same-path paid routes', async () => {
     const alpha = Method.from({
       name: 'alpha',
       intent: 'charge',
@@ -631,7 +641,7 @@ describe('create', () => {
         Service.from('api', {
           baseUrl: 'https://example.com',
           routes: {
-            'GET /v1/stream': handler['alpha/charge']({ amount: '1' }),
+            'GET /v1/stream': handler.compose(['alpha/charge', { amount: '1' }]),
             'PATCH /v1/stream': handler['beta/charge']({ amount: '1' }),
           },
         }),
@@ -907,10 +917,9 @@ describe.runIf(isLocalnet)('plain HTTP session proxy', () => {
 
     const sessionHandler = Mppx_server.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           account: accounts[0],
           currency: asset,
-          escrowContract: sessionEscrow,
           getClient: () => client,
           chainId: client.chain!.id,
         }),
@@ -937,7 +946,6 @@ describe.runIf(isLocalnet)('plain HTTP session proxy', () => {
     const manager = sessionManager({
       account: accounts[1],
       client,
-      escrowContract: sessionEscrow,
       fetch: globalThis.fetch,
       maxDeposit: '3',
     })
@@ -967,10 +975,9 @@ describe.runIf(isLocalnet)('plain HTTP session proxy', () => {
 
     const sessionHandler = Mppx_server.create({
       methods: [
-        tempo_server.sessionLegacy({
+        tempo_server.session({
           account: accounts[0],
           currency: asset,
-          escrowContract: sessionEscrow,
           getClient: () => client,
           chainId: client.chain!.id,
         }),
@@ -997,7 +1004,7 @@ describe.runIf(isLocalnet)('plain HTTP session proxy', () => {
     const sessionClient = Mppx_client.create({
       polyfill: false,
       methods: [
-        tempo_client.sessionLegacy.method({
+        tempo_client.session({
           account: accounts[1],
           getClient: () => client,
           maxDeposit: '2',

package/src/proxy/Proxy.ts

@@ -128,7 +128,14 @@ export function create(config: create.Config): Proxy {
     const endpoint = matched.value as Service.Endpoint
     const ctx: Service.Context = { request, service, upstreamPath }
 
-    if (endpoint === true) return proxyUpstream({ request, service, ctx, proxy })
+    if (endpoint === true)
+      return proxyUpstream({
+        request,
+        service,
+        ctx,
+        proxy,
+        onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+      })
 
     const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay
     const scope =
@@ -161,6 +168,7 @@ export function create(config: create.Config): Proxy {
       service,
       ctx: { ...ctx, ...options },
       proxy,
+      onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
     })
     return result.withReceipt(upstreamRes)
   }
@@ -183,6 +191,8 @@ export declare namespace create {
     docs?: Service.Docs | undefined
     /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
     fetch?: typeof globalThis.fetch | undefined
+    /** Default handler for failed upstream attempts. Services may override it. */
+    onUpstreamError?: Service.UpstreamErrorHandler | undefined
     /** Services to proxy. Each service is mounted at `/{serviceId}/`. */
     services: Service.Service[]
     /** Human-readable title for the proxy shown in `llms.txt`. */
@@ -195,6 +205,7 @@ export declare namespace create {
 declare namespace proxyUpstream {
   type Options = {
     ctx: Service.Context
+    onUpstreamError?: Service.UpstreamErrorHandler | undefined
     proxy: (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>
     request: globalThis.Request
     service: Service.Service
@@ -203,7 +214,7 @@ declare namespace proxyUpstream {
 
 /** @internal */
 async function proxyUpstream(options: proxyUpstream.Options): Promise<Response> {
-  const { request, service, ctx, proxy } = options
+  const { request, service, ctx, proxy, onUpstreamError } = options
   const url = ctx.upstreamPath + new URL(request.url).search
   const headers = Headers.scrub(request.headers)
 
@@ -221,17 +232,137 @@ async function proxyUpstream(options: proxyUpstream.Options): Promise<Response>
     init.duplex = 'half'
   }
 
-  let upstreamReq = new globalThis.Request(new URL(url, new URL(service.baseUrl).origin), init)
+  const upstreamRequest = new globalThis.Request(
+    new URL(url, new URL(service.baseUrl).origin),
+    init,
+  )
+
+  if (!onUpstreamError)
+    return proxyUpstreamOnce({
+      ctx,
+      proxy,
+      service,
+      upstreamRequest,
+    })
+
+  for (let attempt = 1; ; attempt++) {
+    const outcome = await proxyUpstreamAttempt({
+      ctx,
+      proxy,
+      service,
+      upstreamRequest,
+    })
+
+    let response = outcome.response
+    if (response && service.rewriteResponse) response = await service.rewriteResponse(response, ctx)
+    if (response?.ok) return response
+
+    const handlerResponse = response?.clone()
 
-  if (service.rewriteRequest) upstreamReq = await service.rewriteRequest(upstreamReq, ctx)
+    const action = await onUpstreamError({
+      ...ctx,
+      attempt,
+      error: outcome.error,
+      response: handlerResponse,
+      upstreamRequest: outcome.upstreamRequest,
+    })
+
+    if (!action.retry) {
+      if (action.response) {
+        if (response) void cancelResponseBody(response)
+        return action.response
+      }
+      if (response) {
+        if (handlerResponse) void cancelResponseBody(handlerResponse)
+        return response
+      }
+      throw outcome.error
+    }
+
+    for (const failedResponse of [response, handlerResponse])
+      if (failedResponse) void cancelResponseBody(failedResponse)
+    await waitForRetry(action.delay, request.signal)
+  }
+}
+
+/** Proxies one request without retaining a replay copy of its body. */
+async function proxyUpstreamOnce(options: proxyUpstreamAttempt.Options): Promise<Response> {
+  const { ctx, proxy, service } = options
+  let upstreamRequest = options.upstreamRequest
 
-  let upstreamRes = await proxy(upstreamReq)
+  if (service.rewriteRequest) upstreamRequest = await service.rewriteRequest(upstreamRequest, ctx)
 
-  upstreamRes = Headers.scrubResponse(upstreamRes)
+  let response = await proxy(upstreamRequest)
+  response = Headers.scrubResponse(response)
 
-  if (service.rewriteResponse) upstreamRes = await service.rewriteResponse(upstreamRes, ctx)
+  if (service.rewriteResponse) response = await service.rewriteResponse(response, ctx)
 
-  return upstreamRes
+  return response
+}
+
+declare namespace proxyUpstreamAttempt {
+  type Options = {
+    ctx: Service.Context
+    proxy: (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>
+    service: Service.Service
+    upstreamRequest: Request
+  }
+
+  type Result = {
+    error: unknown | undefined
+    response: Response | undefined
+    upstreamRequest: Request
+  }
+}
+
+/** Performs one independently replayable upstream request attempt. */
+async function proxyUpstreamAttempt(
+  options: proxyUpstreamAttempt.Options,
+): Promise<proxyUpstreamAttempt.Result> {
+  const { ctx, proxy, service } = options
+  let upstreamRequest = options.upstreamRequest.clone()
+
+  try {
+    if (service.rewriteRequest) upstreamRequest = await service.rewriteRequest(upstreamRequest, ctx)
+
+    let response = await proxy(upstreamRequest)
+    response = Headers.scrubResponse(response)
+
+    return { error: undefined, response, upstreamRequest }
+  } catch (error) {
+    return { error, response: undefined, upstreamRequest }
+  }
+}
+
+/** Cancels an unused failed response body before a retry. */
+async function cancelResponseBody(response: Response): Promise<void> {
+  if (!response.body || response.bodyUsed) return
+  try {
+    await response.body.cancel()
+  } catch {
+    return
+  }
+}
+
+/** Waits for a retry delay while respecting request cancellation. */
+async function waitForRetry(delay = 0, signal: AbortSignal): Promise<void> {
+  if (signal.aborted)
+    throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
+  if (!Number.isFinite(delay) || delay <= 0) return
+
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timeout)
+      signal.removeEventListener('abort', onAbort)
+      reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'))
+    }
+    const timeout = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, delay)
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) onAbort()
+  })
 }
 
 function buildDiscoveryRoutes(services: Service.Service[]) {
@@ -310,7 +441,14 @@ function matchesPaymentBinding(endpoint: unknown, binding: PaymentBinding | null
   if (!binding) return true
   const payment = Service.paymentOf(endpoint as Exclude<Service.Endpoint, true>)
   if (!payment) return true
-  return payment.method === binding.method && payment.intent === binding.intent
+  const offers = Array.isArray(payment.offers) ? payment.offers : [payment]
+  return offers.some(
+    (offer) =>
+      typeof offer === 'object' &&
+      offer !== null &&
+      offer.method === binding.method &&
+      offer.intent === binding.intent,
+  )
 }
 
 function createFetchProxy(