mppx 0.13.5 → 0.14.0

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

@@ -1,4 +1,4 @@
-import { AmountExceedsDepositError, ChannelClosedError, ChannelNotFoundError, DeltaTooSmallError, InvalidSignatureError, VerificationFailedError, } from '../../../Errors.js';
+import { AmountExceedsDepositError, ChannelClosedError, ChannelNotFoundError, DeltaTooSmallError, InsufficientBalanceError, InvalidSignatureError, VerificationFailedError, } from '../../../Errors.js';
 import { createSessionReceipt } from '../precompile/Protocol.js';
 import { uint96 } from '../precompile/Protocol.js';
 import * as Voucher from '../precompile/Voucher.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,16 +103,91 @@ 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, voucher } = parameters;
+    const { channelState, current, verifiedAt, voucher } = parameters;
     if (!current)
         throw new ChannelNotFoundError({ reason: 'channel not found' });
     if (current.finalized)
         throw new ChannelClosedError({ reason: 'channel is finalized' });
     if (current.closeRequestedAt !== 0n)
         throw new ChannelClosedError({ reason: 'channel has a pending close request' });
-    const onChain = mergeActiveOnChainState(current, channelState);
+    const onChain = {
+        ...mergeActiveOnChainState(current, channelState),
+        ...(verifiedAt === undefined
+            ? {}
+            : { onChainVerifiedAt: Math.max(verifiedAt, current.onChainVerifiedAt ?? 0) }),
+    };
     if (voucher.cumulativeAmount <= current.highestVoucherAmount) {
         return { ...current, ...onChain };
     }
@@ -116,6 +196,7 @@ export function acceptVoucherStateUpdate(parameters) {
         ...onChain,
         highestVoucherAmount: voucher.cumulativeAmount,
         highestVoucher: voucher,
+        retainedVouchers: retainVouchers(current, voucher.cumulativeAmount, onChain.settledOnChain),
     };
 }
 /**
@@ -145,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;
@@ -239,13 +320,58 @@ export async function validateVoucher(parameters) {
         });
     return { alreadyAccepted: false };
 }
+/**
+ * Checks a cumulative voucher's amounts against channel state, without its signature, so the
+ * check can run inside the store update that accepts it.
+ */
+export function assertVoucherAmounts(parameters) {
+    const { channel, channelState, minVoucherDelta, voucher } = parameters;
+    validateChannelState(channelState);
+    if (voucher.cumulativeAmount > channelState.deposit)
+        throw new AmountExceedsDepositError({ reason: 'voucher amount exceeds on-chain deposit' });
+    if (voucher.cumulativeAmount < channel.highestVoucherAmount)
+        throw new VerificationFailedError({
+            reason: 'voucher cumulativeAmount must be strictly greater than highest accepted voucher',
+        });
+    if (voucher.cumulativeAmount <= channelState.settled)
+        throw new VerificationFailedError({
+            reason: 'voucher cumulativeAmount is below on-chain settled amount',
+        });
+    if (voucher.cumulativeAmount === channel.highestVoucherAmount)
+        return { alreadyAccepted: true };
+    const delta = voucher.cumulativeAmount - channel.highestVoucherAmount;
+    if (delta < minVoucherDelta)
+        throw new DeltaTooSmallError({
+            reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
+        });
+    return { alreadyAccepted: false };
+}
+/**
+ * Charges `chargeAmount` to a channel state that just accepted a voucher, for the same store
+ * update. A charge the available balance cannot cover leaves the accepted state uncharged.
+ */
+export function planVoucherAcceptance(parameters) {
+    const { accepted, chargeAmount } = parameters;
+    if (chargeAmount === undefined)
+        return { channel: accepted, charged: false };
+    const deduction = planDeduction(accepted, chargeAmount);
+    if (deduction.op !== 'set')
+        return { channel: accepted, charged: false };
+    return { channel: deduction.value, charged: true };
+}
+/** Reports a request charge that the channel's available balance could not cover. */
+export function insufficientBalanceForCharge(channel, chargeAmount) {
+    return new InsufficientBalanceError({
+        reason: `requested ${chargeAmount}, available ${channel.highestVoucherAmount - channel.spent - reservedStreamAmount(channel)}`,
+    });
+}
 /** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
 export async function verifyAndAcceptVoucher(parameters) {
-    const { store, challenge, channel, voucher, channelState, requireAdvance } = parameters;
+    const { store, challenge, channel, voucher, channelState, requireAdvance, verifiedAt, chargeAmount, } = parameters;
     const validation = await validateVoucher(parameters);
-    if (validation.alreadyAccepted) {
-        if (requireAdvance)
-            throw new DeltaTooSmallError({ reason: 'voucher does not add new funds for this request' });
+    if (validation.alreadyAccepted && requireAdvance)
+        throw new DeltaTooSmallError({ reason: 'voucher does not add new funds for this request' });
+    if (validation.alreadyAccepted && chargeAmount === undefined)
         return createSessionReceipt({
             challengeId: challenge.id,
             channelId: voucher.channelId,
@@ -253,16 +379,26 @@ export async function verifyAndAcceptVoucher(parameters) {
             spent: channel.spent,
             units: channel.units,
         });
-    }
+    let charged = false;
     const updated = await store.updateChannel(voucher.channelId, (current) => {
         if (requireAdvance &&
             current !== null &&
             voucher.cumulativeAmount <= current.highestVoucherAmount)
             throw new DeltaTooSmallError({ reason: 'voucher does not add new funds for this request' });
-        return acceptVoucherStateUpdate({ channelState, current, voucher });
+        const acceptance = planVoucherAcceptance({
+            accepted: acceptVoucherStateUpdate({ channelState, current, verifiedAt, voucher }),
+            chargeAmount,
+        });
+        charged = acceptance.charged;
+        return acceptance.channel;
     });
     if (!updated)
         throw new ChannelNotFoundError({ reason: 'channel not found' });
+    if (chargeAmount !== undefined) {
+        if (!charged)
+            throw insufficientBalanceForCharge(updated, chargeAmount);
+        parameters.onCharged?.(updated);
+    }
     return createSessionReceipt({
         challengeId: challenge.id,
         channelId: voucher.channelId,
@@ -413,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)
@@ -439,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 };
@@ -451,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