mppx 0.8.12 → 0.8.14

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

@@ -44,10 +44,16 @@ import {
 import { respondToSessionCredential } from './RequestState.js'
 import { applyVerifiedHttpAccounting, chargeSessionChannel } from './Settlement.js'
 import { maybeSettleScheduled } from './Settlement.js'
-import { resolveSettlementSchedule, type SettlementSchedule } from './Settlement.js'
+import {
+  resolveSettlementSchedule,
+  type OnSessionSettlement,
+  type SettlementSchedule,
+} from './Settlement.js'
 
 /** Server-side automatic settlement schedule. */
 export type { SettlementSchedule } from './Settlement.js'
+/** Server-side settlement event hook types. */
+export type { OnSessionSettlement, SessionSettlementContext } from './Settlement.js'
 /** Server-side hook types for request-identity channel bootstrap. */
 export type {
   ResolveSessionChannelId,
@@ -312,6 +318,7 @@ export function session<const parameters extends session.Parameters>(
     unitType,
   } = parameters
   const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals)
+  const onSessionSettlement = parameters.onSessionSettlement
 
   const store = ChannelStore.fromStore(rawStore)
   const lastOnChainVerified = new Map<Hex, number>()
@@ -424,6 +431,7 @@ export function session<const parameters extends session.Parameters>(
         feeToken: parameters.feeToken,
         lastOnChainVerified,
         minVoucherDelta: context.minVoucherDelta,
+        onSessionSettlement,
         payload,
         store,
       })
