mppx 0.8.11 → 0.8.13

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

@@ -556,8 +556,21 @@ describe('precompile server session unit guardrails', () => {
   test('request returns a server session snapshot for a known precompile channel', async () => {
     const { method, store } = createServer()
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 200n,
       units: 2,
     })
@@ -585,6 +598,11 @@ describe('precompile server session unit guardrails', () => {
       deposit: '1000',
       descriptor: openPayload.descriptor,
       escrow: tip20ChannelEscrow,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: '250',
+        signature: highestVoucher.signature,
+      },
       requiredCumulative: '201',
       settled: '0',
       spent: '200',
@@ -594,6 +612,14 @@ describe('precompile server session unit guardrails', () => {
 
   test('request can resolve a server session snapshot from request identity', async () => {
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     const { method, store } = createServer({
       resolveChannelId({ request, credential, paymentRequest, store: hookStore }) {
         expect(request?.headers.get('cookie')).toBe('sid=session-1')
@@ -605,6 +631,11 @@ describe('precompile server session unit guardrails', () => {
     })
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 200n,
       units: 2,
     })
@@ -661,8 +692,21 @@ describe('precompile server session unit guardrails', () => {
   test('request uses zero effective amount for non-content snapshot hints', async () => {
     const { method, store } = createServer()
     const openPayload = await createOpenPayload({ initialAmount: 100n })
+    const highestVoucher = await ClientOps.createVoucherPayload(
+      createSigningClient(),
+      payer,
+      openPayload.descriptor,
+      Types.uint96(250n),
+      chainId,
+    )
+    if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
     await persistPrecompileChannel(store, openPayload, {
       highestVoucherAmount: 250n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 250n,
+        signature: highestVoucher.signature,
+      },
       spent: 250n,
       units: 2,
     })
@@ -2032,8 +2076,21 @@ describe('precompile server session unit guardrails', () => {
       const rawStore = Store.memory()
       const store = channelStore(rawStore)
       const openPayload = await createOpenPayload({ initialAmount: 1n })
+      const highestVoucher = await ClientOps.createVoucherPayload(
+        createSigningClient(),
+        payer,
+        openPayload.descriptor,
+        Types.uint96(5n),
+        chainId,
+      )
+      if (highestVoucher.action !== 'voucher') throw new Error('expected voucher payload')
       await persistPrecompileChannel(store, openPayload, {
         highestVoucherAmount: 5n,
+        highestVoucher: {
+          channelId: openPayload.channelId,
+          cumulativeAmount: 5n,
+          signature: highestVoucher.signature,
+        },
         spent: 3n,
         units: 3,
       })
@@ -2056,6 +2113,10 @@ describe('precompile server session unit guardrails', () => {
       expect(snapshot).toMatchObject({
         channelId: openPayload.channelId,
         acceptedCumulative: '5',
+        highestVoucher: {
+          channelId: openPayload.channelId,
+          cumulativeAmount: '5',
+        },
         requiredCumulative: '3',
         spent: '3',
       })
@@ -3337,3 +3398,403 @@ describe('precompile server session unit guardrails', () => {
     ).rejects.toThrow(/tx sender .* is not the channel payee/)
   })
 })
+
+describe('onSessionSettlement', () => {
+  function createSettleClient(channelId: Hex, settledAmount: bigint) {
+    return createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'cc'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'cc'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([settledLog(channelId, settledAmount)])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: settledAmount, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+  }
+
+  test('fires onSessionSettlement for explicit settle() calls', async () => {
+    const events: { trigger: string; txHash: string; amount: bigint; delta: bigint }[] = []
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 100n)
+    await settle(store, client, openPayload.channelId, {
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          txHash: ctx.txHash,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'settle',
+      txHash: `0x${'cc'.repeat(32)}`,
+      amount: 100n,
+      delta: 100n,
+    })
+  })
+
+  test('fires onSessionSettlement for auto-scheduled settlements', async () => {
+    const events: { trigger: string; channelId: string; amount: bigint; delta: bigint }[] = []
+    const rawStore = Store.memory()
+    const openPayload = await createOpenPayload()
+    const store = channelStore(rawStore)
+    await persistPrecompileChannel(store, openPayload, {
+      payee: payer.address,
+      spent: 500n,
+      units: 10,
+      highestVoucherAmount: 500n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 500n,
+        signature: '0x1234',
+      },
+    })
+
+    const { maybeSettleScheduled } = await import('./Settlement.js')
+    const client = createSettleClient(openPayload.channelId, 500n)
+    const channel = await store.getChannel(openPayload.channelId)
+
+    await maybeSettleScheduled({
+      account: payer,
+      channel: channel!,
+      client,
+      schedule: { units: 5 },
+      store,
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          channelId: ctx.channelId,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'scheduled',
+      channelId: openPayload.channelId,
+      amount: 500n,
+      delta: 500n,
+    })
+  })
+
+  test('delta reflects incremental scheduled settlement with prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const rawStore = Store.memory()
+    const openPayload = await createOpenPayload()
+    const store = channelStore(rawStore)
+    await persistPrecompileChannel(store, openPayload, {
+      payee: payer.address,
+      spent: 500n,
+      units: 10,
+      settledOnChain: 200n,
+      highestVoucherAmount: 500n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 500n,
+        signature: '0x1234',
+      },
+    })
+
+    const { maybeSettleScheduled } = await import('./Settlement.js')
+    const client = createSettleClient(openPayload.channelId, 500n)
+    const channel = await store.getChannel(openPayload.channelId)
+
+    await maybeSettleScheduled({
+      account: payer,
+      channel: channel!,
+      client,
+      schedule: { units: 5 },
+      store,
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'scheduled',
+      amount: 500n,
+      delta: 300n,
+    })
+  })
+
+  test('fires onSessionSettlement for cooperative close', async () => {
+    const events: { trigger: string; txHash: string; amount: bigint; delta: bigint }[] = []
+    const openPayload = await createOpenPayload()
+    const closedAmount = 100n
+    const refundedAmount = 900n
+    const rawStore = Store.memory()
+
+    const closeClient = createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([
+              closedLog(openPayload.channelId, closedAmount, refundedAmount),
+            ])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: 0n, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+
+    const method = session({
+      amount: '1',
+      chainId,
+      currency: token,
+      decimals: 0,
+      recipient: payee,
+      store: rawStore,
+      unitType: 'request',
+      getClient: () => closeClient,
+      onSessionSettlement: (ctx) => {
+        events.push({
+          trigger: ctx.trigger,
+          txHash: ctx.txHash,
+          amount: ctx.amount,
+          delta: ctx.delta,
+        })
+      },
+    })
+
+    await persistPrecompileChannel(channelStore(rawStore), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const closeSignature = await Voucher.signVoucher(
+      createSigningClient(),
+      payer,
+      { channelId: openPayload.channelId, cumulativeAmount: 100n },
+      tip20ChannelEscrow,
+      chainId,
+    )
+
+    await method.verify({
+      credential: {
+        challenge: makeChallenge(openPayload.channelId),
+        payload: {
+          action: 'close',
+          channelId: openPayload.channelId,
+          descriptor: openPayload.descriptor,
+          cumulativeAmount: '100',
+          signature: closeSignature,
+        },
+      },
+      request: verifyRequest(openPayload.channelId),
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'close',
+      txHash: `0x${'dd'.repeat(32)}`,
+      amount: closedAmount,
+      delta: closedAmount,
+    })
+  })
+
+  test('delta reflects incremental settlement when channel has prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 300n,
+      settledOnChain: 200n,
+      highestVoucherAmount: 300n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 300n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 300n)
+    await settle(store, client, openPayload.channelId, {
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'settle',
+      amount: 300n,
+      delta: 100n,
+    })
+  })
+
+  test('delta reflects incremental close when channel has prior on-chain settlement', async () => {
+    const events: { trigger: string; amount: bigint; delta: bigint }[] = []
+    const openPayload = await createOpenPayload()
+    const priorSettled = 50n
+    const closedAmount = 100n
+    const refundedAmount = 900n
+    const rawStore = Store.memory()
+
+    const closeClient = createClient({
+      account: payer,
+      chain: testChain,
+      transport: custom({
+        async request(args) {
+          if (args.method === 'eth_chainId') return `0x${chainId.toString(16)}`
+          if (args.method === 'eth_getTransactionCount') return '0x0'
+          if (args.method === 'eth_estimateGas') return '0x5208'
+          if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+          if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+          if (args.method === 'eth_sendRawTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_sendTransaction') return `0x${'dd'.repeat(32)}`
+          if (args.method === 'eth_getTransactionReceipt')
+            return transactionReceipt([
+              closedLog(openPayload.channelId, closedAmount, refundedAmount),
+            ])
+          if (args.method === 'eth_call') {
+            return encodeFunctionResult({
+              abi: escrowAbi,
+              functionName: 'getChannelState',
+              result: { settled: priorSettled, deposit: 1_000n, closeRequestedAt: 0 },
+            })
+          }
+          throw new Error(`unexpected rpc request: ${args.method}`)
+        },
+      }),
+    })
+
+    const method = session({
+      amount: '1',
+      chainId,
+      currency: token,
+      decimals: 0,
+      recipient: payee,
+      store: rawStore,
+      unitType: 'request',
+      getClient: () => closeClient,
+      onSessionSettlement: (ctx) => {
+        events.push({ trigger: ctx.trigger, amount: ctx.amount, delta: ctx.delta })
+      },
+    })
+
+    await persistPrecompileChannel(channelStore(rawStore), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      settledOnChain: priorSettled,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const closeSignature = await Voucher.signVoucher(
+      createSigningClient(),
+      payer,
+      { channelId: openPayload.channelId, cumulativeAmount: 100n },
+      tip20ChannelEscrow,
+      chainId,
+    )
+
+    await method.verify({
+      credential: {
+        challenge: makeChallenge(openPayload.channelId),
+        payload: {
+          action: 'close',
+          channelId: openPayload.channelId,
+          descriptor: openPayload.descriptor,
+          cumulativeAmount: '100',
+          signature: closeSignature,
+        },
+      },
+      request: verifyRequest(openPayload.channelId),
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({
+      trigger: 'close',
+      amount: closedAmount,
+      delta: closedAmount - priorSettled,
+    })
+  })
+
+  test('isolates errors in onSessionSettlement handler', async () => {
+    const store = Store.memory()
+    const openPayload = await createOpenPayload()
+    await persistPrecompileChannel(channelStore(store), openPayload, {
+      payee: payer.address,
+      spent: 100n,
+      highestVoucherAmount: 100n,
+      highestVoucher: {
+        channelId: openPayload.channelId,
+        cumulativeAmount: 100n,
+        signature: '0x1234',
+      },
+    })
+
+    const { settle } = await import('./Session.js')
+    const client = createSettleClient(openPayload.channelId, 100n)
+
+    await expect(
+      settle(store, client, openPayload.channelId, {
+        onSessionSettlement: () => {
+          throw new Error('observer exploded')
+        },
+      }),
+    ).resolves.toBe(`0x${'cc'.repeat(32)}`)
+  })
+})

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.
+  }
+}