mppx 0.13.5 → 0.14.0

package/dist/tempo/session/client/Transports.js

@@ -298,12 +298,22 @@ export async function readProblemDetail(response) {
         return body;
     }
 }
+/** A dispatched deposit may have executed despite a failed or cancelled response. */
+export class UncertainFundingError extends Error {
+    constructor(reason) {
+        const detail = reason instanceof Error || reason instanceof DOMException ? reason.message : String(reason);
+        super(`${detail}; payment outcome unknown`);
+        this.name = 'UncertainFundingError';
+    }
+}
 /** Posts a top-up management credential and returns its receipt, when present. */
 export async function postTopUp(parameters) {
     const { channel, channelId } = parameters;
     if (!channel?.descriptor || channel.channelId !== channelId) {
         throw new Error('Cannot top up session: no local channel descriptor available.');
     }
+    if (channel.uncertainTopUp)
+        throw new Error('Session funding outcome is unknown; reconcile the pending payment before another top-up.');
     const response = await postManagementCredential({
         challenge: parameters.challenge,
         context: {
@@ -316,6 +326,12 @@ export async function postTopUp(parameters) {
         fetch: parameters.fetch,
         input: parameters.input,
         signal: parameters.signal,
+    }).catch(async (error) => {
+        if (error instanceof UncertainFundingError) {
+            channel.uncertainTopUp = true;
+            await parameters.onUncertainFunding?.(channel);
+        }
+        throw error;
     });
     if (!response.ok)
         throw new Error(`Top-up POST failed with status ${response.status}`);
@@ -324,13 +340,42 @@ export async function postTopUp(parameters) {
 }
 /** Posts a management credential and retries once with a refreshed TIP-1034 challenge. */
 async function postManagementCredential(parameters) {
-    const post = async (challenge) => parameters.fetch(managementInput(parameters.input), {
-        method: 'POST',
-        ...(parameters.signal ? { signal: parameters.signal } : {}),
-        headers: {
-            [Constants.Headers.authorization]: await parameters.createSessionCredential(challenge, parameters.context),
-        },
-    });
+    const post = async (challenge) => {
+        parameters.signal?.throwIfAborted();
+        const authorization = await parameters.createSessionCredential(challenge, parameters.context);
+        parameters.signal?.throwIfAborted();
+        const controller = new AbortController();
+        const abort = () => controller.abort(parameters.signal?.reason);
+        parameters.signal?.addEventListener('abort', abort, { once: true });
+        const timeout = setTimeout(() => controller.abort(new DOMException('Session management request timed out; payment outcome unknown', 'TimeoutError')), 30_000);
+        let onAbort;
+        const aborted = new Promise((_, reject) => {
+            onAbort = () => reject(controller.signal.reason);
+            controller.signal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+            // Custom fetch implementations may ignore abort. Do not let their late
+            // response update funding state or trigger a refreshed-challenge retry.
+            return await Promise.race([
+                parameters.fetch(managementInput(parameters.input), {
+                    method: 'POST',
+                    signal: controller.signal,
+                    headers: { [Constants.Headers.authorization]: authorization },
+                }),
+                aborted,
+            ]);
+        }
+        catch (error) {
+            if (parameters.context.action === 'topUp')
+                throw new UncertainFundingError(error);
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            parameters.signal?.removeEventListener('abort', abort);
+            controller.signal.removeEventListener('abort', onAbort);
+        }
+    };
     const response = await post(parameters.challenge);
     if (response.status !== 402)
         return response;

package/dist/tempo/session/precompile/Chain.d.ts

@@ -146,9 +146,9 @@ export declare function getChannel(client: Client, descriptor: ChannelDescriptor
  */
 export declare function getChannelState(client: Client, channelId: Hex, escrow?: Address, blockNumber?: bigint): Promise<ChannelState>;
 /**
- * Read channel states from the TIP20EscrowChannel precompile.
+ * Read channel states from the TIP20EscrowChannel precompile, optionally at one block.
  */
-export declare function getChannelStatesBatch(client: Client, channelIds: readonly Hex[], escrow?: Address): Promise<ChannelState[]>;
+export declare function getChannelStatesBatch(client: Client, channelIds: readonly Hex[], escrow?: Address, blockNumber?: bigint): Promise<ChannelState[]>;
 /** Tuning for {@link readbackWithRetry}. */
 export type ReadbackRetryOptions = {
     /** Additional attempts after the first, before giving up. @default 5 */

package/dist/tempo/session/precompile/Chain.js

@@ -141,14 +141,15 @@ export async function getChannelState(client, channelId, escrow = tip20ChannelEs
     return stateFromTuple(state);
 }
 /**
- * Read channel states from the TIP20EscrowChannel precompile.
+ * Read channel states from the TIP20EscrowChannel precompile, optionally at one block.
  */
-export async function getChannelStatesBatch(client, channelIds, escrow = tip20ChannelEscrow) {
+export async function getChannelStatesBatch(client, channelIds, escrow = tip20ChannelEscrow, blockNumber) {
     const states = await readContract(client, {
         address: escrow,
         abi: escrowAbi,
         functionName: 'getChannelStatesBatch',
         args: [channelIds],
+        ...(blockNumber !== undefined ? { blockNumber } : {}),
     });
     return states.map(stateFromTuple);
 }
@@ -263,8 +264,8 @@ function validateAutoSwapPrefix(parameters) {
         fail('approval amount does not match swap maximum input');
     if (!isAddressEqual(tokenOut, currency))
         fail('output token does not match channel currency');
-    if (swapAmountOut !== amountOut)
-        fail('output amount does not match channel deposit');
+    if (swapAmountOut <= 0n || swapAmountOut > amountOut)
+        fail('output amount must be positive and not exceed channel deposit');
     if (isAddressEqual(tokenIn, tokenOut))
         fail('input and output tokens must differ');
     const canonicalApprove = encodeFunctionData({
@@ -444,6 +445,7 @@ export async function sendCredentialTransaction(parameters) {
         // execution as the sender. It intentionally omits fee fields here; the
         // transport is responsible for validating its final sponsored envelope.
         await simulateTempoTransaction(client, FeePayer.simulationTransaction(transaction, { feePayer: true }));
+        FeePayer.assertRemainingValidity({ transaction, details });
         const txHash = await sendTransaction(client, serializedTransaction);
         return waitForSuccessfulReceipt(client, txHash);
     }
@@ -467,7 +469,9 @@ export async function sendCredentialTransaction(parameters) {
             return { feePayer: feePayer.address, transaction: sponsored };
         },
     });
+    FeePayer.assertRemainingValidity({ transaction: completed.transaction, details });
     const serialized = await signTempoTransaction(client, completed.transaction);
+    FeePayer.assertRemainingValidity({ transaction: completed.transaction, details });
     const receipt = await sendRawTransactionSync(client, {
         serializedTransaction: serialized,
     });

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

@@ -1,5 +1,6 @@
 import type { Address, Hex } from 'viem';
 import type * as Challenge from '../../../Challenge.js';
+import { InsufficientBalanceError } from '../../../Errors.js';
 import type * as Store from '../../../Store.js';
 import type * as Chain from '../precompile/Chain.js';
 import type * as PrecompileChannel from '../precompile/Channel.js';
@@ -23,10 +24,11 @@ import type { SessionMethodDetails } from './RequestState.js';
  * - `deposit` reflects the latest on-chain value
  */
 export type State = BaseState & BackendState;
-/** Result of an atomic channel deduction attempt. */
+/** Result of an atomic channel deduction attempt. `replayed` marks a keyed charge recorded earlier. */
 export type DeductResult = {
     ok: true;
     channel: State;
+    replayed?: boolean | undefined;
 } | {
     ok: false;
     channel: State;
@@ -109,6 +111,8 @@ export type AcceptVoucherStateUpdateParameters = {
     channelState: Chain.ChannelState;
     /** Existing channel state being updated. */
     current: State | null;
+    /** When `channelState` was read from chain; omitted when it came from the store. */
+    verifiedAt?: number | undefined;
     /** Verified signed voucher. */
     voucher: SessionSignedVoucher;
 };
@@ -193,8 +197,14 @@ export type VerifyAndAcceptVoucherParameters = {
     requireAdvance?: boolean | undefined;
     /** Server channel store. */
     store: ChannelStore;
+    /** When `channelState` was read from chain; omitted when it came from the store. */
+    verifiedAt?: number | undefined;
     /** Signed cumulative voucher to verify and accept. */
     voucher: SignedVoucher;
+    /** Request price to charge in the same store update that accepts the voucher. */
+    chargeAmount?: bigint | undefined;
+    /** Called with the stored channel after `chargeAmount` was charged. */
+    onCharged?: ((channel: State) => void) | undefined;
 };
 /** Inputs for validating a cumulative voucher without recording it. */
 export type ValidateVoucherParameters = Omit<VerifyAndAcceptVoucherParameters, 'challenge' | 'store'>;
@@ -257,6 +267,8 @@ export interface BaseState {
     token: Address;
     /** Number of charge operations (API requests) fulfilled in the current session. */
     units: number;
+    /** Unix milliseconds when the channel's on-chain deposit, settlement and close state were last read. */
+    onChainVerifiedAt?: number | undefined;
     /** Uncommitted stream charges shared across workers. */
     streamReservations?: Record<string, {
         amount: bigint;
@@ -271,12 +283,58 @@ export interface BaseState {
     lastSettlementSpent?: bigint | undefined;
     /** Charge operation count when the last server-scheduled settlement ran. */
     lastSettlementUnits?: number | undefined;
+    /**
+     * Accepted vouchers below `highestVoucher`, ascending, that a settlement may capture once
+     * `spent` covers them. See {@link resolveSettleableVoucher}.
+     */
+    retainedVouchers?: readonly RetainedVoucher[] | undefined;
+    /** Settlement transaction that may still land; credits keep `spent` at or above its amount. */
+    pendingSettlement?: PendingSettlement | undefined;
+    /** Outcomes of keyed charges and credits, by `charge:<key>` and `credit:<key>`, until they expire. */
+    idempotencyMarkers?: Record<string, IdempotencyMarker> | undefined;
+    /** First block at which the close supervisor read this channel open on-chain. */
+    closeSupervisedFromBlock?: bigint | undefined;
 }
 /** Expiring ownership claim for one server-scheduled settlement attempt. */
 export type ScheduledSettlementLease = {
     expiresAt: number;
     owner: string;
 };
+/** An accepted voucher kept below the highest one. */
+export type RetainedVoucher = {
+    /** Cumulative amount the voucher authorizes. */
+    cumulativeAmount: bigint;
+    /** Voucher signature. */
+    signature: Hex;
+};
+/** A settlement transaction that may land until `expiresAt`. */
+export type PendingSettlement = {
+    /** Cumulative amount the transaction captures. */
+    amount: bigint;
+    /** Unix milliseconds after which the transaction can no longer be included. */
+    expiresAt: number;
+};
+/** Why a credit was not applied. */
+export type CreditDeclineReason = 
+/** Crediting would take `spent` below what settled, or may still settle, on-chain. */
+'belowSettled'
+/** A close is pending, so its capture is already fixed. */
+ | 'closing'
+/** The amount is larger than `spent`. */
+ | 'exceedsSpent'
+/** The channel is closed. */
+ | 'finalized';
+/** Recorded outcome of one keyed charge or credit. */
+export type IdempotencyMarker = {
+    /** Amount the operation charged or credited. */
+    amount: bigint;
+    /** Unix milliseconds until which a retry with the same key replays this outcome. */
+    expiresAt: number;
+    /** `charged`, `credited`, or why the credit was declined. */
+    outcome: 'charged' | 'credited' | CreditDeclineReason;
+    /** Charge operations a credit returned, when any. */
+    units?: number | undefined;
+};
 /** Returns whether a channel is backed by the TIP20EscrowChannel precompile. */
 export declare function isPrecompileState(state: State): state is BaseState & PrecompileBackendState;
 /** Returns the greater bigint value without decreasing persisted monotonic state. */
@@ -293,6 +351,30 @@ export declare function resolvePrecompileChannelIdentity(parameters: ResolvePrec
 export declare function openChannelState(parameters: OpenChannelStateParameters): State;
 /** Merges top-up on-chain state into persisted channel state without decreasing monotonic fields. */
 export declare function topUpChannelState(parameters: TopUpStateParameters): State | null;
+/**
+ * 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 declare 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 declare function retainVouchers(current: Pick<State, 'highestVoucher' | 'retainedVouchers' | 'settledOnChain'>, highestVoucherAmount: bigint, settledOnChain?: bigint): RetainedVoucher[];
+/**
+ * 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 declare function resolveSettleableVoucher(state: Pick<State, 'channelId' | 'highestVoucher' | 'retainedVouchers' | 'settledOnChain' | 'spent'>): SessionSignedVoucher | null;
 /** Merges an accepted voucher into persisted channel state after signature and on-chain checks pass. */
 export declare function acceptVoucherStateUpdate(parameters: AcceptVoucherStateUpdateParameters): State;
 /**
@@ -302,6 +384,8 @@ export declare function acceptVoucherStateUpdate(parameters: AcceptVoucherStateU
 export declare function resolveCloseCaptureAmount(parameters: ResolveCloseCaptureAmountParameters): bigint;
 /** Seconds a server close transaction stays valid after its pending-close marker is written. */
 export declare const pendingCloseValiditySeconds = 25;
+/** Extra seconds allowed for clock differences between the server and the chain. */
+export declare const pendingCloseClockSkewSeconds = 30;
 /** Clears a server pending-close marker whose close transaction expired without closing the channel. */
 export declare function reconcileExpiredPendingClose(parameters: {
     current: State | null;
@@ -316,6 +400,29 @@ export declare function finalizeClosedChannelState(parameters: FinalizeClosedCha
 export declare function loadPrecompileChannel(parameters: LoadPrecompileChannelParameters): Promise<StoredPrecompileChannel>;
 /** Verifies a cumulative voucher without changing persisted channel state. */
 export declare function validateVoucher(parameters: ValidateVoucherParameters): Promise<VoucherValidation>;
+/**
+ * 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 declare function assertVoucherAmounts(parameters: {
+    channel: Pick<State, 'highestVoucherAmount'>;
+    channelState: Chain.ChannelState;
+    minVoucherDelta: bigint;
+    voucher: Pick<SignedVoucher, 'cumulativeAmount'>;
+}): VoucherValidation;
+/**
+ * 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 declare function planVoucherAcceptance(parameters: {
+    accepted: State;
+    chargeAmount?: bigint | undefined;
+}): {
+    channel: State;
+    charged: boolean;
+};
+/** Reports a request charge that the channel's available balance could not cover. */
+export declare function insufficientBalanceForCharge(channel: State, chargeAmount: bigint): InsufficientBalanceError;
 /** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
 export declare function verifyAndAcceptVoucher(parameters: VerifyAndAcceptVoucherParameters): Promise<SessionReceipt>;
 /**
@@ -371,14 +478,90 @@ export type ChannelStore = {
 export declare function normalizeChannelId(channelId: string): Hex;
 /** Wraps a generic mppx store in the shared session channel-store interface. */
 export declare function fromStore(store: Store.Store | Store.AtomicStore): ChannelStore;
+/**
+ * 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 declare const defaultIdempotencyRetention: number;
+/** Options for charging a channel at most once per key. */
+export type ChargeOptions = {
+    /**
+     * Key of the operation being charged. A retry with the same key and amount returns the recorded
+     * charge without charging again; the same key with a different amount throws
+     * {@link IdempotencyKeyConflictError}. A refused charge records nothing, so it may succeed later.
+     */
+    idempotencyKey?: string | undefined;
+    /**
+     * Milliseconds the charge stays recorded, which must cover every retry. The channel record keeps
+     * one marker per keyed charge and credit of this window; expired markers are removed by the next
+     * keyed charge or credit of the channel. @default 86_400_000
+     */
+    retention?: number | undefined;
+};
+/** Options for returning an amount to a channel at most once per key. */
+export type CreditOptions = {
+    /**
+     * Key of the credit. Its first outcome, credited or declined, is final: a retry with the same key
+     * and terms returns it without crediting again, and the same key with other terms throws
+     * {@link IdempotencyKeyConflictError}.
+     */
+    idempotencyKey: string;
+    /** Milliseconds the outcome stays recorded; see {@link ChargeOptions.retention}. @default 86_400_000 */
+    retention?: number | undefined;
+    /** Charge operations to take back from `units`, e.g. `1` when refunding a whole request. @default 0 */
+    units?: number | undefined;
+};
+/**
+ * Outcome of a credit. `declined` leaves `spent` unchanged, so the caller refunds the amount
+ * another way; a finalized channel whose `settledOnChain` is below `spent` was withdrawn before
+ * its spend was captured. `unknown` means the store write failed and may have committed: retry
+ * with the same key to learn the outcome.
+ */
+export type CreditResult = {
+    status: 'credited';
+    channel: State;
+    replayed: boolean;
+} | {
+    status: 'declined';
+    reason: CreditDeclineReason;
+    channel: State;
+    replayed: boolean;
+} | {
+    status: 'unknown';
+    error: unknown;
+};
+/** Raised when an idempotency key is reused with terms other than those it recorded. */
+export declare class IdempotencyKeyConflictError extends Error {
+    readonly name = "IdempotencyKeyConflictError";
+    /** The reused key. */
+    readonly idempotencyKey: string;
+    constructor(options: {
+        idempotencyKey: string;
+        operation: 'charge' | 'credit';
+    });
+}
+/** Validates the idempotency options of a keyed charge or credit. */
+export declare function assertIdempotencyOptions(options: {
+    idempotencyKey?: string | undefined;
+    retention?: number | undefined;
+}): void;
 /**
  * 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 declare function deductFromChannel(store: ChannelStore, channelId: State['channelId'], amount: bigint, options?: ChargeOptions): Promise<DeductResult>;
+/**
+ * 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 declare function deductFromChannel(store: ChannelStore, channelId: State['channelId'], amount: bigint): Promise<DeductResult>;
+export declare function creditChannel(store: ChannelStore, channelId: State['channelId'], amount: bigint, options: CreditOptions): Promise<CreditResult>;
 /** Returns unexpired stream reservations that ordinary deductions must respect. */
 export declare function reservedStreamAmount(state: Pick<State, 'streamReservations'>): bigint;
 //# sourceMappingURL=ChannelStore.d.ts.map