mppx 0.13.1 → 0.13.3

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

@@ -183,6 +183,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

@@ -326,7 +326,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 +335,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 +350,7 @@ function sendPrecompileContractCall(client, parameters) {
         nonceKey: 'expiring',
         ...(feePayer ? { feePayer } : {}),
         ...(feeToken ? { feeToken } : {}),
+        ...(validBefore ? { validBefore } : {}),
     });
 }
 /**
@@ -674,6 +676,7 @@ async function sendPrecompileTransaction(client, to, data, label, options) {
             feePayer: true,
             feeToken: options.feeToken,
             to,
+            validBefore: options.validBefore,
         });
     }
     if (feePayer && !selfSponsored) {
@@ -690,6 +693,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 +723,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

@@ -27,7 +27,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';
@@ -196,6 +196,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 +210,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 +252,7 @@ export function session(p) {
     });
     const transport = parameters.sse
         ? Transport.sse({
-            settleCharged: settleScheduled,
+            settleCharged,
             store,
             ...(typeof parameters.sse === 'object' ? parameters.sse : undefined),
         })
@@ -305,6 +319,7 @@ export function session(p) {
             lastOnChainVerified,
             minVoucherDelta: context.minVoucherDelta,
             onSessionSettlement,
+            onSessionSettlementFailure,
             payload,
             requireVoucherAdvance: shouldApplyVerifiedHttpAccounting({
                 capturedRequest: envelope?.capturedRequest,
@@ -328,10 +343,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,23 @@ 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;
+    });
+}
 /** 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

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

@@ -1,4 +1,4 @@
-import { isAddress, isAddressEqual, parseUnits, zeroAddress, } from 'viem';
+import { BaseError as viem_BaseError, HttpRequestError, isAddress, isAddressEqual, LimitExceededRpcError, parseUnits, ResourceUnavailableRpcError, SocketClosedError, TimeoutError, WebSocketRequestError, zeroAddress, } from 'viem';
 import { BadRequestError, ChannelClosedError, ChannelNotFoundError, InsufficientBalanceError, VerificationFailedError, } from '../../../Errors.js';
 import { isSessionContentRequest } from '../../server/internal/request-body.js';
 import * as Chain from '../precompile/Chain.js';
@@ -105,7 +105,7 @@ export function isSettlementDue(channel, schedule) {
         return true;
     return false;
 }
-/** Records the channel spend/unit counters that a scheduled settlement captured. */
+/** Releases a completed scheduled settlement lease; {@link settle} records the settled counters. */
 export async function markSettlementComplete(parameters) {
     const { channelId, leaseOwner, store, settledAt = new Date().toISOString() } = parameters;
     await store.updateChannel(channelId, (current) => {
@@ -114,12 +114,7 @@ export async function markSettlementComplete(parameters) {
         if (current.scheduledSettlementLease?.owner !== leaseOwner)
             return current;
         const { scheduledSettlementLease: _, ...channel } = current;
-        return {
-            ...channel,
-            lastSettlementAt: settledAt,
-            lastSettlementSpent: current.spent,
-            lastSettlementUnits: current.units,
-        };
+        return { ...channel, lastSettlementAt: settledAt };
     });
 }
 /** Atomically claims one due scheduled settlement across server workers. */
@@ -244,10 +239,19 @@ export async function maybeSettleScheduled(parameters) {
     const { channel, schedule, store } = parameters;
     if (!schedule || !isSettlementDue(channel, schedule))
         return undefined;
+    const report = (error) => reportSessionSettlementFailure(parameters.onSessionSettlementFailure, {
+        chainId: channel.chainId,
+        channelId: channel.channelId,
+        error,
+        trigger: 'scheduled',
+    });
     const leaseOwner = await claimScheduledSettlement({
         channelId: channel.channelId,
         schedule,
         store,
+    }).catch(async (error) => {
+        await report(error);
+        throw error;
     });
     if (!leaseOwner)
         return undefined;
@@ -258,26 +262,28 @@ export async function maybeSettleScheduled(parameters) {
             store,
         }).catch(() => undefined);
     }, scheduledSettlementLeaseMs / 2);