@@ -444,6 +452,7 @@ export function session<const parameters extends session.Parameters>(
             ...(typeof context.feePayer === 'object' ? { feePayer: context.feePayer } : {}),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: parameters.feeToken,
+            onSessionSettlement,
             schedule: settlementSchedule,
             store,
             channel,
@@ -492,9 +501,20 @@ export namespace session {
     feePayerPolicy?: FeePayerPolicy | undefined
     /** Minimum voucher delta to accept (numeric string, default: "0"). */
     minVoucherDelta?: string | undefined
-    /** Resolve a reusable channel ID from request identity when no credential/request channel ID is present. */
+    /**
+     * Maps authenticated application identity and payment scope to an existing channel ID.
+     * Called only when the request does not already supply a channel ID. MPPx then loads that
+     * ID from `store` and validates the channel before including its snapshot in a challenge or
+     * bootstrap response. The store is not searched automatically and does not need to implement
+     * a secondary-index format.
+     */
     resolveChannelId?: ResolveSessionChannelId | undefined
-    /** Enables same-route HEAD bootstrap using a zero-amount identity proof. */
+    /**
+     * Enables same-route `HEAD` recovery before a paid request. The server issues a zero-amount
+     * identity challenge, verifies the returned proof, passes its authenticated `source` to
+     * `resolveChannelId`, validates the loaded channel's payment scope, and returns a snapshot
+     * containing the signed highest voucher for client rehydration.
+     */
     bootstrap?: boolean | undefined
     /**
      * Atomic store backend for channel state.
@@ -510,6 +530,8 @@ export namespace session {
     chainId?: number | undefined
     /** TIP20EscrowChannel precompile address override. */
     escrowContract?: Address | undefined
+    /** Callback invoked after any on-chain settlement or close transaction is confirmed. */
+    onSessionSettlement?: OnSessionSettlement | undefined
     /** Server-owned automatic settlement cadence. Clients do not receive or control this schedule. */
     settlementSchedule?: SettlementSchedule | undefined
 
@@ -522,11 +544,12 @@ export namespace session {
   /** Defaults derived from `session()` parameters for handler type inference. */
   export type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<
     parameters,
-    Defaults
-  > & {
-    decimals: number
-    escrowContract: Address
-  }
+    Defaults,
+    {
+      currency: string
+      decimals: number
+    }
+  >
 }
 
 /**

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

@@ -16,6 +16,7 @@ import {
   InsufficientBalanceError,
   VerificationFailedError,
 } from '../../../Errors.js'
+import type { MaybePromise } from '../../../internal/types.js'
 import type * as Method from '../../../Method.js'
 import * as Store from '../../../Store.js'
 import type * as FeePayer from '../../internal/fee-payer.js'
@@ -146,6 +147,23 @@ export type SettlementProgress = {
   units: number
 }
 
+/** Context emitted when an on-chain settlement or close transaction is confirmed. */
+export type SessionSettlementContext = Readonly<{
+  /** On-chain transaction hash (or signature on Solana). */
+  txHash: Hex
+  /** Channel ID that was settled. */
+  channelId: Hex
+  /** The trigger that caused settlement. */
+  trigger: 'settle' | 'close' | 'scheduled'
+  /** Cumulative amount settled on-chain to the payee (raw token units). */
+  amount: bigint
+  /** Incremental amount settled in this transaction (raw token units). */
+  delta: bigint
+}>
+
+/** Callback invoked after an on-chain settlement or close transaction is confirmed. */
+export type OnSessionSettlement = (context: SessionSettlementContext) => MaybePromise<void>
+
 /** Inputs used to mark a channel after automatic scheduled settlement succeeds. */
 export type MarkSettlementCompleteParameters = {
   channelId: ChannelStore.State['channelId']
@@ -340,6 +358,8 @@ export type SettlementTransactionOptions = {
   feePayerPolicy?: Partial<FeePayer.Policy> | undefined
   /** Optional fee token override for settlement. */
   feeToken?: Address | undefined
+  /** Callback invoked after the settlement transaction is confirmed. */
+  onSessionSettlement?: OnSessionSettlement | undefined
 }
 
 /** Inputs for applying a server-owned automatic settlement schedule. */
@@ -356,6 +376,8 @@ export type MaybeSettleScheduledParameters = {
   feePayerPolicy?: Partial<FeePayer.Policy> | undefined
   /** Optional fee token override for settlement. */
   feeToken?: Address | undefined
+  /** Callback invoked after the scheduled settlement transaction is confirmed. */
+  onSessionSettlement?: OnSessionSettlement | undefined
   /** Resolved server-owned settlement cadence. */
   schedule: ResolvedSettlementSchedule | undefined
   /** Server-side channel store. */
@@ -400,6 +422,9 @@ export async function maybeSettleScheduled(
     ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
     ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
     ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
+    onSessionSettlement: parameters.onSessionSettlement
+      ? (ctx) => parameters.onSessionSettlement!({ ...ctx, trigger: 'scheduled' })
+      : undefined,
   })
   await markSettlementComplete({ channelId: channel.channelId, store })
   return txHash
@@ -466,6 +491,15 @@ export async function settle(
         }
       : current,
   )
+  if (options?.onSessionSettlement) {
+    await emitSessionSettlement(options.onSessionSettlement, {
+      txHash,
+      channelId,
+      trigger: 'settle',
+      amount: newSettled,
+      delta: newSettled - channel.settledOnChain,
+    })
+  }
   return txHash
 }
 
@@ -480,3 +514,14 @@ export async function settleBatch(
   for (const channelId of channelIds) hashes.push(await settle(store, client, channelId, options))
   return hashes
 }
+
+async function emitSessionSettlement(
+  onSessionSettlement: OnSessionSettlement,
+  context: SessionSettlementContext,
+): Promise<void> {
+  try {
+    await onSessionSettlement(Object.freeze(context))
+  } catch {
+    // Errors are isolated — observers cannot break the settlement flow.
+  }
+}

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

@@ -408,6 +408,119 @@ describe('isows', () => {
     expect(channel?.units).toBe(0)
   })
 
+  test('aborts a blocked application generator before sending close-ready', async () => {
+    const socket = new MockSocket()
+    const store = memoryChannelStore()
+    await seedChannel(store, 1n)
+    let generatorAborted = false
+
+    await Ws.serve({
+      socket,
+      store,
+      url: 'ws://example.test/stream',
+      route: async () => ({
+        status: 200,
+        withReceipt(response = new Response(null, { status: 204 })) {
+          response.headers.set(
+            'Payment-Receipt',
+            serializeSessionReceipt(
+              createSessionReceipt({
+                challengeId: challenge.id,
+                channelId,
+                acceptedCumulative: 1n,
+                spent: 0n,
+                units: 0,
+              }),
+            ),
+          )
+          return response
+        },
+      }),
+      generate: async function* (stream) {
+        await new Promise<void>((resolve) => {
+          stream.signal.addEventListener('abort', () => resolve(), { once: true })
+        })
+        generatorAborted = true
+        yield* []
+      },
+    })
+
+    socket.receive(
+      Ws.formatAuthorizationMessage(
+        makeCredential({
+          action: 'open',
+          channelId,
+          cumulativeAmount: '1',
+          signature: `0x${'77'.repeat(65)}`,
+          transaction: '0x01',
+          type: 'transaction',
+        }),
+      ),
+    )
+    await sleep(10)
+    socket.receive(Ws.formatCloseRequestMessage())
+    await sleep(10)
+
+    expect(generatorAborted).toBe(true)
+    expect(
+      socket.sent
+        .map((message) => Ws.parseMessage(message))
+        .some((message) => message?.mpp === 'payment-close-ready'),
+    ).toBe(true)
+  })
+
+  test('meters an explicit per-message amount independently of the challenge tick cost', async () => {
+    const socket = new MockSocket()
+    const store = memoryChannelStore()
+    await seedChannel(store, 25n)
+
+    await Ws.serve({
+      socket,
+      store,
+      url: 'ws://example.test/stream',
+      route: async () => ({
+        status: 200,
+        withReceipt(response = new Response(null, { status: 204 })) {
+          response.headers.set(
+            'Payment-Receipt',
+            serializeSessionReceipt(
+              createSessionReceipt({
+                challengeId: challenge.id,
+                channelId,
+                acceptedCumulative: 25n,
+                spent: 0n,
+                units: 0,
+              }),
+            ),
+          )
+          return response
+        },
+      }),
+      generate: async function* (stream) {
+        await stream.charge(7n)
+        yield 'priced-response'
+      },
+    })
+
+    socket.receive(
+      Ws.formatAuthorizationMessage(
+        makeCredential({
+          action: 'open',
+          channelId,
+          cumulativeAmount: '25',
+          signature: `0x${'77'.repeat(65)}`,
+          transaction: '0x01',
+          type: 'transaction',
+        }),
+      ),
+    )
+
+    await sleep(10)
+
+    expect(await store.getChannel(channelId)).toMatchObject({ spent: 7n, units: 1 })
+    expect(socket.sent.some((message) => message.includes('priced-response'))).toBe(true)
+  })
+
   test('does not meter or emit application messages after close is requested on-chain', async () => {
     const socket = new MockSocket()
     const store = memoryChannelStore()

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

@@ -322,6 +322,8 @@ export declare namespace serve {
      *  multiple offers — otherwise a client can select the cheapest offer
      *  and still receive the same stream. */
     amount?: string | undefined
+    /** Application stream. A manual stream can call `charge(amount)` with a
+     *  per-message raw-unit amount; omitting it uses the challenge tick cost. */
     generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>)
     pollIntervalMs?: number | undefined
     /** Payment route handler. Receives synthetic `POST` requests with only

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

@@ -3,8 +3,10 @@ export { charge, session, settle, settleBatch } from './Session.js'
 export * as Sse from './Sse.js'
 /** Server-side automatic settlement schedule. */
 export type {
+  OnSessionSettlement,
   ResolveSessionChannelId,
   ResolveSessionChannelIdParameters,
   SessionChannelIdRequest,
+  SessionSettlementContext,
   SettlementSchedule,
 } from './Session.js'

package/src/validation/core.ts

@@ -14,6 +14,7 @@ import {
   parseEndpointArg,
   resolveBodyForEndpoint,
 } from '../cli/validate/helpers.js'
+import { missingDiscoverySuggestion } from '../cli/validate/messages.js'
 import { validatePaymentFlow } from '../cli/validate/payment.js'
 import { validate as validateDiscoveryDoc } from '../discovery/Validate.js'
 
@@ -237,7 +238,7 @@ export async function validate(options: ValidateOptions): Promise<ValidateResult
 
   if (!discovery) throw new Error('Discovery phase did not complete')
 
-  const suggestions = computeSuggestions(endpointResults, { sawTestnet, sawMainnet })
+  const suggestions = computeSuggestions(endpointResults, discovery, { sawTestnet, sawMainnet })
 
   return {
     url: baseUrl,
@@ -250,11 +251,16 @@ export async function validate(options: ValidateOptions): Promise<ValidateResult
 
 function computeSuggestions(
   endpoints: EndpointValidationResult[],
+  discovery: DiscoveryResult,
   flags: { sawTestnet: boolean; sawMainnet: boolean },
 ): string[] {
   const steps: string[] = []
   const allResults = endpoints.flatMap((ep) => [...ep.challenge, ...ep.payment])
 
+  if (!discovery.found) {
+    steps.push(missingDiscoverySuggestion)
+  }
+
   const sawCryptoMainnet = flags.sawMainnet
   const sawCryptoTestnet = flags.sawTestnet
   const sawStripeLive = allResults.some(

package/src/viem/Client.test.ts

@@ -3,12 +3,16 @@ import { privateKeyToAccount } from 'viem/accounts'
 import { signTransaction } from 'viem/actions'
 import { Account as TempoAccount, Transaction } from 'viem/tempo'
 import { tempoLocalnet } from 'viem/tempo/chains'
-import { describe, expect, test } from 'vp/test'
+import { afterEach, describe, expect, test, vi } from 'vp/test'
 
 import * as Client from './Client.js'
 
 const rpcUrl = { 42: 'https://rpc.example.com', 99: 'https://rpc2.example.com' } as const
 
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
 describe('getResolver', () => {
   test('behavior: creates client from rpcUrl for given chainId', async () => {
     const getClient = Client.getResolver({
@@ -61,6 +65,45 @@ describe('getResolver', () => {
       `[Error: No \`rpcUrl\` configured for \`chainId\` (99).]`,
     )
   })
+
+  test('behavior: wraps custom client transports with a hosted fee payer', async () => {
+    const defaultRequests: string[] = []
+    const client = createClient({
+      chain: tempoLocalnet,
+      transport: custom({
+        async request({ method }) {
+          defaultRequests.push(method)
+          return { source: 'default' }
+        },
+      }),
+    })
+    const fetchMock = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      const request = JSON.parse(String(init?.body)) as { id: number; jsonrpc: string }
+      return Response.json({
+        id: request.id,
+        jsonrpc: request.jsonrpc,
+        result: { source: 'relay' },
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const getClient = Client.getResolver({
+      chain: tempoLocalnet,
+      feePayerUrl: 'https://sponsor.example',
+      getClient: () => client,
+      rpcUrl: { [tempoLocalnet.id]: 'https://rpc.example.com' },
+    })
+    const resolved = await getClient({ chainId: tempoLocalnet.id })
+    const result = await resolved.request({
+      method: 'eth_fillTransaction',
+      params: [{ feePayer: true }],
+    } as never)
+
+    expect(result).toEqual({ source: 'relay' })
+    expect(fetchMock).toHaveBeenCalledOnce()
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('https://sponsor.example/')
+    expect(defaultRequests).toEqual([])
+  })
 })
 
 // ---------------------------------------------------------------------------

package/src/viem/Client.ts

@@ -1,4 +1,4 @@
-import { type Chain, type Client, createClient, http } from 'viem'
+import { type Chain, type Client, createClient, createTransport, custom, http } from 'viem'
 import { withFeePayer } from 'viem/tempo'
 
 import type { MaybePromise } from '../internal/types.js'
@@ -23,31 +23,45 @@ export function getResolver(
     if (!chain?.serializers && !feePayerUrl) return getClient
     return async (params) => {
       const client = await getClient(params)
+      let resolvedClient = client
 
       // Wrap the client's transport with `withFeePayer` when a fee payer URL is provided.
       if (feePayerUrl && client.transport.key !== 'feePayer') {
-        const url = (client.transport as { url?: string }).url
-        if (url) {
-          const wrapped = createClient({
-            chain: client.chain,
-            transport: withFeePayer(http(url), http(feePayerUrl)),
-          })
-          Object.assign(client, { transport: wrapped.transport, request: wrapped.request })
-        }
+        const request = client.request.bind(client)
+        // The supplied client already owns retries. Keep the relay middleware retry-free so
+        // failures are not retried once per nested transport layer.
+        const feePayerTransport = withFeePayer(
+          custom({ request: (args) => request(args as never) }, { retryCount: 0 }),
+          http(feePayerUrl, { retryCount: client.transport.retryCount }),
+        )({
+          account: client.account,
+          chain: client.chain,
+          pollingInterval: client.pollingInterval,
+          retryCount: 0,
+        })
+        const wrapped = createTransport(
+          { ...feePayerTransport.config, retryCount: 0 },
+          feePayerTransport.value,
+        )
+        resolvedClient = Object.assign({}, client, {
+          request: wrapped.request,
+          transport: { ...wrapped.config, ...wrapped.value },
+        })
       }
 
-      if (!chain?.serializers || client.chain?.serializers?.transaction) return client
-      return Object.assign({}, client, {
+      if (!chain?.serializers || resolvedClient.chain?.serializers?.transaction)
+        return resolvedClient
+      return Object.assign({}, resolvedClient, {
         chain: {
           ...chain,
-          ...client.chain,
-          formatters: client.chain?.formatters ?? chain.formatters,
+          ...resolvedClient.chain,
+          formatters: resolvedClient.chain?.formatters ?? chain.formatters,
           prepareTransactionRequest:
-            client.chain?.prepareTransactionRequest ?? chain.prepareTransactionRequest,
-          serializers: client.chain?.serializers?.transaction
-            ? client.chain.serializers
+            resolvedClient.chain?.prepareTransactionRequest ?? chain.prepareTransactionRequest,
+          serializers: resolvedClient.chain?.serializers?.transaction
+            ? resolvedClient.chain.serializers
             : chain.serializers,
-        } as typeof client.chain,
+        } as typeof resolvedClient.chain,
       })
     }
   }