mppx 0.13.5 → 0.14.0

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

@@ -0,0 +1,289 @@
+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, 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,
+        supervised: 0,
+        timestamp: pinned.timestamp,
+        unrecovered: 0,
+    };
+    const report = (channelId, outcome, details = {}) => {
+        supervision.supervised += 1;
+        if (outcome === 'cancelled' ||
+            outcome === 'closed' ||
+            outcome === 'failed' ||
+            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 { outcome: 'open' };
+        // 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);
+}
+/** 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/CredentialVerification.d.ts

@@ -85,6 +85,12 @@ export type BroadcastCredentialPayloadParameters = {
     requireVoucherAdvance?: boolean | undefined;
     /** Server-side channel store. */
     store: ChannelStore.ChannelStore;
+    /** Maximum age of verified on-chain state a voucher may be accepted against. See `session.Parameters`. @default 0 */
+    voucherStateMaxAge?: number | undefined;
+    /** Request price a voucher credential pays in the same store update that accepts it. */
+    chargeAmount?: bigint | undefined;
+    /** Called with the stored channel after `chargeAmount` was charged. */
+    onCharged?: ((channel: ChannelStore.State) => void) | undefined;
 };
 /** @deprecated Use {@link BroadcastCredentialPayloadParameters}. */
 export type VerifyCredentialPayloadParameters = BroadcastCredentialPayloadParameters;
@@ -106,7 +112,7 @@ export type VoucherCredentialActionParameters = BroadcastCredentialActionParamet
 /** Inputs for broadcasting and settling a cooperative close credential. */
 export type CloseCredentialActionParameters = BroadcastCredentialActionParameters<'close'>;
 /** Inputs for validating a session credential without applying its state transition. */
