mppx 0.8.15 → 0.8.18

package/dist/tempo/server/internal/transport.d.ts

@@ -1,6 +1,7 @@
 import * as Transport from '../../../server/Transport.js';
 import type { SessionReceipt } from '../../session/precompile/Protocol.js';
 import * as ChannelStore from '../../session/server/ChannelStore.js';
+import type { SettleChargedSessionChannel } from '../../session/server/Settlement.js';
 import * as Sse_core from '../../session/server/Sse.js';
 declare const prepaidSessionTick: unique symbol;
 /** SSE transport with Tempo session controller. */
@@ -21,6 +22,7 @@ export declare function markPrepaidSessionTick(receipt: SessionReceipt): Session
  * - Fallback to standard HTTP receipt handling for plain Response
  */
 export declare function sse(options: sse.Options & {
+    settleCharged?: SettleChargedSessionChannel | undefined;
     store: ChannelStore.ChannelStore;
 }): Sse;
 /** Type helpers for the Tempo SSE transport adapter. */

package/dist/tempo/server/internal/transport.js

@@ -90,6 +90,7 @@ export function sse(options) {
                     tickCost,
                     pollIntervalMs: pollingInterval,
                     generate,
+                    onChargeCommitted: options.settleCharged,
                     prepaidUnits: hasPrepaidSessionTick(receipt) ? 1 : 0,
                     signal: input.signal,
                 });
@@ -138,18 +139,24 @@ export function sse(options) {
                 response: response,
                 challengeId: verifiedChallengeId,
             });
