mppx 0.13.6 → 0.14.1

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

@@ -0,0 +1,310 @@
+import { getAbiItem } from 'viem';
+import { getBlock, getLogs } from 'viem/actions';
+import { VerificationFailedError } from '../../../Errors.js';
+import * as Chain from '../precompile/Chain.js';
+import { escrowAbi } from '../precompile/escrow.abi.js';
+import * as ChannelStore from './ChannelStore.js';
+import { assertSettlementSender, getClientAccount, maybeSettleScheduled, reportSessionSettlementFailure, resolveChannelStore, } from './Settlement.js';
+/** Escrow event every close and withdrawal emits, with the amount paid to the payee. */
+const channelClosedEvent = getAbiItem({ abi: escrowAbi, name: 'ChannelClosed' });
+/** Channels whose escrow states one call reads, bounding its calldata and response size. */
+export const defaultBatchSize = 50;
+/** Widest log query `rpc.tempo.xyz` accepts; wider ones fail with "query exceeds max block range". */
+export const defaultLogBlockRange = 100000n;
+/**
+ * Blocks searched before the previous complete supervision for the close event of a channel no
+ * supervision has read open yet: about 18 minutes of 0.55-second Tempo blocks, longer than the
+ * escrow's 900-second close grace period and the interval between supervisions.
+ */
+export const defaultCloseSearchMarginBlocks = 2000n;
+/**
+ * Answers payer close requests on channels the server is not otherwise touching. After a payer
+ * requests a close on-chain, the escrow lets it withdraw the whole deposit once its close grace
+ * period (900 seconds on Tempo) ends, so call this from a scheduled job well within that period,
+ * for example every minute.
+ *
+ * Each run reads the escrow state of every channel at one pinned block, in batches. A close request
+ * is answered with a payee close capturing `max(spent, settled)`, bounded by the highest voucher and
+ * the deposit, which pays the accepted charges and refunds the rest; the close pays fees as
+ * configured, e.g. `feeToken` when the channel token cannot pay them. A deposit that already left
+ * the escrow is finalized from its `ChannelClosed` event, searched in pages of `logBlockRange`
+ * blocks. A close request cancelled on-chain reopens the channel.
+ */
+export async function superviseCloses(parameters) {
+    const { client } = parameters;
+    const store = resolveChannelStore(parameters.store);
+    const batchSize = parameters.batchSize ?? defaultBatchSize;
+    // A read pinned to this block fails on a node that has not reached it, instead of answering
+    // with older state that would hide a close request.
+    const block = await getBlock(client, { blockTag: 'latest' });
+    const pinned = { number: block.number, timestamp: Number(block.timestamp) };
+    const supervision = {
+        block: pinned.number,
+        cancelled: 0,
+        channels: [],
+        closed: 0,
+        complete: false,
+        failed: 0,
+        settled: 0,
+        supervised: 0,
+        timestamp: pinned.timestamp,
+        unrecovered: 0,
+    };
+    const report = (channelId, outcome, details = {}) => {
+        supervision.supervised += 1;
+        if (outcome === 'cancelled' ||
+            outcome === 'closed' ||
+            outcome === 'failed' ||
+            outcome === 'settled' ||
+            outcome === 'unrecovered')
+            supervision[outcome] += 1;
+        supervision.channels.push({ channelId, outcome, ...details });
+    };
+    const superviseBatch = async (channelIds) => {
+        const live = [];
+        for (const channelId of channelIds) {
+            let channel;
+            try {
+                channel = await store.getChannel(channelId);
+            }
+            catch (error) {
+                report(channelId, 'failed', { error });
+                continue;
+            }
+            if (!channel || !ChannelStore.isPrecompileState(channel))
+                report(channelId, 'missing');
+            else if (channel.finalized)
+                report(channelId, 'finalized');
+            else if (client.chain && client.chain.id !== channel.chainId)
+                report(channelId, 'failed', {
+                    error: new Error(`Channel is on chain ${channel.chainId}, not ${client.chain.id}.`),
+                });
+            else
+                live.push(channel);
+        }
+        const byEscrow = new Map();
+        for (const channel of live) {
+            const escrow = channel.escrowContract.toLowerCase();
+            byEscrow.set(escrow, [...(byEscrow.get(escrow) ?? []), channel]);
+        }
+        for (const members of byEscrow.values()) {
+            let states;
+            try {
+                states = await Chain.getChannelStatesBatch(client, members.map(({ channelId }) => channelId), members[0].escrowContract, pinned.number);
+            }
+            catch (error) {
+                for (const { channelId } of members)
+                    report(channelId, 'failed', { error });
+                continue;
+            }
+            for (const [index, channel] of members.entries()) {
+                const state = states[index];
+                if (!state) {
+                    report(channel.channelId, 'failed', { error: new Error('Escrow state missing.') });
+                    continue;
+                }
+                try {
+                    const { outcome, txHash } = await superviseChannel(parameters, store, channel, state, {
+                        pinned,
+                        previous: parameters.previousBlock,
+                    });
+                    report(channel.channelId, outcome, { txHash });
+                }
+                catch (error) {
+                    // A close that landed before this failure is found by its close event next time.
+                    report(channel.channelId, 'failed', { error });
+                }
+            }
+        }
+    };
+    let batch = [];
+    for await (const channelId of parameters.channelIds) {
+        batch.push(channelId);
+        if (batch.length < batchSize)
+            continue;
+        await superviseBatch(batch);
+        batch = [];
+    }
+    if (batch.length > 0)
+        await superviseBatch(batch);
+    supervision.complete = supervision.failed === 0;
+    return supervision;
+}
+/** Applies one pinned escrow read of a supervised channel. */
+async function superviseChannel(parameters, store, channel, state, blocks) {
+    const { channelId } = channel;
+    if (state.deposit === 0n) {
+        // A complete supervision read every listed channel that is still supervised, so a channel read
+        // open lost its deposit after the later of that read and the previous complete supervision. A
+        // channel no supervision has read open was listed after the previous complete one.
+        const since = channel.closeSupervisedFromBlock;
+        const { previous } = blocks;
+        const margin = parameters.closeSearchMarginBlocks ?? defaultCloseSearchMarginBlocks;
+        const fromBlock = since === undefined
+            ? (previous ?? blocks.pinned.number) - margin
+            : previous !== undefined && previous > since
+                ? previous
+                : since;
+        const paid = await findSettledToPayee(parameters, channel, {
+            fromBlock: fromBlock > 0n ? fromBlock : 0n,
+            toBlock: blocks.pinned.number,
+        });
+        if (paid === undefined) {
+            // An open landing after the pinned block also reads as no deposit; a later run reads it.
+            if (since === undefined)
+                return { outcome: 'open' };
+            throw new VerificationFailedError({
+                reason: 'channel left the escrow without a ChannelClosed event in its search range',
+            });
+        }
+        const finalized = await store.updateChannel(channelId, (current) => current && !current.finalized
+            ? {
+                ...current,
+                closeRequestedAt: 0n,
+                deposit: 0n,
+                finalized: true,
+                settledOnChain: ChannelStore.keepGreater(current.settledOnChain, paid),
+            }
+            : current);
+        return { outcome: paid >= (finalized?.spent ?? channel.spent) ? 'closed' : 'unrecovered' };
+    }
+    if (channel.closeSupervisedFromBlock === undefined)
+        await store.updateChannel(channelId, (current) => current && current.closeSupervisedFromBlock === undefined
+            ? { ...current, closeSupervisedFromBlock: blocks.pinned.number }
+            : current);
+    if (state.closeRequestedAt === 0) {
+        if (channel.closeRequestedAt === 0n)
+            return settleDue(parameters, store, channel);
+        // A pinned read without a request means the payer cancelled it, unless the record holds a
+        // server close that may still land: those expire before they are cleared.
+        const cleared = {};
+        await store.updateChannel(channelId, (current) => {
+            cleared.channel = ChannelStore.reconcileExpiredPendingClose({
+                current,
+                now: blocks.pinned.timestamp,
+                state,
+            });
+            return cleared.channel;
+        });
+        return {
+            outcome: cleared.channel && cleared.channel.closeRequestedAt === 0n && !cleared.channel.finalized
+                ? 'cancelled'
+                : 'open',
+        };
+    }
+    // A pending close stops charges and credits, so the spend this close captures stays fixed.
+    const closing = await store.updateChannel(channelId, (current) => current && !current.finalized
+        ? { ...current, ...ChannelStore.mergeActiveOnChainState(current, state) }
+        : current);
+    if (!closing || closing.finalized || !ChannelStore.isPrecompileState(closing))
+        return { outcome: 'finalized' };
+    return closeAtSpend(parameters, store, closing, state);
+}
+/** Settles an open channel when its spend crossed the settlement schedule. */
+async function settleDue(parameters, store, channel) {
+    const { client, settlementSchedule } = parameters;
+    if (!settlementSchedule)
+        return { outcome: 'open' };
+    const txHash = await maybeSettleScheduled({
+        account: parameters.account ?? getClientAccount(client),
+        channel,
+        client,
+        ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
+        ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
+        ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
+        onSessionSettlement: parameters.onSessionSettlement,
+        onSessionSettlementFailure: parameters.onSessionSettlementFailure,
+        schedule: settlementSchedule,
+        store,
+    });
+    return txHash ? { outcome: 'settled', txHash } : { outcome: 'open' };
+}
+/** Sends a payee close capturing the channel's spend and finalizes the channel. */
+async function closeAtSpend(parameters, store, channel, state) {
+    const { client } = parameters;
+    const { channelId } = channel;
+    try {
+        const voucher = channel.highestVoucher;
+        if (!voucher)
+            throw new VerificationFailedError({ reason: 'no voucher to close with' });
+        const capture = ChannelStore.resolveCloseCaptureAmount({
+            cumulativeAmount: voucher.cumulativeAmount,
+            onChainDeposit: state.deposit,
+            onChainSettled: state.settled,
+            spent: channel.spent,
+        });
+        if (capture <= state.settled)
+            return { outcome: 'closing' };
+        const account = parameters.account ?? getClientAccount(client);
+        assertSettlementSender({
+            operation: 'close',
+            channelId,
+            operator: channel.operator,
+            payee: channel.payee,
+            sender: account?.address,
+        });
+        const txHash = await Chain.closeOnChain(client, channel.descriptor, voucher.cumulativeAmount, capture, voucher.signature, channel.escrowContract, account
+            ? {
+                account,
+                candidateFeeTokens: parameters.candidateFeeTokens ?? [channel.token],
+                ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
+                ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
+                ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
+            }
+            : undefined);
+        const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
+        const { refundedToPayer, settledToPayee } = Chain.readChannelClosedReceiptFields(Chain.getChannelEvent(receipt, 'ChannelClosed', channelId));
+        if (settledToPayee > capture || settledToPayee + refundedToPayer > state.deposit)
+            throw new VerificationFailedError({ reason: 'ChannelClosed amounts do not match state' });
+        await store.updateChannel(channelId, (current) => ChannelStore.finalizeClosedChannelState({
+            captureAmount: settledToPayee,
+            channelId,
+            cumulativeAmount: voucher.cumulativeAmount,
+            current,
+            signature: voucher.signature,
+        }));
+        if (parameters.onSessionSettlement) {
+            try {
+                await parameters.onSessionSettlement(Object.freeze({
+                    amount: settledToPayee,
+                    channelId,
+                    delta: settledToPayee - state.settled,
+                    trigger: 'close',
+                    txHash,
+                }));
+            }
+            catch {
+                // Errors are isolated: observers cannot break the close.
+            }
+        }
+        return { outcome: 'closed', txHash };
+    }
+    catch (error) {
+        await reportSessionSettlementFailure(parameters.onSessionSettlementFailure, {
+            chainId: channel.chainId,
+            channelId,
+            error,
+            trigger: 'close',
+        });
+        throw error;
+    }
+}
+/** Amount paid to the payee when the channel closed within the blocks, if it did. */
+async function findSettledToPayee(parameters, channel, range) {
+    const step = parameters.logBlockRange ?? defaultLogBlockRange;
+    for (let from = range.fromBlock; from <= range.toBlock; from += step) {
+        const to = from + step - 1n < range.toBlock ? from + step - 1n : range.toBlock;
+        const logs = await getLogs(parameters.client, {
+            address: channel.escrowContract,
+            args: { channelId: channel.channelId },
+            event: channelClosedEvent,
+            fromBlock: from,
+            toBlock: to,
+        });
+        const paid = logs.find((log) => !log.removed)?.args.settledToPayee;
+        if (paid !== undefined)
+            return paid;
+    }
+    return undefined;
+}
+//# sourceMappingURL=CloseSupervisor.js.map

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

