mppx 0.8.12 → 0.8.14

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

@@ -12,7 +12,7 @@ import {
   type Hex,
 } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
-import { Transaction } from 'viem/tempo'
+import { Abis, Addresses, Transaction } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
 
 import { VerificationFailedError } from '../../../Errors.js'
@@ -36,6 +36,7 @@ const descriptor = {
 const deposit = Types.uint96(1_000_000n)
 const chainId = 42431
 const txHash = `0x${'ab'.repeat(32)}` as const
+const sourceToken = '0x6666666666666666666666666666666666666666' as const
 const feePayer = privateKeyToAccount(
   '0x59c6995e998f97a5a0044966f0945389d1fc6e60e7346d6c36c49d32f75b9a1b',
 )
@@ -62,6 +63,7 @@ function createMockClient(
         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_sendTransaction') return txHash
         if (args.method === 'eth_sendRawTransaction') return txHash
         if (args.method === 'eth_sendRawTransactionSync') return parameters.receipt ?? receipt([])
         if (args.method === 'eth_getTransactionReceipt') return parameters.receipt ?? null
@@ -161,7 +163,11 @@ function topUpLog(parameters: { channelId: `0x${string}`; newDeposit: bigint })
 }
 
 async function createSerializedTransaction(parameters: {
-  calls: { to: `0x${string}`; data?: `0x${string}` | undefined }[]
+  calls: {
+    to?: `0x${string}` | undefined
+    data?: `0x${string}` | undefined
+    value?: bigint | undefined
+  }[]
   gas?: bigint | undefined
   signed?: boolean | undefined
 }) {
@@ -191,6 +197,28 @@ async function createSerializedTransaction(parameters: {
   } as never)) as `0x${string}`
 }
 
+function autoSwapCalls(amountOut: bigint = deposit) {
+  const maxAmountIn = amountOut + 1_000n
+  return [
+    {
+      to: sourceToken,
+      data: encodeFunctionData({
+        abi: Abis.tip20,
+        functionName: 'approve',
+        args: [Addresses.stablecoinDex, maxAmountIn],
+      }),
+    },
+    {
+      to: Addresses.stablecoinDex,
+      data: encodeFunctionData({
+        abi: Abis.stablecoinDex,
+        functionName: 'swapExactAmountOut',
+        args: [sourceToken, descriptor.token, amountOut, maxAmountIn],
+      }),
+    },
+  ] as const
+}
+
 async function createOpenTransaction(
   parameters: {
     authorizedSigner?: `0x${string}` | undefined
@@ -200,6 +228,13 @@ async function createOpenTransaction(
     signed?: boolean | undefined
     token?: `0x${string}` | undefined
     to?: `0x${string}` | undefined
+    prefixCalls?:
+      | readonly {
+          to?: `0x${string}` | undefined
+          data?: `0x${string}` | undefined
+          value?: bigint | undefined
+        }[]
+      | undefined
   } = {},
 ) {
   const data = encodeFunctionData({
@@ -215,7 +250,7 @@ async function createOpenTransaction(
     ],
   })
   return createSerializedTransaction({
-    calls: [{ to: parameters.to ?? tip20ChannelEscrow, data }],
+    calls: [...(parameters.prefixCalls ?? []), { to: parameters.to ?? tip20ChannelEscrow, data }],
     gas: parameters.gas,
     signed: parameters.signed,
   })
@@ -228,6 +263,13 @@ async function createTopUpTransaction(
     gas?: bigint | undefined
     signed?: boolean | undefined
     to?: `0x${string}` | undefined
+    prefixCalls?:
+      | readonly {
+          to?: `0x${string}` | undefined
+          data?: `0x${string}` | undefined
+          value?: bigint | undefined
+        }[]
+      | undefined
   } = {},
 ) {
   const data = encodeFunctionData({
@@ -239,7 +281,7 @@ async function createTopUpTransaction(
     ],
   })
   return createSerializedTransaction({
-    calls: [{ to: parameters.to ?? tip20ChannelEscrow, data }],
+    calls: [...(parameters.prefixCalls ?? []), { to: parameters.to ?? tip20ChannelEscrow, data }],
     gas: parameters.gas,
     signed: parameters.signed,
   })
@@ -290,6 +332,31 @@ describe('precompile receipt wait', () => {
   })
 })
 