+            const chargePlainResponse = async () => {
+                const result = await ChannelStore.deductFromChannel(store, channelId, tickCost);
+                if (result.ok)
+                    await options.settleCharged?.(result.channel);
+                return result;
+            };
             // Non-SSE response (e.g. upstream returned JSON instead of event-stream).
             // Need to deduct tickCost so request isn't free.
             // For null-body statuses, the request shape determines whether the
             // response is management (no charge) or plain content (charge one tick).
             if (isNullBodyStatus(chargedResponse.status)) {
-                void ChannelStore.deductFromChannel(store, channelId, tickCost);
+                void chargePlainResponse();
                 return chargedResponse;
             }
             const stream = new ReadableStream({
                 async start(controller) {
                     // deduction completes before consumer reads
-                    const result = await ChannelStore.deductFromChannel(store, channelId, tickCost);
+                    const result = await chargePlainResponse();
                     if (!result.ok) {
                         controller.error(new Errors.InsufficientBalanceError({
                             reason: `requested ${tickCost}, available ${result.channel.highestVoucherAmount - result.channel.spent}`,

package/dist/tempo/session/client/ChannelOps.d.ts

@@ -33,19 +33,33 @@ export type ChannelEntry = {
     chainId: number;
     /** Whether the client considers the channel reusable for new vouchers. */
     opened: boolean;
+    /** Logical merchant payment scope when it differs from the on-chain descriptor. */
+    paymentScope?: {
+        payee: Address;
+        token: Address;
+    } | undefined;
 };
 /** Resolves the voucher authority address for a client account. */
 export declare function resolveAuthorizedSigner(account: Account): Address;
-/** Resolves the escrow precompile from local override, challenge hints, or canonical default. */
+/** Resolves the server-advertised escrow against the client's trust policy. */
 export declare function resolveEscrow(challenge: {
     request: {
         methodDetails?: unknown;
     };
-}, escrowOverride?: Address | undefined): Address;
+}, escrowOverride?: Address | undefined, allowCustomEscrow?: boolean): Address;
 /** Serializes a session credential with a DID source bound to the payer account. */
 export declare function serializeCredential(challenge: Challenge, payload: SessionCredentialPayload, chainId: number, account: Account): string;
 /** Case-insensitive EVM address equality. */
 export declare function isSameAddress(a: Address, b: Address): boolean;
+/** Returns whether a stored entry funds a machine-token session channel. */
+export declare function isMachineChannel(entry: Pick<ChannelEntry, 'chainId' | 'descriptor' | 'escrow'>): boolean;
+/**
+ * Returns whether a stored entry's logical payment scope differs from its
+ * on-chain descriptor. Such entries cannot be re-derived from a challenge, so
+ * their descriptor is the only local copy — even when the deployment table no
+ * longer recognizes the route (for example after a rotation).
+ */
+export declare function hasRewrittenScope(entry: Pick<ChannelEntry, 'descriptor' | 'paymentScope'>): boolean;
 /**
  * Signs and creates a TIP-1034 voucher credential payload for an existing channel.
  *
@@ -71,6 +85,7 @@ export declare function createOpenPayload(client: Client, account: Account, para
     deposit: bigint;
     escrow?: Address | undefined;
     feePayer?: boolean | undefined;
+    feeToken?: Address | undefined;
     initialAmount: bigint;
     operator?: Address | undefined;
     payee: Address;
@@ -83,5 +98,5 @@ export declare function createOpenPayload(client: Client, account: Account, para
  *
  * @see https://tips.sh/1034-1#execution-semantics
  */
-export declare function createTopUpPayload(client: Client, account: Account, descriptor: Channel.ChannelDescriptor, additionalDeposit: bigint, chainId: number, feePayer?: boolean | undefined, escrow?: Address, prefixCalls?: readonly TempoChannelCall[]): Promise<TopUpCredentialPayload>;
+export declare function createTopUpPayload(client: Client, account: Account, descriptor: Channel.ChannelDescriptor, additionalDeposit: bigint, chainId: number, feePayer?: boolean | undefined, escrow?: Address, prefixCalls?: readonly TempoChannelCall[], feeToken?: Address): Promise<TopUpCredentialPayload>;
 //# sourceMappingURL=ChannelOps.d.ts.map

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

@@ -13,6 +13,7 @@ import { encodeFunctionData, isAddress } from 'viem';
 import { prepareTransactionRequest, signTransaction } from 'viem/actions';
 import { Transaction } from 'viem/tempo';
 import * as Credential from '../../../Credential.js';
+import * as MachineTokenSession from '../../internal/machine-token-session.js';
 import * as Channel from '../precompile/Channel.js';
 import { escrowAbi } from '../precompile/escrow.abi.js';
 import { tip20ChannelEscrow } from '../precompile/Protocol.js';
@@ -58,14 +59,21 @@ async function prepareTempoChannelTransaction(client, parameters) {
 async function signPreparedTempoTransaction(client, prepared) {
     return (await signTransaction(client, prepared));
 }
-/** Resolves the escrow precompile from local override, challenge hints, or canonical default. */
-export function resolveEscrow(challenge, escrowOverride) {
+/** Resolves the server-advertised escrow against the client's trust policy. */
+export function resolveEscrow(challenge, escrowOverride, allowCustomEscrow = false) {
     const methodDetails = challenge.request.methodDetails;
     const challengeEscrow = isObject(methodDetails)
         ? (readOptionalAddress(methodDetails.escrowContract) ??
             readOptionalAddress(methodDetails.escrow))
         : undefined;
-    return escrowOverride ?? challengeEscrow ?? tip20ChannelEscrow;
+    const expectedEscrow = escrowOverride ?? tip20ChannelEscrow;
+    if (challengeEscrow &&
+        !isSameAddress(challengeEscrow, expectedEscrow) &&
+        (!allowCustomEscrow || escrowOverride !== undefined))
+        throw new Error(`Tempo session escrow ${challengeEscrow} does not match client escrow ${expectedEscrow}.`);
+    if (challengeEscrow && !isSameAddress(challengeEscrow, expectedEscrow))
+        return challengeEscrow;
+    return expectedEscrow;
 }
 /** Serializes a session credential with a DID source bound to the payer account. */
 export function serializeCredential(challenge, payload, chainId, account) {
@@ -79,6 +87,27 @@ export function serializeCredential(challenge, payload, chainId, account) {
 export function isSameAddress(a, b) {
     return a.toLowerCase() === b.toLowerCase();
 }
+/** Returns whether a stored entry funds a machine-token session channel. */
+export function isMachineChannel(entry) {
+    return (isSameAddress(entry.escrow, tip20ChannelEscrow) &&
+        MachineTokenSession.matchDeployment({
+            chainId: entry.chainId,
+            descriptor: entry.descriptor,
+        }) !== undefined);
+}
+/**
+ * Returns whether a stored entry's logical payment scope differs from its
+ * on-chain descriptor. Such entries cannot be re-derived from a challenge, so
+ * their descriptor is the only local copy — even when the deployment table no
+ * longer recognizes the route (for example after a rotation).
+ */
+export function hasRewrittenScope(entry) {
+    const scope = entry.paymentScope;
+    if (!scope)
+        return false;
+    return (!isSameAddress(scope.payee, entry.descriptor.payee) ||
+        !isSameAddress(scope.token, entry.descriptor.token));
+}
 /**
  * Signs and creates a TIP-1034 voucher credential payload for an existing channel.
  *
@@ -139,7 +168,7 @@ export async function createOpenPayload(client, account, parameters) {
         account,
         calls: [...(parameters.prefixCalls ?? []), { to: escrow, data: openData }],
         feePayer: parameters.feePayer,
-        feeToken: parameters.token,
+        feeToken: parameters.feeToken ?? parameters.token,
     });
     const transaction = await signPreparedTempoTransaction(client, prepared);
     const signed = Transaction.deserialize(transaction);
@@ -178,7 +207,7 @@ export async function createOpenPayload(client, account, parameters) {
  *
  * @see https://tips.sh/1034-1#execution-semantics
  */
-export async function createTopUpPayload(client, account, descriptor, additionalDeposit, chainId, feePayer, escrow = tip20ChannelEscrow, prefixCalls = []) {
+export async function createTopUpPayload(client, account, descriptor, additionalDeposit, chainId, feePayer, escrow = tip20ChannelEscrow, prefixCalls = [], feeToken = descriptor.token) {
     const channelId = Channel.computeId({
         ...descriptor,
         chainId,
@@ -199,7 +228,7 @@ export async function createTopUpPayload(client, account, descriptor, additional
             },
         ],
         feePayer,
-        feeToken: descriptor.token,
+        feeToken,
         validAfter: randomValidAfter(),
     });
     const transaction = await signPreparedTempoTransaction(client, prepared);

package/dist/tempo/session/client/ChannelStore.d.ts

@@ -10,11 +10,6 @@ export type ChannelStore = {
     /** Removes the channel cached for `key`. */
     delete(key: string): MaybePromise<void>;
 };
-/** Channel persistence and update notification for credential results. */
-export type ChannelSink = {
-    store: ChannelStore;
-    notifyUpdate: (entry: ChannelEntry) => void;
-};
 /** Returns the scope key for a reusable payer session channel. */
 export declare function channelKey(scope: {
     payee: Address;

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

@@ -6,8 +6,8 @@ export function channelKey(scope) {
 /** Returns the scope key for a stored channel entry. */
 export function entryKey(entry) {
     return channelKey({
-        payee: entry.descriptor.payee,
-        token: entry.descriptor.token,
+        payee: entry.paymentScope?.payee ?? entry.descriptor.payee,
+        token: entry.paymentScope?.token ?? entry.descriptor.token,
         escrow: entry.escrow,
         chainId: entry.chainId,
     });

package/dist/tempo/session/client/CredentialState.d.ts

@@ -8,7 +8,6 @@ import * as Channel from '../precompile/Channel.js';
 import type { SessionCredentialPayload } from '../precompile/Protocol.js';
 import type { SessionSnapshot } from '../Snapshot.js';
 import { type ChannelEntry } from './ChannelOps.js';
-import { type ChannelSink } from './ChannelStore.js';
 /** Credential payload variants that carry cumulative voucher authorization. */
 export type CumulativeCredentialPayload = Extract<SessionCredentialPayload, {
     cumulativeAmount: string;
@@ -22,10 +21,10 @@ export declare const sessionContextSchema: z.ZodMiniObject<{
     account: z.ZodMiniOptional<z.ZodMiniCustom<`0x${string}` | Account.Account | undefined, `0x${string}` | Account.Account | undefined>>;
     autoSwap: z.ZodMiniOptional<z.ZodMiniCustom<AutoSwap.resolve.Value, AutoSwap.resolve.Value>>;
     action: z.ZodMiniOptional<z.ZodMiniEnum<{
+        close: "close";
         open: "open";
         topUp: "topUp";
         voucher: "voucher";
-        close: "close";
     }>>;
     channelId: z.ZodMiniOptional<z.ZodMiniCustom<`0x${string}`, `0x${string}`>>;
     cumulativeAmount: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -98,6 +97,8 @@ export type ClientSessionMethodDetails = {
     escrow?: Address | undefined;
     /** Whether the challenge allows fee-sponsored open/top-up transactions. */
     feePayer?: boolean | undefined;
+    /** Fee token selected by the server for open/top-up transactions. */
+    feeToken?: Address | undefined;
     /** Channel operator address advertised by the server. */
     operator?: Address | undefined;
     /** Server bootstrap snapshot for a reusable session channel. */
@@ -105,6 +106,8 @@ export type ClientSessionMethodDetails = {
 };
 /** Dependencies used to resolve a challenge into typed credential-planning data. */
 export type ResolveChallengeContextParameters = {
+    /** Whether to accept a noncanonical escrow advertised by the server. @default false */
+    allowCustomEscrow?: boolean | undefined;
     /** Challenge received from the 402 response. */
     challenge: Challenge.Challenge;
     /** Optional local escrow override. */
@@ -159,9 +162,15 @@ export type ChallengeContext = {
     client: Client;
     escrow: Address;
     feePayer?: boolean | undefined;
+    feeToken?: Address | undefined;
     key: string;
     operator?: Address | undefined;
     payee: Address;
+    /** Logical merchant scope when the channel uses an indirect payment route. */
+    paymentScope?: {
+        payee: Address;
+        token: Address;
+    } | undefined;
     snapshot?: SessionSnapshot | undefined;
     /** Server-provided raw deposit hint for opening a channel, before local maxDeposit capping. */
     suggestedDepositRaw?: string | undefined;
@@ -248,8 +257,14 @@ export type CredentialPlan =
     account: ViemAccount;
     context: ManualSessionDescriptorContext;
     decimals: number;
+    entry?: ChannelEntry | undefined;
     resolved: ChallengeContext;
 };
+/** Signed credential plus the channel state to commit after all signing succeeds. */
+export type CredentialResult = {
+    payload: SessionCredentialPayload;
+    entry?: ChannelEntry | undefined;
+};
 /** Resolves raw challenge fields into the typed data required by client credential planning. */
 export declare function resolveChallengeContext(parameters: ResolveChallengeContextParameters): Promise<ChallengeContext>;
 /** Validates descriptor identity and reads open channel state for client-side recovery. */
@@ -265,5 +280,5 @@ export declare function canSignDescriptor(account: ViemAccount, descriptor: Chan
 /** Chooses the next credential plan from local channel cache and optional caller context. */
 export declare function planCredential(parameters: PlanCredentialParameters): CredentialPlan;
 /** Executes a credential plan and returns the concrete session credential payload. */
-export declare function executeCredentialPlan(plan: CredentialPlan, sink: ChannelSink, autoSwap?: AutoSwap.resolve.Resolved | false): Promise<SessionCredentialPayload>;
+export declare function executeCredentialPlan(plan: CredentialPlan, autoSwap?: AutoSwap.resolve.Resolved | false, feeToken?: Address | undefined): Promise<CredentialResult>;
 //# sourceMappingURL=CredentialState.d.ts.map

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

@@ -6,7 +6,7 @@ import * as Chain from '../precompile/Chain.js';
 import * as Channel from '../precompile/Channel.js';
 import * as Voucher from '../precompile/Voucher.js';
 import { createClosePayload, createOpenPayload, createTopUpPayload, createVoucherPayload, isSameAddress, resolveAuthorizedSigner, resolveEscrow, } from './ChannelOps.js';
-import { channelKey, entryKey } from './ChannelStore.js';
+import { channelKey } from './ChannelStore.js';
 import { assertWithinMaxDeposit, resolveOpeningDeposit } from './Runtime.js';
 /** Returns whether a credential payload carries cumulative voucher authorization. */
 export function hasCredentialCumulativeAmount(payload) {
@@ -18,33 +18,18 @@ export function readCredentialCumulativeAmount(payload) {
         return undefined;
     return BigInt(payload.cumulativeAmount);
 }
-/**
- * Persists a channel entry through the sink and notifies observers. Closed
- * channels are removed from the store but still reported to observers so callers
- * can react to the close.
- */
-async function storeChannelEntry(sink, entry) {
-    if (entry.opened)
-        await sink.store.set(entry);
-    else
-        await sink.store.delete(entryKey(entry));
-    sink.notifyUpdate(entry);
-}
-/** Applies a credential payload's cumulative amount to the stored channel at `key`. */
-async function applyCumulative(sink, key, payload) {
+/** Applies a credential payload to a matching cached channel without persisting it. */
+function applyCredential(entry, payload) {
     const cumulativeAmount = readCredentialCumulativeAmount(payload);
-    if (cumulativeAmount === undefined)
-        return;
-    const entry = await sink.store.get(key);
-    if (!entry)
-        return;
-    if (entry.channelId.toLowerCase() !== payload.channelId.toLowerCase())
-        return;
-    entry.cumulativeAmount =
-        entry.cumulativeAmount > cumulativeAmount ? entry.cumulativeAmount : cumulativeAmount;
-    if (payload.action === 'close')
-        entry.opened = false;
-    await storeChannelEntry(sink, entry);
+    if (cumulativeAmount === undefined ||
+        !entry ||
+        entry.channelId.toLowerCase() !== payload.channelId.toLowerCase())
+        return undefined;
+    return {
+        ...entry,
+        cumulativeAmount: entry.cumulativeAmount > cumulativeAmount ? entry.cumulativeAmount : cumulativeAmount,
+        opened: payload.action === 'close' ? false : entry.opened,
+    };
 }
 const hexSchema = z.custom((value) => typeof value === 'string' && /^0x[0-9a-fA-F]*$/.test(value));
 const hashSchema = z.custom((value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value));
@@ -106,6 +91,7 @@ function readMethodDetails(challenge) {
         escrowContract: readOptionalAddress(methodDetails.escrowContract),
         escrow: readOptionalAddress(methodDetails.escrow),
         feePayer: typeof methodDetails.feePayer === 'boolean' ? methodDetails.feePayer : undefined,
+        feeToken: readOptionalAddress(methodDetails.feeToken),
         operator: readOptionalAddress(methodDetails.operator),
         sessionSnapshot: Constants.getMethodDetail(methodDetails, Constants.MethodDetailKeys.sessionSnapshot),
     };
@@ -125,13 +111,13 @@ function readSuggestedDeposit(value) {
 }
 /** Resolves raw challenge fields into the typed data required by client credential planning. */
 export async function resolveChallengeContext(parameters) {
-    const { challenge, escrowOverride, getClient } = parameters;
+    const { allowCustomEscrow, challenge, escrowOverride, getClient } = parameters;
     const methodDetails = readMethodDetails(challenge);
     const client = await getClient({ chainId: methodDetails.chainId });
     const chainId = methodDetails.chainId ?? client.chain?.id;
     if (!chainId)
         throw new Error('No chainId configured for TIP-1034 session challenge.');
-    const escrow = resolveEscrow(challenge, escrowOverride);
+    const escrow = resolveEscrow(challenge, escrowOverride, allowCustomEscrow);
     const payee = readAddress(challenge.request.recipient, 'recipient');
     const token = readAddress(challenge.request.currency, 'currency');
     return {
@@ -141,6 +127,7 @@ export async function resolveChallengeContext(parameters) {
         client,
         escrow,
         feePayer: methodDetails.feePayer,
+        feeToken: methodDetails.feeToken,
         key: channelKey({ payee, token, escrow, chainId }),
         operator: methodDetails.operator,
         payee,
@@ -288,6 +275,7 @@ export function planCredential(parameters) {
             account,
             context,
             decimals,
+            entry,
             resolved,
         };
     }
@@ -295,30 +283,39 @@ export function planCredential(parameters) {
         throw new Error('descriptor required to reuse TIP-1034 channel');
     const recoverContext = resolveRecoverContext({ context, snapshot: resolved.snapshot });
     if (!entry && recoverContext && canSignDescriptor(account, recoverContext.descriptor)) {
-        return {
-            type: 'recover',
-            account,
-            context: recoverContext,
-            decimals,
-            maxDeposit,
-            resolved,
-        };
+        // A server snapshot may describe another rail's channel (e.g. a
+        // machine-token descriptor advertised to a direct-rail client); ignore
+        // hints that do not match this challenge instead of failing recovery on
+        // every attempt. Explicit caller descriptors keep failing loudly in
+        // recovery validation.
+        const recoverable = context?.descriptor !== undefined ||
+            (isSameAddress(recoverContext.descriptor.payee, resolved.payee) &&
+                isSameAddress(recoverContext.descriptor.token, resolved.token));
+        if (recoverable)
+            return {
+                type: 'recover',
+                account,
+                context: recoverContext,
+                decimals,
+                maxDeposit,
+                resolved,
+            };
     }
     if (entry?.opened && canSignDescriptor(account, entry.descriptor))
         return { type: 'voucher', account, entry, maxDeposit, resolved };
     return { type: 'open', account, context, maxDeposit, resolved };
 }
 /** Executes a credential plan and returns the concrete session credential payload. */
-export async function executeCredentialPlan(plan, sink, autoSwap = false) {
+export async function executeCredentialPlan(plan, autoSwap = false, feeToken) {
     switch (plan.type) {
         case 'open':
-            return open(plan, sink, autoSwap);
+            return open(plan, autoSwap, feeToken);
         case 'recover':
-            return recover(plan, sink);
+            return recover(plan);
         case 'voucher':
-            return voucher(plan, sink);
+            return voucher(plan);
         case 'manual':
-            return manual(plan, sink, autoSwap);
+            return manual(plan, autoSwap, feeToken);
     }
 }
 async function resolveAutoSwapCalls(autoSwap, parameters) {
@@ -332,7 +329,7 @@ async function resolveAutoSwapCalls(autoSwap, parameters) {
         slippage: autoSwap.slippage,
     }));
 }
-async function open(plan, sink, autoSwap) {
+async function open(plan, autoSwap, feeToken) {
     const { account, resolved } = plan;
     const deposit = resolveOpeningDeposit({
         contextDepositRaw: plan.context?.depositRaw,
@@ -345,6 +342,7 @@ async function open(plan, sink, autoSwap) {
         deposit,
         escrow: resolved.escrow,
         feePayer: resolved.feePayer,
+        feeToken,
         initialAmount: resolved.amount,
         operator: resolved.operator,
         payee: resolved.payee,
@@ -356,18 +354,21 @@ async function open(plan, sink, autoSwap) {
         }),
         token: resolved.token,
     });
-    await storeChannelEntry(sink, {
-        channelId: payload.channelId,
-        cumulativeAmount: resolved.amount,
-        deposit,
-        descriptor: payload.descriptor,
-        escrow: resolved.escrow,
-        chainId: resolved.chainId,
-        opened: true,
-    });
-    return payload;
+    return {
+        payload,
+        entry: {
+            channelId: payload.channelId,
+            cumulativeAmount: resolved.amount,
+            deposit,
+            descriptor: payload.descriptor,
+            escrow: resolved.escrow,
+            chainId: resolved.chainId,
+            opened: true,
+            ...(resolved.paymentScope && { paymentScope: resolved.paymentScope }),
+        },
+    };
 }
-async function recover(plan, sink) {
+async function recover(plan) {
     const { account, context, decimals, maxDeposit, resolved } = plan;
     const { descriptor } = context;
     const reusable = await resolveReusableChannel({
@@ -394,27 +395,28 @@ async function recover(plan, sink) {
         throw new Error('recovered voucher amount exceeds on-chain channel deposit');
     assertWithinMaxDeposit(cumulativeAmount, maxDeposit);
     const payload = await createVoucherPayload(resolved.client, account, descriptor, cumulativeAmount, resolved.chainId, resolved.escrow);
-    await storeChannelEntry(sink, {
-        channelId: reusable.channelId,
-        cumulativeAmount,
-        deposit: reusable.state.deposit,
-        descriptor,
-        escrow: resolved.escrow,
-        chainId: resolved.chainId,
-        opened: true,
-    });
-    return payload;
+    return {
+        payload,
+        entry: {
+            channelId: reusable.channelId,
+            cumulativeAmount,
+            deposit: reusable.state.deposit,
+            descriptor,
+            escrow: resolved.escrow,
+            chainId: resolved.chainId,
+            opened: true,
+            ...(resolved.paymentScope && { paymentScope: resolved.paymentScope }),
+        },
+    };
 }
-async function voucher(plan, sink) {
+async function voucher(plan) {
     const { account, entry, resolved } = plan;
     const cumulativeAmount = entry.cumulativeAmount + resolved.amount;
     assertWithinMaxDeposit(cumulativeAmount, plan.maxDeposit);
     const payload = await createVoucherPayload(resolved.client, account, entry.descriptor, cumulativeAmount, resolved.chainId, resolved.escrow);
-    entry.cumulativeAmount = cumulativeAmount;
-    await storeChannelEntry(sink, entry);
-    return payload;
+    return { payload, entry: { ...entry, cumulativeAmount } };
 }
-async function manual(plan, sink, autoSwap) {
+async function manual(plan, autoSwap, feeToken) {
     const { account, context, decimals, resolved } = plan;
     const { descriptor } = context;
     const channelId = Channel.computeId({
@@ -438,16 +440,15 @@ async function manual(plan, sink, autoSwap) {
         decimals,
         descriptor,
         resolved,
-    }, autoSwap);
-    await applyCumulative(sink, resolved.key, payload);
-    return payload;
+    }, autoSwap, feeToken);
+    return { payload, entry: applyCredential(plan.entry, payload) };
 }
-async function executeManualCredential(parameters, autoSwap) {
+async function executeManualCredential(parameters, autoSwap, feeToken) {
     switch (parameters.context.action) {
         case 'open':
             return manualOpen(parameters);
         case 'topUp':
-            return manualTopUp(parameters, autoSwap);
+            return manualTopUp(parameters, autoSwap, feeToken);
         case 'voucher':
             return manualVoucher(parameters);
         case 'close':
@@ -471,7 +472,7 @@ async function manualOpen(parameters) {
         authorizedSigner: descriptor.authorizedSigner,
     };
 }
-async function manualTopUp(parameters, autoSwap) {
+async function manualTopUp(parameters, autoSwap, feeToken) {
     const { account, channelId, context, decimals, descriptor, resolved } = parameters;
     const additionalDeposit = requireContextAmount(context, decimals, 'additionalDeposit', 'topUp');
     if (context.transaction) {
@@ -489,7 +490,7 @@ async function manualTopUp(parameters, autoSwap) {
         amountOut: additionalDeposit,
         client: resolved.client,
         tokenOut: resolved.token,
-    }));
+    }), feeToken);
 }
 function manualVoucher(parameters) {
     const { account, context, decimals, descriptor, resolved } = parameters;

package/dist/tempo/session/client/Runtime.d.ts

@@ -308,8 +308,10 @@ export type ExpectedCloseReceiptParameters = {
     challengeId: string;
     /** Channel ID being closed. */
     channelId: Hex;
-    /** Expected final cumulative/spent amount. */
+    /** Expected final cumulative authorization. */
     expectedCloseAmount: string;
+    /** Lowest cumulative spend already confirmed by the client. */
+    minimumSpent?: bigint | undefined;
     /** Receipt to test. */
     receipt: SessionReceipt;
 };
@@ -434,7 +436,7 @@ export declare function closedStateFromReceipt(receipt: SessionReceipt, entry: C
  * Priority:
  * 1. Matching close-ready receipt spend.
  * 2. Matching socket delivery estimate (`deliveredChunks * tickCost`) clamped by cumulative.
- * 3. Latest receipt-tracked spend for HTTP/SSE.
+ * 3. Local cumulative authorization high-water mark for HTTP/SSE.
  */
 export declare function computeFallbackCloseAmount(parameters: FallbackCloseAmountParameters): bigint;
 /**

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

@@ -319,18 +319,27 @@ export function localCloseSpendLimit(parameters) {
 /** Throws when a close-ready receipt asks the client to sign beyond local state. */
 export function assertCloseReadyWithinLocalState(parameters) {
     const { cumulativeAmount, readySpent, spent } = parameters;
+    if (!Ws.isUint96(readySpent))
+        throw new Error('close-ready spent is not a uint96 amount');
+    if (readySpent < spent)
+        throw new Error('close-ready spent is below locally confirmed spend');
     if (readySpent > localCloseSpendLimit({ cumulativeAmount, spent })) {
         throw new Error('close-ready spent exceeds local voucher state');
     }
 }
 /** Returns whether a receipt is the expected final close settlement receipt. */
 export function isExpectedCloseReceipt(parameters) {
-    const { challengeId, channelId, expectedCloseAmount, receipt } = parameters;
+    const { challengeId, channelId, expectedCloseAmount, minimumSpent = 0n, receipt } = parameters;
+    const expected = Ws.parseUint96Amount(expectedCloseAmount);
+    const receiptSpent = Ws.parseUint96Amount(receipt.spent);
+    if (expected === undefined || receiptSpent === undefined || !Ws.isUint96(minimumSpent))
+        return false;
     return (Boolean(receipt.txHash) &&
         receipt.challengeId === challengeId &&
         receipt.channelId === channelId &&
         receipt.acceptedCumulative === expectedCloseAmount &&
-        receipt.spent === expectedCloseAmount);
+        receiptSpent >= minimumSpent &&
+        receiptSpent <= expected);
 }
 /** Projects cached channel data into an active state-machine state. */
 export function activeStateFromChannel(parameters) {
@@ -402,21 +411,27 @@ export function closedStateFromReceipt(receipt, entry) {
  * Priority:
  * 1. Matching close-ready receipt spend.
  * 2. Matching socket delivery estimate (`deliveredChunks * tickCost`) clamped by cumulative.
- * 3. Latest receipt-tracked spend for HTTP/SSE.
+ * 3. Local cumulative authorization high-water mark for HTTP/SSE.
  */
 export function computeFallbackCloseAmount(parameters) {
     const { challengeId, channelId, closeReadyReceipt, cumulativeAmount, deliveredChunks = 0n, socketChallengeId, socketChannelId, spent, tickCost = 0n, } = parameters;
+    if (spent > cumulativeAmount) {
+        throw new Error('locally confirmed spend exceeds local voucher state');
+    }
     if (closeReadyReceipt &&
         closeReadyReceipt.challengeId === challengeId &&
         closeReadyReceipt.channelId === channelId) {
-        return BigInt(closeReadyReceipt.spent);
+        const closeReadySpent = Ws.parseUint96Amount(closeReadyReceipt.spent);
+        if (closeReadySpent === undefined)
+            throw new Error('close-ready spent is not a uint96 amount');
+        return closeReadySpent > spent ? closeReadySpent : spent;
     }
     if (socketChallengeId === challengeId && socketChannelId === channelId && tickCost > 0n) {
         const deliveryEstimate = deliveredChunks * tickCost;
         const bestSpent = spent > deliveryEstimate ? spent : deliveryEstimate;
         return bestSpent > cumulativeAmount ? cumulativeAmount : bestSpent;
     }
-    return spent;
+    return cumulativeAmount;
 }
 /**
  * Restores a channel's cumulative voucher boundary and returns the refreshed active state.
@@ -501,6 +516,7 @@ export async function closeSocketSession(parameters) {
             challengeId: target.challenge.id,
             channelId: target.channelId,
             expectedCloseAmount,
+            minimumSpent: readySpent,
             receipt,
         }));
         activeSocket.send(Ws.formatAuthorizationMessage(credential));