@@ -18,8 +18,9 @@ import * as Transport from '../../server/internal/transport.js';
 import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as serializeSessionSnapshot } from '../Snapshot.js';
 import * as ChannelStore from './ChannelStore.js';
 import { type ResolveSessionChannelId } from './RequestState.js';
-import { type SettleChargedSessionChannel } from './Settlement.js';
+import { type SessionStoreInput, type SettleChargedSessionChannel } from './Settlement.js';
 import { type OnSessionSettlement, type OnSessionSettlementFailure, type SettlementSchedule } from './Settlement.js';
+import * as SponsorshipLimit from './SponsorshipLimit.js';
 import * as Ws from './Ws.js';
 /** @internal Reuses a method's escrow verifier when composing shared currency helpers. */
 export declare function verifyStream(method: object, channelId: Hex): Promise<void>;
@@ -208,6 +209,14 @@ export declare namespace session {
         settlementSchedule?: SettlementSchedule | undefined;
         /** Optional fee token for management and server-driven settle/close transactions. */
         feeToken?: Address | undefined;
+        /**
+         * Limits fee-payer-sponsored channel opens and top-ups to `perDay` of each per payer per UTC
+         * day (default 5), counted in `store`. The payer is the verified signer of the transaction, never
+         * the credential's client-supplied `source`. A transaction over the limit, or one whose
+         * signatures prove no payer, is broadcast unsponsored, so it lands only if the payer pays its
+         * own fees.
+         */
+        sponsorshipLimit?: SponsorshipLimit.Parameters | undefined;
     } & Account.resolve.Parameters & Client.getResolver.Parameters & Defaults & Method.ComposableHooks<typeof Methods.session>;
     /** Defaults derived from `session()` parameters for handler type inference. */
     type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<parameters, Defaults, {
@@ -223,6 +232,36 @@ export declare namespace session {
  *
  * Delegates to the shared `deductFromChannel` atomic helper and translates
  * failure modes into typed errors (`InsufficientBalanceError`, `ChannelClosedError`).
+ *
+ * With `options.idempotencyKey` the channel is charged at most once per key: a retry with the same
+ * key and amount returns the channel without charging again, and the same key with a different
+ * amount throws `IdempotencyKeyConflictError`.
+ *
+ * @example
+ * ```ts
+ * // One durable job per voucher, retried under its operation ID.
+ * const channel = await Session.Server.charge(store, channelId, jobCost, {
+ *   idempotencyKey: operationId,
+ * })
+ * ```
+ */
+export declare function charge(store: SessionStoreInput, channelId: Hex, amount: bigint, options?: ChannelStore.ChargeOptions): Promise<ChannelStore.State>;
+/**
+ * Returns an unused amount to a channel's `spent` at most once per idempotency key.
+ *
+ * The first outcome for a key is final. A credit is `declined` when the channel is closing or
+ * finalized, or when it would take `spent` below zero or below what settled, or may still settle,
+ * on-chain, because a close captures `max(spent, settled)`; the caller then refunds another way.
+ * `unknown` reports a store write that failed and may have committed; retrying with the same key
+ * returns the outcome that was recorded.
+ *
+ * @example
+ * ```ts
+ * const result = await Session.Server.credit(store, channelId, unused, {
+ *   idempotencyKey: `refund:${flowId}`,
+ * })
+ * if (result.status === 'declined') await refundAnotherWay()
+ * ```
  */
-export declare function charge(store: ChannelStore.ChannelStore, channelId: Hex, amount: bigint): Promise<ChannelStore.State>;
+export declare function credit(store: SessionStoreInput, channelId: Hex, amount: bigint, options: ChannelStore.CreditOptions): Promise<ChannelStore.CreditResult>;
 //# sourceMappingURL=Session.d.ts.map

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

@@ -28,9 +28,10 @@ import { broadcastCredentialPayload, validateCredentialPayload } from './Credent
 import { requireSessionCredentialPayload, validateChannelState } from './CredentialVerification.js';
 import { resolveCredentialVerificationContext, resolveSessionChannelId, resolveSessionSnapshot, resolveSessionPaymentRequest, } from './RequestState.js';
 import { respondToSessionCredential } from './RequestState.js';
-import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, shouldChargeVoucherOnAcceptance, } from './Settlement.js';
+import { applyVerifiedHttpAccounting, chargeSessionChannel, resolveChannelStore, shouldApplyVerifiedHttpAccounting, shouldChargeVoucherOnAcceptance, } from './Settlement.js';
 import { ignoreRetryableSettlementFailure, isSettlementDue, maybeSettleScheduled, reportSessionSettlementFailure, } from './Settlement.js';
 import { resolveSettlementSchedule, } from './Settlement.js';
+import * as SponsorshipLimit from './SponsorshipLimit.js';
 import * as Ws from './Ws.js';
 const streamVerifiers = new WeakMap();
 /** @internal Reuses a method's escrow verifier when composing shared currency helpers. */
@@ -218,6 +219,7 @@ export function session(p) {
     const parameters = p;
     const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = fallbackStore('tempo.session'), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
+    SponsorshipLimit.assertParameters(parameters.sponsorshipLimit);
     const onSessionSettlement = parameters.onSessionSettlement;
     const onSessionSettlementFailure = parameters.onSessionSettlementFailure;
     const store = ChannelStore.fromStore(rawStore);
@@ -395,7 +397,12 @@ export function session(p) {
             credentialSource: credential.source,
             escrow: context.escrow,
             expectedOperator: context.methodDetails.operator,
-            feePayer: context.feePayer,
+            feePayer: await SponsorshipLimit.limitFeePayer({
+                chainId: context.chainId,
+                feePayer: context.feePayer,
+                limit: parameters.sponsorshipLimit,
+                payload,
+            }),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: context.methodDetails.feeToken,
             lastOnChainVerified,
@@ -525,8 +532,40 @@ export function session(p) {
  *
  * Delegates to the shared `deductFromChannel` atomic helper and translates
  * failure modes into typed errors (`InsufficientBalanceError`, `ChannelClosedError`).
+ *
+ * With `options.idempotencyKey` the channel is charged at most once per key: a retry with the same
+ * key and amount returns the channel without charging again, and the same key with a different
+ * amount throws `IdempotencyKeyConflictError`.
+ *
+ * @example
+ * ```ts
+ * // One durable job per voucher, retried under its operation ID.
+ * const channel = await Session.Server.charge(store, channelId, jobCost, {
+ *   idempotencyKey: operationId,
+ * })
+ * ```
+ */
+export async function charge(store, channelId, amount, options) {
+    return chargeSessionChannel({ ...options, store: resolveChannelStore(store), channelId, amount });
+}
+/**
+ * Returns an unused amount to a channel's `spent` at most once per idempotency key.
+ *
+ * The first outcome for a key is final. A credit is `declined` when the channel is closing or
+ * finalized, or when it would take `spent` below zero or below what settled, or may still settle,
+ * on-chain, because a close captures `max(spent, settled)`; the caller then refunds another way.
+ * `unknown` reports a store write that failed and may have committed; retrying with the same key
+ * returns the outcome that was recorded.
+ *
+ * @example
+ * ```ts
+ * const result = await Session.Server.credit(store, channelId, unused, {
+ *   idempotencyKey: `refund:${flowId}`,
+ * })
+ * if (result.status === 'declined') await refundAnotherWay()
+ * ```
  */
-export async function charge(store, channelId, amount) {
-    return chargeSessionChannel({ store, channelId, amount });
+export async function credit(store, channelId, amount, options) {
+    return ChannelStore.creditChannel(resolveChannelStore(store), channelId, amount, options);
 }
 //# sourceMappingURL=Session.js.map

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

@@ -112,8 +112,8 @@ export declare function resolveSettlementSchedule(schedule: SettlementSchedule |
  * Computes the schedule progress for an unsettled precompile-backed channel.
  *
  * Returns `undefined` for channels that cannot be scheduled: non-precompile
- * records, channels without an accepted voucher, or channels with no unsettled
- * voucher amount.
+ * records, or channels without an accepted voucher above the settled amount and
+ * within `spent` (see {@link ChannelStore.resolveSettleableVoucher}).
  */
 export declare function resolveSettlementProgress(channel: ChannelStore.State): SettlementProgress | undefined;
 /** Returns whether the precompile channel has crossed any configured settlement threshold. */
@@ -145,7 +145,7 @@ export type ChargeSessionChannel = (channelId: Hex, amount: bigint) => Promise<C
 /** Callback used by post-verification accounting to run server-owned settlement policy. */
 export type SettleChargedSessionChannel = (channel: ChannelStore.State) => Promise<Hex | undefined>;
 /** Inputs for charging a precompile-backed session channel. */
-export type ChargeParameters = {
+export type ChargeParameters = ChannelStore.ChargeOptions & {
     /** Server-side channel store. */
     store: ChannelStore.ChannelStore;
     /** Channel ID to deduct from. */
@@ -247,7 +247,12 @@ export declare function getClientAccount(client: {
 export declare function assertSettlementSender(parameters: SettlementSenderParameters): void;
 /** Applies automatic settlement when the server-owned schedule is due. */
 export declare function maybeSettleScheduled(parameters: MaybeSettleScheduledParameters): Promise<Hex | undefined>;
-/** Settles the highest accepted voucher for a precompile-backed session channel. */
+/**
+ * Settles the largest accepted voucher within the channel's `spent` for a precompile-backed session
+ * channel (see {@link ChannelStore.resolveSettleableVoucher}). The escrow captures the voucher's
+ * whole cumulative amount, so a voucher above `spent`, such as the highest one after a credit, is
+ * never settled. Until the transaction can no longer land, credits keep `spent` at or above it.
+ */
 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 {

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

@@ -67,15 +67,14 @@ export function resolveSettlementSchedule(schedule, decimals) {
  * Computes the schedule progress for an unsettled precompile-backed channel.
  *
  * Returns `undefined` for channels that cannot be scheduled: non-precompile
- * records, channels without an accepted voucher, or channels with no unsettled
- * voucher amount.
+ * records, or channels without an accepted voucher above the settled amount and
+ * within `spent` (see {@link ChannelStore.resolveSettleableVoucher}).
  */
 export function resolveSettlementProgress(channel) {
     if (!ChannelStore.isPrecompileState(channel))
         return undefined;
-    if (!channel.highestVoucher)
-        return undefined;
-    if (channel.highestVoucher.cumulativeAmount <= channel.settledOnChain)
+    // A settlement captures a voucher whole, so only a voucher within spend can be scheduled.
+    if (!ChannelStore.resolveSettleableVoucher(channel))
         return undefined;
     const amountBoundary = channel.lastSettlementSpent ?? channel.settledOnChain;
     const timestampBoundary = Date.parse(channel.lastSettlementAt ?? channel.createdAt);
@@ -203,12 +202,18 @@ export async function applyVerifiedHttpAccounting(parameters) {
 }
 /** Atomically deducts spend from a channel and maps store failures to typed session errors. */
 export async function chargeSessionChannel(parameters) {
-    const { store, channelId, amount } = parameters;
+    const { store, channelId, amount, idempotencyKey, retention } = parameters;
+    ChannelStore.assertIdempotencyOptions({ idempotencyKey, retention });
     let result;
     try {
-        result = await ChannelStore.deductFromChannel(store, channelId, amount);
+        result = await ChannelStore.deductFromChannel(store, channelId, amount, {
+            idempotencyKey,
+            retention,
+        });
     }
-    catch {
+    catch (error) {
+        if (error instanceof ChannelStore.IdempotencyKeyConflictError)
+            throw error;
         throw new ChannelClosedError({ reason: 'channel not found' });
     }
     if (!result.ok) {
@@ -298,7 +303,12 @@ export async function maybeSettleScheduled(parameters) {
     await markSettlementComplete({ channelId: channel.channelId, leaseOwner, store }).catch(release);
     return txHash;
 }
-/** Settles the highest accepted voucher for a precompile-backed session channel. */
+/**
+ * Settles the largest accepted voucher within the channel's `spent` for a precompile-backed session
+ * channel (see {@link ChannelStore.resolveSettleableVoucher}). The escrow captures the voucher's
+ * whole cumulative amount, so a voucher above `spent`, such as the highest one after a credit, is
+ * never settled. Until the transaction can no longer land, credits keep `spent` at or above it.
+ */
 export async function settle(store_, client, channelId_, options) {
     const store = resolveChannelStore(store_);
     const channelId = ChannelStore.normalizeChannelId(channelId_);
@@ -318,20 +328,72 @@ export async function settle(store_, client, channelId_, options) {
         payee: channel.payee,
         sender: account?.address,
     });
-    const amount = uint96(channel.highestVoucher.cumulativeAmount);
-    const { signature } = channel.highestVoucher;
-    // A replica behind the open or top-up that admitted this voucher rejects the settle while
-    // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
-    const txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
-        ? {
-            account,
-            ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
-            ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
-            ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
-            candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
-        }
-        : undefined), { shouldRetry: isExecutionRevert });
-    const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
+    // Pin the transaction's expiry so the credit floor below can expire once it can no longer land.
+    const validBefore = Math.floor(Date.now() / 1000) + ChannelStore.pendingCloseValiditySeconds;
+    const pending = {
+        amount: 0n,
+        expiresAt: (validBefore + ChannelStore.pendingCloseClockSkewSeconds) * 1000,
+    };
+    const claim = {};
+    // Choosing the voucher and raising the credit floor in one update keeps a concurrent credit from
+    // lowering spent below what this transaction captures.
+    await store.updateChannel(channelId, (current) => {
+        claim.channel = current ?? undefined;
+        claim.voucher = (current && ChannelStore.resolveSettleableVoucher(current)) ?? undefined;
+        if (!current || !claim.voucher)
+            return current;
+        pending.amount = claim.voucher.cumulativeAmount;
+        const live = current.pendingSettlement && current.pendingSettlement.expiresAt > Date.now()
+            ? current.pendingSettlement
+            : undefined;
+        return {
+            ...current,
+            pendingSettlement: {
+                amount: ChannelStore.keepGreater(live?.amount ?? 0n, pending.amount),
+                expiresAt: Math.max(live?.expiresAt ?? 0, pending.expiresAt),
+            },
+        };
+    });
+    const { voucher } = claim;
+    if (!voucher || !claim.channel)
+        throw new VerificationFailedError({
+            reason: 'nothing to settle: no accepted voucher above the settled amount is within spent',
+        });
+    const claimed = claim.channel;
+    const amount = uint96(voucher.cumulativeAmount);
+    const { signature } = voucher;
+    // A revert proves the transaction will not land, so its credit floor can go at once.
+    const release = () => store
+        .updateChannel(channelId, (current) => {
+        if (current?.pendingSettlement?.amount !== pending.amount ||
+            current.pendingSettlement.expiresAt !== pending.expiresAt)
+            return current;
+        const { pendingSettlement: _, ...rest } = current;
+        return rest;
+    })
+        .catch(() => undefined);
+    let txHash;
+    let receipt;
+    try {
+        // A replica behind the open or top-up that admitted this voucher rejects the settle while
+        // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
+        txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
+            ? {
+                account,
+                ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
+                ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
+                ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
+                candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
+                validBefore,
+            }
+            : { validBefore }), { shouldRetry: isExecutionRevert });
+        receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
+    }
+    catch (error) {
+        if (isExecutionRevert(error) || error instanceof VerificationFailedError)
+            await release();
+        throw error;
+    }
     const settled = readSettledReceiptFields(Chain.getChannelEvent(receipt, 'Settled', channelId));
     const { deltaPaid, newSettled } = settled;
     if (newSettled < amount)
@@ -344,16 +406,29 @@ export async function settle(store_, client, channelId_, options) {
         });
     let checkpointError;
     await store
-        .updateChannel(channelId, (current) => current
-        ? {
-            ...current,
-            settledOnChain: newSettled > current.settledOnChain ? newSettled : current.settledOnChain,
+        .updateChannel(channelId, (current) => {
+        if (!current)
+            return current;
+        const settledOnChain = ChannelStore.keepGreater(current.settledOnChain, newSettled);
+        const { pendingSettlement, ...rest } = current;
+        return {
+            ...rest,
+            // The recorded settlement now keeps spent at or above what this transaction captured.
+            ...(pendingSettlement && pendingSettlement.amount > settledOnChain
+                ? { pendingSettlement }
+                : {}),
+            ...(current.retainedVouchers
+                ? {
+                    retainedVouchers: current.retainedVouchers.filter((retained) => retained.cumulativeAmount > settledOnChain),
+                }
+                : {}),
+            settledOnChain,
             lastSettlementAt: new Date().toISOString(),
-            // 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)
+            // Charges accepted after the voucher was chosen are not covered by this transaction.
+            lastSettlementSpent: ChannelStore.keepGreater(current.lastSettlementSpent ?? 0n, amount),
+            lastSettlementUnits: Math.max(current.lastSettlementUnits ?? 0, claimed.units),
+        };
+    })
         .catch((cause) => {
         checkpointError = { cause };
     });