mppx 0.3.8 → 0.3.11

package/src/tempo/server/Charge.test.ts

@@ -524,6 +524,68 @@ describe('tempo', () => {
     })
   })
 
+  describe('intent: charge; type: transaction; waitForConfirmation: false', () => {
+    test('returns receipt without waiting for confirmation', async () => {
+      const serverNoWait = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient() {
+              return client
+            },
+            currency: asset,
+            account: accounts[0],
+            waitForConfirmation: false,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [
+          tempo_client({
+            account: accounts[1],
+            getClient() {
+              return client
+            },
+          }),
+        ],
+      })
+
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          serverNoWait.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const credential = await mppx.createCredential(response)
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: credential },
+        })
+        expect(response.status).toBe(200)
+
+        const receipt = Receipt.fromResponse(response)
+        expect(receipt.status).toBe('success')
+        expect(receipt.method).toBe('tempo')
+        expect(receipt.reference).toBeDefined()
+      }
+
+      httpServer.close()
+    })
+  })
+
   describe('intent: unknown', () => {
     test('behavior: returns 402 for invalid payload schema', async () => {
       const httpServer = await Http.createServer(async (req, res) => {

package/src/tempo/server/Charge.ts

@@ -5,7 +5,12 @@ import {
   type TransactionReceipt,
   toFunctionSelector,
 } from 'viem'
-import { getTransactionReceipt, sendRawTransactionSync, signTransaction } from 'viem/actions'
+import {
+  getTransactionReceipt,
+  sendRawTransaction,
+  sendRawTransactionSync,
+  signTransaction,
+} from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Abis, Transaction } from 'viem/tempo'
 import { PaymentExpiredError } from '../../Errors.js'
@@ -14,6 +19,7 @@ import * as Method from '../../Method.js'
 import * as Client from '../../viem/Client.js'
 import * as Account from '../internal/account.js'
 import * as defaults from '../internal/defaults.js'
+import { simulateTransaction } from '../internal/simulate.js'
 import type * as types from '../internal/types.js'
 import * as Methods from '../Methods.js'
 
@@ -45,6 +51,7 @@ export function charge<const parameters extends charge.Parameters>(
     description,
     externalId,
     memo,
+    waitForConfirmation = true,
   } = parameters
 
   const { recipient, feePayer } = Account.resolve(parameters)
@@ -250,11 +257,30 @@ export function charge<const parameters extends charge.Parameters>(
             return serializedTransaction
           })()
 
-          const receipt = await sendRawTransactionSync(client, {
-            serializedTransaction: serializedTransaction_final,
-          })
-
-          return toReceipt(receipt)
+          if (waitForConfirmation) {
+            const receipt = await sendRawTransactionSync(client, {
+              serializedTransaction: serializedTransaction_final,
+            })
+            return toReceipt(receipt)
+          } else {
+            // Optimistic path: simulate to catch obvious reverts, then broadcast
+            // without waiting for on-chain confirmation. The returned receipt
+            // assumes success — callers opt into this risk via waitForConfirmation: false.
+            await simulateTransaction(client, {
+              ...transaction,
+              from: transaction.from as `0x${string}`,
+              calls,
+            })
+            const hash = await sendRawTransaction(client, {
+              serializedTransaction: serializedTransaction_final,
+            })
+            return {
+              method: 'tempo',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: hash,
+            } as const
+          }
         }
 
         default:
@@ -270,6 +296,18 @@ export declare namespace charge {
   type Parameters = {
     /** Testnet mode. */
     testnet?: boolean | undefined
+    /**
+     * Whether to wait for the charge transaction to confirm on-chain before
+     * responding. @default true
+     *
+     * When `false`, the transaction is simulated via `eth_estimateGas` and
+     * broadcast without waiting for inclusion. The receipt will optimistically
+     * report `status: 'success'` based on simulation alone — if the
+     * transaction reverts on-chain after broadcast (e.g. due to a state
+     * change between simulation and inclusion), the receipt will not reflect
+     * the failure.
+     */
+    waitForConfirmation?: boolean | undefined
   } & Client.getResolver.Parameters &
     Account.resolve.Parameters &
     Defaults

package/src/tempo/server/Session.test.ts

@@ -929,7 +929,7 @@ describe('session', () => {
         request: makeRequest(),
       })
 
-      const settleTxHash = await settle(store, client, channelId, escrowContract)
+      const settleTxHash = await settle(store, client, channelId, { escrowContract })
       expect(settleTxHash).toMatch(/^0x/)
 
       const ch = await store.getChannel(channelId)
@@ -939,7 +939,7 @@ describe('session', () => {
     test('settle rejects when no channel found', async () => {
       const fakeChannelId =
         '0x0000000000000000000000000000000000000000000000000000000000000000' as Hex
-      await expect(settle(store, client, fakeChannelId, escrowContract)).rejects.toThrow(
+      await expect(settle(store, client, fakeChannelId, { escrowContract })).rejects.toThrow(
         ChannelNotFoundError,
       )
     })
@@ -1101,6 +1101,55 @@ describe('session', () => {
       expect(result).toBeUndefined()
     })
 
+    test('returns undefined for open POST with content-length > 0 (content request)', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'open' },
+        },
+        input: new Request('http://localhost', {
+          method: 'POST',
+          headers: { 'content-length': '42' },
+        }),
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
+    test('returns undefined for open POST with transfer-encoding header (content request)', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'open' },
+        },
+        input: new Request('http://localhost', {
+          method: 'POST',
+          headers: { 'transfer-encoding': 'chunked' },
+        }),
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
+    test('returns 204 for GET with topUp action', () => {
+      const server = createServer()
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'topUp' },
+        },
+        input: new Request('http://localhost', { method: 'GET' }),
+      } as any)
+      expect(result).toBeInstanceOf(Response)
+      expect((result as Response).status).toBe(204)
+    })
+
     test('returns undefined for voucher POST with content-length > 0 (content request)', () => {
       const server = createServer()
       const result = server.respond!({

package/src/tempo/server/Session.ts

@@ -85,13 +85,17 @@ export function session<const parameters extends session.Parameters>(p?: paramet
   const parameters = p as parameters
   const {
     amount,
+    channelStateTtl = 60_000,
     currency = defaults.resolveCurrency(parameters),
     decimals = defaults.decimals,
     store: rawStore = Store.memory(),
     suggestedDeposit,
     unitType,
+    waitForConfirmation = true,
   } = parameters
 
+  const lastOnChainVerified = new Map<Hex, number>()
+
   const store = ChannelStore.fromStore(rawStore)
 
   const getClient = Client.getResolver({
@@ -187,7 +191,9 @@ export function session<const parameters extends session.Parameters>(p?: paramet
             payload,
             methodDetails,
             resolvedFeePayer,
+            waitForConfirmation,
           )
+          lastOnChainVerified.set(payload.channelId, Date.now())
           break
 
         case 'topUp':
@@ -199,6 +205,7 @@ export function session<const parameters extends session.Parameters>(p?: paramet
             methodDetails,
             resolvedFeePayer,
           )
+          lastOnChainVerified.set(payload.channelId, Date.now())
           break
 
         case 'voucher':
@@ -209,6 +216,8 @@ export function session<const parameters extends session.Parameters>(p?: paramet
             challenge,
             payload,
             methodDetails,
+            channelStateTtl,
+            lastOnChainVerified,
           )
           break
 
@@ -220,6 +229,7 @@ export function session<const parameters extends session.Parameters>(p?: paramet
             payload,
             methodDetails,
             account,
+            resolvedFeePayer,
           )
           break
 
@@ -237,34 +247,30 @@ export function session<const parameters extends session.Parameters>(p?: paramet
     // invoking the user's route handler. When it returns undefined, the
     // user's handler runs normally and serves content.
     //
-    // Management actions (open, topUp, close) are always gated — they
-    // return 204 regardless of request method.
+    // close and topUp are always gated (204) — they are pure management.
     //
-    // Voucher POSTs are gated only when they have no request body, which
-    // signals a mid-session voucher update (the client is just topping up
-    // the channel balance). Voucher POSTs WITH a body are content requests
-    // (e.g., an API call to a POST endpoint) and fall through to the
-    // user's handler. GET requests with vouchers always fall through so
-    // auto-mode clients (whose fetch wrapper bundles open+voucher into a
-    // single GET retry) receive content as expected.
+    // open and voucher are gated only for bodyless POSTs (management
+    // updates). POSTs with a body are content requests — the client's
+    // original request piggybacked on the credential — so they fall
+    // through to serve content. GETs always fall through so auto-mode
+    // clients (whose fetch wrapper bundles open+voucher into a single
+    // GET retry) receive content as expected.
     respond({ credential, input }) {
       const { payload } = credential as Credential.Credential<SessionCredentialPayload>
 
       if (payload.action === 'close') return new Response(null, { status: 204 })
-
-      const isManagement = payload.action === 'open' || payload.action === 'topUp'
-      if (isManagement && input.method === 'POST') return new Response(null, { status: 204 })
-
-      const isVoucher = payload.action === 'voucher'
-      if (!isVoucher) return undefined
-
-      // Only gate voucher POSTs with no body (mid-session balance updates).
-      // POSTs with a body are content requests that should reach the handler.
-      if (input.method !== 'POST') return undefined
-      const contentLength = input.headers.get('content-length')
-      if (contentLength !== null && contentLength !== '0') return undefined
-      if (input.headers.has('transfer-encoding')) return undefined
-      return new Response(null, { status: 204 })
+      if (payload.action === 'topUp') return new Response(null, { status: 204 })
+
+      // open and voucher: gate only bodyless POSTs (management updates).
+      // POSTs with a body are content requests — fall through so the
+      // upstream response is returned to the client.
+      if (input.method === 'POST') {
+        const contentLength = input.headers.get('content-length')
+        if (contentLength !== null && contentLength !== '0') return undefined
+        if (input.headers.has('transfer-encoding')) return undefined
+        return new Response(null, { status: 204 })
+      }
+      return undefined
     },
   })
 }
@@ -276,8 +282,22 @@ export declare namespace session {
   >
 
   type Parameters = {
+    /** TTL in milliseconds for cached on-chain channel state. After this duration, the server re-queries on-chain state during voucher handling to detect forced close requests. @default 60_000 */
+    channelStateTtl?: number | undefined
     /** Minimum voucher delta to accept (numeric string, default: "0"). */
     minVoucherDelta?: string | undefined
+    /**
+     * Whether to wait for the open transaction to confirm on-chain before
+     * responding. @default true
+     *
+     * When `false`, the transaction is simulated via `eth_estimateGas` and
+     * broadcast without waiting for inclusion. The receipt will optimistically
+     * report `status: 'success'` based on simulation alone — if the
+     * transaction reverts on-chain after broadcast (e.g. due to a state
+     * change between simulation and inclusion), the receipt will not reflect
+     * the failure.
+     */
+    waitForConfirmation?: boolean | undefined
     /** Store backend for channel state. */
     store?: Store.Store | undefined
     /**
@@ -310,7 +330,10 @@ export async function settle(
   store: ChannelStore.ChannelStore,
   client: viem_Client,
   channelId: Hex,
-  escrowContract?: Address | undefined,
+  options?: {
+    escrowContract?: Address | undefined
+    feePayer?: viem_Account | undefined
+  },
 ): Promise<Hex> {
   const channel = await store.getChannel(channelId)
   if (!channel) throw new ChannelNotFoundError({ reason: 'channel not found' })
@@ -318,11 +341,17 @@ export async function settle(
 
   const chainId = client.chain?.id
   const resolvedEscrow =
-    escrowContract ?? defaults.escrowContract[chainId as keyof typeof defaults.escrowContract]
+    options?.escrowContract ??
+    defaults.escrowContract[chainId as keyof typeof defaults.escrowContract]
   if (!resolvedEscrow) throw new Error(`No escrow contract for chainId ${chainId}.`)
 
   const settledAmount = channel.highestVoucher.cumulativeAmount
-  const txHash = await settleOnChain(client, resolvedEscrow, channel.highestVoucher)
+  const txHash = await settleOnChain(
+    client,
+    resolvedEscrow,
+    channel.highestVoucher,
+    options?.feePayer,
+  )
 
   await store.updateChannel(channelId, (current) => {
     if (!current) return null
@@ -482,7 +511,12 @@ async function verifyAndAcceptVoucher(parameters: {
 }
 
 /**
- * Handle 'open' action - broadcast open transaction, verify voucher, and create channel.
+ * Handle 'open' action - verify voucher, create channel, and broadcast.
+ *
+ * When `waitForConfirmation` is true (default), the open transaction is
+ * broadcast and confirmed on-chain before responding. When false, the
+ * transaction is validated and simulated via `eth_estimateGas`; the receipt
+ * is returned immediately and the broadcast runs in the background.
  */
 async function handleOpen(
   store: ChannelStore.ChannelStore,
@@ -491,6 +525,7 @@ async function handleOpen(
   payload: SessionCredentialPayload & { action: 'open' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
+  waitForConfirmation: boolean,
 ): Promise<SessionReceipt> {
   const voucher = parseVoucherFromPayload(
     payload.channelId,
@@ -510,6 +545,7 @@ async function handleOpen(
     recipient,
     currency,
     feePayer,
+    waitForConfirmation,
   })
 
   validateOnChainChannel(onChain, recipient, currency, amount)
@@ -621,6 +657,7 @@ async function handleTopUp(
     serializedTransaction: payload.transaction,
     escrowContract: methodDetails.escrowContract,
     channelId: payload.channelId,
+    currency: challenge.request.currency as Address,
     declaredDeposit,
     previousDeposit: channel.deposit,
     feePayer,
@@ -645,11 +682,13 @@ async function handleTopUp(
  */
 async function handleVoucher(
   store: ChannelStore.ChannelStore,
-  _client: viem_Client,
+  client: viem_Client,
   minVoucherDelta: bigint,
   challenge: Challenge.Challenge,
   payload: SessionCredentialPayload & { action: 'voucher' },
   methodDetails: SessionMethodDetails,
+  channelStateTtl: number,
+  lastOnChainVerified: Map<Hex, number>,
 ): Promise<SessionReceipt> {
   const channel = await store.getChannel(payload.channelId)
   if (!channel) {
@@ -671,15 +710,28 @@ async function handleVoucher(
   // same session can safely use the cached deposit/signer values.
   // This avoids an RPC round-trip per voucher, which is critical for
   // high-frequency SSE streaming where vouchers arrive per-token.
-  const cachedOnChain: OnChainChannel = {
-    payer: channel.payer,
-    payee: channel.payee,
-    token: channel.token,
-    deposit: channel.deposit,
-    settled: channel.settledOnChain,
-    finalized: channel.finalized,
-    authorizedSigner: channel.authorizedSigner,
-    closeRequestedAt: 0n,
+  //
+  // To guard against the payer initiating a forced close while vouchers
+  // are still being accepted, re-query on-chain state when the cache
+  // exceeds the configured staleness TTL.
+  const lastVerified = lastOnChainVerified.get(payload.channelId) ?? 0
+  const isStale = Date.now() - lastVerified > channelStateTtl
+
+  let cachedOnChain: OnChainChannel
+  if (isStale) {
+    cachedOnChain = await getOnChainChannel(client, methodDetails.escrowContract, payload.channelId)
+    lastOnChainVerified.set(payload.channelId, Date.now())
+  } else {
+    cachedOnChain = {
+      payer: channel.payer,
+      payee: channel.payee,
+      token: channel.token,
+      deposit: channel.deposit,
+      settled: channel.settledOnChain,
+      finalized: channel.finalized,
+      authorizedSigner: channel.authorizedSigner,
+      closeRequestedAt: 0n,
+    }
   }
 
   return verifyAndAcceptVoucher({
@@ -704,6 +756,7 @@ async function handleClose(
   payload: SessionCredentialPayload & { action: 'close' },
   methodDetails: SessionMethodDetails,
   account?: viem_Account,
+  feePayer?: viem_Account,
 ): Promise<SessionReceipt> {
   const channel = await store.getChannel(payload.channelId)
   if (!channel) {
@@ -754,7 +807,13 @@ async function handleClose(
     throw new InvalidSignatureError({ reason: 'invalid voucher signature' })
   }
 
-  const txHash = await closeOnChain(client, methodDetails.escrowContract, voucher, account)
+  const txHash = await closeOnChain(
+    client,
+    methodDetails.escrowContract,
+    voucher,
+    account,
+    feePayer,
+  )
 
   const updated = await store.updateChannel(payload.channelId, (current) => {
     if (!current) return null