mppx 0.8.17 → 0.8.18

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

@@ -3,9 +3,10 @@ import * as Constants from '../../../Constants.js';
 import { VerificationFailedError } from '../../../Errors.js';
 import * as Methods from '../../Methods.js';
 import { captureRequestBodyProbe, isSessionContentRequest, } from '../../server/internal/request-body.js';
-import { tip20ChannelEscrow } from '../precompile/Protocol.js';
+import { tip20ChannelEscrow, uint96, } from '../precompile/Protocol.js';
+import * as Voucher from '../precompile/Voucher.js';
 import * as ChannelStore from './ChannelStore.js';
-import { requireSessionCredentialAction } from './CredentialVerification.js';
+import { requireSessionCredentialAction, requireSessionCredentialPayload, } from './CredentialVerification.js';
 import { resolveCredentialFeePayer, resolveRequestFeePayer, } from './Settlement.js';
 /** Normalizes a session channel ID hint when one is present. */
 export function normalizeSessionChannelId(value) {
@@ -29,6 +30,27 @@ function normalizeResolvedSessionChannelId(value) {
         return undefined;
     return ChannelStore.normalizeChannelId(value);
 }
+/** Returns a close credential's channel once its voucher signature verifies. */
+async function verifiedCloseCredentialChannel(credential, store) {
+    try {
+        const payload = requireSessionCredentialPayload(credential?.payload);
+        if (payload.action !== 'close')
+            return undefined;
+        const channelId = payload.channelId;
+        const channel = await store.getChannel(channelId);
+        if (!channel || !ChannelStore.isPrecompileState(channel))
+            return undefined;
+        const verified = Voucher.verifyVoucher(channel.escrowContract, channel.chainId, {
+            channelId,
+            cumulativeAmount: uint96(BigInt(payload.cumulativeAmount)),
+            signature: payload.signature,
+        }, channel.authorizedSigner);
+        return verified ? { channelId, channel } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Resolves the channel ID used to build server-side session bootstrap hints. */
 export async function resolveSessionChannelId(parameters) {
     const { capturedRequest, credential, request, resolveChannelId, source, store } = parameters;
@@ -47,10 +69,10 @@ export async function resolveSessionChannelId(parameters) {
 }
 /** Builds server bootstrap hints for a reusable precompile session channel. */
 export async function resolveSessionSnapshot(parameters) {
-    const { amount, channelId, expected, store } = parameters;
+    const { amount, channelId, expected, matchPaymentFields, store } = parameters;
     if (!channelId)
         return undefined;
-    const channel = await store.getChannel(ChannelStore.normalizeChannelId(channelId));
+    const channel = parameters.channel ?? (await store.getChannel(ChannelStore.normalizeChannelId(channelId)));
     if (!channel || !ChannelStore.isPrecompileState(channel))
         return undefined;
     if (channel.finalized)
@@ -61,8 +83,18 @@ export async function resolveSessionSnapshot(parameters) {
         return undefined;
     if (channel.highestVoucher.cumulativeAmount !== channel.highestVoucherAmount)
         return undefined;
-    if (expected && !matchesSnapshotPaymentFields(channel, expected))
-        return undefined;
+    if (expected && !matchesSnapshotPaymentFields(channel, expected)) {
+        // The snapshot is an optional reuse hint: a failing matcher (for example a
+        // transient RPC error during the route check) must omit the hint rather
+        // than fail challenge issuance or bootstrap preflight.
+        let matched = false;
+        try {
+            matched = (await matchPaymentFields?.(channel, expected)) ?? false;
+        }
+        catch { }
+        if (!matched)
+            return undefined;
+    }
     const requiredCumulative = channel.spent + amount;
     return {
         acceptedCumulative: channel.highestVoucherAmount.toString(),
@@ -115,6 +147,9 @@ function isCanonicalSessionMethodDetails(value) {
         typeof value.escrowContract === 'string' &&
         isAddress(value.escrowContract, { strict: false }) &&
         (value.feePayer === undefined || typeof value.feePayer === 'boolean') &&
+        (value.feeToken === undefined ||
+            (typeof value.feeToken === 'string' && isAddress(value.feeToken, { strict: false }))) &&
+        (value.machineTokenEnabled === undefined || typeof value.machineTokenEnabled === 'boolean') &&
         (value.minVoucherDelta === undefined || typeof value.minVoucherDelta === 'string') &&
         (value.operator === undefined ||
             (typeof value.operator === 'string' && isAddress(value.operator, { strict: false }))) &&
@@ -156,7 +191,7 @@ export async function resolveRequestChainId(parameters) {
 }
 /** Resolves request-time TIP-1034 details and server bootstrap hints for a challenge. */
 export async function resolveSessionPaymentRequest(parameters) {
-    const { capturedRequest, credential, decimals, defaultFeePayer, getClient, parameterChainId, parameterEscrowContract, parameterFeePayer, request, resolveChannelId, source, store, } = parameters;
+    const { capturedRequest, credential, decimals, defaultFeePayer, getClient, matchSnapshotPaymentFields, parameterChainId, parameterEscrowContract, parameterFeePayer, request, resolveChannelId, source, store, } = parameters;
     const chainId = await resolveRequestChainId({
         getClient,
         parameterChainId,
@@ -170,16 +205,24 @@ export async function resolveSessionPaymentRequest(parameters) {
     const escrowContract = resolveRequestEscrowContract(request.escrowContract, parameterEscrowContract);
     const operator = resolveRequestOperator(request.operator);
     const requestAmount = parseUnits(request.amount, decimals);
-    const channelId = await resolveSessionChannelId({
-        capturedRequest,
-        credential,
-        request,
-        resolveChannelId,
-        source,
-        store,
-    });
+    // A close credential names the channel it settles; advertising that channel's
+    // snapshot on the retry challenge lets clients without a configured
+    // `resolveChannelId` learn the exact capture amount a machine-token close
+    // voucher must match. Only trusted once the voucher signature verifies, and
+    // matched with close semantics so retired routes stay closable.
+    const verifiedClose = await verifiedCloseCredentialChannel(credential, store);
+    const channelId = verifiedClose?.channelId ??
+        (await resolveSessionChannelId({
+            capturedRequest,
+            credential,
+            request,
+            resolveChannelId,
+            source,
+            store,
+        }));
     const sessionSnapshot = await resolveSessionSnapshot({
         amount: capturedRequest && !isSessionContentRequest(capturedRequest) ? 0n : requestAmount,
+        channel: verifiedClose?.channel,
         channelId,
         expected: {
             chainId,
@@ -187,6 +230,9 @@ export async function resolveSessionPaymentRequest(parameters) {
             escrowContract,
             recipient: readChallengeAddress(request.recipient, 'recipient'),
         },
+        matchPaymentFields: matchSnapshotPaymentFields && (verifiedClose || request.machineTokenEnabled)
+            ? (channel, expected) => matchSnapshotPaymentFields(channel, expected, verifiedClose ? { action: 'close' } : undefined)
+            : undefined,
         store,
     });
     const { operator: _operator, ...requestWithoutOperator } = request;

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

@@ -36,6 +36,7 @@ export declare function session<const parameters extends session.Parameters>(p?:
         credential: {
             payload: import("zod/mini").ZodMiniDiscriminatedUnion<[import("zod/mini").ZodMiniObject<{
                 action: import("zod/mini").ZodMiniLiteral<"open">;
+                authorizationSignature: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 authorizedSigner: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 channelId: import("zod/mini").ZodMiniString<string>;
                 cumulativeAmount: import("zod/mini").ZodMiniString<string>;
@@ -52,15 +53,18 @@ export declare function session<const parameters extends session.Parameters>(p?:
                 type: import("zod/mini").ZodMiniLiteral<"transaction">;
             }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
                 action: import("zod/mini").ZodMiniLiteral<"voucher">;
+                authorizationSignature: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 channelId: import("zod/mini").ZodMiniString<string>;
                 cumulativeAmount: import("zod/mini").ZodMiniString<string>;
                 descriptor: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<import("../precompile/Protocol.js").ChannelDescriptor, import("../precompile/Protocol.js").ChannelDescriptor>>;
                 signature: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniObject<{
                 action: import("zod/mini").ZodMiniLiteral<"close">;
+                authorizationSignature: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 channelId: import("zod/mini").ZodMiniString<string>;
                 cumulativeAmount: import("zod/mini").ZodMiniString<string>;
                 descriptor: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<import("../precompile/Protocol.js").ChannelDescriptor, import("../precompile/Protocol.js").ChannelDescriptor>>;
+                refundSignature: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 signature: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>], "action">;
         };
@@ -72,6 +76,8 @@ export declare function session<const parameters extends session.Parameters>(p?:
             decimals: import("zod/mini").ZodMiniNumber<number>;
             escrowContract: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             feePayer: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniUnion<readonly [import("zod/mini").ZodMiniBoolean<boolean>, import("zod/mini").ZodMiniCustom<import("viem").Account, import("viem").Account>]>, import("zod/mini").ZodMiniTransform<boolean, boolean | import("viem").Account>>>;
+            feeToken: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+            machineTokenEnabled: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniBoolean<boolean>>;
             minVoucherDelta: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             operator: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             recipient: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
@@ -94,6 +100,8 @@ export declare function session<const parameters extends session.Parameters>(p?:
                 minVoucherDelta?: string | undefined;
                 chainId?: number | undefined;
                 feePayer?: boolean | undefined;
+                feeToken?: string | undefined;
+                machineTokenEnabled?: boolean | undefined;
                 operator?: string | undefined;
                 sessionProtocol?: "v1" | "v2" | undefined;
                 sessionSnapshot?: import("../Snapshot.js").SessionSnapshot | undefined;
@@ -106,6 +114,8 @@ export declare function session<const parameters extends session.Parameters>(p?:
             decimals: number;
             escrowContract?: string | undefined;
             feePayer?: boolean | undefined;
+            feeToken?: string | undefined;
+            machineTokenEnabled?: boolean | undefined;
             minVoucherDelta?: string | undefined;
             operator?: string | undefined;
             recipient?: string | undefined;
@@ -167,14 +177,16 @@ export declare namespace session {
         sse?: boolean | Transport.sse.Options | undefined;
         /** Tempo chain ID used for TIP-1034 channel escrow challenges. Defaults to the resolved client chain ID. */
         chainId?: number | undefined;
-        /** TIP20EscrowChannel precompile address override. */
+        /** Escrow contract advertised to clients. Defaults to the canonical TIP20EscrowChannel address. */
         escrowContract?: Address | undefined;
         /** Callback invoked after any on-chain settlement or close transaction is confirmed. */
         onSessionSettlement?: OnSessionSettlement | undefined;
         /** Server-owned automatic settlement cadence. Clients do not receive or control this schedule. */
         settlementSchedule?: SettlementSchedule | undefined;
-        /** Optional fee token used for server-driven close transactions. */
+        /** Optional fee token for management and server-driven settle/close transactions. */
         feeToken?: Address | undefined;
+        /** Enables first-party machine-token funding when the configured deployment is available. */
+        machineTokenEnabled?: boolean | undefined;
     } & Account.resolve.Parameters & Client.getResolver.Parameters & Defaults & Method.ComposableHooks<typeof Methods.session>;
     /** Defaults derived from `session()` parameters for handler type inference. */
     type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<parameters, Defaults, {

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

@@ -5,7 +5,7 @@
  * and one-shot settlement. Each incoming request carries a session credential
  * with a cumulative voucher that the server validates and records.
  */
-import { isAddress } from 'viem';
+import { isAddress, isAddressEqual } from 'viem';
 import { tempo as tempo_chain } from 'viem/chains';
 import * as Challenge from '../../../Challenge.js';
 import * as Constants from '../../../Constants.js';
@@ -16,6 +16,7 @@ import * as Store from '../../../Store.js';
 import * as Client from '../../../viem/Client.js';
 import * as Account from '../../internal/account.js';
 import * as defaults from '../../internal/defaults.js';
+import * as MachineTokenSession from '../../internal/machine-token-session.js';
 import * as Methods from '../../Methods.js';
 import * as ChargeServer from '../../server/Charge.js';
 import * as Transport from '../../server/internal/transport.js';
@@ -178,6 +179,9 @@ async function handleBootstrapPreflight(parameters) {
             escrowContract: resolveBootstrapEscrowContract(parameters.paymentRequest, parameters.parameterEscrowContract),
             recipient: readBootstrapAddress(request.recipient, 'recipient'),
         },
+        matchPaymentFields: parameters.paymentRequest.machineTokenEnabled
+            ? parameters.matchSnapshotPaymentFields
+            : undefined,
         store: parameters.store,
     });
     const headers = new Headers({ 'Cache-Control': 'no-store' });
@@ -190,19 +194,33 @@ 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, machineTokenEnabled, operator, store: rawStore = Store.memory(), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
     const onSessionSettlement = parameters.onSessionSettlement;
     const store = ChannelStore.fromStore(rawStore);
     const lastOnChainVerified = new Map();
     const { account, feePayer, feePayerUrl, recipient } = Account.resolve(parameters);
     const configuredFeePayer = feePayer ?? feePayerUrl;
+    const settlementFeePayer = feePayer ?? (feePayerUrl ? true : undefined);
     const getClient = Client.getResolver({
         chain: tempo_chain,
         feePayerUrl,
         getClient: parameters.getClient,
         rpcUrl: defaults.rpcUrl,
     });
+    const matchSnapshotPaymentFields = async (channel, expected, options) => {
+        if (channel.chainId !== expected.chainId ||
+            !isAddressEqual(channel.escrowContract, expected.escrowContract) ||
+            !isAddressEqual(expected.escrowContract, tip20ChannelEscrow))
+            return false;
+        return !!(await MachineTokenSession.matchRoute(await getClient({ chainId: expected.chainId }), {
+            active: options?.action !== 'close',
+            chainId: expected.chainId,
+            descriptor: channel.descriptor,
+            merchant: expected.recipient,
+            targetToken: expected.currency,
+        }));
+    };
     const settleScheduled = async (channel) => {
         if (!isSettlementDue(channel, settlementSchedule))
             return undefined;
@@ -210,7 +228,7 @@ export function session(p) {
             account,
             channel,
             client: await getClient({ chainId: channel.chainId }),
-            ...(feePayer ? { feePayer } : {}),
+            ...(settlementFeePayer ? { feePayer: settlementFeePayer } : {}),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: parameters.feeToken,
             onSessionSettlement,
@@ -260,6 +278,7 @@ export function session(p) {
             expectedOperator: context.methodDetails.operator,
             feePayer: context.feePayer,
             feePayerPolicy: parameters.feePayerPolicy,
+            feeToken: context.methodDetails.feeToken,
             lastOnChainVerified,
             minVoucherDelta: context.minVoucherDelta,
             payload,
@@ -296,7 +315,7 @@ export function session(p) {
             expectedOperator: context.methodDetails.operator,
             feePayer: context.feePayer,
             feePayerPolicy: parameters.feePayerPolicy,
-            feeToken: parameters.feeToken,
+            feeToken: context.methodDetails.feeToken,
             lastOnChainVerified,
             minVoucherDelta: context.minVoucherDelta,
             onSessionSettlement,
@@ -314,7 +333,7 @@ export function session(p) {
             settleCharged: (channel) => maybeSettleScheduled({
                 account,
                 client: context.client,
-                ...(typeof context.feePayer === 'object' ? { feePayer: context.feePayer } : {}),
+                ...(context.feePayer ? { feePayer: context.feePayer } : {}),
                 feePayerPolicy: parameters.feePayerPolicy,
                 feeToken: parameters.feeToken,
                 onSessionSettlement,
@@ -331,6 +350,7 @@ export function session(p) {
             amount,
             currency,
             decimals,
+            machineTokenEnabled,
             operator,
             recipient,
             suggestedDeposit,
@@ -351,6 +371,7 @@ export function session(p) {
                     defaultRecipient: recipient,
                     expires,
                     getClient,
+                    matchSnapshotPaymentFields,
                     parameterChainId: parameters.chainId,
                     parameterEscrowContract: parameters.escrowContract,
                     paymentRequest: options,
@@ -368,6 +389,7 @@ export function session(p) {
                 decimals,
                 defaultFeePayer: feePayer,
                 getClient,
+                matchSnapshotPaymentFields,
                 parameterChainId: parameters.chainId,
                 parameterEscrowContract: parameters.escrowContract,
                 parameterFeePayer: parameters.feePayer,
@@ -375,8 +397,17 @@ export function session(p) {
                 resolveChannelId: parameters.resolveChannelId,
                 store,
             });
+            // Only advertise the capability when this logical session can use a
+            // configured unified router on the canonical escrow.
+            const { machineTokenEnabled: requestedMachineTokenEnabled, ...requestWithoutMachineToken } = resolvedRequest;
+            const machineSessionSupported = MachineTokenSession.isSupported(resolvedRequest.chainId) &&
+                isAddressEqual(resolvedRequest.escrowContract, tip20ChannelEscrow);
             return {
-                ...resolvedRequest,
+                ...requestWithoutMachineToken,
+                feeToken: parameters.feeToken,
+                ...(requestedMachineTokenEnabled && machineSessionSupported
+                    ? { machineTokenEnabled: true }
+                    : {}),
                 sessionProtocol: Constants.SessionProtocols.v2,
             };
         },

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

@@ -160,8 +160,8 @@ export type SettlementTransactionOptions = {
     candidateFeeTokens?: readonly Address[] | undefined;
     /** TIP20EscrowChannel precompile address override. */
     escrowContract?: Address | undefined;
-    /** Optional fee-payer account for sponsored settlement. */
-    feePayer?: viem_Account | undefined;
+    /** Fee-payer account, or `true` when the client transport uses a configured hosted fee-payer service. */
+    feePayer?: viem_Account | true | undefined;
     /** Optional policy for sponsored settlement. */
     feePayerPolicy?: Partial<FeePayer.Policy> | undefined;
     /** Optional fee token override for settlement. */
@@ -177,8 +177,8 @@ export type MaybeSettleScheduledParameters = {
     channel: ChannelStore.State;
     /** viem client used to settle on-chain. */
     client: Chain.TransactionClient;
-    /** Optional fee-payer account for sponsored settlement. */
-    feePayer?: viem_Account | undefined;
+    /** Fee-payer account, or `true` when the client transport uses a configured hosted fee-payer service. */
+    feePayer?: viem_Account | true | undefined;
     /** Optional policy for sponsored settlement. */
     feePayerPolicy?: Partial<FeePayer.Policy> | undefined;
     /** Optional fee token override for settlement. */
@@ -198,6 +198,13 @@ export declare function getClientAccount(client: {
 }): viem_Account | undefined;
 /** Validates that the transaction sender is the channel payee or nonzero operator. */
 export declare function assertSettlementSender(parameters: SettlementSenderParameters): void;
+/**
+ * Assembles transaction options for settle/close transactions. Machine
+ * channels pin PathUSD (or an explicit override); direct channels leave the
+ * fee token unset so balance-aware selection can pick a funded candidate.
+ * The rail comes from the caller so fee pinning always matches dispatch.
+ */
+export declare function resolveChannelTransactionOptions(channel: Pick<ChannelStore.StoredPrecompileChannel, 'chainId' | 'token'>, options: SettlementTransactionOptions | undefined, account: viem_Account | undefined, machineRouter: Address | undefined): Chain.ChannelTransactionOptions | undefined;
 /** Applies automatic settlement when the server-owned schedule is due. */
 export declare function maybeSettleScheduled(parameters: MaybeSettleScheduledParameters): Promise<Hex | undefined>;
 /** Settles the highest accepted voucher for a precompile-backed session channel. */

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

@@ -1,5 +1,6 @@
 import { isAddress, isAddressEqual, parseUnits, zeroAddress, } from 'viem';
 import { BadRequestError, ChannelClosedError, ChannelNotFoundError, InsufficientBalanceError, VerificationFailedError, } from '../../../Errors.js';
+import * as MachineTokenSession from '../../internal/machine-token-session.js';
 import { isSessionContentRequest } from '../../server/internal/request-body.js';
 import * as Chain from '../precompile/Chain.js';
 import { readSettledReceiptFields } from '../precompile/Chain.js';
@@ -28,12 +29,10 @@ export function resolveRequestFeePayer(parameters) {
     if (requestFeePayer === false)
         return credential ? false : undefined;
     const account = typeof requestFeePayer === 'object' ? requestFeePayer : defaultFeePayer;
+    const hosted = parameterFeePayer === true || typeof parameterFeePayer === 'string';
     if (credential)
-        return account ?? undefined;
-    if (account ||
-        defaultFeePayer ||
-        parameterFeePayer === true ||
-        typeof parameterFeePayer === 'string')
+        return account ?? (hosted ? true : undefined);
+    if (account || hosted)
         return true;
     return undefined;
 }
@@ -184,6 +183,30 @@ export function assertSettlementSender(parameters) {
             ' If using an access key, pass a Tempo access-key account whose address is the payee/operator wallet, not the raw delegated key address.',
     });
 }
+/**
+ * Assembles transaction options for settle/close transactions. Machine
+ * channels pin PathUSD (or an explicit override); direct channels leave the
+ * fee token unset so balance-aware selection can pick a funded candidate.
+ * The rail comes from the caller so fee pinning always matches dispatch.
+ */
+export function resolveChannelTransactionOptions(channel, options, account, machineRouter) {
+    if (!account)
+        return undefined;
+    const feeToken = options?.feeToken ??
+        (machineRouter
+            ? MachineTokenSession.resolveFeeToken({
+                chainId: channel.chainId,
+                paymentToken: channel.token,
+            })
+            : undefined);
+    return {
+        account,
+        ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
+        ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
+        ...(feeToken ? { feeToken } : {}),
+        candidateFeeTokens: options?.candidateFeeTokens ?? [feeToken ?? channel.token],
+    };
+}
 /** Applies automatic settlement when the server-owned schedule is due. */
 export async function maybeSettleScheduled(parameters) {
     const { channel, schedule, store } = parameters;
@@ -214,23 +237,32 @@ export async function settle(store_, client, channelId_, options) {
         throw new VerificationFailedError({ reason: 'no voucher to settle' });
     const escrow = options?.escrowContract ?? channel.escrowContract;
     const account = options?.account ?? getClientAccount(client);
-    assertSettlementSender({
-        operation: 'settle',
-        channelId,
-        operator: channel.operator,
-        payee: channel.payee,
-        sender: account?.address,
-    });
+    const machineRouter = MachineTokenSession.matchDeployment({
+        chainId: channel.chainId,
+        descriptor: channel.descriptor,
+    })?.swap;
+    if (!machineRouter || !account)
+        assertSettlementSender({
+            operation: 'settle',
+            channelId,
+            operator: channel.operator,
+            payee: channel.payee,
+            sender: account?.address,
+        });
     const amount = uint96(channel.highestVoucher.cumulativeAmount);
-    const txHash = await Chain.settleOnChain(client, channel.descriptor, amount, channel.highestVoucher.signature, escrow, account
-        ? {
-            account,
-            ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
-            ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
-            ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
-            candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
-        }
-        : undefined);
+    const transactionOptions = resolveChannelTransactionOptions(channel, options, account, machineRouter);
+    let txHash;
+    if (machineRouter) {
+        const authorizationSignature = channel.highestVoucher.authorizationSignature;
+        if (!authorizationSignature)
+            throw new VerificationFailedError({
+                reason: 'machine-token voucher is missing its router authorization',
+            });
+        txHash = await Chain.settleMachineSessionOnChain(client, channel.descriptor, amount, channel.highestVoucher.signature, authorizationSignature, machineRouter, transactionOptions);
+    }
+    else {
+        txHash = await Chain.settleOnChain(client, channel.descriptor, amount, channel.highestVoucher.signature, escrow, transactionOptions);
+    }
     const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
     const settled = readSettledReceiptFields(Chain.getChannelEvent(receipt, 'Settled', channelId));
     const { newSettled } = settled;

package/dist/x402/client/Exact.d.ts

@@ -6,6 +6,8 @@ import * as Types from '../Types.js';
  * Creates an x402 exact `PAYMENT-SIGNATURE` credential.
  */
 export declare function createCredential(parameters: createCredential.Parameters): Promise<string>;
+/** Returns whether this client can sign the given x402 exact challenge. */
+export declare function canHandleChallenge(parameters: canHandleChallenge.Parameters): boolean;
 export declare namespace createCredential {
     type Parameters = {
         challenge: Challenge.Challenge<Types.ExactRequest>;
@@ -13,6 +15,12 @@ export declare namespace createCredential {
         context?: Context | undefined;
     };
 }
+export declare namespace canHandleChallenge {
+    type Parameters = {
+        challenge: Challenge.Challenge<Types.ExactRequest>;
+        config: Config;
+    };
+}
 export type Context = {
     account?: Account | undefined;
 };

package/dist/x402/client/Exact.js

@@ -13,9 +13,11 @@ export async function createCredential(parameters) {
     const request = parameters.challenge.request;
     const accepted = Types.toPaymentRequirements(request);
     assertPolicy(parameters.config, accepted);
-    if (!request.resource || !request.extensions?.mppx)
-        throw new Error('x402 exact EIP-3009 requires route binding.');
-    const extensions = withNonceSalt(request.extensions);
+    if (!request.resource)
+        throw new Error('x402 exact EIP-3009 requires resource information.');
+    const extensions = request.extensions?.mppx
+        ? withNonceSalt(request.extensions)
+        : request.extensions;
     const transferMethod = accepted.extra?.assetTransferMethod ?? 'eip3009';
     if (transferMethod !== 'eip3009')
         throw new Error(`x402 exact ${String(transferMethod)} signing is not implemented yet.`);
@@ -26,11 +28,13 @@ export async function createCredential(parameters) {
     const now = Math.floor(Date.now() / 1000);
     const authorization = {
         from: getAddress(account.address),
-        nonce: RouteBinding.nonce({
-            accepted,
-            extensions,
-            resource: request.resource,
-        }),
+        nonce: extensions?.mppx
+            ? RouteBinding.nonce({
+                accepted,
+                extensions,
+                resource: request.resource,
+            })
+            : randomAuthorizationNonce(),
         to: getAddress(accepted.payTo),
         validAfter: (now - 600).toString(),
         validBefore: (now + accepted.maxTimeoutSeconds).toString(),
@@ -54,7 +58,7 @@ export async function createCredential(parameters) {
     });
     return Header.encodePaymentSignature({
         accepted,
-        extensions,
+        ...(extensions ? { extensions } : {}),
         payload: {
             authorization,
             signature,
@@ -63,6 +67,26 @@ export async function createCredential(parameters) {
         x402Version: 2,
     });
 }
+/** Returns whether this client can sign the given x402 exact challenge. */
+export function canHandleChallenge(parameters) {
+    const request = parameters.challenge.request;
+    let accepted;
+    try {
+        accepted = Types.toPaymentRequirements(request);
+        assertPolicy(parameters.config, accepted);
+    }
+    catch {
+        return false;
+    }
+    if (!request.resource)
+        return false;
+    const transferMethod = accepted.extra?.assetTransferMethod ?? 'eip3009';
+    if (transferMethod !== 'eip3009')
+        return false;
+    const name = accepted.extra?.name;
+    const version = accepted.extra?.version;
+    return typeof name === 'string' && typeof version === 'string';
+}
 const authorizationTypes = {
     TransferWithAuthorization: [
         { name: 'from', type: 'address' },
@@ -125,10 +149,16 @@ function withNonceSalt(extensions) {
     };
 }
 function randomNonceSalt() {
+    return randomBytes32().slice(2);
+}
+function randomAuthorizationNonce() {
+    return randomBytes32();
+}
+function randomBytes32() {
     const crypto = globalThis.crypto;
     if (!crypto?.getRandomValues)
         throw new Error('x402 exact requires crypto randomness.');
     const bytes = crypto.getRandomValues(new Uint8Array(32));
-    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
 }
 //# sourceMappingURL=Exact.js.map

package/dist/x402/server/EvmCharge.d.ts

@@ -9,11 +9,33 @@ export type Options = {
     fetch?: typeof globalThis.fetch | undefined;
     /** Maximum time in seconds allowed for x402-compatible payment completion. @default 300 */
     maxTimeoutSeconds?: number | undefined;
+    /**
+     * How a route-scoped charge binds an x402 credential to its route.
+     *
+     * - `'resource'` — accept either binding. A credential carrying
+     *   `extensions.mppx` is verified in full, including the route-bound nonce; one
+     *   without it is bound the way x402 itself binds, by comparing the echoed
+     *   `resource` and `accepted`. Any spec-compliant client can pay a scoped route.
+     * - `'required'` — every credential must carry `extensions.mppx` and the
+     *   route-bound nonce. Only clients that implement mppx's binding can pay.
+     *
+     * `'resource'` is weaker for clients that don't bind: `resource` sits outside
+     * the EIP-3009 signature, so a holder of a valid payload could re-present it at
+     * another route with identical `accepted`. It prevents honest cross-route reuse
+     * and client bugs, not an active attacker. Body binding is unaffected either
+     * way — `challenge.digest` is verified against the actual body.
+     *
+     * @default 'resource'
+     */
+    routeBinding?: RouteBindingMode | undefined;
 };
+/** How a route-scoped charge binds an x402 credential to its route. */
+export type RouteBindingMode = 'required' | 'resource';
 export type ResolvedOptions = {
     authorization: Types.AuthorizationConfig;
     facilitator?: x402_Types.Facilitator | undefined;
     maxTimeoutSeconds: number;
+    routeBinding: RouteBindingMode;
 };
 export type Path = {
     bindCredential: NonNullable<ServerTransport.Http['bindCredential']>;