-    try {
-        const txHash = await settle(store, parameters.client, channel.channelId, {
-            account: parameters.account,
-            ...(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, leaseOwner, store });
-        return txHash;
-    }
-    catch (error) {
-        await releaseScheduledSettlement({ channelId: channel.channelId, leaseOwner, store }).catch(() => undefined);
+    const release = () => releaseScheduledSettlement({ channelId: channel.channelId, leaseOwner, store }).catch(() => undefined);
+    const txHash = await settle(store, parameters.client, channel.channelId, {
+        account: parameters.account,
+        ...(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,
+    })
+        .catch(async (error) => {
+        await release();
+        // The transaction confirmed and collected the charge; only the local record failed.
+        if (error instanceof SettlementCheckpointError)
+            return error.txHash;
+        await report(error);
         throw error;
-    }
-    finally {
-        clearInterval(renewal);
-    }
+    })
+        .finally(() => clearInterval(renewal));
+    // Bookkeeping after a confirmed settlement must not fail the charged request.
+    await markSettlementComplete({ channelId: channel.channelId, leaseOwner, store }).catch(release);
+    return txHash;
 }
 /** Settles the highest accepted voucher for a precompile-backed session channel. */
 export async function settle(store_, client, channelId_, options) {
@@ -319,15 +325,21 @@ export async function settle(store_, client, channelId_, options) {
         throw new VerificationFailedError({
             reason: 'on-chain channel state does not match settle receipt',
         });
-    await store.updateChannel(channelId, (current) => current
+    let checkpointError;
+    await store
+        .updateChannel(channelId, (current) => current
         ? {
             ...current,
             settledOnChain: newSettled > current.settledOnChain ? newSettled : current.settledOnChain,
             lastSettlementAt: new Date().toISOString(),
-            lastSettlementSpent: current.spent,
-            lastSettlementUnits: current.units,
+            // Charges accepted after the voucher was read are not covered by this transaction.
+            lastSettlementSpent: ChannelStore.keepGreater(current.lastSettlementSpent ?? 0n, channel.spent),
+            lastSettlementUnits: Math.max(current.lastSettlementUnits ?? 0, channel.units),
         }
-        : current);
+        : current)
+        .catch((cause) => {
+        checkpointError = { cause };
+    });
     if (options?.onSessionSettlement) {
         await emitSessionSettlement(options.onSessionSettlement, {
             txHash,
@@ -337,8 +349,20 @@ export async function settle(store_, client, channelId_, options) {
             delta: newSettled - channel.settledOnChain,
         });
     }
+    if (checkpointError)
+        throw new SettlementCheckpointError({ cause: checkpointError.cause, txHash });
     return txHash;
 }
+/** Raised when a settlement transaction confirmed but the channel store could not record it. */
+export class SettlementCheckpointError extends Error {
+    name = 'SettlementCheckpointError';
+    /** Hash of the confirmed settlement transaction. */
+    txHash;
+    constructor(options) {
+        super(`Settlement ${options.txHash} confirmed but was not recorded.`, { cause: options.cause });
+        this.txHash = options.txHash;
+    }
+}
 /** Settles multiple precompile-backed session channels with the same validation as {@link settle}. */
 export async function settleBatch(store, client, channelIds, options) {
     const hashes = [];
@@ -346,6 +370,36 @@ export async function settleBatch(store, client, channelIds, options) {
         hashes.push(await settle(store, client, channelId, options));
     return hashes;
 }
+/**
+ * @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 function ignoreRetryableSettlementFailure(error) {
+    if (isRetryableSettlementFailure(error))
+        return undefined;
+    throw error;
+}
+function isRetryableSettlementFailure(error) {
+    if (!(error instanceof viem_BaseError))
+        return false;
+    // Only unavailable or overloaded upstreams clear on retry; node-rejected transactions repeat.
+    return Boolean(error.walk((cause) => (cause instanceof HttpRequestError &&
+        (cause.status === undefined || cause.status === 429 || cause.status >= 500)) ||
+        cause instanceof LimitExceededRpcError ||
+        cause instanceof ResourceUnavailableRpcError ||
+        cause instanceof SocketClosedError ||
+        cause instanceof TimeoutError ||
+        cause instanceof WebSocketRequestError));
+}
+/** @internal Reports a settlement failure without letting observer errors replace it. */
+export async function reportSessionSettlementFailure(onSessionSettlementFailure, context) {
+    try {
+        await onSessionSettlementFailure?.(Object.freeze(context));
+    }
+    catch {
+        // Errors are isolated: observers cannot replace the settlement failure.
+    }
+}
 async function emitSessionSettlement(onSessionSettlement, context) {
     try {
         await onSessionSettlement(Object.freeze(context));

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

@@ -2,5 +2,5 @@ export { charge, session, settle, settleBatch } from './Session.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
 /** Server-side automatic settlement schedule. */
-export type { OnSessionSettlement, ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SessionSettlementContext, SettlementSchedule, } from './Session.js';
+export type { OnSessionSettlement, OnSessionSettlementFailure, ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SessionSettlementContext, SessionSettlementFailureContext, SettlementSchedule, } from './Session.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",