mppx 0.8.17 → 0.8.18

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

@@ -1,5 +1,6 @@
 import { isAddress, isAddressEqual, zeroAddress, } from 'viem';
 import { AmountExceedsDepositError, ChannelClosedError, ChannelNotFoundError, InsufficientBalanceError, InvalidSignatureError, VerificationFailedError, } from '../../../Errors.js';
+import * as MachineTokenSession from '../../internal/machine-token-session.js';
 import * as Chain from '../precompile/Chain.js';
 import { readChannelClosedReceiptFields } from '../precompile/Chain.js';
 import * as Channel from '../precompile/Channel.js';
@@ -7,20 +8,13 @@ import { createSessionReceipt, uint96, } from '../precompile/Protocol.js';
 import * as Voucher from '../precompile/Voucher.js';
 import * as ChannelStore from './ChannelStore.js';
 import { getChallengePaymentFields } from './RequestState.js';
-import { assertSettlementSender, getClientAccount } from './Settlement.js';
+import { assertSettlementSender, getClientAccount, resolveChannelTransactionOptions, } from './Settlement.js';
 /** Returns the effective voucher signer for a TIP-1034 descriptor. */
 export function authorizedSigner(descriptor) {
     return isAddressEqual(descriptor.authorizedSigner, zeroAddress)
         ? descriptor.payer
         : descriptor.authorizedSigner;
 }
-/** Asserts that a credential payload includes a TIP-1034 descriptor. */
-export function assertDescriptor(payload) {
-    if (!payload.descriptor)
-        throw new VerificationFailedError({
-            reason: 'descriptor required for TIP-1034 session action',
-        });
-}
 /** Asserts that two TIP-1034 descriptors identify the same channel. */
 export function assertSameDescriptor(a, b) {
     if (!isAddressEqual(a.payer, b.payer) ||
@@ -58,6 +52,53 @@ export function validateChannelDescriptor(descriptor, channelId, chainId, escrow
         });
     }
 }
