mppx 0.8.15 → 0.8.17

package/src/tempo/server/internal/transport.test.ts

@@ -738,8 +738,15 @@ describe('sse transport', () => {
 
   test('respondReceipt with non-SSE upstream Response still deducts from channel', async () => {
     const store = memoryStore()
+    const settled: Array<{ spent: bigint; units: number }> = []
     await seedChannel(store, 10000000n)
-    const transport = sse({ store })
+    const transport = sse({
+      store,
+      async settleCharged(channel) {
+        settled.push({ spent: channel.spent, units: channel.units })
+        return undefined
+      },
+    })
     const request = new Request('https://test.example.com/session', {
       body: JSON.stringify({ prompt: 'hello' }),
       headers: makeAuthorizedRequest().headers,
@@ -768,6 +775,7 @@ describe('sse transport', () => {
     expect(channel!.units).toBe(1)
     expect(receipt.spent).toBe('1000000')
     expect(receipt.units).toBe(1)
+    expect(settled).toEqual([{ spent: 1000000n, units: 1 }])
 
     expect(JSON.parse(body)).toEqual({ content: 'hello' })
     expect(response.headers.get('Content-Type')).toBe('application/json')
@@ -806,8 +814,18 @@ describe('sse transport', () => {
 
   test('respondReceipt with 204 content response still deducts from channel', async () => {
     const store = memoryStore()
+    let resolveSettlement!: (channel: ChannelStore.State) => void
+    const settlement = new Promise<ChannelStore.State>((resolve) => {
+      resolveSettlement = resolve
+    })
     await seedChannel(store, 10000000n)
-    const transport = sse({ store })
+    const transport = sse({
+      store,
+      async settleCharged(channel) {
+        resolveSettlement(channel)
+        return undefined
+      },
+    })
     const request = new Request('https://test.example.com/session', {
       body: JSON.stringify({ prompt: 'hello' }),
       headers: makeAuthorizedRequest().headers,
@@ -827,11 +845,12 @@ describe('sse transport', () => {
     expect(await response.text()).toBe('')
     const receipt = deserializeSessionReceipt(response.headers.get('Payment-Receipt')!)
 
-    await Promise.resolve()
+    const settled = await settlement
 
     const channel = await store.getChannel(channelId)
     expect(channel!.spent).toBe(1000000n)
     expect(channel!.units).toBe(1)
+    expect(settled).toMatchObject({ spent: 1000000n, units: 1 })
     expect(receipt.spent).toBe('1000000')
     expect(receipt.units).toBe(1)
   })

package/src/tempo/server/internal/transport.ts

@@ -12,6 +12,7 @@ import * as Transport from '../../../server/Transport.js'
 import type { SessionReceipt } from '../../session/precompile/Protocol.js'
 import { requireSessionCredentialContext } from '../../session/precompile/Protocol.js'
 import * as ChannelStore from '../../session/server/ChannelStore.js'
+import type { SettleChargedSessionChannel } from '../../session/server/Settlement.js'
 import * as Sse_core from '../../session/server/Sse.js'
 import { captureRequestBodyProbe, shouldChargePlainResponse } from './request-body.js'
 
@@ -48,7 +49,12 @@ function hasPrepaidSessionTick(receipt: SessionReceipt): boolean {
  * - Auto-detection of upstream SSE responses
  * - Fallback to standard HTTP receipt handling for plain Response
  */
-export function sse(options: sse.Options & { store: ChannelStore.ChannelStore }): Sse {
+export function sse(
+  options: sse.Options & {
+    settleCharged?: SettleChargedSessionChannel | undefined
+    store: ChannelStore.ChannelStore
+  },
+): Sse {
   const { pollingInterval, poll } = options
 
   // When `poll` is true, strip `waitForUpdate` so the SSE charge loop
@@ -117,6 +123,7 @@ export function sse(options: sse.Options & { store: ChannelStore.ChannelStore })
           tickCost,
           pollIntervalMs: pollingInterval,
           generate,
+          onChargeCommitted: options.settleCharged,
           prepaidUnits: hasPrepaidSessionTick(receipt as SessionReceipt) ? 1 : 0,
           signal: input.signal,
         })
@@ -174,20 +181,25 @@ export function sse(options: sse.Options & { store: ChannelStore.ChannelStore })
         response: response as Response,
         challengeId: verifiedChallengeId,
       })
+      const chargePlainResponse = async () => {
+        const result = await ChannelStore.deductFromChannel(store, channelId, tickCost)
+        if (result.ok) await options.settleCharged?.(result.channel)
+        return result
+      }
 
       // Non-SSE response (e.g. upstream returned JSON instead of event-stream).
       // Need to deduct tickCost so request isn't free.
       // For null-body statuses, the request shape determines whether the
       // response is management (no charge) or plain content (charge one tick).
       if (isNullBodyStatus(chargedResponse.status)) {
-        void ChannelStore.deductFromChannel(store, channelId, tickCost)
+        void chargePlainResponse()
         return chargedResponse
       }
 
       const stream = new ReadableStream<Uint8Array>({
         async start(controller) {
           // deduction completes before consumer reads
-          const result = await ChannelStore.deductFromChannel(store, channelId, tickCost)
+          const result = await chargePlainResponse()
           if (!result.ok) {
             controller.error(
               new Errors.InsufficientBalanceError({

package/src/tempo/session/README.md

@@ -186,6 +186,118 @@ sequenceDiagram
 The initial SSE POST is excluded from default HTTP charging to prevent double
 counting. Stream accounting remains owned by the transport driver.
 
+## Server transport configuration
+
+A session method owns the account, channel store, verification policy, and
+settlement schedule. Routes add prices and application content. HTTP and SSE
+run through configured route handlers; WebSocket uses a session-bound helper
+because its application messages no longer pass through HTTP.
+
+| Server shape           | Session option | Content API                         | Charging                            |
+| ---------------------- | -------------- | ----------------------------------- | ----------------------------------- |
+| HTTP only              | Omit `sse`     | `result.withReceipt(Response)`      | Once per billable request           |
+| SSE only               | `sse: true`    | `result.withReceipt(AsyncIterable)` | Each `stream.charge()`              |
+| WebSocket only         | Omit `sse`     | `mppx.session.serveWebSocket(...)`  | Each `stream.charge()`              |
+| HTTP + SSE + WebSocket | `sse: true`    | All three APIs                      | Selected by route and response type |
+
+All transports for one session service must share the same configured session
+method and store. `serveWebSocket` is bound to both the store and settlement
+policy, so callers pass neither dependency again. `tempo.Ws.serve` remains the
+low-level adapter for custom integrations.
+
+### Shared method configuration
+
+```ts
+const session = tempo.session({
+  account,
+  currency,
+  getClient: () => client,
+  settlementSchedule: { units: 100 },
+  store,
+  // Include when this instance serves any SSE route.
+  sse: true,
+})
+
+const mppx = Mppx.create({ methods: [session], secretKey })
+```
+
+`sse: true` enables async-iterable responses without changing ordinary
+`Response` handling, so a mixed server uses one session method.
+
+### HTTP
+
+```ts
+const httpRoute = mppx.session({ amount: '0.01', unitType: 'request' })
+const result = await httpRoute(request)
+
+if (result.status === 402) return result.challenge
+return result.withReceipt(Response.json({ ok: true }))
+```
+
+HTTP accounting charges the configured route amount before application content
+runs. A plain `Response` selects normal HTTP handling even when `sse: true`.
+
+### SSE
+
+```ts
+const sseRoute = mppx.session({ amount: '0.001', unitType: 'token' })
+const result = await sseRoute(request)
+
+if (result.status === 402) return result.challenge
+return result.withReceipt(async function* (stream) {
+  for await (const token of generateTokens()) {
+    await stream.charge()
+    yield token
+  }
+})
+```
+
+SSE requires `sse: true` on the shared session method. The async iterable
+selects SSE framing and transport-owned metering.
+
+### WebSocket
+
+```ts
+const wsRoute = mppx.session({ amount: '0.001', unitType: 'token' })
+
+webSocketServer.on('connection', (socket, request) => {
+  void mppx.session.serveWebSocket({
+    generate: async function* (stream) {
+      for await (const token of generateTokens()) {
+        await stream.charge()
+        yield token
+      }
+    },
+    route: wsRoute,
+    socket,
+    url: new URL(request.url!, `ws://${request.headers.host}`),
+  })
+})
+```
+
+The application still exposes `wsRoute` over HTTP for the initial challenge
+probe. The bound helper reuses the session store and automatic settlement
+schedule for in-band WebSocket vouchers and charges.
+
+### Mixed server
+
+```ts
+const httpRoute = mppx.session({ amount: '0.01', unitType: 'request' })
+const sseRoute = mppx.session({ amount: '0.001', unitType: 'token' })
+const wsRoute = mppx.session({ amount: '0.001', unitType: 'token' })
+
+async function handler(request: Request) {
+  const pathname = new URL(request.url).pathname
+  if (pathname === '/api/data') return serveHttp(httpRoute, request)
+  if (pathname === '/api/events') return serveSse(sseRoute, request)
+  if (pathname === '/ws') return serveWebSocketProbe(wsRoute, request)
+  return new Response('Not found', { status: 404 })
+}
+```
+
+Each route can choose its own price and unit type. Verification, channel state,
+and settlement policy remain shared through the single session method.
+
 ## Extension boundaries
 
 | Change                         | Preserve                                                                                        |

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

@@ -522,6 +522,55 @@ async function simulateTempoTransaction(client: Client, request: unknown) {
   await call(client, request as never)
 }
 
+/** Simulates an unsponsored client-signed session transaction without broadcasting it. */
+export async function simulateCredentialTransaction(parameters: {
+  /** viem client used for the read-only execution simulation. */
+  client: TransactionClient
+  /** Fee-payer configuration for the eventual broadcast. Sponsored transactions are simulated after completion. */
+  feePayer?: Account | true | undefined
+  /** Parsed client-signed Tempo transaction. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}): Promise<void> {
+  if (parameters.feePayer) return
+  await simulateTempoTransaction(
+    parameters.client,
+    FeePayer.simulationTransaction(parameters.transaction, { feePayer: false }),
+  )
+}
+
+function validateCredentialSponsorship(parameters: {
+  allowedFeeTokens: readonly Address[]
+  challengeExpires?: string | undefined
+  chainId: number
+  details: Record<string, string>
+  feePayer?: Account | true | undefined
+  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}) {
+  const {
+    allowedFeeTokens,
+    challengeExpires,
+    chainId,
+    details,
+    feePayer,
+    feePayerPolicy,
+    transaction,
+  } = parameters
+  if (!feePayer || feePayer === true) return
+  FeePayer.prepareSponsoredTransaction({
+    account: feePayer,
+    allowedFeeTokens,
+    challengeExpires,
+    chainId,
+    details,
+    policy: feePayerPolicy,
+    transaction: {
+      ...transaction,
+      ...(allowedFeeTokens[0] ? { feeToken: transaction.feeToken ?? allowedFeeTokens[0] } : {}),
+    },
+  })
+}
+
 async function signTempoTransaction(client: Client, transaction: unknown): Promise<Hex> {
   return (await signTransaction(client, transaction as never)) as Hex
 }
@@ -874,10 +923,25 @@ export type BroadcastOpenTransactionParameters = {
   serializedTransaction: Hex
 }
 
-/** Broadcast and validate a client-signed TIP-1034 open transaction. */
-export async function broadcastOpenTransaction(
-  parameters: BroadcastOpenTransactionParameters,
-): Promise<BroadcastOpenTransactionResult> {
+/** Inputs for validating a client-signed TIP-1034 open transaction without broadcasting it. */
+export type ValidateOpenCredentialTransactionParameters = Omit<
+  BroadcastOpenTransactionParameters,
+  'beforeBroadcast' | 'client'
+>
+
+/** Validated fields recovered from a client-signed TIP-1034 open transaction. */
+export type ValidatedOpenCredentialTransaction = Omit<
+  BroadcastOpenTransactionResult,
+  'state' | 'txHash'
+> & {
+  /** Parsed client-signed transaction, reused by simulation and broadcast. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}
+
+/** Validates the immutable fields of a client-signed TIP-1034 open transaction. */
+export function validateOpenCredentialTransaction(
+  parameters: ValidateOpenCredentialTransactionParameters,
+): ValidatedOpenCredentialTransaction {
   const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
@@ -909,6 +973,19 @@ export async function broadcastOpenTransaction(
     channelId: parameters.expectedChannelId,
   })
   if (parameters.feePayer) assertSenderSigned(transaction)
+  validateCredentialSponsorship({
+    allowedFeeTokens: [parameters.expectedCurrency],
+    challengeExpires: parameters.challengeExpires,
+    chainId: parameters.chainId,
+    details: {
+      channelId: parameters.expectedChannelId,
+      currency: parameters.expectedCurrency,
+      recipient: parameters.expectedPayee,
+    },
+    feePayer: parameters.feePayer,
+    feePayerPolicy: parameters.feePayerPolicy,
+    transaction,
+  })
   const expiringNonceHash = ChannelUtils.computeExpiringNonceHash(
     ChannelUtils.transactionForExpiringNonceHash({
       feePayer: parameters.feePayer,
@@ -920,10 +997,19 @@ export async function broadcastOpenTransaction(
     throw new VerificationFailedError({
       reason: 'credential expiringNonceHash does not match transaction',
     })
+  return { descriptor, expiringNonceHash, openDeposit: open.deposit, transaction }
+}
+
+/** Broadcast and validate a client-signed TIP-1034 open transaction. */
+export async function broadcastOpenTransaction(
+  parameters: BroadcastOpenTransactionParameters,
+): Promise<BroadcastOpenTransactionResult> {
+  const { descriptor, expiringNonceHash, openDeposit, transaction } =
+    validateOpenCredentialTransaction(parameters)
   await parameters.beforeBroadcast?.({
     descriptor,
     expiringNonceHash,
-    openDeposit: open.deposit,
+    openDeposit,
   })
   const receipt = await sendCredentialTransaction({
     challengeExpires: parameters.challengeExpires,
@@ -952,7 +1038,7 @@ export async function broadcastOpenTransaction(
     emittedExpiringNonceHash: opened.expiringNonceHash,
     escrow: parameters.escrowContract,
     expectedChannelId: parameters.expectedChannelId,
-    openDeposit: open.deposit,
+    openDeposit,
   })
   const chainChannel = await readbackWithRetry(() =>
     getChannel(parameters.client, descriptor, parameters.escrowContract, receipt.blockNumber),
@@ -964,7 +1050,7 @@ export async function broadcastOpenTransaction(
     descriptor,
     state,
     expiringNonceHash: opened.expiringNonceHash,
-    openDeposit: open.deposit,
+    openDeposit,
   }
 }
 
@@ -1004,10 +1090,22 @@ export type BroadcastTopUpTransactionParameters = {
   serializedTransaction: Hex
 }
 
-/** Broadcast and validate a client-signed TIP-1034 top-up transaction. */
-export async function broadcastTopUpTransaction(
-  parameters: BroadcastTopUpTransactionParameters,
-): Promise<BroadcastTopUpTransactionResult> {
+/** Inputs for validating a client-signed TIP-1034 top-up transaction without broadcasting it. */
+export type ValidateTopUpCredentialTransactionParameters = Omit<
+  BroadcastTopUpTransactionParameters,
+  'client'
+>
+
+/** Validated fields recovered from a client-signed TIP-1034 top-up transaction. */
+export type ValidatedTopUpCredentialTransaction = {
+  /** Parsed client-signed transaction, reused by simulation and broadcast. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}
+
+/** Validates the immutable fields of a client-signed TIP-1034 top-up transaction. */
+export function validateTopUpCredentialTransaction(
+  parameters: ValidateTopUpCredentialTransactionParameters,
+): ValidatedTopUpCredentialTransaction {
   const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
@@ -1027,6 +1125,28 @@ export async function broadcastTopUpTransaction(
     label: 'topUp',
     prefixCalls,
   })
+  if (parameters.feePayer) assertSenderSigned(transaction)
+  validateCredentialSponsorship({
+    allowedFeeTokens: [parameters.expectedCurrency],
+    challengeExpires: parameters.challengeExpires,
+    chainId: parameters.chainId,
+    details: {
+      additionalDeposit: parameters.additionalDeposit.toString(),
+      channelId: parameters.expectedChannelId,
+      currency: parameters.expectedCurrency,
+    },
+    feePayer: parameters.feePayer,
+    feePayerPolicy: parameters.feePayerPolicy,
+    transaction,
+  })
+  return { transaction }
+}
+
+/** Broadcast and validate a client-signed TIP-1034 top-up transaction. */
+export async function broadcastTopUpTransaction(
+  parameters: BroadcastTopUpTransactionParameters,
+): Promise<BroadcastTopUpTransactionResult> {
+  const { transaction } = validateTopUpCredentialTransaction(parameters)
   const receipt = await sendCredentialTransaction({
     challengeExpires: parameters.challengeExpires,
     chainId: parameters.chainId,

package/src/tempo/session/server/ChannelStore.ts

@@ -240,6 +240,18 @@ export type VerifyAndAcceptVoucherParameters = {
   voucher: SignedVoucher
 }
 
+/** Inputs for validating a cumulative voucher without recording it. */
+export type ValidateVoucherParameters = Omit<
+  VerifyAndAcceptVoucherParameters,
+  'challenge' | 'store'
+>
+
+/** Result of validating a cumulative voucher against persisted channel state. */
+export type VoucherValidation = {
+  /** Whether the voucher was already accepted at the same cumulative amount. */
+  alreadyAccepted: boolean
+}
+
 /** Channel backend-specific fields. */
 export type BackendState = CompatibilityBackendState | PrecompileBackendState
 
@@ -520,12 +532,11 @@ export async function loadPrecompileChannel(
   return channel
 }
 
-/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
-export async function verifyAndAcceptVoucher(
-  parameters: VerifyAndAcceptVoucherParameters,
-): Promise<SessionReceipt> {
-  const { store, minVoucherDelta, challenge, channel, voucher, channelState, methodDetails } =
-    parameters
+/** Verifies a cumulative voucher without changing persisted channel state. */
+export async function validateVoucher(
+  parameters: ValidateVoucherParameters,
+): Promise<VoucherValidation> {
+  const { minVoucherDelta, channel, voucher, channelState, methodDetails } = parameters
 
   validateChannelState(channelState)
   if (voucher.cumulativeAmount > channelState.deposit)
@@ -546,7 +557,22 @@ export async function verifyAndAcceptVoucher(
     throw new VerificationFailedError({
       reason: 'voucher cumulativeAmount is below on-chain settled amount',
     })
-  if (voucher.cumulativeAmount === channel.highestVoucherAmount)
+  if (voucher.cumulativeAmount === channel.highestVoucherAmount) return { alreadyAccepted: true }
+  const delta = voucher.cumulativeAmount - channel.highestVoucherAmount
+  if (delta < minVoucherDelta)
+    throw new DeltaTooSmallError({
+      reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
+    })
+  return { alreadyAccepted: false }
+}
+
+/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
+export async function verifyAndAcceptVoucher(
+  parameters: VerifyAndAcceptVoucherParameters,
+): Promise<SessionReceipt> {
+  const { store, challenge, channel, voucher, channelState } = parameters
+  const validation = await validateVoucher(parameters)
+  if (validation.alreadyAccepted)
     return createSessionReceipt({
       challengeId: challenge.id,
       channelId: voucher.channelId,
@@ -554,11 +580,6 @@ export async function verifyAndAcceptVoucher(
       spent: channel.spent,
       units: channel.units,
     })
-  const delta = voucher.cumulativeAmount - channel.highestVoucherAmount
-  if (delta < minVoucherDelta)
-    throw new DeltaTooSmallError({
-      reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
-    })
   const updated = await store.updateChannel(voucher.channelId, (current) =>
     acceptVoucherStateUpdate({ channelState, current, voucher }),
   )

package/src/tempo/session/server/CredentialVerification.test.ts

@@ -9,11 +9,11 @@ import * as Voucher from '../precompile/Voucher.js'
 import * as ChannelStore from './ChannelStore.js'
 import {
   assertOpenCredentialCoversRequest,
+  broadcastCredentialPayload,
   requireSessionCredentialAction,
   requireSessionCredentialPayload,
   requireSessionCredentialPayloadHeader,
   validateChannelDescriptor,
-  verifyCredentialPayload,
 } from './CredentialVerification.js'
 
 describe('SessionCredentialGuards', () => {
@@ -190,7 +190,7 @@ describe('SessionCredentialGuards', () => {
     })
   })
 
-  describe('verifyCredentialPayload', () => {
+  describe('broadcastCredentialPayload', () => {
     const escrow = '0x4D50500000000000000000000000000000000000' as Address
     const testChainId = chainIds.testnet
     const computedChannelId = Channel.computeId({ ...descriptor, chainId: testChainId, escrow })
@@ -246,7 +246,7 @@ describe('SessionCredentialGuards', () => {
       const verifyVoucher = vi.spyOn(Voucher, 'verifyVoucher').mockResolvedValue(true)
 
       await expect(
-        verifyCredentialPayload({
+        broadcastCredentialPayload({
           challenge,
           channelStateTtl: 60_000,
           chainId: testChainId,
@@ -274,7 +274,7 @@ describe('SessionCredentialGuards', () => {
       const verifyVoucher = vi.spyOn(Voucher, 'verifyVoucher').mockResolvedValue(true)
 
       await expect(
-        verifyCredentialPayload({
+        broadcastCredentialPayload({
           challenge,
           channelStateTtl: 60_000,
           chainId: testChainId,