mppx 0.13.2 → 0.13.4

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

@@ -1,4 +1,4 @@
-import { isAddress, isAddressEqual, parseUnits, zeroAddress, } from 'viem';
+import { BaseError as viem_BaseError, 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';
@@ -105,7 +105,7 @@ export function isSettlementDue(channel, schedule) {
         return true;
     return false;
 }
-/** Records the channel spend/unit counters that a scheduled settlement captured. */
+/** Releases a completed scheduled settlement lease; {@link settle} records the settled counters. */
 export async function markSettlementComplete(parameters) {
     const { channelId, leaseOwner, store, settledAt = new Date().toISOString() } = parameters;
     await store.updateChannel(channelId, (current) => {
@@ -114,12 +114,7 @@ export async function markSettlementComplete(parameters) {
         if (current.scheduledSettlementLease?.owner !== leaseOwner)
             return current;
         const { scheduledSettlementLease: _, ...channel } = current;
-        return {
-            ...channel,
-            lastSettlementAt: settledAt,
-            lastSettlementSpent: current.spent,
-            lastSettlementUnits: current.units,
-        };
+        return { ...channel, lastSettlementAt: settledAt };
     });
 }
 /** Atomically claims one due scheduled settlement across server workers. */
@@ -244,10 +239,20 @@ export async function maybeSettleScheduled(parameters) {
     const { channel, schedule, store } = parameters;
     if (!schedule || !isSettlementDue(channel, schedule))
         return undefined;
+    const report = (error) => reportSessionSettlementFailure(parameters.onSessionSettlementFailure, {
+        chainId: channel.chainId,
+        channelId: channel.channelId,
+        error,
+        trigger: 'scheduled',
+    });
     const leaseOwner = await claimScheduledSettlement({
         channelId: channel.channelId,
         schedule,
         store,
+    }).catch(async (error) => {
+        await report(error);
+        // Nothing was submitted, so the next settlement can still collect this charge.
+        throw new SettlementLeaseError({ cause: error });
     });
     if (!leaseOwner)
         return undefined;
@@ -258,26 +263,28 @@ export async function maybeSettleScheduled(parameters) {
             store,
         }).catch(() => undefined);
     }, scheduledSettlementLeaseMs / 2);
-    try {
-        const txHash = await settle(store, parameters.client, channel.channelId, {
-            account: parameters.account,
-            ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
-            ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
-            ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
-            onSessionSettlement: parameters.onSessionSettlement
-                ? (ctx) => parameters.onSessionSettlement({ ...ctx, trigger: 'scheduled' })
-                : undefined,
-        });
-        await markSettlementComplete({ channelId: channel.channelId, leaseOwner, store });
-        return txHash;
-    }
-    catch (error) {
-        await releaseScheduledSettlement({ channelId: channel.channelId, leaseOwner, store }).catch(() => undefined);
+    const release = () => releaseScheduledSettlement({ channelId: channel.channelId, leaseOwner, store }).catch(() => undefined);
+    const txHash = await settle(store, parameters.client, channel.channelId, {
+        account: parameters.account,
+        ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
+        ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
+        ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
+        onSessionSettlement: parameters.onSessionSettlement
+            ? (ctx) => parameters.onSessionSettlement({ ...ctx, trigger: 'scheduled' })
+            : undefined,
+    })
+        .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;
         throw error;
-    }
-    finally {
-        clearInterval(renewal);
-    }
+    })
+        .finally(() => clearInterval(renewal));
+    // Bookkeeping after a confirmed settlement must not fail the charged request.
+    await markSettlementComplete({ channelId: channel.channelId, leaseOwner, store }).catch(release);
+    return txHash;
 }
 /** Settles the highest accepted voucher for a precompile-backed session channel. */
 export async function settle(store_, client, channelId_, options) {
@@ -311,34 +318,61 @@ export async function settle(store_, client, channelId_, options) {
         : undefined);
     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',
         });
-    await store.updateChannel(channelId, (current) => current
+    let checkpointError;
+    await store
+        .updateChannel(channelId, (current) => current
         ? {
             ...current,
             settledOnChain: newSettled > current.settledOnChain ? newSettled : current.settledOnChain,
             lastSettlementAt: new Date().toISOString(),
-            lastSettlementSpent: current.spent,
-            lastSettlementUnits: current.units,
+            // Charges accepted after the voucher was read are not covered by this transaction.
+            lastSettlementSpent: ChannelStore.keepGreater(current.lastSettlementSpent ?? 0n, channel.spent),
+            lastSettlementUnits: Math.max(current.lastSettlementUnits ?? 0, channel.units),
         }
-        : current);
+        : current)
+        .catch((cause) => {
+        checkpointError = { cause };
+    });
     if (options?.onSessionSettlement) {
         await emitSessionSettlement(options.onSessionSettlement, {
             txHash,
             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)
+        throw new SettlementCheckpointError({ cause: checkpointError.cause, txHash });
     return txHash;
 }
+/** Raised when a settlement transaction confirmed but the channel store could not record it. */
+export class SettlementCheckpointError extends Error {
+    name = 'SettlementCheckpointError';
+    /** Hash of the confirmed settlement transaction. */
+    txHash;
+    constructor(options) {
+        super(`Settlement ${options.txHash} confirmed but was not recorded.`, { cause: options.cause });
+        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 = [];
@@ -346,6 +380,43 @@ export async function settleBatch(store, client, channelIds, options) {
         hashes.push(await settle(store, client, channelId, options));
     return hashes;
 }
+/**
+ * @internal Keeps a charged request served when its scheduled settlement hit a transport or RPC
+ * failure; the next settlement retries it. Reverts and configuration errors fail the request.
+ */
+export function ignoreRetryableSettlementFailure(error) {
+    if (isRetryableSettlementFailure(error))
+        return undefined;
+    throw error;
+}
+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. */
+export async function reportSessionSettlementFailure(onSessionSettlementFailure, context) {
+    try {
+        await onSessionSettlementFailure?.(Object.freeze(context));
+    }
+    catch {
+        // Errors are isolated: observers cannot replace the settlement failure.
+    }
+}
 async function emitSessionSettlement(onSessionSettlement, context) {
     try {
         await onSessionSettlement(Object.freeze(context));

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

@@ -2,5 +2,5 @@ export { charge, session, settle, settleBatch } from './Session.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
 /** Server-side automatic settlement schedule. */
-export type { OnSessionSettlement, ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SessionSettlementContext, SettlementSchedule, } from './Session.js';
+export type { OnSessionSettlement, OnSessionSettlementFailure, ResolveSessionChannelId, ResolveSessionChannelIdParameters, SessionChannelIdRequest, SessionSettlementContext, SessionSettlementFailureContext, SettlementSchedule, } from './Session.js';
 //# sourceMappingURL=index.d.ts.map

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.2",
+  "version": "0.13.4",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",