+async function resolveCredentialRoute(parameters) {
+    const { challenge, chainId, client, escrow, payload } = parameters;
+    const { descriptor } = payload;
+    const channelId = ChannelStore.normalizeChannelId(payload.channelId);
+    if (Channel.computeId({ ...descriptor, chainId, escrow }).toLowerCase() !== channelId.toLowerCase())
+        throw new VerificationFailedError({ reason: 'channel descriptor does not match channelId' });
+    const request = getChallengePaymentFields(challenge);
+    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const direct = isAddressEqual(descriptor.payee, request.recipient) &&
+        isAddressEqual(descriptor.token, request.currency) &&
+        isAddressEqual(descriptor.operator, expectedOperator);
+    if (direct)
+        return {
+            allowedFeeTokens: MachineTokenSession.allowedSponsoredFeeTokens({
+                chainId,
+                override: parameters.feeToken,
+                paymentToken: request.currency,
+            }),
+            expectedOperator,
+            payment: request,
+        };
+    if (payload.action !== 'close' && !MachineTokenSession.isEnabledChallenge(challenge))
+        throw new VerificationFailedError({ reason: 'credential descriptor does not match challenge' });
+    const route = await MachineTokenSession.matchRoute(client, {
+        active: payload.action !== 'close',
+        chainId,
+        descriptor,
+        merchant: request.recipient,
+        targetToken: request.currency,
+    });
+    if (!route)
+        throw new VerificationFailedError({
+            reason: 'machine-token channel is not bound to the challenged merchant and currency',
+        });
+    return {
+        allowedFeeTokens: [
+            MachineTokenSession.resolveFeeToken({
+                chainId,
+                override: parameters.feeToken,
+                paymentToken: route.token,
+            }),
+        ],
+        expectedOperator: route.operator,
+        machineRouter: route.operator,
+        payment: { ...request, currency: route.token, recipient: route.payee },
+    };
+}
 /** Validates on-chain channel state before accepting or charging a credential. */
 export function validateChannelState(state, amount) {
     if (state.deposit === 0n) {
@@ -133,6 +174,9 @@ function readHex(value, field) {
         return value;
     throw new VerificationFailedError({ reason: `invalid session credential ${field}` });
 }
+function readOptionalHex(value, field) {
+    return value === undefined ? undefined : readHex(value, field);
+}
 function readRawAmount(value, field) {
     if (typeof value === 'string' && /^[0-9]+$/.test(value))
         return value;
@@ -195,6 +239,7 @@ export function requireSessionCredentialPayload(payload) {
                 channelId: header.channelId,
                 transaction: readHex(candidate.transaction, 'transaction'),
                 signature: readHex(candidate.signature, 'signature'),
+                authorizationSignature: readOptionalHex(candidate.authorizationSignature, 'authorizationSignature'),
                 descriptor: readDescriptor(candidate.descriptor),
                 cumulativeAmount: readRawAmount(candidate.cumulativeAmount, 'cumulativeAmount'),
                 ...(candidate.authorizedSigner === undefined
@@ -219,6 +264,7 @@ export function requireSessionCredentialPayload(payload) {
                 descriptor: readDescriptor(candidate.descriptor),
                 cumulativeAmount: readRawAmount(candidate.cumulativeAmount, 'cumulativeAmount'),
                 signature: readHex(candidate.signature, 'signature'),
+                authorizationSignature: readOptionalHex(candidate.authorizationSignature, 'authorizationSignature'),
             };
         case 'close':
             return {
@@ -227,6 +273,8 @@ export function requireSessionCredentialPayload(payload) {
                 descriptor: readDescriptor(candidate.descriptor),
                 cumulativeAmount: readRawAmount(candidate.cumulativeAmount, 'cumulativeAmount'),
                 signature: readHex(candidate.signature, 'signature'),
+                authorizationSignature: readOptionalHex(candidate.authorizationSignature, 'authorizationSignature'),
+                refundSignature: readOptionalHex(candidate.refundSignature, 'refundSignature'),
             };
     }
 }
@@ -244,28 +292,26 @@ const refreshOnChainVerificationCache = {
 /** Validates all action-specific session credential invariants without changing payment state. */
 export async function validateCredentialPayload(parameters) {
     const { payload } = parameters;
+    const context = await resolveCredentialContext(parameters);
     switch (payload.action) {
         case 'open':
-            await validateOpenCredential(parameters, payload);
+            await validateOpenCredential(context, payload);
             break;
         case 'topUp':
-            await validateTopUpCredential(parameters, payload);
+            await validateTopUpCredential(context, payload);
             break;
         case 'voucher':
-            await validateVoucherCredential(parameters, payload);
+            await validateVoucherCredential(context, payload);
             break;
         case 'close':
-            await validateCloseCredential(parameters, payload);
+            await validateCloseCredential(context, payload);
             break;
     }
     return { action: payload.action, channelId: ChannelStore.normalizeChannelId(payload.channelId) };
 }
 async function validateOpenCredential(parameters, payload) {
-    const { challenge, chainId, client, escrow } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { challenge, chainId, client, escrow, expectedOperator, payment: request } = parameters;
     const cumulativeAmount = uint96(BigInt(payload.cumulativeAmount));
-    assertDescriptor(payload);
     if (payload.authorizedSigner !== undefined &&
         !isAddressEqual(payload.authorizedSigner, payload.descriptor.authorizedSigner))
         throw new VerificationFailedError({
@@ -274,6 +320,7 @@ async function validateOpenCredential(parameters, payload) {
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const transaction = Chain.validateOpenCredentialTransaction({
+        allowedFeeTokens: parameters.allowedFeeTokens,
         challengeExpires: challenge.expires,
         chainId,
         escrowContract: escrow,
@@ -306,11 +353,8 @@ async function validateOpenCredential(parameters, payload) {
     });
 }
 async function validateTopUpCredential(parameters, payload) {
-    const { challenge, chainId, client, escrow, store } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { challenge, chainId, client, escrow, expectedOperator, payment: request, store, } = parameters;
     const additionalDeposit = uint96(BigInt(payload.additionalDeposit));
-    assertDescriptor(payload);
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const channel = await ChannelStore.loadPrecompileChannel({
@@ -323,6 +367,7 @@ async function validateTopUpCredential(parameters, payload) {
     });
     const transaction = Chain.validateTopUpCredentialTransaction({
         additionalDeposit,
+        allowedFeeTokens: parameters.allowedFeeTokens,
         challengeExpires: challenge.expires,
         chainId,
         descriptor: channel.descriptor,
@@ -341,12 +386,10 @@ async function validateTopUpCredential(parameters, payload) {
     });
 }
 async function validateVoucherCredential(parameters, payload) {
-    const { challenge, chainId, client, credentialSource, escrow, minVoucherDelta, store, channelStateTtl, lastOnChainVerified, } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { chainId, client, credentialSource, escrow, minVoucherDelta, store, channelStateTtl, lastOnChainVerified, payment: request, } = parameters;
+    const { expectedOperator } = parameters;
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
-    const voucher = Voucher.parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature);
-    assertDescriptor(payload);
+    const voucher = Voucher.parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature, payload.authorizationSignature);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const channel = await ChannelStore.loadPrecompileChannel({
         descriptor: payload.descriptor,
@@ -387,14 +430,56 @@ async function resolveVoucherChannelState(parameters) {
         closeRequestedAt: state?.closeRequestedAt ?? Number(channel.closeRequestedAt),
     };
 }
-async function validateCloseCredential(parameters, payload) {
-    const { challenge, chainId, client, escrow, store } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+function verifyMachineSessionAuthorization(parameters) {
+    const { chainId, payload, router } = parameters;
+    if (payload.action === 'topUp')
+        return undefined;
+    if (!router)
+        return undefined;
+    // The escrow resolves a zero authorizedSigner to the payer, but the router
+    // domain is bound to an explicit signer; reject the delegation up front
+    // instead of failing signature verification against the zero address.
+    if (isAddressEqual(payload.descriptor.authorizedSigner, zeroAddress))
+        throw new VerificationFailedError({
+            reason: 'machine-token sessions require an explicit authorizedSigner',
+        });
+    if (!payload.authorizationSignature)
+        throw new VerificationFailedError({
+            reason: 'machine-token voucher requires a router authorization',
+        });
+    const valid = MachineTokenSession.verifyAuthorization({
+        authorization: {
+            channelId: ChannelStore.normalizeChannelId(payload.channelId),
+            cumulativeAmount: uint96(BigInt(payload.cumulativeAmount)),
+        },
+        chainId,
+        expectedSigner: payload.descriptor.authorizedSigner,
+        router,
+        signature: payload.authorizationSignature,
+    });
+    if (!valid)
+        throw new InvalidSignatureError({ reason: 'invalid machine-token router authorization' });
+}
+async function resolveCredentialContext(parameters) {
+    const route = await resolveCredentialRoute(parameters);
+    verifyMachineSessionAuthorization({
+        chainId: parameters.chainId,
+        payload: parameters.payload,
+        router: route.machineRouter,
+    });
+    return { ...parameters, ...route };
+}
+function assertMachineCloseAmount(machineRouter, cumulativeAmount, captureAmount) {
+    if (machineRouter && cumulativeAmount !== captureAmount)
+        throw new VerificationFailedError({
+            reason: `machine-token close voucher amount must equal ${captureAmount} (capture amount)`,
+        });
+}
+async function inspectCloseCredential(parameters, payload) {
+    const { account: accountOverride, chainId, client, escrow, expectedOperator, machineRouter, payment, store, } = parameters;
     const cumulativeAmount = uint96(BigInt(payload.cumulativeAmount));
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
-    assertDescriptor(payload);
-    validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
+    validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, payment.recipient, payment.currency, expectedOperator);
     const channel = await ChannelStore.loadPrecompileChannel({
         descriptor: payload.descriptor,
         channelId,
@@ -417,24 +502,47 @@ async function validateCloseCredential(parameters, payload) {
         throw new VerificationFailedError({
             reason: `close voucher amount must be >= ${state.settled} (on-chain settled)`,
         });
-    const valid = await Voucher.verifyVoucher(escrow, chainId, { channelId, cumulativeAmount, signature: payload.signature }, channel.authorizedSigner);
-    if (!valid)
+    if (!(await Voucher.verifyVoucher(escrow, chainId, { channelId, cumulativeAmount, signature: payload.signature }, channel.authorizedSigner)))
         throw new InvalidSignatureError({ reason: 'invalid voucher signature' });
+    const refundSignature = machineRouter ? payload.refundSignature : undefined;
+    if (machineRouter) {
+        if (!refundSignature)
+            throw new VerificationFailedError({
+                reason: 'machine-token close requires a refund authorization',
+            });
+        if (!(await Voucher.verifyVoucher(escrow, chainId, { channelId, cumulativeAmount: uint96(state.deposit), signature: refundSignature }, payload.descriptor.authorizedSigner)))
+            throw new InvalidSignatureError({ reason: 'invalid machine-token refund authorization' });
+    }
     const captureAmount = uint96(channel.spent > state.settled ? channel.spent : state.settled);
     if (captureAmount > state.deposit)
         throw new AmountExceedsDepositError({ reason: 'close capture amount exceeds on-chain deposit' });
-    const account = parameters.account ?? getClientAccount(client);
-    assertSettlementSender({
-        operation: 'close',
+    assertMachineCloseAmount(machineRouter, cumulativeAmount, captureAmount);
+    const account = accountOverride ?? getClientAccount(client);
+    if (!machineRouter || !account)
+        assertSettlementSender({
+            operation: 'close',
+            channelId,
+            operator: channel.operator,
+            payee: channel.payee,
+            sender: account?.address,
+        });
+    return {
+        account,
+        authorizationSignature: machineRouter ? payload.authorizationSignature : undefined,
+        captureAmount,
+        channel,
         channelId,
-        operator: channel.operator,
-        payee: channel.payee,
-        sender: account?.address,
-    });
+        cumulativeAmount,
+        refundSignature,
+        state,
+    };
+}
+async function validateCloseCredential(parameters, payload) {
+    await inspectCloseCredential(parameters, payload);
 }
 /** Broadcasts a validated session credential payload and applies its state transition. */
 export async function broadcastCredentialPayload(context) {
-    const receipt = await broadcastCredentialAction(context);
+    const receipt = await broadcastCredentialAction(await resolveCredentialContext(context));
     if (refreshOnChainVerificationCache[context.payload.action])
         context.lastOnChainVerified.set(receipt.channelId, Date.now());
     return receipt;
@@ -460,11 +568,8 @@ function actionContext(context, payload) {
     return { ...context, payload };
 }
 async function handleOpenCredential(parameters) {
-    const { store, client, challenge, payload, chainId, escrow } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { store, client, challenge, payload, chainId, escrow, expectedOperator, payment: request, } = parameters;
     const cumulativeAmount = uint96(BigInt(payload.cumulativeAmount));
-    assertDescriptor(payload);
     if (payload.authorizedSigner !== undefined &&
         !isAddressEqual(payload.authorizedSigner, payload.descriptor.authorizedSigner))
         throw new VerificationFailedError({
@@ -473,6 +578,7 @@ async function handleOpenCredential(parameters) {
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const result = await Chain.broadcastOpenTransaction({
+        allowedFeeTokens: parameters.allowedFeeTokens,
         challengeExpires: challenge.expires,
         chainId,
         client,
@@ -514,6 +620,7 @@ async function handleOpenCredential(parameters) {
         expiringNonceHash: result.expiringNonceHash,
         cumulativeAmount,
         signature: payload.signature,
+        authorizationSignature: payload.authorizationSignature,
         state,
     }));
     if (!updated)
@@ -528,11 +635,8 @@ async function handleOpenCredential(parameters) {
     });
 }
 async function handleTopUpCredential(parameters) {
-    const { store, client, challenge, payload, chainId, escrow } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { store, client, challenge, payload, chainId, escrow, expectedOperator, payment: request, } = parameters;
     const additionalDeposit = uint96(BigInt(payload.additionalDeposit));
-    assertDescriptor(payload);
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const channel = await ChannelStore.loadPrecompileChannel({
@@ -545,6 +649,7 @@ async function handleTopUpCredential(parameters) {
     });
     const result = await Chain.broadcastTopUpTransaction({
         additionalDeposit,
+        allowedFeeTokens: parameters.allowedFeeTokens,
         challengeExpires: challenge.expires,
         chainId,
         client,
@@ -569,12 +674,10 @@ async function handleTopUpCredential(parameters) {
     });
 }
 async function handleVoucherCredential(parameters) {
-    const { store, client, challenge, credentialSource, payload, chainId, escrow, minVoucherDelta, channelStateTtl, lastOnChainVerified, } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
+    const { store, client, challenge, credentialSource, payload, chainId, escrow, minVoucherDelta, channelStateTtl, lastOnChainVerified, payment: request, } = parameters;
+    const { expectedOperator } = parameters;
     const channelId = ChannelStore.normalizeChannelId(payload.channelId);
-    const voucher = Voucher.parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature);
-    assertDescriptor(payload);
+    const voucher = Voucher.parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature, payload.authorizationSignature);
     validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
     const channel = await ChannelStore.loadPrecompileChannel({
         descriptor: payload.descriptor,
@@ -616,41 +719,10 @@ async function handleVoucherCredential(parameters) {
     });
 }
 async function handleCloseCredential(parameters) {
-    const { store, client, challenge, payload, chainId, escrow } = parameters;
-    const request = getChallengePaymentFields(challenge);
-    const expectedOperator = parameters.expectedOperator ?? zeroAddress;
-    const cumulativeAmount = uint96(BigInt(payload.cumulativeAmount));
-    const channelId = ChannelStore.normalizeChannelId(payload.channelId);
-    assertDescriptor(payload);
-    validateChannelDescriptor(payload.descriptor, channelId, chainId, escrow, request.recipient, request.currency, expectedOperator);
-    const channel = await ChannelStore.loadPrecompileChannel({
-        descriptor: payload.descriptor,
-        channelId,
-        chainId,
-        escrow,
-        store,
-    });
-    if (channel.finalized)
-        throw new ChannelClosedError({ reason: 'channel is already finalized' });
-    const state = await Chain.getChannelState(client, channelId, escrow);
-    if (state.closeRequestedAt !== 0)
-        throw new ChannelClosedError({ reason: 'channel has a pending close request' });
-    if (state.deposit === 0n && (cumulativeAmount !== 0n || channel.spent !== 0n))
-        throw new ChannelClosedError({ reason: 'channel deposit is zero (settled)' });
-    if (cumulativeAmount < channel.spent)
-        throw new VerificationFailedError({
-            reason: `close voucher amount must be >= ${channel.spent} (spent)`,
-        });
-    if (cumulativeAmount < state.settled)
-        throw new VerificationFailedError({
-            reason: `close voucher amount must be >= ${state.settled} (on-chain settled)`,
-        });
-    const valid = await Voucher.verifyVoucher(escrow, chainId, { channelId, cumulativeAmount: cumulativeAmount, signature: payload.signature }, channel.authorizedSigner);
-    if (!valid)
-        throw new InvalidSignatureError({ reason: 'invalid voucher signature' });
-    let captureAmount = uint96(channel.spent > state.settled ? channel.spent : state.settled);
-    if (captureAmount > state.deposit)
-        throw new AmountExceedsDepositError({ reason: 'close capture amount exceeds on-chain deposit' });
+    const { store, client, challenge, payload, escrow, machineRouter } = parameters;
+    const inspected = await inspectCloseCredential(parameters, payload);
+    const { account, authorizationSignature, channel, channelId, cumulativeAmount, refundSignature, state, } = inspected;
+    let { captureAmount } = inspected;
     const pendingCloseStartedAt = BigInt(Math.floor(Date.now() / 1000) || 1);
     const previousCloseRequestedAt = channel.closeRequestedAt;
     let pendingCloseMarked = false;
@@ -663,31 +735,26 @@ async function handleCloseCredential(parameters) {
             onChainSettled: state.settled,
         });
         if (next.state) {
+            assertMachineCloseAmount(machineRouter, cumulativeAmount, next.captureAmount);
             captureAmount = next.captureAmount;
             pendingCloseMarked = true;
         }
         return next.state;
     });
-    const account = parameters.account ?? getClientAccount(client);
     let txHash;
     let receipt;
     try {
-        assertSettlementSender({
-            operation: 'close',
-            channelId,
-            operator: channel.operator,
-            payee: channel.payee,
-            sender: account?.address,
-        });
-        txHash = await Chain.closeOnChain(client, channel.descriptor, cumulativeAmount, captureAmount, payload.signature, escrow, account
-            ? {
-                account,
-                ...(typeof parameters.feePayer === 'object' ? { feePayer: parameters.feePayer } : {}),
-                ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
-                ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
-                candidateFeeTokens: [channel.token],
-            }
-            : undefined);
+        const transactionOptions = resolveChannelTransactionOptions(channel, parameters, account, machineRouter);
+        if (machineRouter) {
+            if (!authorizationSignature || !refundSignature)
+                throw new VerificationFailedError({
+                    reason: 'machine-token close requires router and refund authorizations',
+                });
+            txHash = await Chain.closeMachineSessionOnChain(client, channel.descriptor, cumulativeAmount, payload.signature, authorizationSignature, refundSignature, machineRouter, transactionOptions);
+        }
+        else {
+            txHash = await Chain.closeOnChain(client, channel.descriptor, cumulativeAmount, captureAmount, payload.signature, escrow, transactionOptions);
+        }
         receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
     }
     catch (error) {
@@ -700,9 +767,18 @@ async function handleCloseCredential(parameters) {
     }
     const closed = readChannelClosedReceiptFields(Chain.getChannelEvent(receipt, 'ChannelClosed', channelId));
     const { refundedToPayer, settledToPayee } = closed;
-    if (settledToPayee > captureAmount || settledToPayee + refundedToPayer > state.deposit)
+    if (machineRouter) {
+        if (settledToPayee !== state.deposit || refundedToPayer !== 0n)
+            throw new VerificationFailedError({
+                reason: 'machine-token ChannelClosed amounts are invalid',
+            });
+    }
+    else if (settledToPayee > captureAmount || settledToPayee + refundedToPayer > state.deposit) {
         throw new VerificationFailedError({ reason: 'ChannelClosed amounts do not match state' });
+    }
+    const logicalSettled = machineRouter ? captureAmount : settledToPayee;
     const updated = await store.updateChannel(channelId, (current) => ChannelStore.finalizeClosedChannelState({
+        authorizationSignature,
         captureAmount,
         channelId,
         cumulativeAmount,
@@ -715,8 +791,8 @@ async function handleCloseCredential(parameters) {
                 txHash,
                 channelId,
                 trigger: 'close',
-                amount: settledToPayee,
-                delta: settledToPayee - state.settled,
+                amount: logicalSettled,
+                delta: logicalSettled - state.settled,
             }));
         }
         catch {

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

@@ -35,7 +35,7 @@ export type MeteredStreamOptions = {
     onChargeCommitted?: ((channel: ChannelStore.State) => MaybePromise<unknown>) | undefined;
     /** Store polling interval when `waitForUpdate` is unavailable. */
     pollIntervalMs: number;
-    /** Pre-authorized units that may be emitted without reserving new voucher headroom. */
+    /** Pre-authorized implicit tick-cost units that may be emitted without a new reservation. */
     prepaidUnits?: number | undefined;
     /** Optional abort signal for stream cancellation. */
     signal?: AbortSignal | undefined;

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

@@ -4,22 +4,23 @@ export async function* meterIterable(options) {
     let prepaidUnits = options.prepaidUnits ?? 0;
     let reservedAmount = 0n;
     let reservedUnits = 0;
-    const charge = async (amount = options.tickCost) => {
-        if (prepaidUnits > 0) {
+    const charge = async (amount) => {
+        if (amount === undefined && prepaidUnits > 0) {
             prepaidUnits -= 1;
             return;
         }
+        const resolvedAmount = amount ?? options.tickCost;
         await reserveChargeOrWait({
             store: options.store,
             channelId: options.channelId,
-            amount,
+            amount: resolvedAmount,
             reservedAmount,
             emit: options.emitNeedVoucher,
             formatNeedVoucher: options.formatNeedVoucher,
             pollIntervalMs: options.pollIntervalMs,
             signal: options.signal,
         });
-        reservedAmount += amount;
+        reservedAmount += resolvedAmount;
         reservedUnits += 1;
     };
     const signal = options.signal ?? new AbortController().signal;

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

@@ -2,6 +2,7 @@ import { type Account as viem_Account, type Address, type Hex } from 'viem';
 import * as Constants from '../../../Constants.js';
 import type * as Credential from '../../../Credential.js';
 import type { Challenge } from '../../../index.js';
+import type { MaybePromise } from '../../../internal/types.js';
 import type * as z from '../../../zod.js';
 import * as Methods from '../../Methods.js';
 import { isSessionContentRequest, type RequestBodyProbe } from '../../server/internal/request-body.js';
@@ -14,10 +15,14 @@ import { type ParameterFeePayer, type ResolvedFeePayer } from './Settlement.js';
 export type ResolveSessionSnapshotParameters = {
     /** Raw request amount that must be covered by the next voucher. */
     amount: bigint;
+    /** Already-loaded channel for `channelId`, skipping the store read. */
+    channel?: ChannelStore.State | null | undefined;
     /** Channel ID from credential or challenge request, when available. */
     channelId: Hex | undefined;
     /** Payment fields the reusable channel must match before it is advertised. */
     expected?: SessionSnapshotPaymentFields | undefined;
+    /** Optional alternate-rail matcher when the stored descriptor differs from logical payment fields. */
+    matchPaymentFields?: MatchSessionSnapshotPaymentFields | undefined;
     /** Server channel store. */
     store: ChannelStore.ChannelStore;
 };
@@ -32,6 +37,15 @@ export type SessionSnapshotPaymentFields = {
     /** Payee address expected by the challenge. */
     recipient: Address;
 };
+/**
+ * Validates an alternate channel descriptor against the logical session payment
+ * fields. `options.action` names the credential the snapshot serves: close
+ * credentials accept retired routes, so their recovery snapshots match
+ * inactive routes too.
+ */
+export type MatchSessionSnapshotPaymentFields = (channel: ChannelStore.StoredPrecompileChannel, expected: SessionSnapshotPaymentFields, options?: {
+    action?: SessionCredentialPayload['action'] | undefined;
+} | undefined) => MaybePromise<boolean>;
 /** Request metadata available to `resolveChannelId` without exposing a mutable `Request`. */
 export type SessionChannelIdRequest = {
     /** Request headers, useful for cookies or auth/session headers. */
@@ -125,6 +139,10 @@ export type SessionMethodDetails = {
     escrowContract: Address;
     /** Whether this challenge allows fee-sponsored management transactions. */
     feePayer?: boolean | undefined;
+    /** Fee token clients must use for open/top-up transactions. */
+    feeToken?: Address | undefined;
+    /** Whether clients may fund this logical session through the first-party machine-token rail. */
+    machineTokenEnabled?: boolean | undefined;
     /** Minimum raw-unit increase required for voucher credentials. */
     minVoucherDelta?: string | undefined;
     /** Channel operator address the client should encode in new open transactions. */
@@ -147,6 +165,7 @@ export type ResolveSessionPaymentRequestParameters = {
     decimals: number;
     defaultFeePayer?: viem_Account | undefined;
     getClient: ResolveRequestChainIdParameters['getClient'];
+    matchSnapshotPaymentFields?: MatchSessionSnapshotPaymentFields | undefined;
     parameterChainId?: number | undefined;
     parameterEscrowContract?: Address | undefined;
     parameterFeePayer?: ParameterFeePayer;