Add hook to tempo sessions, triggered on each on-chain tx

.changeset/warm-pandas-climb.md

@@ -0,0 +1,5 @@
+---
+'mppx': minor
+---
+
+Added `onSessionSettlement` hook for visibility into on-chain session settlement transactions, with chain-agnostic context including trigger, txHash, channelId, cumulative amount, and incremental delta.

src/tempo/server/index.ts

@@ -4,5 +4,9 @@ export * as Ws from '../session/server/Ws.js'
 export { charge } from './Charge.js'
 export { sessionLegacy, settleLegacy, tempo } from './Methods.js'
 export { session, settle, settleBatch } from '../session/server/Session.js'
-export type { SettlementSchedule } from '../session/server/Session.js'
+export type {
+  OnSessionSettlement,
+  SessionSettlementContext,
+  SettlementSchedule,
+} from '../session/server/Session.js'
 export { renew as renewSubscription, subscription } from './Subscription.js'

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,