mppx 0.13.3 → 0.13.5

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

@@ -679,11 +679,12 @@ export async function probeWebSocketSession(parameters) {
 }
 /** Probes a WebSocket endpoint over HTTP and creates the opening credential. */
 export async function prepareWebSocketSession(parameters) {
+    parameters.signal?.throwIfAborted();
     const probed = await probeWebSocketSession(parameters);
-    return {
-        ...probed,
-        credential: await parameters.createSessionCredential(probed.challenge, {}),
-    };
+    parameters.signal?.throwIfAborted();
+    const credential = await parameters.createSessionCredential(probed.challenge, {});
+    parameters.signal?.throwIfAborted();
+    return { ...probed, credential };
 }
 /** Creates the initial runtime state for a paid WebSocket from its opening credential. */
 export function createActiveSocketSession(parameters) {
@@ -741,6 +742,8 @@ export function validateSocketPaymentReceipt(parameters) {
  */
 export async function openWebSocketSession(parameters) {
     const { challenge, credential, options, WebSocket: WebSocketImpl, wsUrl } = parameters;
+    const signal = options?.signal;
+    signal?.throwIfAborted();
     const rawSocket = new WebSocketImpl(wsUrl, options?.protocols);
     const socketState = createActiveSocketSession({
         challenge,
@@ -757,7 +760,13 @@ export async function openWebSocketSession(parameters) {
             rawSocket.close(ClientWebSocketProtocolErrorCloseCode, message);
         }
     };
+    const onAbort = () => {
+        parameters.rejectReceipt(new Error('WebSocket payment flow aborted.'));
+        parameters.rejectCloseReady(new Error('WebSocket payment flow aborted.'));
+        rawSocket.close();
+    };
     rawSocket.addEventListener('close', (event) => {
+        signal?.removeEventListener('abort', onAbort);
         socketState.socket = null;
         socketState.expectedCloseAmount = null;
         parameters.rejectReceipt(new Error('WebSocket closed before the payment flow completed.'));
@@ -785,29 +794,47 @@ export async function openWebSocketSession(parameters) {
             socketState,
         });
     });
-    options?.signal?.addEventListener('abort', () => {
-        parameters.rejectReceipt(new Error('WebSocket payment flow aborted.'));
-        parameters.rejectCloseReady(new Error('WebSocket payment flow aborted.'));
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        await waitForSocketOpen(rawSocket, managedSocket.emit, wsUrl, signal);
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        signal?.removeEventListener('abort', onAbort);
         rawSocket.close();
-    }, { once: true });
-    await waitForSocketOpen(rawSocket, managedSocket.emit, wsUrl);
+        throw error;
+    }
     rawSocket.send(Ws.formatAuthorizationMessage(credential));
     await parameters.waitForReceipt();
     return managedSocket.socket;
 }
-function waitForSocketOpen(rawSocket, managedEmit, wsUrl) {
+function waitForSocketOpen(rawSocket, managedEmit, wsUrl, signal) {
     return new Promise((resolve, reject) => {
-        const onOpen = () => {
+        const cleanup = () => {
+            rawSocket.removeEventListener('open', onOpen);
             rawSocket.removeEventListener('error', onError);
+            rawSocket.removeEventListener('close', onError);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const onOpen = () => {
+            cleanup();
             managedEmit('open', { type: 'open' });
             resolve();
         };
         const onError = () => {
-            rawSocket.removeEventListener('open', onOpen);
+            cleanup();
             reject(new Error(`WebSocket connection to ${wsUrl} failed to open.`));
         };
+        const onAbort = () => {
+            cleanup();
+            reject(signal?.reason);
+        };
         rawSocket.addEventListener('open', onOpen, { once: true });
         rawSocket.addEventListener('error', onError, { once: true });
+        rawSocket.addEventListener('close', onError, { once: true });
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
     });
 }
 async function handleSocketMessage(parameters) {

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

@@ -71,6 +71,8 @@ export type TopUpReceiptFields = {
 };
 /** Typed fields decoded from a Settled receipt event. */
 export type SettledReceiptFields = {
+    /** Amount this settlement paid to the payee. */
+    deltaPaid: bigint;
     /** New cumulative amount settled on-chain. */
     newSettled: bigint;
 };
@@ -153,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

@@ -39,6 +39,7 @@ export function readTopUpReceiptFields(event) {
 /** Reads and validates typed fields from a Settled receipt event. */
 export function readSettledReceiptFields(event) {
     return {
+        deltaPaid: readUint96(event.args.deltaPaid, 'Settled deltaPaid'),
         newSettled: readUint96(event.args.newSettled, 'Settled newSettled'),
     };
 }
@@ -168,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 {
@@ -176,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));
         }

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

@@ -12,12 +12,13 @@ import * as Constants from '../../../Constants.js';
 import * as Errors from '../../../Errors.js';
 import * as Expires from '../../../Expires.js';
 import * as Method from '../../../Method.js';
-import * as Store from '../../../Store.js';
+import * as ChallengeMeta from '../../../server/internal/challengeMeta.js';
 import * as Client from '../../../viem/Client.js';
 import * as Account from '../../internal/account.js';
 import * as defaults from '../../internal/defaults.js';
 import * as Methods from '../../Methods.js';
 import * as ChargeServer from '../../server/Charge.js';
+import { fallbackStore } from '../../server/internal/fallback-store.js';
 import * as Transport from '../../server/internal/transport.js';
 import { tip20ChannelEscrow } from '../precompile/Protocol.js';
 import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as serializeSessionSnapshot, } from '../Snapshot.js';
@@ -58,23 +59,21 @@ function isBootstrapChargeCredential(credential) {
 function createBootstrapChallenge(parameters) {
     return Challenge.fromMethod(Methods.charge, {
         expires: parameters.expires,
+        meta: ChallengeMeta.withNonce(undefined),
         realm: parameters.realm,
         request: parameters.request,
         secretKey: parameters.secretKey,
     });
 }
 function respondBootstrapChallenge(challenge, error) {
-    const headers = new Headers({
-        [Constants.Headers.wwwAuthenticate]: Challenge.serialize(challenge),
-        'Cache-Control': 'no-store',
-    });
+    const headers = new Headers({ 'Cache-Control': 'no-store' });
+    // A 403 is final: omit the challenge, as `Transport.http()` does.
+    if (error?.status !== 403)
+        headers.set(Constants.Headers.wwwAuthenticate, Challenge.serialize(challenge));
     if (!error)
         return new Response(null, { status: 402, headers });
     headers.set('Content-Type', 'application/problem+json');
-    return new Response(JSON.stringify(error.toProblemDetails(challenge.id)), {
-        status: error.status,
-        headers,
-    });
+    return new Response(JSON.stringify(error.toProblemDetails(error.status === 403 ? undefined : challenge.id)), { status: error.status, headers });
 }
 function assertBootstrapChallengeMatches(expected, actual) {
     if (actual.method !== Constants.Methods.tempo || actual.intent !== Constants.Intents.charge)
@@ -162,7 +161,9 @@ async function handleBootstrapPreflight(parameters) {
         });
     }
     catch (error) {
-        return respondBootstrapChallenge(challenge, error instanceof Errors.PaymentError ? error : new Errors.InternalPaymentError());
+        return respondBootstrapChallenge(challenge, error instanceof Errors.PaymentError
+            ? error
+            : new Errors.InternalPaymentError({ cause: error }));
     }
     const channelId = await resolveSessionChannelId({
         capturedRequest: parameters.capturedRequest,
@@ -193,7 +194,7 @@ async function handleBootstrapPreflight(parameters) {
 /** Creates a server-side TIP20EscrowChannel precompile session payment method. */
 export function session(p) {
     const parameters = p;
-    const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = Store.memory(), suggestedDeposit, unitType, } = parameters;
+    const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = fallbackStore('tempo.session'), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
     const onSessionSettlement = parameters.onSessionSettlement;
     const onSessionSettlementFailure = parameters.onSessionSettlementFailure;

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

@@ -250,6 +250,13 @@ export declare class SettlementCheckpointError extends Error {
         txHash: Hex;
     });
 }
+/** Raised when a scheduled settlement could not claim its lease; no transaction was submitted. */
+export declare class SettlementLeaseError extends Error {
+    readonly name = "SettlementLeaseError";
+    constructor(options: {
+        cause: unknown;
+    });
+}
 /** Settles multiple precompile-backed session channels with the same validation as {@link settle}. */
 export declare function settleBatch(store: SessionStoreInput, client: Chain.TransactionClient, channelIds: readonly Hex[], options?: SettlementTransactionOptions): Promise<Hex[]>;
 /**

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

@@ -1,4 +1,4 @@
-import { BaseError as viem_BaseError, HttpRequestError, isAddress, isAddressEqual, LimitExceededRpcError, parseUnits, ResourceUnavailableRpcError, SocketClosedError, TimeoutError, WebSocketRequestError, zeroAddress, } from 'viem';
+import { BaseError as viem_BaseError, ExecutionRevertedError, HttpRequestError, InternalRpcError, isAddress, isAddressEqual, LimitExceededRpcError, parseUnits, ResourceUnavailableRpcError, RpcRequestError, SocketClosedError, TimeoutError, WaitForTransactionReceiptTimeoutError, WebSocketRequestError, zeroAddress, } from 'viem';
 import { BadRequestError, ChannelClosedError, ChannelNotFoundError, InsufficientBalanceError, VerificationFailedError, } from '../../../Errors.js';
 import { isSessionContentRequest } from '../../server/internal/request-body.js';
 import * as Chain from '../precompile/Chain.js';
@@ -251,7 +251,8 @@ export async function maybeSettleScheduled(parameters) {
         store,
     }).catch(async (error) => {
         await report(error);
-        throw error;
+        // Nothing was submitted, so the next settlement can still collect this charge.
+        throw new SettlementLeaseError({ cause: error });
     });
     if (!leaseOwner)
         return undefined;
@@ -274,10 +275,10 @@ export async function maybeSettleScheduled(parameters) {
     })
         .catch(async (error) => {
         await release();
+        await report(error);
         // The transaction confirmed and collected the charge; only the local record failed.
         if (error instanceof SettlementCheckpointError)
             return error.txHash;
-        await report(error);
         throw error;
     })
         .finally(() => clearInterval(renewal));
@@ -306,7 +307,10 @@ export async function settle(store_, client, channelId_, options) {
         sender: account?.address,
     });
     const amount = uint96(channel.highestVoucher.cumulativeAmount);
-    const txHash = await Chain.settleOnChain(client, channel.descriptor, amount, channel.highestVoucher.signature, escrow, account
+    const { signature } = channel.highestVoucher;
+    // A replica behind the open or top-up that admitted this voucher rejects the settle while
+    // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
+    const txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
         ? {
             account,
             ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
@@ -314,13 +318,14 @@ export async function settle(store_, client, channelId_, options) {
             ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
             candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
         }
-        : undefined);
+        : undefined), { shouldRetry: isExecutionRevert });
     const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
     const settled = readSettledReceiptFields(Chain.getChannelEvent(receipt, 'Settled', channelId));
-    const { newSettled } = settled;
+    const { deltaPaid, newSettled } = settled;
     if (newSettled < amount)
         throw new VerificationFailedError({ reason: 'Settled event is below voucher amount' });
-    const state = await Chain.getChannelState(client, channelId, escrow);
+    // A replica behind the receipt's block would report the pre-settlement state.
+    const state = await Chain.readbackWithRetry(() => Chain.getChannelState(client, channelId, escrow, receipt.blockNumber));
     if (state.settled !== newSettled)
         throw new VerificationFailedError({
             reason: 'on-chain channel state does not match settle receipt',
@@ -346,7 +351,8 @@ export async function settle(store_, client, channelId_, options) {
             channelId,
             trigger: 'settle',
             amount: newSettled,
-            delta: newSettled - channel.settledOnChain,
+            // The stored checkpoint can be stale after a failed write; the receipt is authoritative.
+            delta: deltaPaid,
         });
     }
     if (checkpointError)
@@ -363,6 +369,13 @@ export class SettlementCheckpointError extends Error {
         this.txHash = options.txHash;
     }
 }
+/** Raised when a scheduled settlement could not claim its lease; no transaction was submitted. */
+export class SettlementLeaseError extends Error {
+    name = 'SettlementLeaseError';
+    constructor(options) {
+        super('Scheduled settlement lease could not be claimed.', { cause: options.cause });
+    }
+}
 /** Settles multiple precompile-backed session channels with the same validation as {@link settle}. */
 export async function settleBatch(store, client, channelIds, options) {
     const hashes = [];
@@ -379,16 +392,28 @@ export function ignoreRetryableSettlementFailure(error) {
         return undefined;
     throw error;
 }
+/** Whether a settlement failed because the node's execution reverted it. */
+function isExecutionRevert(error) {
+    return (error instanceof viem_BaseError &&
+        Boolean(error.walk((cause) => cause instanceof ExecutionRevertedError)));
+}
 function isRetryableSettlementFailure(error) {
+    if (error instanceof SettlementLeaseError)
+        return true;
     if (!(error instanceof viem_BaseError))
         return false;
     // Only unavailable or overloaded upstreams clear on retry; node-rejected transactions repeat.
     return Boolean(error.walk((cause) => (cause instanceof HttpRequestError &&
         (cause.status === undefined || cause.status === 429 || cause.status >= 500)) ||
+        // Rate limits some providers return in a JSON-RPC body rather than as HTTP 429.
+        (cause instanceof RpcRequestError && cause.code === 429) ||
+        cause instanceof InternalRpcError ||
         cause instanceof LimitExceededRpcError ||
         cause instanceof ResourceUnavailableRpcError ||
         cause instanceof SocketClosedError ||
         cause instanceof TimeoutError ||
+        // The settlement was broadcast; a later settlement collects the charge if it never lands.
+        cause instanceof WaitForTransactionReceiptTimeoutError ||
         cause instanceof WebSocketRequestError));
 }
 /** @internal Reports a settlement failure without letting observer errors replace it. */

package/dist/x402/server/EvmCharge.js

@@ -7,6 +7,7 @@ import * as Credential_ from '../../Credential.js';
 import { VerificationFailedError } from '../../Errors.js';
 import * as Types from '../../evm/Types.js';
 import * as PaymentRequest from '../../PaymentRequest.js';
+import * as ChallengeMeta from '../../server/internal/challengeMeta.js';
 import * as Scope from '../../server/internal/scope.js';
 import * as x402_Header from '../Header.js';
 import * as x402_RouteBinding from '../internal/RouteBinding.js';
@@ -83,8 +84,9 @@ export function createPath(config) {
             const clientNonce = paymentPayload.extensions?.[mppxExtensionKey]?.info.nonce;
             const isRouteBound = clientNonce !== undefined;
             const routeRequiresBinding = challenge.digest !== undefined ||
-                challenge.opaque !== undefined ||
-                challenge.meta !== undefined;
+                (challenge.meta === undefined
+                    ? challenge.opaque !== undefined
+                    : ChallengeMeta.routeMeta(challenge.meta) !== undefined);
             // `extensions.mppx` binding is not part of the x402 spec, so a client mppx
             // did not write cannot produce it. Requiring it makes every scoped route —
             // and everything behind `Proxy`, which scopes what it serves — unpayable by
@@ -296,7 +298,12 @@ function routeExtensions(challenge, input) {
         binding[Scope.reservedMetaKey] = scope;
     if (challenge.digest !== undefined)
         binding.digest = challenge.digest;
-    const opaque = challenge.opaque ?? (challenge.meta ? PaymentRequest.serialize(challenge.meta) : undefined);
+    const meta = ChallengeMeta.routeMeta(challenge.meta);
+    const opaque = challenge.meta === undefined
+        ? challenge.opaque
+        : meta
+            ? PaymentRequest.serialize(meta)
+            : undefined;
     if (opaque !== undefined)
         binding.opaque = opaque;
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",