mppx 0.13.6 → 0.14.0

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

@@ -82,6 +82,11 @@ export function openChannelState(parameters) {
         settledOnChain: onChain.settledOnChain,
         highestVoucherAmount: highestVoucher.highestVoucherAmount,
         highestVoucher: highestVoucher.highestVoucher,
+        ...(current && highestVoucher.highestVoucherAmount > current.highestVoucherAmount
+            ? {
+                retainedVouchers: retainVouchers(current, highestVoucher.highestVoucherAmount, onChain.settledOnChain),
+            }
+            : {}),
         spent: keepGreater(current?.spent ?? 0n, state.settled),
         units: current?.units ?? 0,
         finalized: current?.finalized ?? false,
@@ -98,6 +103,76 @@ export function topUpChannelState(parameters) {
         ...mergeActiveOnChainState(current, state),
     };
 }
+/**
+ * Number of accepted vouchers kept below the highest one. Clients sign every voucher above their
+ * last one, so once a credit lowers `spent` the highest voucher stays above it for good and only
+ * earlier vouchers can be settled; those fall at or below `spent` as later charges accumulate.
+ * Each costs about 200 bytes of the channel record. In a simulated 20,000-request channel crediting
+ * up to 80% of each request back, which left the highest voucher 80,000 units above `spent`,
+ * settling every 50 requests left on average 1,290 units unsettled with 16 retained vouchers and
+ * 784 with 32.
+ */
+export const maxRetainedVouchers = 16;
+/**
+ * Returns the vouchers to keep once `highestVoucherAmount` replaces the highest voucher: the
+ * retained ones and the superseded highest voucher, above `settledOnChain`. Beyond
+ * {@link maxRetainedVouchers} it repeatedly drops the voucher whose neighbours are closest, so the
+ * kept ones stay spread over the unsettled range and some keep falling at or below `spent` however
+ * far credits have moved it below the highest voucher.
+ */
+export function retainVouchers(current, highestVoucherAmount, settledOnChain = current.settledOnChain) {
+    const candidates = [...(current.retainedVouchers ?? [])];
+    if (current.highestVoucher)
+        candidates.push({
+            cumulativeAmount: current.highestVoucher.cumulativeAmount,
+            signature: current.highestVoucher.signature,
+        });
+    const kept = candidates
+        .filter(({ cumulativeAmount }) => cumulativeAmount > settledOnChain && cumulativeAmount < highestVoucherAmount)
+        .sort((a, b) => a.cumulativeAmount < b.cumulativeAmount
+        ? -1
+        : a.cumulativeAmount > b.cumulativeAmount
+            ? 1
+            : 0);
+    while (kept.length > maxRetainedVouchers) {
+        let drop = 0;
+        let narrowest;
+        for (let index = 0; index < kept.length; index++) {
+            const below = index === 0 ? settledOnChain : kept[index - 1].cumulativeAmount;
+            const above = index === kept.length - 1 ? highestVoucherAmount : kept[index + 1].cumulativeAmount;
+            if (narrowest === undefined || above - below < narrowest) {
+                narrowest = above - below;
+                drop = index;
+            }
+        }
+        kept.splice(drop, 1);
+    }
+    return kept;
+}
+/**
+ * Returns the largest accepted voucher a settlement may capture. The escrow's `settle` captures a
+ * voucher's whole cumulative amount, and a credit may leave the highest voucher above `spent`, so
+ * the voucher must be at most `spent`; one at or below `settledOnChain` captures nothing.
+ */
+export function resolveSettleableVoucher(state) {
+    let settleable;
+    for (const voucher of [
+        ...(state.retainedVouchers ?? []),
+        ...(state.highestVoucher ? [state.highestVoucher] : []),
+    ]) {
+        if (voucher.cumulativeAmount > state.spent || voucher.cumulativeAmount <= state.settledOnChain)
+            continue;
+        if (!settleable || voucher.cumulativeAmount > settleable.cumulativeAmount)
+            settleable = voucher;
+    }
+    if (!settleable)
+        return null;
+    return {
+        channelId: state.channelId,
+        cumulativeAmount: settleable.cumulativeAmount,
+        signature: settleable.signature,
+    };
+}
 /** Merges an accepted voucher into persisted channel state after signature and on-chain checks pass. */
 export function acceptVoucherStateUpdate(parameters) {
     const { channelState, current, verifiedAt, voucher } = parameters;
@@ -121,6 +196,7 @@ export function acceptVoucherStateUpdate(parameters) {
         ...onChain,
         highestVoucherAmount: voucher.cumulativeAmount,
         highestVoucher: voucher,
+        retainedVouchers: retainVouchers(current, voucher.cumulativeAmount, onChain.settledOnChain),
     };
 }
 /**
@@ -150,7 +226,7 @@ export function resolveCloseCaptureAmount(parameters) {
 /** 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;
+export 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;
@@ -473,14 +549,76 @@ export function fromStore(store) {
     storeCache.set(store, cs);
     return cs;
 }
+/**
+ * Default time a keyed charge or credit outcome is kept: a day, longer than any retry within one
+ * request or durable job step. Callers whose retries span longer pass their own `retention`.
+ */
+export const defaultIdempotencyRetention = 24 * 60 * 60 * 1000;
+/** Raised when an idempotency key is reused with terms other than those it recorded. */
+export class IdempotencyKeyConflictError extends Error {
+    name = 'IdempotencyKeyConflictError';
+    /** The reused key. */
+    idempotencyKey;
+    constructor(options) {
+        super(`Session ${options.operation} "${options.idempotencyKey}" was recorded with different terms.`);
+        this.idempotencyKey = options.idempotencyKey;
+    }
+}
+/** Atomic read-modify-write through `updateChannelResult`, or `updateChannel` when absent. */
+async function applyChange(store, channelId, fn) {
+    if (store.updateChannelResult)
+        return store.updateChannelResult(channelId, fn);
+    // The callback can rerun on a contended write; the result of its last run is the stored one.
+    let result;
+    await store.updateChannel(channelId, (current) => {
+        const change = fn(current);
+        result = change.result;
+        if (change.op === 'set')
+            return change.value;
+        if (change.op === 'delete')
+            return null;
+        return current;
+    });
+    return result;
+}
+/** Validates the idempotency options of a keyed charge or credit. */
+export function assertIdempotencyOptions(options) {
+    const { idempotencyKey, retention } = options;
+    if (idempotencyKey !== undefined && (typeof idempotencyKey !== 'string' || !idempotencyKey))
+        throw new Error('`idempotencyKey` must be a non-empty string.');
+    if (retention !== undefined && (!Number.isFinite(retention) || retention <= 0))
+        throw new Error('`retention` must be a positive number.');
+}
+/** Markers of a channel that have not expired. */
+function liveMarkers(state, now) {
+    const markers = {};
+    for (const [key, marker] of Object.entries(state.idempotencyMarkers ?? {}))
+        if (marker.expiresAt > now)
+            markers[key] = marker;
+    return markers;
+}
 /**
  * Atomically deducts `amount` from a channel's available voucher balance.
  *
  * Returns `{ ok: true, channel }` with updated spend/unit counters when the
  * deduction succeeds. Returns `{ ok: false, channel }` without mutating state
- * when the channel exists but cannot currently be charged.
+ * when the channel exists but cannot currently be charged. With an
+ * `idempotencyKey`, a charge recorded under the key returns
+ * `{ ok: true, channel, replayed: true }` without charging again.
  */