+describe('precompile server transactions', () => {
+  test('does not add a fee-payer signature when the sender and fee payer are the same account', async () => {
+    const rpcMethods: string[] = []
+    const client = createMockClient({ rpcMethods })
+    const sender = { address: feePayer.address, type: 'json-rpc' } as const
+
+    await Chain.closeOnChain(
+      client,
+      descriptor,
+      1n,
+      1n,
+      `0x${'11'.repeat(65)}`,
+      tip20ChannelEscrow,
+      {
+        account: sender,
+        candidateFeeTokens: [descriptor.token],
+        feePayer,
+      },
+    )
+
+    expect(rpcMethods).toContain('eth_sendTransaction')
+    expect(rpcMethods).not.toContain('eth_sendRawTransactionSync')
+  })
+})
+
 describe('precompile open calldata parsing', () => {
   test('parseOpenCall accepts TIP-1034 open calldata', () => {
     const data = encodeFunctionData({
@@ -420,8 +487,152 @@ describe('precompile broadcastOpenTransaction', () => {
         expectedPayer: descriptor.payer,
         serializedTransaction,
       }),
-    ).rejects.toThrow('TIP-1034 open transaction must contain exactly one call')
+    ).rejects.toThrow(
+      'TIP-1034 open transaction must contain one management call, optionally preceded by an auto-swap',
+    )
+  })
+
+  const [validApprove, validSwap] = autoSwapCalls()
+  const wrongToken = '0x7777777777777777777777777777777777777777' as const
+  const maxAmountIn = deposit + 1_000n
+  const approve = (parameters: {
+    amount?: bigint | undefined
+    spender?: Address | undefined
+    token?: Address | undefined
+  }) => ({
+    to: parameters.token ?? sourceToken,
+    data: encodeFunctionData({
+      abi: Abis.tip20,
+      functionName: 'approve',
+      args: [parameters.spender ?? Addresses.stablecoinDex, parameters.amount ?? maxAmountIn],
+    }),
+  })
+  const swap = (parameters: {
+    amountOut?: bigint | undefined
+    maxAmount?: bigint | undefined
+    tokenIn?: Address | undefined
+    tokenOut?: Address | undefined
+  }) => ({
+    to: Addresses.stablecoinDex as Address,
+    data: encodeFunctionData({
+      abi: Abis.stablecoinDex,
+      functionName: 'swapExactAmountOut',
+      args: [
+        parameters.tokenIn ?? sourceToken,
+        parameters.tokenOut ?? descriptor.token,
+        parameters.amountOut ?? deposit,
+        parameters.maxAmount ?? maxAmountIn,
+      ],
+    }),
   })
+  const invalidAutoSwapPrefixes = [
+    {
+      name: 'missing call target',
+      prefixCalls: [{ data: validApprove.data }, validSwap],
+      reason: 'call is missing a target or calldata',
+    },
+    {
+      name: 'native value',
+      prefixCalls: [{ ...validApprove, value: 1n }, validSwap],
+      reason: 'calls must not transfer native value',
+    },
+    {
+      name: 'wrong DEX target',
+      prefixCalls: [validApprove, { ...validSwap, to: wrongToken }],
+      reason: 'targets the wrong DEX',
+    },
+    {
+      name: 'invalid approval calldata',
+      prefixCalls: [{ ...validApprove, data: '0x12345678' as const }, validSwap],
+      reason: 'approval calldata is invalid',
+    },
+    {
+      name: 'invalid swap calldata',
+      prefixCalls: [validApprove, { ...validSwap, data: '0x12345678' as const }],
+      reason: 'swap calldata is invalid',
+    },
+    {
+      name: 'wrong approval function',
+      prefixCalls: [
+        {
+          to: sourceToken,
+          data: encodeFunctionData({
+            abi: Abis.tip20,
+            functionName: 'transfer',
+            args: [Addresses.stablecoinDex, maxAmountIn],
+          }),
+        },
+        validSwap,
+      ],
+      reason: 'must contain approve followed by swapExactAmountOut',
+    },
+    {
+      name: 'approval token mismatch',
+      prefixCalls: [approve({ token: wrongToken }), validSwap],
+      reason: 'approval token does not match swap input',
+    },
+    {
+      name: 'approval spender mismatch',
+      prefixCalls: [approve({ spender: wrongToken }), validSwap],
+      reason: 'approval spender is not the DEX',
+    },
+    {
+      name: 'approval amount mismatch',
+      prefixCalls: [approve({ amount: maxAmountIn + 1n }), validSwap],
+      reason: 'approval amount does not match swap maximum input',
+    },
+    {
+      name: 'output token mismatch',
+      prefixCalls: [validApprove, swap({ tokenOut: wrongToken })],
+      reason: 'output token does not match channel currency',
+    },
+    {
+      name: 'output amount mismatch',
+      prefixCalls: [
+        approve({ amount: maxAmountIn + 1n }),
+        swap({ amountOut: deposit + 1n, maxAmount: maxAmountIn + 1n }),
+      ],
+      reason: 'output amount does not match channel deposit',
+    },
+    {
+      name: 'identical input and output tokens',
+      prefixCalls: [approve({ token: descriptor.token }), swap({ tokenIn: descriptor.token })],
+      reason: 'input and output tokens must differ',
+    },
+    {
+      name: 'non-canonical approval calldata',
+      prefixCalls: [{ ...validApprove, data: `${validApprove.data}00` as Hex }, validSwap],
+      reason: 'approval calldata is not canonical',
+    },
+    {
+      name: 'non-canonical swap calldata',
+      prefixCalls: [validApprove, { ...validSwap, data: `${validSwap.data}00` as Hex }],
+      reason: 'swap calldata is not canonical',
+    },
+  ] as const
+
+  test.each(invalidAutoSwapPrefixes)(
+    'rejects an auto-swap with $name',
+    async ({ prefixCalls, reason }) => {
+      const serializedTransaction = await createOpenTransaction({ prefixCalls })
+
+      await expect(
+        Chain.broadcastOpenTransaction({
+          chainId,
+          client: createMockClient(),
+          escrowContract: tip20ChannelEscrow,
+          expectedAuthorizedSigner: descriptor.authorizedSigner,
+          expectedChannelId: `0x${'11'.repeat(32)}`,
+          expectedCurrency: descriptor.token,
+          expectedExpiringNonceHash: expectedExpiringNonceHash(serializedTransaction),
+          expectedOperator: descriptor.operator,
+          expectedPayee: descriptor.payee,
+          expectedPayer: descriptor.payer,
+          serializedTransaction,
+        }),
+      ).rejects.toThrow(`TIP-1034 open auto-swap ${reason}`)
+    },
+  )
 
   test('rejects open transactions targeting the wrong escrow contract', async () => {
     const serializedTransaction = await createOpenTransaction({ to: descriptor.token })
@@ -689,8 +900,8 @@ describe('precompile broadcastOpenTransaction', () => {
     ).rejects.toThrow('credential expiringNonceHash does not match transaction')
   })
 
-  test('returns tx hash, descriptor, event fields, and read-back state on success', async () => {
-    const serializedTransaction = await createOpenTransaction()
+  test('accepts an exact-output auto-swap before open', async () => {
+    const serializedTransaction = await createOpenTransaction({ prefixCalls: autoSwapCalls() })
     const expiringNonceHash = expectedExpiringNonceHash(serializedTransaction)
     const expectedDescriptor = { ...descriptor, expiringNonceHash }
     const channelId = Channel.computeId({
@@ -832,7 +1043,9 @@ describe('precompile broadcastTopUpTransaction', () => {
         expectedCurrency: descriptor.token,
         serializedTransaction,
       }),
-    ).rejects.toThrow('TIP-1034 topUp transaction must contain exactly one call')
+    ).rejects.toThrow(
+      'TIP-1034 topUp transaction must contain one management call, optionally preceded by an auto-swap',
+    )
   })
 
   test('rejects top-up transactions targeting the wrong escrow contract', async () => {
@@ -999,8 +1212,8 @@ describe('precompile broadcastTopUpTransaction', () => {
     ).rejects.toThrow('topUp deposit does not match credential')
   })
 
-  test('returns tx hash, new deposit, and read-back state on success', async () => {
-    const serializedTransaction = await createTopUpTransaction()
+  test('accepts an exact-output auto-swap before top-up', async () => {
+    const serializedTransaction = await createTopUpTransaction({ prefixCalls: autoSwapCalls() })
     const channelId = Channel.computeId({ ...descriptor, chainId, escrow: tip20ChannelEscrow })
     const newDeposit = deposit * 2n
     const state = { settled: 0n, deposit: newDeposit, closeRequestedAt: 0 }

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

@@ -1,5 +1,5 @@
 import type { Account, Address, Client, Hex } from 'viem'
-import { encodeFunctionData, isAddressEqual, parseEventLogs } from 'viem'
+import { decodeFunctionData, encodeFunctionData, isAddressEqual, parseEventLogs } from 'viem'
 import {
   call,
   prepareTransactionRequest,
@@ -10,7 +10,7 @@ import {
   signTransaction,
   waitForTransactionReceipt,
 } from 'viem/actions'
-import { Transaction } from 'viem/tempo'
+import { Abis, Addresses, Transaction } from 'viem/tempo'
 
 import { BadRequestError, VerificationFailedError } from '../../../Errors.js'
 import * as FeePayer from '../../internal/fee-payer.js'
@@ -401,6 +401,7 @@ export type ChannelTransactionOptions = {
 
 type ParsedPrecompileCredentialTransaction = {
   call: Transaction.TransactionTempo['calls'][number] & { data: Hex; to: Address }
+  prefixCalls: readonly Transaction.TransactionTempo['calls'][number][]
   transaction: ReturnType<(typeof Transaction)['deserialize']>
 }
 
@@ -418,11 +419,11 @@ function parsePrecompileCredentialTransaction(parameters: {
     serializedTransaction as Transaction.TransactionSerializedTempo,
   )
   const calls = transaction.calls
-  if (calls.length !== 1)
+  if (calls.length !== 1 && calls.length !== 3)
     throw new VerificationFailedError({
-      reason: `TIP-1034 ${label} transaction must contain exactly one call`,
+      reason: `TIP-1034 ${label} transaction must contain one management call, optionally preceded by an auto-swap`,
     })
-  const call = calls[0]!
+  const call = calls[calls.length - 1]!
   if (!call.to || !isAddressEqual(call.to, escrowContract))
     throw new VerificationFailedError({
       reason: `TIP-1034 ${label} transaction targets the wrong address`,
@@ -431,7 +432,88 @@ function parsePrecompileCredentialTransaction(parameters: {
     throw new VerificationFailedError({
       reason: `TIP-1034 ${label} transaction is missing calldata`,
     })
-  return { transaction, call: { ...call, data: call.data, to: call.to } }
+  return {
+    transaction,
+    call: { ...call, data: call.data, to: call.to },
+    prefixCalls: calls.slice(0, -1),
+  }
+}
+
+function validateAutoSwapPrefix(parameters: {
+  amountOut: bigint
+  currency: Address
+  label: 'open' | 'topUp'
+  prefixCalls: readonly Transaction.TransactionTempo['calls'][number][]
+}) {
+  const { amountOut, currency, label, prefixCalls } = parameters
+  if (prefixCalls.length === 0) return
+
+  const fail = (reason: string): never => {
+    throw new VerificationFailedError({ reason: `TIP-1034 ${label} auto-swap ${reason}` })
+  }
+  if (prefixCalls.length !== 2) fail('must contain exactly approve and swap calls')
+
+  const approveCall = prefixCalls[0]!
+  const swapCall = prefixCalls[1]!
+  const approveTo = approveCall.to
+  const approveData = approveCall.data
+  const swapTo = swapCall.to
+  const swapData = swapCall.data
+  if (!approveTo || !approveData || !swapTo || !swapData)
+    fail('call is missing a target or calldata')
+  const checkedApproveTo = approveTo as Address
+  const checkedApproveData = approveData as Hex
+  const checkedSwapTo = swapTo as Address
+  const checkedSwapData = swapData as Hex
+  if ((approveCall.value ?? 0n) !== 0n || (swapCall.value ?? 0n) !== 0n)
+    fail('calls must not transfer native value')
+  if (!isAddressEqual(checkedSwapTo, Addresses.stablecoinDex)) fail('targets the wrong DEX')
+
+  const approve = (() => {
+    try {
+      return decodeFunctionData({ abi: Abis.tip20, data: checkedApproveData })
+    } catch {
+      return fail('approval calldata is invalid')
+    }
+  })()
+  const swap = (() => {
+    try {
+      return decodeFunctionData({ abi: Abis.stablecoinDex, data: checkedSwapData })
+    } catch {
+      return fail('swap calldata is invalid')
+    }
+  })()
+  if (approve.functionName !== 'approve' || swap.functionName !== 'swapExactAmountOut')
+    fail('must contain approve followed by swapExactAmountOut')
+
+  const [spender, approvedAmount] = approve.args as readonly [Address, bigint]
+  const [tokenIn, tokenOut, swapAmountOut, maxAmountIn] = swap.args as readonly [
+    Address,
+    Address,
+    bigint,
+    bigint,
+  ]
+  if (!isAddressEqual(checkedApproveTo, tokenIn)) fail('approval token does not match swap input')
+  if (!isAddressEqual(spender, Addresses.stablecoinDex)) fail('approval spender is not the DEX')
+  if (approvedAmount !== maxAmountIn) fail('approval amount does not match swap maximum input')
+  if (!isAddressEqual(tokenOut, currency)) fail('output token does not match channel currency')
+  if (swapAmountOut !== amountOut) fail('output amount does not match channel deposit')
+  if (isAddressEqual(tokenIn, tokenOut)) fail('input and output tokens must differ')
+
+  const canonicalApprove = encodeFunctionData({
+    abi: Abis.tip20,
+    functionName: 'approve',
+    args: [spender, approvedAmount],
+  })
+  const canonicalSwap = encodeFunctionData({
+    abi: Abis.stablecoinDex,
+    functionName: 'swapExactAmountOut',
+    args: [tokenIn, tokenOut, swapAmountOut, maxAmountIn],
+  })
+  if (checkedApproveData.toLowerCase() !== canonicalApprove.toLowerCase())
+    fail('approval calldata is not canonical')
+  if (checkedSwapData.toLowerCase() !== canonicalSwap.toLowerCase())
+    fail('swap calldata is not canonical')
 }
 
 async function simulateTempoTransaction(client: Client, request: unknown) {
@@ -796,7 +878,7 @@ export type BroadcastOpenTransactionParameters = {
 export async function broadcastOpenTransaction(
   parameters: BroadcastOpenTransactionParameters,
 ): Promise<BroadcastOpenTransactionResult> {
-  const { transaction, call } = parsePrecompileCredentialTransaction({
+  const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
     label: 'open',
@@ -812,6 +894,12 @@ export async function broadcastOpenTransaction(
       authorizedSigner: parameters.expectedAuthorizedSigner,
     },
   })
+  validateAutoSwapPrefix({
+    amountOut: open.deposit,
+    currency: parameters.expectedCurrency,
+    label: 'open',
+    prefixCalls,
+  })
   const descriptor = ChannelOps.descriptorFromOpen({
     chainId: parameters.chainId,
     escrow: parameters.escrowContract,
@@ -920,7 +1008,7 @@ export type BroadcastTopUpTransactionParameters = {
 export async function broadcastTopUpTransaction(
   parameters: BroadcastTopUpTransactionParameters,
 ): Promise<BroadcastTopUpTransactionResult> {
-  const { transaction, call } = parsePrecompileCredentialTransaction({
+  const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
     label: 'topUp',
@@ -933,6 +1021,12 @@ export async function broadcastTopUpTransaction(
       additionalDeposit: parameters.additionalDeposit,
     },
   })
+  validateAutoSwapPrefix({
+    amountOut: parameters.additionalDeposit,
+    currency: parameters.expectedCurrency,
+    label: 'topUp',
+    prefixCalls,
+  })
   const receipt = await sendCredentialTransaction({
     challengeExpires: parameters.challengeExpires,
     chainId: parameters.chainId,
@@ -1001,8 +1095,11 @@ async function sendPrecompileTransaction(
   label: string,
   options?: ChannelTransactionOptions,
 ): Promise<Hex> {
-  if (options?.feePayer) {
-    const account = options.account ?? client.account
+  const account = options?.account ?? client.account
+  const selfSponsored =
+    account && options?.feePayer && isAddressEqual(account.address, options.feePayer.address)
+
+  if (options?.feePayer && !selfSponsored) {
     if (!account) throw new Error(`Cannot ${label} precompile channel: no account available.`)
     const feeToken =
       options.feeToken ??
@@ -1033,10 +1130,20 @@ async function sendPrecompileTransaction(
     return receipt.transactionHash
   }
 
+  const feeToken =
+    options?.feeToken ??
+    (selfSponsored
+      ? await resolveFeeToken({
+          account: account.address,
+          candidateTokens: options?.candidateFeeTokens,
+          client,
+        })
+      : undefined)
+
   return sendPrecompileContractCall(client, {
-    account: options?.account,
+    account,
     to,
     data,
-    feeToken: options?.feeToken,
+    feeToken,
   })
 }

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

@@ -27,6 +27,15 @@ const transaction = {
 } as const satisfies Channel.ExpiringNonceTransaction
 
 describe('precompile Channel.computeId', () => {
+  test('uses the payer when the descriptor delegates to the zero address', () => {
+    expect(
+      Channel.resolveAuthorizedSigner({
+        ...descriptor,
+        authorizedSigner: '0x0000000000000000000000000000000000000000',
+      }),
+    ).toBe(descriptor.payer)
+  })
+
   test('returns deterministic 32-byte hash for fixed inputs', () => {
     const id = Channel.computeId({ ...descriptor, chainId })
     expect(Channel.computeId({ ...descriptor, chainId })).toBe(id)

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

@@ -9,6 +9,11 @@ import type { ChannelDescriptor } from './Protocol.js'
 /** Re-export of the TIP-1034 channel descriptor shape. */
 export type { ChannelDescriptor } from './Protocol.js'
 
+/** Resolves the descriptor's effective voucher signer; zero delegates to the payer. */
+export function resolveAuthorizedSigner(descriptor: ChannelDescriptor): Address {
+  return BigInt(descriptor.authorizedSigner) === 0n ? descriptor.payer : descriptor.authorizedSigner
+}
+
 /** Tempo transaction shape used to derive the TIP-1034 `expiringNonceHash`. */
 export type ExpiringNonceTransaction = (
   | z_TransactionSerializableTempo

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

@@ -30,7 +30,7 @@ import {
 import * as Voucher from '../precompile/Voucher.js'
 import * as ChannelStore from './ChannelStore.js'
 import { getChallengePaymentFields } from './RequestState.js'
-import { assertSettlementSender, getClientAccount } from './Settlement.js'
+import { assertSettlementSender, getClientAccount, type OnSessionSettlement } from './Settlement.js'
 
 /** Returns the effective voucher signer for a TIP-1034 descriptor. */
 export function authorizedSigner(descriptor: Channel.ChannelDescriptor): Address {
@@ -344,6 +344,8 @@ export type VerifyCredentialPayloadParameters = {
   lastOnChainVerified: Map<Hex, number>
   /** Minimum allowed voucher delta in raw units. */
   minVoucherDelta: bigint
+  /** Callback invoked after an on-chain settlement or close transaction is confirmed. */
+  onSessionSettlement?: OnSessionSettlement | undefined
   /** Discriminated session credential payload to verify. */
   payload: SessionCredentialPayload
   /** Server-side channel store. */
@@ -747,6 +749,21 @@ async function handleCloseCredential(
       signature: payload.signature,
     }),
   )
+  if (parameters.onSessionSettlement && txHash) {
+    try {
+      await parameters.onSessionSettlement(
+        Object.freeze({
+          txHash,
+          channelId,
+          trigger: 'close' as const,
+          amount: settledToPayee,
+          delta: settledToPayee - state.settled,
+        }),
+      )
+    } catch {
+      // Errors are isolated — observers cannot break the settlement flow.
+    }
+  }
   return createSessionReceipt({
     challengeId: challenge.id,
     channelId,

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

@@ -12,8 +12,14 @@ export type SessionController = {
    * The reservation blocks until sufficient voucher headroom exists, but the
    * charge is only committed once a chunk is actually emitted. If the stream
    * ends or aborts before that emission, the reservation is dropped.
+   *
+   * Pass an explicit raw-unit `amount` for request-aware or otherwise dynamic
+   * pricing. When omitted, the session challenge's configured tick cost is
+   * used.
    */
-  charge(): Promise<void>
+  charge(amount?: bigint): Promise<void>
+  /** Aborted when the client closes or requests the final session receipt. */
+  signal: AbortSignal
 }
 
 /** Async stream source accepted by paid session transports. */
@@ -49,7 +55,7 @@ export async function* meterIterable(options: MeteredStreamOptions): AsyncGenera
   let reservedAmount = 0n
   let reservedUnits = 0
 
-  const charge = async () => {
+  const charge = async (amount = options.tickCost) => {
     if (prepaidUnits > 0) {
       prepaidUnits -= 1
       return
@@ -58,19 +64,20 @@ export async function* meterIterable(options: MeteredStreamOptions): AsyncGenera
     await reserveChargeOrWait({
       store: options.store,
       channelId: options.channelId,
-      amount: options.tickCost,
+      amount,
       reservedAmount,
       emit: options.emitNeedVoucher,
       formatNeedVoucher: options.formatNeedVoucher,
       pollIntervalMs: options.pollIntervalMs,
       signal: options.signal,
     })
-    reservedAmount += options.tickCost
+    reservedAmount += amount
     reservedUnits += 1
   }
 
+  const signal = options.signal ?? new AbortController().signal
   const iterable =
-    typeof options.generate === 'function' ? options.generate({ charge }) : options.generate
+    typeof options.generate === 'function' ? options.generate({ charge, signal }) : options.generate
 
   for await (const value of iterable) {
     if (options.signal?.aborted) break