mppx 0.13.4 → 0.13.6

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

@@ -155,6 +155,8 @@ export type ReadbackRetryOptions = {
     retries?: number | undefined;
     /** Delay between attempts, in milliseconds. @default 250 */
     delayMs?: number | undefined;
+    /** Whether a failed attempt may be retried. @default every failure */
+    shouldRetry?: ((error: unknown) => boolean) | undefined;
 };
 /**
  * Retry an on-chain readback that is pinned to the block containing a just-sent

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

@@ -169,7 +169,7 @@ export async function getChannelStatesBatch(client, channelIds, escrow = tip20Ch
  * verification even though the open transaction succeeded.
  */
 export async function readbackWithRetry(read, options = {}) {
-    const { retries = 5, delayMs = 250 } = options;
+    const { retries = 5, delayMs = 250, shouldRetry = () => true } = options;
     let lastError;
     for (let attempt = 0; attempt <= retries; attempt++) {
         try {
@@ -177,6 +177,8 @@ export async function readbackWithRetry(read, options = {}) {
         }
         catch (error) {
             lastError = error;
+            if (!shouldRetry(error))
+                break;
             if (attempt < retries)
                 await new Promise((resolve) => setTimeout(resolve, delayMs));
         }
@@ -261,8 +263,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({
@@ -442,6 +444,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);
     }
@@ -465,7 +468,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';
@@ -109,6 +110,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 +196,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 +266,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;
@@ -316,6 +327,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>;
 /**

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';
@@ -100,14 +100,19 @@ export function topUpChannelState(parameters) {
 }
 /** 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 };
     }
@@ -239,13 +244,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 +303,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,

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

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