-export type ValidateCredentialPayloadParameters = Pick<BroadcastCredentialPayloadParameters, 'account' | 'channelStateTtl' | 'chainId' | 'client' | 'credentialSource' | 'escrow' | 'expectedOperator' | 'feePayer' | 'feePayerPolicy' | 'feeToken' | 'lastOnChainVerified' | 'minVoucherDelta' | 'payload' | 'store' | 'challenge'> & {
+export type ValidateCredentialPayloadParameters = Pick<BroadcastCredentialPayloadParameters, 'account' | 'channelStateTtl' | 'chainId' | 'client' | 'credentialSource' | 'escrow' | 'expectedOperator' | 'feePayer' | 'feePayerPolicy' | 'feeToken' | 'lastOnChainVerified' | 'minVoucherDelta' | 'payload' | 'store' | 'challenge' | 'voucherStateMaxAge'> & {
     /** Allows terminal broadcast to recover accepted funds before rejecting a pending close. */
     allowPendingClose?: boolean | undefined;
 };

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

@@ -368,14 +368,22 @@ async function validateVoucherCredential(parameters, payload) {
     assertCredentialSourceCanSpend({ chainId, channel, source: credentialSource });
     if (channel.finalized)
         throw new ChannelClosedError({ reason: 'channel is finalized' });
-    const channelState = await resolveVoucherChannelState({
+    const channelState = canUseStoredChannelState({
         channel,
         channelId,
-        channelStateTtl,
-        client,
-        escrow,
         lastOnChainVerified,
-    });
+        voucher,
+        voucherStateMaxAge: parameters.voucherStateMaxAge ?? 0,
+    })
+        ? storedChannelState(channel)
+        : await resolveVoucherChannelState({
+            channel,
+            channelId,
+            channelStateTtl,
+            client,
+            escrow,
+            lastOnChainVerified,
+        });
     if (parameters.allowPendingClose && channelState.closeRequestedAt !== 0)
         return;
     await ChannelStore.validateVoucher({
@@ -387,17 +395,36 @@ async function validateVoucherCredential(parameters, payload) {
     });
 }
 async function resolveVoucherChannelState(parameters) {
-    const { channel, channelId, channelStateTtl, client, escrow, forceRefresh, lastOnChainVerified } = parameters;
+    const { channelId, channelStateTtl, client, escrow, forceRefresh, lastOnChainVerified } = parameters;
     const shouldRefresh = forceRefresh || Date.now() - (lastOnChainVerified.get(channelId) ?? 0) > channelStateTtl;
     const state = shouldRefresh ? await Chain.getChannelState(client, channelId, escrow) : undefined;
-    if (state?.closeRequestedAt)
+    if (state && (state.closeRequestedAt !== 0 || state.deposit === 0n))
         lastOnChainVerified.delete(channelId);
     else if (state)
         lastOnChainVerified.set(channelId, Date.now());
+    if (state)
+        return state;
+    const { channel } = parameters;
+    return storedChannelState(typeof channel === 'function' ? await channel() : channel);
+}
+/**
+ * Whether a voucher may be checked against the stored channel instead of waiting for a chain read.
+ * A payer can withdraw only after the escrow's close grace period, so a voucher within the deposit
+ * of recently verified open state stays settleable while a fresh read finishes.
+ */
+function canUseStoredChannelState(parameters) {
+    const { channel, channelId, lastOnChainVerified, voucher, voucherStateMaxAge } = parameters;
+    const verifiedAt = Math.max(lastOnChainVerified.get(channelId) ?? 0, channel.onChainVerifiedAt ?? 0);
+    return (voucherStateMaxAge > 0 &&
+        channel.closeRequestedAt === 0n &&
+        Date.now() - verifiedAt <= voucherStateMaxAge &&
+        voucher.cumulativeAmount <= channel.deposit);
+}
+function storedChannelState(channel) {
     return {
-        deposit: state?.deposit ?? uint96(channel.deposit),
-        settled: state?.settled ?? uint96(channel.settledOnChain),
-        closeRequestedAt: state?.closeRequestedAt ?? Number(channel.closeRequestedAt),
+        deposit: uint96(channel.deposit),
+        settled: uint96(channel.settledOnChain),
+        closeRequestedAt: Number(channel.closeRequestedAt),
     };
 }
 async function validateCloseCredential(parameters, payload) {
@@ -602,26 +629,81 @@ async function handleVoucherCredential(parameters) {
     const voucher = Voucher.parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature);
     assertDescriptor(payload);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
-    const channel = await ChannelStore.loadPrecompileChannel({
-        descriptor: payload.descriptor,
-        channelId,
-        chainId,
-        escrow,
-        store,
-        validateDescriptor: true,
-    });
+    const voucherStateMaxAge = parameters.voucherStateMaxAge ?? 0;
+    const { chargeAmount, onCharged } = parameters;
+    let loadingChannel;
+    const loadChannel = () => {
+        loadingChannel ??= ChannelStore.loadPrecompileChannel({
+            descriptor: payload.descriptor,
+            channelId,
+            chainId,
+            escrow,
+            store,
+            validateDescriptor: true,
+        });
+        return loadingChannel;
+    };
+    // The on-chain read does not depend on the stored channel, so it overlaps the store read.
+    // Store errors still take precedence because the stored channel is awaited first.
+    let reading;
+    const readChannelState = () => {
+        if (reading)
+            return reading;
+        const startedAt = Date.now();
+        const state = resolveVoucherChannelState({
+            channel: loadChannel,
+            channelId,
+            channelStateTtl,
+            client,
+            escrow,
+            forceRefresh: true,
+            lastOnChainVerified,
+        });
+        state.catch(() => { });
+        reading = { startedAt, state };
+        return reading;
+    };
+    const recentlyRead = voucherStateMaxAge > 0 &&
+        Date.now() - (lastOnChainVerified.get(channelId) ?? 0) <=
+            Math.min(channelStateTtl, voucherStateMaxAge);
+    if (!recentlyRead)
+        readChannelState();
+    if (voucherStateMaxAge > 0 && store.updateChannelResult) {
+        const receipt = await acceptVoucherInOneUpdate(parameters, voucher, payload.descriptor);
+        if (receipt) {
+            if (reading)
+                recordOnChainReadInBackground(parameters, channelId, reading);
+            return receipt;
+        }
+    }
+    const channel = await loadChannel();
     assertCredentialSourceCanSpend({ chainId, channel, source: credentialSource });
     if (channel.finalized)
         throw new ChannelClosedError({ reason: 'channel is finalized' });
-    const channelState = await resolveVoucherChannelState({
+    if (canUseStoredChannelState({
         channel,
         channelId,
-        channelStateTtl,
-        client,
-        escrow,
-        forceRefresh: true,
         lastOnChainVerified,
-    });
+        voucher,
+        voucherStateMaxAge,
+    })) {
+        if (reading)
+            recordOnChainReadInBackground(parameters, channelId, reading);
+        return ChannelStore.verifyAndAcceptVoucher({
+            store,
+            minVoucherDelta,
+            requireAdvance: parameters.requireVoucherAdvance,
+            challenge,
+            channel,
+            voucher,
+            channelState: storedChannelState(channel),
+            methodDetails: { chainId, escrowContract: escrow },
+            chargeAmount,
+            onCharged,
+        });
+    }
+    const { startedAt, state } = readChannelState();
+    const channelState = await state;
     const reconciled = channel.closeRequestedAt === 0n
         ? channel
         : ((await store.updateChannel(channelId, (current) => ChannelStore.reconcileExpiredPendingClose({
@@ -630,30 +712,7 @@ async function handleVoucherCredential(parameters) {
             state: channelState,
         }))) ?? channel);
     if (channelState.closeRequestedAt !== 0) {
-        const closing = await store.updateChannel(channelId, (current) => current
-            ? {
-                ...current,
-                settledOnChain: channelState.settled > current.settledOnChain
-                    ? channelState.settled
-                    : current.settledOnChain,
-                closeRequestedAt: BigInt(channelState.closeRequestedAt) > current.closeRequestedAt
-                    ? BigInt(channelState.closeRequestedAt)
-                    : current.closeRequestedAt,
-            }
-            : current);
-        if (closing && !closing.finalized && channelState.deposit > 0n)
-            await maybeSettleScheduled({
-                account: parameters.account,
-                channel: closing,
-                client,
-                feePayer: parameters.feePayer,
-                feePayerPolicy: parameters.feePayerPolicy,
-                feeToken: parameters.feeToken,
-                onSessionSettlement: parameters.onSessionSettlement,
-                onSessionSettlementFailure: parameters.onSessionSettlementFailure,
-                schedule: {},
-                store,
-            });
+        await recordPendingClose(parameters, channelId, channelState);
         throw new ChannelClosedError({ reason: 'channel has a pending close request' });
     }
     return ChannelStore.verifyAndAcceptVoucher({
@@ -665,8 +724,121 @@ async function handleVoucherCredential(parameters) {
         voucher,
         channelState,
         methodDetails: { chainId, escrowContract: escrow },
+        verifiedAt: startedAt,
+        chargeAmount,
+        onCharged,
     });
 }
+/**
+ * Accepts a voucher, and charges its request, in one store update with no separate read: the
+ * update checks the stored channel itself. Returns `undefined` without writing when the stored
+ * on-chain state was not verified recently enough to accept against.
+ */
+async function acceptVoucherInOneUpdate(parameters, voucher, descriptor) {
+    const { challenge, chainId, chargeAmount, credentialSource, escrow, lastOnChainVerified, minVoucherDelta, requireVoucherAdvance, store, } = parameters;
+    const voucherStateMaxAge = parameters.voucherStateMaxAge ?? 0;
+    const valid = await Voucher.verifyVoucher(escrow, chainId, voucher, authorizedSigner(descriptor));
+    if (!valid)
+        throw new InvalidSignatureError({ reason: 'invalid voucher signature' });
+    const outcome = await store.updateChannelResult(voucher.channelId, (current) => {
+        if (!current)
+            throw new ChannelNotFoundError({ reason: 'channel not found' });
+        if (!ChannelStore.isPrecompileState(current))
+            throw new VerificationFailedError({ reason: 'channel is not precompile-backed' });
+        assertSameDescriptor(descriptor, current.descriptor);
+        validateChannelDescriptor(descriptor, voucher.channelId, chainId, escrow, current.payee, current.token);
+        assertCredentialSourceCanSpend({ chainId, channel: current, source: credentialSource });
+        if (current.finalized)
+            throw new ChannelClosedError({ reason: 'channel is finalized' });
+        if (!canUseStoredChannelState({
+            channel: current,
+            channelId: voucher.channelId,
+            lastOnChainVerified,
+            voucher,
+            voucherStateMaxAge,
+        }))
+            return { op: 'noop', result: undefined };
+        if (requireVoucherAdvance && voucher.cumulativeAmount <= current.highestVoucherAmount)
+            throw new DeltaTooSmallError({ reason: 'voucher does not add new funds for this request' });
+        const channelState = storedChannelState(current);
+        const { alreadyAccepted } = ChannelStore.assertVoucherAmounts({
+            channel: current,
+            channelState,
+            minVoucherDelta,
+            voucher,
+        });
+        if (alreadyAccepted && chargeAmount === undefined)
+            return { op: 'noop', result: { channel: current, charged: false } };
+        const acceptance = ChannelStore.planVoucherAcceptance({
+            accepted: ChannelStore.acceptVoucherStateUpdate({ channelState, current, voucher }),
+            chargeAmount,
+        });
+        return { op: 'set', value: acceptance.channel, result: acceptance };
+    });
+    if (!outcome)
+        return undefined;
+    if (chargeAmount !== undefined) {
+        if (!outcome.charged)
+            throw ChannelStore.insufficientBalanceForCharge(outcome.channel, chargeAmount);
+        parameters.onCharged?.(outcome.channel);
+    }
+    return createSessionReceipt({
+        challengeId: challenge.id,
+        channelId: voucher.channelId,
+        acceptedCumulative: outcome.channel.highestVoucherAmount,
+        spent: outcome.channel.spent,
+        units: outcome.channel.units,
+    });
+}
+/** Persists a pending close seen on chain and settles the channel while the payee still can. */
+async function recordPendingClose(parameters, channelId, channelState) {
+    const { client, store } = parameters;
+    const closing = await store.updateChannel(channelId, (current) => current
+        ? {
+            ...current,
+            settledOnChain: channelState.settled > current.settledOnChain
+                ? channelState.settled
+                : current.settledOnChain,
+            closeRequestedAt: BigInt(channelState.closeRequestedAt) > current.closeRequestedAt
+                ? BigInt(channelState.closeRequestedAt)
+                : current.closeRequestedAt,
+        }
+        : current);
+    if (closing && !closing.finalized && channelState.deposit > 0n)
+        await maybeSettleScheduled({
+            account: parameters.account,
+            channel: closing,
+            client,
+            feePayer: parameters.feePayer,
+            feePayerPolicy: parameters.feePayerPolicy,
+            feeToken: parameters.feeToken,
+            onSessionSettlement: parameters.onSessionSettlement,
+            onSessionSettlementFailure: parameters.onSessionSettlementFailure,
+            schedule: {},
+            store,
+        });
+}
+/**
+ * Records an on-chain read that a voucher did not wait for: a pending close is persisted so later
+ * vouchers are rejected, and open state extends the verified age of the stored channel.
+ */
+function recordOnChainReadInBackground(parameters, channelId, read) {
+    read.state
+        .then(async (state) => {
+        if (state.closeRequestedAt !== 0)
+            return recordPendingClose(parameters, channelId, state);
+        if (state.deposit === 0n)
+            return;
+        await parameters.store.updateChannel(channelId, (current) => current && !current.finalized && current.closeRequestedAt === 0n
+            ? {
+                ...current,
+                ...ChannelStore.mergeActiveOnChainState(current, state),
+                onChainVerifiedAt: Math.max(read.startedAt, current.onChainVerifiedAt ?? 0),
+            }
+            : current);
+    })
+        .catch(() => { });
+}
 const sendMethods = new Set([
     'eth_sendRawTransaction',
     'eth_sendRawTransactionSync',

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

@@ -5,12 +5,11 @@ import * as ChannelStore from './ChannelStore.js';
 /** Controller passed to manual-charge streaming generators. */
 export type SessionController = {
     /**
-     * Reserve voucher coverage for the next emitted chunk.
+     * Commit a charge before performing billable work.
      *
-     * The reservation blocks until sufficient voucher headroom exists, but the
-     * charge is committed when a chunk is emitted or when the generator finishes
-     * successfully. A reservation is only dropped when the stream aborts or the
-     * generator fails before the charge can be committed.
+     * Waits for sufficient voucher coverage and commits the charge before resolving.
+     * Once resolved, the charge is retained even if the stream is canceled or the
+     * generator fails. Await this method before starting the corresponding work.
      *
      * Pass an explicit raw-unit `amount` for request-aware or otherwise dynamic
      * pricing. When omitted, the session challenge's configured tick cost is
@@ -32,6 +31,8 @@ export type MeteredStreamOptions = {
     formatNeedVoucher(parameters: NeedVoucherEvent): string;
     /** Async source or manual-charge source. */
     generate: SessionStreamGenerator;
+    /** Verifies that the channel can still fund work and delivery; failures stop the stream. */
+    beforeCharge?: (() => MaybePromise<void>) | undefined;
     /** Runs after a nonzero reserved charge has been committed. */
     onChargeCommitted?: ((channel: ChannelStore.State) => MaybePromise<unknown>) | undefined;
     /** Store polling interval when `waitForUpdate` is unavailable. */