mppx 0.13.2 → 0.13.4

package/dist/tempo/session/client/Transports.js

@@ -679,11 +679,12 @@ export async function probeWebSocketSession(parameters) {
 }
 /** Probes a WebSocket endpoint over HTTP and creates the opening credential. */
 export async function prepareWebSocketSession(parameters) {
+    parameters.signal?.throwIfAborted();
     const probed = await probeWebSocketSession(parameters);
-    return {
-        ...probed,
-        credential: await parameters.createSessionCredential(probed.challenge, {}),
-    };
+    parameters.signal?.throwIfAborted();
+    const credential = await parameters.createSessionCredential(probed.challenge, {});
+    parameters.signal?.throwIfAborted();
+    return { ...probed, credential };
 }
 /** Creates the initial runtime state for a paid WebSocket from its opening credential. */
 export function createActiveSocketSession(parameters) {
@@ -741,6 +742,8 @@ export function validateSocketPaymentReceipt(parameters) {
  */
 export async function openWebSocketSession(parameters) {
     const { challenge, credential, options, WebSocket: WebSocketImpl, wsUrl } = parameters;
+    const signal = options?.signal;
+    signal?.throwIfAborted();
     const rawSocket = new WebSocketImpl(wsUrl, options?.protocols);
     const socketState = createActiveSocketSession({
         challenge,
@@ -757,7 +760,13 @@ export async function openWebSocketSession(parameters) {
             rawSocket.close(ClientWebSocketProtocolErrorCloseCode, message);
         }
     };
+    const onAbort = () => {
+        parameters.rejectReceipt(new Error('WebSocket payment flow aborted.'));
+        parameters.rejectCloseReady(new Error('WebSocket payment flow aborted.'));
+        rawSocket.close();
+    };
     rawSocket.addEventListener('close', (event) => {
+        signal?.removeEventListener('abort', onAbort);
         socketState.socket = null;
         socketState.expectedCloseAmount = null;
         parameters.rejectReceipt(new Error('WebSocket closed before the payment flow completed.'));
@@ -785,29 +794,47 @@ export async function openWebSocketSession(parameters) {
             socketState,
         });
     });
-    options?.signal?.addEventListener('abort', () => {
-        parameters.rejectReceipt(new Error('WebSocket payment flow aborted.'));
-        parameters.rejectCloseReady(new Error('WebSocket payment flow aborted.'));
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        await waitForSocketOpen(rawSocket, managedSocket.emit, wsUrl, signal);
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        signal?.removeEventListener('abort', onAbort);
         rawSocket.close();
-    }, { once: true });
-    await waitForSocketOpen(rawSocket, managedSocket.emit, wsUrl);
+        throw error;
+    }
     rawSocket.send(Ws.formatAuthorizationMessage(credential));
     await parameters.waitForReceipt();
     return managedSocket.socket;
 }
-function waitForSocketOpen(rawSocket, managedEmit, wsUrl) {
+function waitForSocketOpen(rawSocket, managedEmit, wsUrl, signal) {
     return new Promise((resolve, reject) => {
-        const onOpen = () => {
+        const cleanup = () => {
+            rawSocket.removeEventListener('open', onOpen);
             rawSocket.removeEventListener('error', onError);
+            rawSocket.removeEventListener('close', onError);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const onOpen = () => {
+            cleanup();
             managedEmit('open', { type: 'open' });
             resolve();
         };
         const onError = () => {
-            rawSocket.removeEventListener('open', onOpen);
+            cleanup();
             reject(new Error(`WebSocket connection to ${wsUrl} failed to open.`));
         };
+        const onAbort = () => {
+            cleanup();
+            reject(signal?.reason);
+        };
         rawSocket.addEventListener('open', onOpen, { once: true });
         rawSocket.addEventListener('error', onError, { once: true });
+        rawSocket.addEventListener('close', onError, { once: true });
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
     });
 }
 async function handleSocketMessage(parameters) {

package/dist/tempo/session/precompile/Chain.d.ts

@@ -71,6 +71,8 @@ export type TopUpReceiptFields = {
 };
 /** Typed fields decoded from a Settled receipt event. */
 export type SettledReceiptFields = {
+    /** Amount this settlement paid to the payee. */
+    deltaPaid: bigint;
     /** New cumulative amount settled on-chain. */
     newSettled: bigint;
 };
@@ -183,6 +185,8 @@ export type ChannelTransactionOptions = {
     feePayerPolicy?: Partial<FeePayer.Policy> | undefined;
     /** Explicit fee token for the transaction. */
     feeToken?: Address | undefined;
+    /** Unix time in seconds after which the expiring-nonce transaction cannot be included. */
+    validBefore?: number | undefined;
 };
 /** Simulates an unsponsored client-signed session transaction without broadcasting it. */
 export declare function simulateCredentialTransaction(parameters: {

package/dist/tempo/session/precompile/Chain.js

@@ -39,6 +39,7 @@ export function readTopUpReceiptFields(event) {
 /** Reads and validates typed fields from a Settled receipt event. */
 export function readSettledReceiptFields(event) {
     return {
+        deltaPaid: readUint96(event.args.deltaPaid, 'Settled deltaPaid'),
         newSettled: readUint96(event.args.newSettled, 'Settled newSettled'),
     };
 }
@@ -326,7 +327,7 @@ async function signTempoTransaction(client, transaction) {
     return (await signTransaction(client, transaction));
 }
 async function prepareFeePayerCallTransaction(client, parameters) {
-    const { account, data, feeToken, to } = parameters;
+    const { account, data, feeToken, to, validBefore } = parameters;
     // viem's stable request type does not expose Tempo fee-payer transaction
     // fields for this call shape. Keep the cast at the boundary.
     return prepareTransactionRequest(client, {
@@ -335,10 +336,11 @@ async function prepareFeePayerCallTransaction(client, parameters) {
         feePayer: true,
         nonceKey: 'expiring',
         ...(feeToken ? { feeToken } : {}),
+        ...(validBefore ? { validBefore } : {}),
     });
 }
 function sendPrecompileContractCall(client, parameters) {
-    const { account, data, feePayer, feeToken, to } = parameters;
+    const { account, data, feePayer, feeToken, to, validBefore } = parameters;
     // `feeToken` is Tempo-specific and not represented on viem's base
     // transaction request type.
     return sendViemTransaction(client, {
@@ -349,6 +351,7 @@ function sendPrecompileContractCall(client, parameters) {
         nonceKey: 'expiring',
         ...(feePayer ? { feePayer } : {}),
         ...(feeToken ? { feeToken } : {}),
+        ...(validBefore ? { validBefore } : {}),
     });
 }
 /**
@@ -674,6 +677,7 @@ async function sendPrecompileTransaction(client, to, data, label, options) {
             feePayer: true,
             feeToken: options.feeToken,
             to,
+            validBefore: options.validBefore,
         });
     }
     if (feePayer && !selfSponsored) {
@@ -690,6 +694,7 @@ async function sendPrecompileTransaction(client, to, data, label, options) {
             data,
             feeToken,
             to,
+            validBefore: options.validBefore,
         });
         assertPrecompileFeePayerPolicy({ prepared, policy: options.feePayerPolicy });
         const serialized = await signTempoTransaction(client, {
@@ -719,6 +724,7 @@ async function sendPrecompileTransaction(client, to, data, label, options) {
         to,
         data,
         feeToken,
+        validBefore: options?.validBefore,
     });
 }
 //# sourceMappingURL=Chain.js.map

package/dist/tempo/session/server/ChannelStore.d.ts

@@ -300,6 +300,14 @@ export declare function acceptVoucherStateUpdate(parameters: AcceptVoucherStateU
  * close voucher and current on-chain deposit.
  */
 export declare function resolveCloseCaptureAmount(parameters: ResolveCloseCaptureAmountParameters): bigint;
+/** Seconds a server close transaction stays valid after its pending-close marker is written. */
+export declare const pendingCloseValiditySeconds = 25;
+/** Clears a server pending-close marker whose close transaction expired without closing the channel. */
+export declare function reconcileExpiredPendingClose(parameters: {
+    current: State | null;
+    now: number;
+    state: OnChainChannelState;
+}): State | null;
 /** Marks local channel state as pending close and returns the bounded capture amount. */
 export declare function markPendingClose(parameters: MarkPendingCloseParameters): PendingCloseUpdate;
 /** Finalizes local channel state after a successful close transaction. */

package/dist/tempo/session/server/ChannelStore.js

@@ -142,6 +142,23 @@ export function resolveCloseCaptureAmount(parameters) {
     }
     return captureAmount;
 }
+/** Seconds a server close transaction stays valid after its pending-close marker is written. */
+export const pendingCloseValiditySeconds = 25;
+/** Extra seconds allowed for clock differences between the server and the chain. */
+const pendingCloseClockSkewSeconds = 30;
+/** Clears a server pending-close marker whose close transaction expired without closing the channel. */
+export function reconcileExpiredPendingClose(parameters) {
+    const { current, now, state } = parameters;
+    if (!current || current.finalized || current.closeRequestedAt === 0n)
+        return current;
+    // An open channel with no on-chain close request proves the expired close never executed.
+    if (BigInt(state.closeRequestedAt) !== 0n || state.deposit === 0n)
+        return current;
+    const expiresAt = current.closeRequestedAt + BigInt(pendingCloseValiditySeconds);
+    if (BigInt(now) <= expiresAt + BigInt(pendingCloseClockSkewSeconds))
+        return current;
+    return { ...current, closeRequestedAt: 0n };
+}
 /** Marks local channel state as pending close and returns the bounded capture amount. */
 export function markPendingClose(parameters) {
     const { closeRequestedAt, cumulativeAmount, current, onChainSettled, onChainDeposit } = parameters;

package/dist/tempo/session/server/CredentialVerification.d.ts

@@ -5,7 +5,7 @@ import * as Chain from '../precompile/Chain.js';
 import * as Channel from '../precompile/Channel.js';
 import { type SessionCredentialPayload, type SessionReceipt } from '../precompile/Protocol.js';
 import * as ChannelStore from './ChannelStore.js';
-import { type OnSessionSettlement } from './Settlement.js';
+import { type OnSessionSettlement, type OnSessionSettlementFailure } from './Settlement.js';
 /** Returns the effective voucher signer for a TIP-1034 descriptor. */
 export declare function authorizedSigner(descriptor: Channel.ChannelDescriptor): Address;
 /** Asserts that a credential payload includes a TIP-1034 descriptor. */
@@ -77,6 +77,8 @@ export type BroadcastCredentialPayloadParameters = {
     minVoucherDelta: bigint;
     /** Callback invoked after an on-chain settlement or close transaction is confirmed. */
     onSessionSettlement?: OnSessionSettlement | undefined;
+    /** Callback invoked when a scheduled settlement or close transaction fails. */
+    onSessionSettlementFailure?: OnSessionSettlementFailure | undefined;
     /** Discriminated session credential payload to verify. */
     payload: SessionCredentialPayload;
     /** Whether an open or voucher credential must add new funds for this request. */

package/dist/tempo/session/server/CredentialVerification.js

@@ -1,4 +1,4 @@
-import { isAddress, isAddressEqual, zeroAddress, } from 'viem';
+import { createClient, custom, isAddress, isAddressEqual, zeroAddress, } from 'viem';
 import { AmountExceedsDepositError, ChannelClosedError, ChannelNotFoundError, DeltaTooSmallError, InsufficientBalanceError, InvalidSignatureError, VerificationFailedError, } from '../../../Errors.js';
 import * as Chain from '../precompile/Chain.js';
 import { readChannelClosedReceiptFields } from '../precompile/Chain.js';
@@ -7,7 +7,7 @@ import { createSessionReceipt, uint96, } from '../precompile/Protocol.js';
 import * as Voucher from '../precompile/Voucher.js';
 import * as ChannelStore from './ChannelStore.js';
 import { getChallengePaymentFields } from './RequestState.js';
-import { assertSettlementSender, getClientAccount, maybeSettleScheduled, } from './Settlement.js';
+import { assertSettlementSender, getClientAccount, maybeSettleScheduled, reportSessionSettlementFailure, } from './Settlement.js';
 /** Returns the effective voucher signer for a TIP-1034 descriptor. */
 export function authorizedSigner(descriptor) {
     return isAddressEqual(descriptor.authorizedSigner, zeroAddress)
@@ -622,6 +622,13 @@ async function handleVoucherCredential(parameters) {
         forceRefresh: true,
         lastOnChainVerified,
     });
+    const reconciled = channel.closeRequestedAt === 0n
+        ? channel
+        : ((await store.updateChannel(channelId, (current) => ChannelStore.reconcileExpiredPendingClose({
+            current,
+            now: Math.floor(Date.now() / 1000),
+            state: channelState,
+        }))) ?? channel);
     if (channelState.closeRequestedAt !== 0) {
         const closing = await store.updateChannel(channelId, (current) => current
             ? {
@@ -643,6 +650,7 @@ async function handleVoucherCredential(parameters) {
                 feePayerPolicy: parameters.feePayerPolicy,
                 feeToken: parameters.feeToken,
                 onSessionSettlement: parameters.onSessionSettlement,
+                onSessionSettlementFailure: parameters.onSessionSettlementFailure,
                 schedule: {},
                 store,
             });
@@ -653,12 +661,36 @@ async function handleVoucherCredential(parameters) {
         minVoucherDelta,
         requireAdvance: parameters.requireVoucherAdvance,
         challenge,
-        channel,
+        channel: reconciled,
         voucher,
         channelState,
         methodDetails: { chainId, escrowContract: escrow },
     });
 }
+const sendMethods = new Set([
+    'eth_sendRawTransaction',
+    'eth_sendRawTransactionSync',
+    'eth_sendTransaction',
+]);
+/** Wraps a client so a failed close can tell whether its transaction was handed to the node. */
+function trackSendAttempts(client) {
+    const tracked = { attempted: false };
+    const trackedClient = createClient({
+        account: client.account,
+        chain: client.chain,
+        pollingInterval: client.pollingInterval,
+        transport: custom({
+            request(parameters) {
+                if (sendMethods.has(parameters.method))
+                    tracked.attempted = true;
+                return client.request(parameters);
+            },
+        }, 
+        // The wrapped client already owns retries.
+        { retryCount: 0 }),
+    });
+    return { client: trackedClient, tracked };
+}
 async function handleCloseCredential(parameters) {
     const { store, client, challenge, payload, chainId, escrow } = parameters;
     const request = getChallengePaymentFields(challenge);
@@ -698,14 +730,14 @@ async function handleCloseCredential(parameters) {
     let captureAmount = uint96(channel.spent > state.settled ? channel.spent : state.settled);
     if (captureAmount > state.deposit)
         throw new AmountExceedsDepositError({ reason: 'close capture amount exceeds on-chain deposit' });
-    const pendingCloseStartedAt = BigInt(Math.floor(Date.now() / 1000) || 1);
-    const previousCloseRequestedAt = channel.closeRequestedAt;
+    const now = Math.floor(Date.now() / 1000) || 1;
+    const pendingCloseStartedAt = BigInt(now);
     let pendingCloseMarked = false;
     await store.updateChannel(channelId, (current) => {
         const next = ChannelStore.markPendingClose({
             closeRequestedAt: pendingCloseStartedAt,
             cumulativeAmount,
-            current,
+            current: ChannelStore.reconcileExpiredPendingClose({ current, now, state }),
             onChainDeposit: state.deposit,
             onChainSettled: state.settled,
         });
@@ -716,8 +748,11 @@ async function handleCloseCredential(parameters) {
         return next.state;
     });
     const account = parameters.account ?? getClientAccount(client);
-    let txHash;
+    // Pin the close transaction's expiry to the marker so an expired marker proves it can no longer land.
+    const validBefore = now + ChannelStore.pendingCloseValiditySeconds;
+    const send = trackSendAttempts(client);
     let receipt;
+    let txHash;
     try {
         assertSettlementSender({
             operation: 'close',
@@ -726,21 +761,31 @@ async function handleCloseCredential(parameters) {
             payee: channel.payee,
             sender: account?.address,
         });
-        txHash = await Chain.closeOnChain(client, channel.descriptor, cumulativeAmount, captureAmount, payload.signature, escrow, account
+        txHash = await Chain.closeOnChain(send.client, channel.descriptor, cumulativeAmount, captureAmount, payload.signature, escrow, account
             ? {
                 account,
                 ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
                 ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
                 ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
                 candidateFeeTokens: [channel.token],
+                validBefore,
             }
-            : undefined);
+            : { validBefore });
         receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
     }
     catch (error) {
-        if (pendingCloseMarked) {
+        await reportSessionSettlementFailure(parameters.onSessionSettlementFailure, {
+            chainId,
+            channelId,
+            error,
+            trigger: 'close',
+        });
+        // A close whose send RPC was attempted may still land, so it keeps the marker until it expires and
+        // a later credential reconciles it. Verification errors prove a rejection or revert.
+        const closeFailed = !send.tracked.attempted || error instanceof VerificationFailedError;
+        if (pendingCloseMarked && closeFailed) {
             await store.updateChannel(channelId, (current) => current && current.closeRequestedAt === pendingCloseStartedAt
-                ? { ...current, closeRequestedAt: previousCloseRequestedAt }
+                ? { ...current, closeRequestedAt: 0n }
                 : current);
         }
         throw error;

package/dist/tempo/session/server/Session.d.ts

@@ -19,12 +19,12 @@ import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as
 import * as ChannelStore from './ChannelStore.js';
 import { type ResolveSessionChannelId } from './RequestState.js';
 import { type SettleChargedSessionChannel } from './Settlement.js';
-import { type OnSessionSettlement, type SettlementSchedule } from './Settlement.js';
+import { type OnSessionSettlement, type OnSessionSettlementFailure, type SettlementSchedule } from './Settlement.js';
 import * as Ws from './Ws.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';
+export type { OnSessionSettlement, OnSessionSettlementFailure, SessionSettlementContext, SessionSettlementFailureContext, } from './Settlement.js';
 /** Server-side hook types for request-identity channel bootstrap. */
 export type { ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, } from './RequestState.js';
 export { settle, settleBatch } from './Settlement.js';
@@ -175,6 +175,8 @@ export declare namespace session {
         escrowContract?: Address | undefined;
         /** Callback invoked after any on-chain settlement or close transaction is confirmed. */
         onSessionSettlement?: OnSessionSettlement | undefined;
+        /** Callback invoked when a scheduled settlement or close transaction fails. Observer errors are ignored. */
+        onSessionSettlementFailure?: OnSessionSettlementFailure | undefined;
         /** Server-owned automatic settlement cadence. Clients do not receive or control this schedule. */
         settlementSchedule?: SettlementSchedule | undefined;
         /** Optional fee token for management and server-driven settle/close transactions. */

package/dist/tempo/session/server/Session.js

@@ -12,6 +12,7 @@ import * as Constants from '../../../Constants.js';
 import * as Errors from '../../../Errors.js';
 import * as Expires from '../../../Expires.js';
 import * as Method from '../../../Method.js';
+import * as ChallengeMeta from '../../../server/internal/challengeMeta.js';
 import * as Store from '../../../Store.js';
 import * as Client from '../../../viem/Client.js';
 import * as Account from '../../internal/account.js';
@@ -27,7 +28,7 @@ import { requireSessionCredentialPayload } from './CredentialVerification.js';
 import { resolveCredentialVerificationContext, resolveSessionChannelId, resolveSessionSnapshot, resolveSessionPaymentRequest, } from './RequestState.js';
 import { respondToSessionCredential } from './RequestState.js';
 import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, } from './Settlement.js';
-import { isSettlementDue, maybeSettleScheduled } from './Settlement.js';
+import { ignoreRetryableSettlementFailure, isSettlementDue, maybeSettleScheduled, reportSessionSettlementFailure, } from './Settlement.js';
 import { resolveSettlementSchedule, } from './Settlement.js';
 import * as Ws from './Ws.js';
 export { settle, settleBatch } from './Settlement.js';
@@ -58,6 +59,7 @@ function isBootstrapChargeCredential(credential) {
 function createBootstrapChallenge(parameters) {
     return Challenge.fromMethod(Methods.charge, {
         expires: parameters.expires,
+        meta: ChallengeMeta.withNonce(undefined),
         realm: parameters.realm,
         request: parameters.request,
         secretKey: parameters.secretKey,
@@ -196,6 +198,7 @@ export function session(p) {
     const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = Store.memory(), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
     const onSessionSettlement = parameters.onSessionSettlement;
+    const onSessionSettlementFailure = parameters.onSessionSettlementFailure;
     const store = ChannelStore.fromStore(rawStore);
     const lastOnChainVerified = new Map();
     const { account, feePayer, remoteFeePayer, recipient } = Account.resolve(parameters);
@@ -209,21 +212,34 @@ export function session(p) {
     const settleScheduled = async (channel) => {
         if (!isSettlementDue(channel, settlementSchedule))
             return undefined;
+        const client = await (async () => getClient({ chainId: channel.chainId }))().catch(async (error) => {
+            await reportSessionSettlementFailure(onSessionSettlementFailure, {
+                chainId: channel.chainId,
+                channelId: channel.channelId,
+                error,
+                trigger: 'scheduled',
+            });
+            throw error;
+        });
         return maybeSettleScheduled({
             account,
             channel,
-            client: await getClient({ chainId: channel.chainId }),
+            client,
             ...(configuredFeePayer ? { feePayer: configuredFeePayer } : {}),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: parameters.feeToken,
             onSessionSettlement,
+            onSessionSettlementFailure,
             schedule: settlementSchedule,
             store,
         });
     };
+    // A failed scheduled settlement is reported and retried by the next one; the charged request
+    // stays served because the payer's voucher already covers the charge.
+    const settleCharged = (channel) => settleScheduled(channel).catch(ignoreRetryableSettlementFailure);
     const serveWebSocket = (options) => Ws.serve({
         ...options,
-        onChargeCommitted: settleScheduled,
+        onChargeCommitted: settleCharged,
         store,
     });
     const bootstrapCharge = ChargeServer.charge({
@@ -238,7 +254,7 @@ export function session(p) {
     });
     const transport = parameters.sse
         ? Transport.sse({
-            settleCharged: settleScheduled,
+            settleCharged,
             store,
             ...(typeof parameters.sse === 'object' ? parameters.sse : undefined),
         })
@@ -305,6 +321,7 @@ export function session(p) {
             lastOnChainVerified,
             minVoucherDelta: context.minVoucherDelta,
             onSessionSettlement,
+            onSessionSettlementFailure,
             payload,
             requireVoucherAdvance: shouldApplyVerifiedHttpAccounting({
                 capturedRequest: envelope?.capturedRequest,
@@ -328,10 +345,11 @@ export function session(p) {
                 feePayerPolicy: parameters.feePayerPolicy,
                 feeToken: parameters.feeToken,
                 onSessionSettlement,
+                onSessionSettlementFailure,
                 schedule: settlementSchedule,
                 store,
                 channel,
-            }),
+            }).catch(ignoreRetryableSettlementFailure),
         });
     };
     const method = Method.toServer(Methods.session, {

package/dist/tempo/session/server/Settlement.d.ts

@@ -86,6 +86,19 @@ export type SessionSettlementContext = Readonly<{
 }>;
 /** Callback invoked after an on-chain settlement or close transaction is confirmed. */
 export type OnSessionSettlement = (context: SessionSettlementContext) => MaybePromise<void>;
+/** Context emitted when a scheduled settlement or close transaction fails. */
+export type SessionSettlementFailureContext = Readonly<{
+    /** Chain ID of the channel. */
+    chainId: number;
+    /** Channel ID whose settlement or close failed. */
+    channelId: Hex;
+    /** Error thrown by the settlement or close. */
+    error: unknown;
+    /** `close` for a failed close transaction; `scheduled` for a failed scheduled settlement. */
+    trigger: 'close' | 'scheduled';
+}>;
+/** Callback invoked when a scheduled settlement or close transaction fails. */
+export type OnSessionSettlementFailure = (context: SessionSettlementFailureContext) => MaybePromise<void>;
 /** Inputs used to mark a channel after automatic scheduled settlement succeeds. */
 export type MarkSettlementCompleteParameters = {
     channelId: ChannelStore.State['channelId'];
@@ -105,7 +118,7 @@ export declare function resolveSettlementSchedule(schedule: SettlementSchedule |
 export declare function resolveSettlementProgress(channel: ChannelStore.State): SettlementProgress | undefined;
 /** Returns whether the precompile channel has crossed any configured settlement threshold. */
 export declare function isSettlementDue(channel: ChannelStore.State, schedule: ResolvedSettlementSchedule | undefined): boolean;
-/** Records the channel spend/unit counters that a scheduled settlement captured. */
+/** Releases a completed scheduled settlement lease; {@link settle} records the settled counters. */
 export declare function markSettlementComplete(parameters: MarkSettlementCompleteParameters): Promise<void>;
 /** Atomically claims one due scheduled settlement across server workers. */
 export declare function claimScheduledSettlement(parameters: {
@@ -208,6 +221,8 @@ export type MaybeSettleScheduledParameters = {
     feeToken?: Address | undefined;
     /** Callback invoked after the scheduled settlement transaction is confirmed. */
     onSessionSettlement?: OnSessionSettlement | undefined;
+    /** Callback invoked when the scheduled settlement fails. */
+    onSessionSettlementFailure?: OnSessionSettlementFailure | undefined;
     /** Resolved server-owned settlement cadence. */
     schedule: ResolvedSettlementSchedule | undefined;
     /** Server-side channel store. */
@@ -225,6 +240,30 @@ export declare function assertSettlementSender(parameters: SettlementSenderParam
 export declare function maybeSettleScheduled(parameters: MaybeSettleScheduledParameters): Promise<Hex | undefined>;
 /** Settles the highest accepted voucher for a precompile-backed session channel. */
 export declare function settle(store_: SessionStoreInput, client: Chain.TransactionClient, channelId_: Hex, options?: SettlementTransactionOptions): Promise<Hex>;
+/** Raised when a settlement transaction confirmed but the channel store could not record it. */
+export declare class SettlementCheckpointError extends Error {
+    readonly name = "SettlementCheckpointError";
+    /** Hash of the confirmed settlement transaction. */
+    readonly txHash: Hex;
+    constructor(options: {
+        cause: unknown;
+        txHash: Hex;
+    });
+}
+/** Raised when a scheduled settlement could not claim its lease; no transaction was submitted. */
+export declare class SettlementLeaseError extends Error {
+    readonly name = "SettlementLeaseError";
+    constructor(options: {
+        cause: unknown;
+    });
+}
 /** Settles multiple precompile-backed session channels with the same validation as {@link settle}. */
 export declare function settleBatch(store: SessionStoreInput, client: Chain.TransactionClient, channelIds: readonly Hex[], options?: SettlementTransactionOptions): Promise<Hex[]>;
+/**
+ * @internal Keeps a charged request served when its scheduled settlement hit a transport or RPC
+ * failure; the next settlement retries it. Reverts and configuration errors fail the request.
+ */
+export declare function ignoreRetryableSettlementFailure(error: unknown): undefined;
+/** @internal Reports a settlement failure without letting observer errors replace it. */
+export declare function reportSessionSettlementFailure(onSessionSettlementFailure: OnSessionSettlementFailure | undefined, context: SessionSettlementFailureContext): Promise<void>;
 //# sourceMappingURL=Settlement.d.ts.map