-export async function deductFromChannel(store, channelId, amount) {
+export async function deductFromChannel(store, channelId, amount, options) {
+    const idempotencyKey = options?.idempotencyKey;
+    if (idempotencyKey !== undefined) {
+        assertIdempotencyOptions(options);
+        const now = Date.now();
+        const expiresAt = now + (options?.retention ?? defaultIdempotencyRetention);
+        const result = await applyChange(store, channelId, (current) => planKeyedDeduction(current, amount, idempotencyKey, expiresAt, now));
+        if (!result)
+            throw new Error('channel not found');
+        if (result === 'conflict')
+            throw new IdempotencyKeyConflictError({ idempotencyKey, operation: 'charge' });
+        return result;
+    }
     if (store.updateChannelResult) {
         const result = await store.updateChannelResult(channelId, (current) => planDeduction(current, amount));
         if (!result)
@@ -499,6 +637,26 @@ export async function deductFromChannel(store, channelId, amount) {
         throw new Error('channel not found');
     return result ?? { ok: false, channel };
 }
+function planKeyedDeduction(current, amount, idempotencyKey, expiresAt, now) {
+    if (!current)
+        return { op: 'noop', result: null };
+    const markers = liveMarkers(current, now);
+    const markerKey = `charge:${idempotencyKey}`;
+    const recorded = markers[markerKey];
+    if (recorded) {
+        if (recorded.outcome !== 'charged' || recorded.amount !== amount)
+            return { op: 'noop', result: 'conflict' };
+        return { op: 'noop', result: { ok: true, channel: current, replayed: true } };
+    }
+    const deduction = planDeduction(current, amount);
+    if (deduction.op !== 'set')
+        return deduction;
+    const channel = {
+        ...deduction.value,
+        idempotencyMarkers: { ...markers, [markerKey]: { amount, expiresAt, outcome: 'charged' } },
+    };
+    return { op: 'set', value: channel, result: { ok: true, channel } };
+}
 function planDeduction(current, amount) {
     if (!current)
         return { op: 'noop', result: null };
@@ -511,6 +669,88 @@ function planDeduction(current, amount) {
     const next = { ...current, spent: current.spent + amount, units: current.units + 1 };
     return { op: 'set', value: next, result: { ok: true, channel: next } };
 }
+/**
+ * Returns `amount` to a channel's `spent` at most once per idempotency key. The 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 first outcome for a key is final, so a declined credit is never applied later.
+ */
+export async function creditChannel(store, channelId, amount, options) {
+    const { idempotencyKey, units = 0 } = options;
+    assertIdempotencyOptions(options);
+    if (typeof idempotencyKey !== 'string')
+        throw new Error('`idempotencyKey` is required.');
+    if (amount <= 0n)
+        throw new Error('Credit amount must be positive.');
+    if (!Number.isSafeInteger(units) || units < 0)
+        throw new Error('`units` must be a non-negative integer.');
+    const now = Date.now();
+    const expiresAt = now + (options.retention ?? defaultIdempotencyRetention);
+    let result;
+    try {
+        result = await applyChange(store, channelId, (current) => planCredit(current, { amount, expiresAt, idempotencyKey, now, units }));
+    }
+    catch (error) {
+        return { status: 'unknown', error };
+    }
+    if (!result)
+        throw new ChannelNotFoundError({ reason: 'channel not found' });
+    if (result === 'conflict')
+        throw new IdempotencyKeyConflictError({ idempotencyKey, operation: 'credit' });
+    return result;
+}
+function planCredit(current, terms) {
+    const { amount, expiresAt, idempotencyKey, now, units } = terms;
+    if (!current)
+        return { op: 'noop', result: null };
+    const markers = liveMarkers(current, now);
+    const markerKey = `credit:${idempotencyKey}`;
+    const recorded = markers[markerKey];
+    if (recorded) {
+        if (recorded.outcome === 'charged' ||
+            recorded.amount !== amount ||
+            (recorded.units ?? 0) !== units)
+            return { op: 'noop', result: 'conflict' };
+        return {
+            op: 'noop',
+            result: recorded.outcome === 'credited'
+                ? { status: 'credited', channel: current, replayed: true }
+                : { status: 'declined', reason: recorded.outcome, channel: current, replayed: true },
+        };
+    }
+    const reason = creditDeclineReason(current, amount, now);
+    const marker = {
+        amount,
+        expiresAt,
+        outcome: reason ?? 'credited',
+        ...(units > 0 ? { units } : {}),
+    };
+    const channel = {
+        ...current,
+        ...(reason ? {} : { spent: current.spent - amount, units: Math.max(0, current.units - units) }),
+        idempotencyMarkers: { ...markers, [markerKey]: marker },
+    };
+    return {
+        op: 'set',
+        value: channel,
+        result: reason
+            ? { status: 'declined', reason, channel, replayed: false }
+            : { status: 'credited', channel, replayed: false },
+    };
+}
+function creditDeclineReason(current, amount, now) {
+    if (current.finalized)
+        return 'finalized';
+    if (current.closeRequestedAt !== 0n)
+        return 'closing';
+    if (amount > current.spent)
+        return 'exceedsSpent';
+    const pending = current.pendingSettlement;
+    const settling = pending && pending.expiresAt > now ? pending.amount : 0n;
+    if (current.spent - amount < keepGreater(current.settledOnChain, settling))
+        return 'belowSettled';
+    return undefined;
+}
 /** Returns unexpired stream reservations that ordinary deductions must respect. */
 export function reservedStreamAmount(state) {
     const now = Date.now();

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

@@ -0,0 +1,98 @@
+import { type Hex } from 'viem';
+import * as Chain from '../precompile/Chain.js';
+import { type OnSessionSettlementFailure, type SessionStoreInput, type SettlementTransactionOptions } from './Settlement.js';
+/** Channels whose escrow states one call reads, bounding its calldata and response size. */
+export declare const defaultBatchSize = 50;
+/** Widest log query `rpc.tempo.xyz` accepts; wider ones fail with "query exceeds max block range". */
+export declare 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 declare const defaultCloseSearchMarginBlocks = 2000n;
+/** What one supervision did with a channel. */
+export type CloseSupervisionOutcome = 
+/** Open with no close request, or not yet open at the pinned block. */
+'open'
+/** Close requested, with nothing above the settled amount to capture; the payer's withdrawal finalizes it. */
+ | 'closing'
+/** A close request recorded on the channel was cancelled on-chain, so the channel accepts charges again. */
+ | 'cancelled'
+/** A payee close captured the channel's spend, or its deposit left the escrow with it paid. */
+ | 'closed'
+/** The deposit left the escrow paying the payee less than the channel's spend. */
+ | 'unrecovered'
+/** Already finalized in the store. */
+ | 'finalized'
+/** No precompile channel record in the store. */
+ | 'missing'
+/** The channel could not be read or answered; a later supervision retries it. */
+ | 'failed';
+/** Result of one {@link superviseCloses} run. */
+export type CloseSupervision = {
+    /** Block every escrow read was pinned to. Pass it as `previousBlock` once `complete`. */
+    block: bigint;
+    /** Timestamp of `block` in Unix seconds, e.g. to alert when the last complete run grows old. */
+    timestamp: number;
+    /** Whether every channel was read and handled, so `block` bounds later close-event searches. */
+    complete: boolean;
+    /** Channels supervised. */
+    supervised: number;
+    /** Close requests found cancelled. */
+    cancelled: number;
+    /** Channels closed or found closed with their spend paid. */
+    closed: number;
+    /** Channels that failed. */
+    failed: number;
+    /** Channels whose deposit left the escrow before their spend was captured. */
+    unrecovered: number;
+    /**
+     * Per-channel outcomes, in supervision order. Channels whose outcome is `closed`, `unrecovered`,
+     * `finalized` or `missing` need no further supervision.
+     */
+    channels: {
+        channelId: Hex;
+        outcome: CloseSupervisionOutcome;
+        error?: unknown;
+        txHash?: Hex | undefined;
+    }[];
+};
+/** Inputs for {@link superviseCloses}. */
+export type SuperviseClosesParameters = Pick<SettlementTransactionOptions, 'account' | 'candidateFeeTokens' | 'feePayer' | 'feePayerPolicy' | 'feeToken' | 'onSessionSettlement'> & {
+    /** Channels per escrow state read. @default 50 */
+    batchSize?: number | undefined;
+    /**
+     * Channels to supervise. A channel store cannot list its channels, so the caller keeps their IDs:
+     * add a channel before its first charge and drop it once a supervision reports it `closed`,
+     * `unrecovered`, `finalized` or `missing`.
+     */
+    channelIds: Iterable<Hex> | AsyncIterable<Hex>;
+    /** viem client for reads and payee closes on the channels' chain. */
+    client: Chain.TransactionClient;
+    /** Blocks searched before `previousBlock` for a channel no supervision has read open. @default 2_000n */
+    closeSearchMarginBlocks?: bigint | undefined;
+    /** Widest block range of one log query. @default 100_000n */
+    logBlockRange?: bigint | undefined;
+    /** Callback invoked when a payee close fails. Observer errors are ignored. */
+    onSessionSettlementFailure?: OnSessionSettlementFailure | undefined;
+    /** `block` of the last `complete` supervision, which bounds close-event searches. */
+    previousBlock?: bigint | undefined;
+    /** Server channel store. */
+    store: SessionStoreInput;
+};
+/**
+ * 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 declare function superviseCloses(parameters: SuperviseClosesParameters): Promise<CloseSupervision>;
+//# sourceMappingURL=CloseSupervisor.d.ts.map

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