mppx 0.13.4 → 0.13.6

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. */

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

@@ -1,38 +1,24 @@
-import { commitReservedCharges, releaseReservedCharges, renewReservedCharges, reserveChargeOrWait, streamReservationLeaseMs, } from './Transports.js';
+import { commitReservedCharges, releaseReservedCharges, reserveChargeOrWait } from './Transports.js';
 /** Applies voucher reservation and spend commits to an async session stream. */
 export async function* meterIterable(options) {
+    const manual = typeof options.generate === 'function';
     let prepaidUnits = options.prepaidUnits ?? 0;
-    const controller = new AbortController();
-    const signal = controller.signal;
+    const signal = options.signal ?? new AbortController().signal;
     const reservation = {
         store: options.store,
         channelId: options.channelId,
         reservationId: globalThis.crypto.randomUUID(),
     };
     let pending = false;
-    let cancelled = false;
-    const onAbort = () => {
-        if (signal.aborted)
-            return;
-        cancelled = true;
-        controller.abort(options.signal?.reason);
-    };
-    options.signal?.addEventListener('abort', onAbort, { once: true });
-    if (options.signal?.aborted)
-        onAbort();
-    const renewal = setInterval(() => {
-        if (pending)
-            void renewReservedCharges(reservation).catch((error) => controller.abort(error));
-    }, streamReservationLeaseMs / 3);
-    renewal.unref?.();
     const releaseOnAbort = () => {
-        clearInterval(renewal);
         void releaseReservedCharges(reservation).catch(() => { });
     };
     signal.addEventListener('abort', releaseOnAbort, { once: true });
     if (signal.aborted)
         releaseOnAbort();
     const charge = async (amount) => {
+        signal.throwIfAborted();
+        await options.beforeCharge?.();
         signal.throwIfAborted();
         if (amount === undefined && prepaidUnits > 0) {
             prepaidUnits -= 1;
@@ -50,9 +36,13 @@ export async function* meterIterable(options) {
             signal,
         });
         pending = true;
+        if (manual)
+            await commit();
         signal.throwIfAborted();
     };
     const commit = async () => {
+        signal.throwIfAborted();
+        await options.beforeCharge?.();
         signal.throwIfAborted();
         if (!pending)
             return;
@@ -63,7 +53,6 @@ export async function* meterIterable(options) {
         await options.onChargeCommitted?.(channel);
     };
     try {
-        const manual = typeof options.generate === 'function';
         const iterable = typeof options.generate === 'function'
             ? options.generate({ charge, signal })
             : options.generate;
@@ -74,7 +63,7 @@ export async function* meterIterable(options) {
                 if (signal.aborted)
                     break;
                 if (done) {
-                    if (manual)
+                    if (manual && pending)
                         await commit();
                     break;
                 }
@@ -83,18 +72,13 @@ export async function* meterIterable(options) {
                 await commit();
                 yield value;
             }
-            if (!cancelled)
-                signal.throwIfAborted();
         }
         finally {
-            clearInterval(renewal);
             await releaseReservedCharges(reservation);
             await iterator.return?.();
         }
     }
     finally {
-        clearInterval(renewal);
-        options.signal?.removeEventListener('abort', onAbort);
         signal.removeEventListener('abort', releaseOnAbort);
         await releaseReservedCharges(reservation);
     }

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

@@ -21,6 +21,8 @@ import { type ResolveSessionChannelId } from './RequestState.js';
 import { type SettleChargedSessionChannel } from './Settlement.js';
 import { type OnSessionSettlement, type OnSessionSettlementFailure, type SettlementSchedule } from './Settlement.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>;
 /** Server-side automatic settlement schedule. */
 export type { SettlementSchedule } from './Settlement.js';
 /** Server-side settlement event hook types. */
@@ -131,15 +133,27 @@ export declare namespace session {
         serveWebSocket: (options: ServeWebSocketOptions) => Promise<void>;
     };
     /** WebSocket server options supplied after the session binds shared dependencies. */
-    type ServeWebSocketOptions = Omit<Ws.serve.Options, 'onChargeCommitted' | 'settleScheduled' | 'store'>;
+    type ServeWebSocketOptions = Omit<Ws.serve.Options, 'beforeCharge' | 'onChargeCommitted' | 'settleScheduled' | 'store'>;
     /** Request defaults inferred from the Tempo session method schema. */
     type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.session>, 'escrowContract' | 'feePayer' | 'recipient'>;
     /** Partial fee-sponsor policy used for server-submitted session transactions. */
     type FeePayerPolicy = Partial<FeePayer.Policy>;
     /** Parameters accepted by the TIP-1034 server session payment method. */
     type Parameters = {
-        /** TTL in milliseconds for cached on-chain channel state during non-mutating validation. Voucher acceptance always refreshes on-chain state. @default 5_000 */
+        /** TTL in milliseconds for cached on-chain channel state during non-mutating validation, and before a voucher accepted under `voucherStateMaxAge` starts a fresh read. @default 5_000 */
         channelStateTtl?: number | undefined;
+        /**
+         * Maximum age in milliseconds of verified on-chain channel state that a voucher may be validated
+         * and accepted against without waiting for a fresh read. The fresh read then finishes in the background and
+         * records a pending close, so later vouchers are rejected. `0` reads on-chain state before every
+         * acceptance.
+         *
+         * A payer can withdraw only after the escrow's `CLOSE_GRACE_PERIOD` (900 s on Tempo) following a
+         * close request, so vouchers accepted this way stay settleable as long as the payee settles them
+         * within the grace period minus this age. Keep it well below that bound.
+         * @default 0
+         */
+        voucherStateMaxAge?: number | undefined;
         /** Override the fee-sponsor policy used for sponsored open/topUp transactions and server-driven close transactions. */
         feePayerPolicy?: FeePayerPolicy | undefined;
         /** Minimum voucher delta to accept (numeric string, default: "0"). */
@@ -159,6 +173,19 @@ export declare namespace session {
          * containing the signed highest voucher for client rehydration.
          */
         bootstrap?: boolean | undefined;
+        /**
+         * Lets a session challenge pay for later requests to the same route until it expires. The
+         * challenge is bound to its route, currency, recipient and channel terms but not to the amount
+         * it quoted, and every request is charged its own price from the channel's accepted balance.
+         * A client can then send a voucher with a request instead of waiting for a `402`.
+         */
+        reusableChallenges?: boolean | undefined;
+        /**
+         * Charges request-priced content (`unitType: 'request'`) in the same store update that accepts
+         * its voucher, before the response, instead of in a second update when the response is
+         * delivered. The server must then refund requests it cannot serve.
+         */
+        chargeOnAcceptance?: boolean | undefined;
         /**
          * Atomic store backend for channel state.
          *