mppx 0.8.15 → 0.8.18

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

@@ -1,4 +1,4 @@
-import { type Address } from 'viem';
+import { type Account as ViemAccount, type Address } from 'viem';
 import * as Method from '../../../Method.js';
 import * as Account from '../../../viem/Account.js';
 import * as Client from '../../../viem/Client.js';
@@ -19,9 +19,10 @@ export declare function session(parameters?: session.Parameters): Method.Client<
     readonly name: "tempo";
     readonly intent: "session";
     readonly schema: {
-        readonly credential: {
-            readonly payload: import("zod/mini").ZodMiniDiscriminatedUnion<[import("zod/mini").ZodMiniObject<{
+        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>;
@@ -38,26 +39,31 @@ export declare function session(parameters?: session.Parameters): Method.Client<
                 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<Channel.ChannelDescriptor, Channel.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<Channel.ChannelDescriptor, Channel.ChannelDescriptor>>;
+                refundSignature: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
                 signature: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>], "action">;
         };
-        readonly request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
+        request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
             amount: import("zod/mini").ZodMiniString<string>;
             chainId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniNumber<number>>;
             channelId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             currency: import("zod/mini").ZodMiniString<string>;
             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>>>;
+            feePayer: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniUnion<readonly [import("zod/mini").ZodMiniBoolean<boolean>, import("zod/mini").ZodMiniCustom<ViemAccount, ViemAccount>]>, import("zod/mini").ZodMiniTransform<boolean, boolean | ViemAccount>>>;
+            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>>;
@@ -69,46 +75,50 @@ export declare function session(parameters?: session.Parameters): Method.Client<
             suggestedDeposit: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             unitType: import("zod/mini").ZodMiniString<string>;
         }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
+            currency: string;
+            recipient?: string | undefined;
+            unitType: string;
+            amount: string;
+            suggestedDeposit?: string | undefined;
             methodDetails: {
-                sessionSnapshot?: import("./Runtime.js").SessionSnapshot | undefined;
-                sessionProtocol?: "v1" | "v2" | undefined;
-                operator?: string | undefined;
-                feePayer?: boolean | undefined;
-                chainId?: number | undefined;
-                minVoucherDelta?: string | undefined;
-                channelId?: string | undefined;
                 escrowContract: string | undefined;
+                channelId?: string | undefined;
+                minVoucherDelta?: string | undefined;
+                chainId?: number | undefined;
+                feePayer?: boolean | undefined;
+                feeToken?: string | undefined;
+                machineTokenEnabled?: boolean | undefined;
+                operator?: string | undefined;
+                sessionProtocol?: "v1" | "v2" | undefined;
+                sessionSnapshot?: import("./Runtime.js").SessionSnapshot | undefined;
             };
-            suggestedDeposit?: string | undefined;
-            amount: string;
-            currency: string;
-            unitType: string;
-            recipient?: string | undefined;
         }, {
             amount: string;
-            currency: string;
-            decimals: number;
-            unitType: string;
             chainId?: number | undefined;
             channelId?: string | undefined;
+            currency: string;
+            decimals: number;
             escrowContract?: string | undefined;
             feePayer?: boolean | undefined;
+            feeToken?: string | undefined;
+            machineTokenEnabled?: boolean | undefined;
             minVoucherDelta?: string | undefined;
             operator?: string | undefined;
             recipient?: string | undefined;
             sessionProtocol?: "v1" | "v2" | undefined;
             sessionSnapshot?: import("./Runtime.js").SessionSnapshot | undefined;
             suggestedDeposit?: string | undefined;
+            unitType: string;
         }>>;
     };
 }, import("zod/mini").ZodMiniObject<{
     account: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<`0x${string}` | Account.Account | undefined, `0x${string}` | Account.Account | undefined>>;
     autoSwap: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<AutoSwap.resolve.Value, AutoSwap.resolve.Value>>;
     action: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniEnum<{
+        close: "close";
         open: "open";
         topUp: "topUp";
         voucher: "voucher";
-        close: "close";
     }>>;
     channelId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniCustom<`0x${string}`, `0x${string}`>>;
     cumulativeAmount: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
@@ -124,13 +134,15 @@ export declare namespace session {
     type ResolveAccount = ResolveAccount_;
     type ResolveAccountInfo = ResolveAccountInfo_;
     type Parameters = Account.getResolver.Parameters & Client.getResolver.Parameters & {
+        /** Accept a noncanonical escrow contract advertised by the server. @default false */
+        allowCustomEscrow?: boolean | undefined;
         /** Automatically acquire the session currency from fallback stablecoins before open/top-up. */
         autoSwap?: AutoSwap.resolve.Value | undefined;
         /** Pluggable persistence for reusable channels. Defaults to an in-memory store. */
         channelStore?: ChannelStore | undefined;
         /** Token decimals for parsing human-readable amounts (default: 6). */
         decimals?: number | undefined;
-        /** TIP20EscrowChannel address override. */
+        /** Exact TIP20EscrowChannel address pin. Takes precedence over `allowCustomEscrow`. */
         escrow?: Address | undefined;
         /** Maximum channel deposit in human-readable units. Caps server-suggested opens and automatic top-ups. */
         maxDeposit?: string | undefined;

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

@@ -1,4 +1,4 @@
-import { parseUnits } from 'viem';
+import { isAddressEqual, parseUnits } from 'viem';
 import { tempo as tempo_chain } from 'viem/chains';
 import * as MethodChallenge from '../../../client/internal/MethodChallenge.js';
 import * as MethodResponse from '../../../client/internal/MethodResponse.js';
@@ -9,13 +9,15 @@ import * as Account from '../../../viem/Account.js';
 import * as Client from '../../../viem/Client.js';
 import * as AutoSwap from '../../internal/auto-swap.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 Chain from '../precompile/Chain.js';
 import * as Channel from '../precompile/Channel.js';
-import { deserializeSessionReceipt, isEventStream, readSessionChallengeAmount, requireSessionCredentialContext, } from '../precompile/Protocol.js';
-import { serializeCredential } from './ChannelOps.js';
-import { createChannelStore } from './ChannelStore.js';
-import { canSignDescriptor, executeCredentialPlan, hasSessionAction, planCredential, resolveChallengeContext, resolveRecoverContext, sessionContextSchema, } from './CredentialState.js';
-import { assertWithinMaxDeposit, resolveAutomaticTopUp } from './Runtime.js';
+import { deserializeSessionReceipt, isEventStream, readSessionChallengeAmount, requireSessionCredentialContext, tip20ChannelEscrow, } from '../precompile/Protocol.js';
+import { createVoucherPayload, serializeCredential } from './ChannelOps.js';
+import { createChannelStore, entryKey } from './ChannelStore.js';
+import { canSignDescriptor, executeCredentialPlan, hasSessionAction, planCredential, requireContextAmount, resolveChallengeContext, resolveRecoverContext, sessionContextSchema, } from './CredentialState.js';
+import { assertWithinMaxDeposit, resolveAutomaticTopUp, resolveOpeningDeposit } from './Runtime.js';
 import { getSessionSnapshot, handleSseNeedVoucher, isTip1034SessionChallenge, postTopUp, wrapSseResponse, } from './Transports.js';
 export { sessionContextSchema } from './CredentialState.js';
 /** Tail promise for each payment scope, used to serialize automatic opens per store. */
@@ -69,6 +71,42 @@ function acknowledgesOpen(outcome, challenge, opened) {
         return matchesOpen(opened, getSessionSnapshot(candidate));
     }) ?? false);
 }
+function applyMachineTokenRoute(resolved, route) {
+    const snapshotDescriptor = resolved.snapshot?.descriptor;
+    const snapshotMatches = snapshotDescriptor &&
+        isAddressEqual(snapshotDescriptor.payee, route.payee) &&
+        isAddressEqual(snapshotDescriptor.operator, route.operator) &&
+        isAddressEqual(snapshotDescriptor.token, route.token);
+    return {
+        ...resolved,
+        operator: route.operator,
+        payee: route.payee,
+        paymentScope: { payee: resolved.payee, token: resolved.token },
+        snapshot: snapshotMatches ? resolved.snapshot : undefined,
+        token: route.token,
+    };
+}
+async function resolveMachineContext(resolved, context) {
+    const descriptor = context?.descriptor ?? resolved.snapshot?.descriptor;
+    if (!descriptor)
+        return undefined;
+    if (!MachineTokenSession.matchDeployment({ chainId: resolved.chainId, descriptor }))
+        return undefined;
+    const closing = context?.action === 'close';
+    if ((!closing && !MachineTokenSession.isEnabledChallenge(resolved.challenge)) ||
+        !isAddressEqual(resolved.escrow, tip20ChannelEscrow))
+        return undefined;
+    const route = await MachineTokenSession.matchRoute(resolved.client, {
+        active: !closing,
+        chainId: resolved.chainId,
+        descriptor,
+        merchant: resolved.payee,
+        targetToken: resolved.token,
+    });
+    if (!route)
+        throw new Error('Machine-token channel is not bound to this merchant session challenge.');
+    return applyMachineTokenRoute(resolved, route);
+}
 /**
  * Creates the low-level TIP-1034 session payment method for use with `Mppx.create()`.
  *
@@ -77,7 +115,7 @@ function acknowledgesOpen(outcome, challenge, opened) {
  * channel descriptor).
  */
 export function session(parameters = {}) {
-    const { account, autoSwap: autoSwapParameter, channelStore, decimals = defaults.decimals, escrow: escrowOverride, getClient: getClientParameter, maxDeposit: maxDepositParameter, topUpAmount: topUpAmountParameter, onChannelUpdate, resolveAccount, } = parameters;
+    const { account, allowCustomEscrow = false, autoSwap: autoSwapParameter, channelStore, decimals = defaults.decimals, escrow: escrowOverride, getClient: getClientParameter, maxDeposit: maxDepositParameter, topUpAmount: topUpAmountParameter, onChannelUpdate, resolveAccount, } = parameters;
     const getClient = Client.getResolver({
         chain: tempo_chain,
         getClient: getClientParameter,
@@ -87,7 +125,15 @@ export function session(parameters = {}) {
     const maxDeposit = maxDepositParameter !== undefined ? parseUnits(maxDepositParameter, decimals) : undefined;
     const topUpAmount = topUpAmountParameter !== undefined ? parseUnits(topUpAmountParameter, decimals) : undefined;
     const store = channelStore ?? createChannelStore();
-    const sink = { store, notifyUpdate: (entry) => onChannelUpdate?.(entry) };
+    const commitEntry = async (entry) => {
+        if (!entry)
+            return;
+        if (entry.opened)
+            await store.set(entry);
+        else
+            await store.delete(entryKey(entry));
+        onChannelUpdate?.(entry);
+    };
     const resolveCredentialAccount = async (resolved, context, entry) => {
         const defaultAccount = getAccount(resolved.client, context);
         const descriptor = context?.action
@@ -103,60 +149,132 @@ export function session(parameters = {}) {
             },
         })) ?? defaultAccount);
     };
-    const resolveCredentialPlan = async (resolved, context, entry) => planCredential({
-        account: await resolveCredentialAccount(resolved, context, entry),
-        entry,
-        context,
-        decimals,
-        maxDeposit,
-        resolved,
+    const resolveContext = (challenge) => resolveChallengeContext({
+        allowCustomEscrow,
+        challenge,
+        escrowOverride,
+        getClient,
     });
+    /** Selects one rail for this channel lifecycle before any credential is signed. */
+    const resolveRail = async (direct, context) => {
+        let account;
+        const descriptor = context?.descriptor ?? direct.snapshot?.descriptor;
+        if (descriptor || hasSessionAction(context)) {
+            const machine = descriptor ? await resolveMachineContext(direct, context) : undefined;
+            const resolved = machine ?? direct;
+            return {
+                account,
+                entry: await store.get(resolved.key),
+                machine: machine !== undefined,
+                resolved,
+            };
+        }
+        const directEntry = await store.get(direct.key);
+        if (directEntry?.opened) {
+            if (!MachineTokenSession.matchDeployment({
+                chainId: direct.chainId,
+                descriptor: directEntry.descriptor,
+            }))
+                return { account, entry: directEntry, machine: false, resolved: direct };
+            const machine = await resolveMachineContext(direct, { descriptor: directEntry.descriptor });
+            if (!machine)
+                throw new Error('Machine-token channel is not bound to this merchant session challenge.');
+            return { account, entry: directEntry, machine: true, resolved: machine };
+        }
+        if (!MachineTokenSession.isEnabledChallenge(direct.challenge) ||
+            !isAddressEqual(direct.escrow, tip20ChannelEscrow))
+            return { account, entry: undefined, machine: false, resolved: direct };
+        const route = await MachineTokenSession.resolveRoute(direct.client, {
+            chainId: direct.chainId,
+            merchant: direct.payee,
+            targetToken: direct.token,
+        }).catch(() => undefined);
+        if (!route)
+            return { account, entry: undefined, machine: false, resolved: direct };
+        const machine = applyMachineTokenRoute(direct, route);
+        account = await resolveCredentialAccount(machine, context, undefined);
+        const openingDeposit = resolveOpeningDeposit({
+            contextDepositRaw: context?.depositRaw,
+            maxDeposit,
+            requestAmount: direct.amount,
+            suggestedDepositRaw: direct.suggestedDepositRaw,
+        });
+        const funded = await MachineTokenSession.hasSufficientBalance(machine.client, {
+            account: account.address,
+            amount: openingDeposit,
+            token: machine.token,
+        });
+        return funded
+            ? { account, entry: undefined, machine: true, resolved: machine }
+            : { account, entry: undefined, machine: false, resolved: direct };
+    };
     const method = Method.toClient(Methods.session, {
         canHandleChallenge: ({ challenge }) => isTip1034SessionChallenge(challenge),
         context: sessionContextSchema,
         async createCredential(parameters) {
             const { challenge, context } = parameters;
-            const resolved = await resolveChallengeContext({
-                challenge,
-                escrowOverride,
-                getClient,
-            });
             const attempt = MethodResponse.getAttempt(parameters);
             let release = () => { };
             try {
-                let entry = await store.get(resolved.key);
-                let plan = await resolveCredentialPlan(resolved, context, entry);
-                if (attempt && plan.type === 'open') {
-                    release = await lockChannel(store, resolved.key);
-                    const nextEntry = await store.get(resolved.key);
-                    if (nextEntry?.channelId !== entry?.channelId) {
-                        entry = nextEntry;
-                        if (entry?.opened) {
-                            await attempt.prepare();
-                            entry = await store.get(resolved.key);
-                        }
-                        plan = await resolveCredentialPlan(resolved, context, entry);
-                    }
+                const direct = await resolveContext(challenge);
+                if (!hasSessionAction(context) && context?.descriptor === undefined) {
+                    release = await lockChannel(store, direct.key);
+                    if (attempt && (await store.get(direct.key))?.opened)
+                        await attempt.prepare();
                 }
-                let pendingOpen;
-                // Defer opens only when low-level Fetch owns the response lifecycle.
-                // SessionManager unregisters this hook and keeps its existing transaction boundary.
-                const credentialSink = attempt && plan.type === 'open'
-                    ? {
-                        store: {
-                            get: (key) => store.get(key),
-                            async set(next) {
-                                pendingOpen = next;
-                            },
-                            delete: (key) => store.delete(key),
-                        },
-                        notifyUpdate() { },
+                const { account, entry, machine, resolved } = await resolveRail(direct, context);
+                const credentialAccount = account ?? (await resolveCredentialAccount(resolved, context, entry));
+                const plan = planCredential({
+                    account: credentialAccount,
+                    entry,
+                    context,
+                    decimals,
+                    maxDeposit,
+                    resolved,
+                });
+                if (machine && plan.type === 'manual' && plan.context.action === 'topUp') {
+                    const additionalDeposit = requireContextAmount(plan.context, plan.decimals, 'additionalDeposit', 'topUp');
+                    if (!(await MachineTokenSession.hasSufficientBalance(plan.resolved.client, {
+                        account: plan.account.address,
+                        amount: additionalDeposit,
+                        token: plan.resolved.token,
+                    })))
+                        throw new Error('Insufficient machine-token balance for session top-up.');
+                }
+                const feeToken = MachineTokenSession.resolveFeeToken({
+                    chainId: resolved.chainId,
+                    override: resolved.feeToken,
+                    paymentToken: resolved.token,
+                });
+                const result = await executeCredentialPlan(plan, AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies), feeToken);
+                let { payload } = result;
+                if (machine && payload.action !== 'topUp') {
+                    if (payload.action === 'close') {
+                        const state = await Chain.getChannelState(plan.resolved.client, payload.channelId, plan.resolved.escrow);
+                        if (state.deposit === 0n)
+                            throw new Error('Cannot authorize a machine-token refund for an empty channel.');
+                        // The refund authorization covers the full on-chain deposit, while
+                        // the close voucher remains the exact amount the merchant captures.
+                        const depositSignature = BigInt(payload.cumulativeAmount) === state.deposit
+                            ? payload.signature
+                            : (await createVoucherPayload(plan.resolved.client, plan.account, payload.descriptor, state.deposit, plan.resolved.chainId, plan.resolved.escrow)).signature;
+                        payload = { ...payload, refundSignature: depositSignature };
                     }
-                    : sink;
-                const payload = await executeCredentialPlan(plan, credentialSink, AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies));
+                    const authorizationSignature = await MachineTokenSession.signAuthorization(plan.resolved.client, plan.account, {
+                        authorization: {
+                            channelId: payload.channelId,
+                            cumulativeAmount: BigInt(payload.cumulativeAmount),
+                        },
+                        chainId: plan.resolved.chainId,
+                        router: plan.resolved.operator,
+                    });
+                    payload = { ...payload, authorizationSignature };
+                }
+                if (!(attempt && plan.type === 'open'))
+                    await commitEntry(result.entry);
                 const credential = await serializeCredential(challenge, payload, resolved.chainId, plan.account);
-                if (attempt && pendingOpen) {
-                    const opened = pendingOpen;
+                if (attempt && plan.type === 'open' && result.entry) {
+                    const opened = result.entry;
                     attempt.settle = async (outcome) => {
                         const accepted = outcome.status === 'accepted' || acknowledgesOpen(outcome, challenge, opened);
                         if (!accepted && outcome.status === 'pending')
@@ -166,8 +284,7 @@ export function session(parameters = {}) {
                                 const current = await store.get(resolved.key);
                                 if (!current?.opened ||
                                     current.channelId.toLowerCase() !== opened.channelId.toLowerCase()) {
-                                    await store.set(opened);
-                                    sink.notifyUpdate(opened);
+                                    await commitEntry(opened);
                                 }
                             }
                             return true;
@@ -211,9 +328,14 @@ export function session(parameters = {}) {
         const nextDeposit = knownDeposit + additionalDeposit;
         if (nextDeposit === channel.deposit)
             return;
-        const updated = { ...channel, deposit: nextDeposit };
+        const current = await store.get(entryKey(channel));
+        const latest = current?.channelId.toLowerCase() === channel.channelId.toLowerCase() ? current : channel;
+        const updated = {
+            ...latest,
+            deposit: latest.deposit > nextDeposit ? latest.deposit : nextDeposit,
+        };
         await store.set(updated);
-        sink.notifyUpdate(updated);
+        onChannelUpdate?.(updated);
     };
     MethodChallenge.register(method, async ({ challenge, context, fetch, input }) => {
         if (!isTip1034SessionChallenge(challenge))
@@ -221,8 +343,11 @@ export function session(parameters = {}) {
         const sessionContext = context === undefined ? undefined : sessionContextSchema.parse(context);
         if (hasSessionAction(sessionContext))
             return;
-        const resolved = await resolveChallengeContext({ challenge, escrowOverride, getClient });
-        const channel = await store.get(resolved.key);
+        const direct = await resolveContext(challenge);
+        const { entry: channel, resolved } = await resolveRail(direct, sessionContext).catch(() => ({
+            entry: undefined,
+            resolved: direct,
+        }));
         if (!channel?.opened)
             return;
         const snapshot = resolved.snapshot?.channelId.toLowerCase() === channel.channelId.toLowerCase()
@@ -250,19 +375,17 @@ export function session(parameters = {}) {
     return MethodResponse.register(method, async ({ challenge, credential, fetch, headers, input, refetch, response, signal }) => {
         if (!isTip1034SessionChallenge(challenge))
             return response;
+        const credentialContext = requireSessionCredentialContext(Credential.deserialize(credential).payload);
         if (!isEventStream(response)) {
-            const credentialContext = requireSessionCredentialContext(Credential.deserialize(credential).payload);
             if (credentialContext.action === 'open' &&
                 headers.get('accept')?.toLowerCase().includes('text/event-stream'))
                 return (await refetch?.()) ?? response;
             return response;
         }
-        const channelKey = (await resolveChallengeContext({
-            challenge,
-            escrowOverride,
-            getClient,
-        })).key;
-        let channel = await store.get(channelKey);
+        const resolvedContext = await resolveContext(challenge)
+            .then(async (direct) => (await resolveMachineContext(direct, credentialContext)) ?? direct)
+            .catch(() => undefined);
+        const channel = resolvedContext ? await store.get(resolvedContext.key) : undefined;
         const driver = {
             assertVoucherWithinLocalLimit: (cumulativeAmount) => assertWithinMaxDeposit(cumulativeAmount, maxDeposit),
             createSessionCredential: (challenge, context) => method.createCredential({ challenge, context }),

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

@@ -64,6 +64,8 @@ export declare namespace sessionManager {
     const serializeSnapshot: typeof serializeSessionSnapshot;
     const deserializeSnapshot: typeof deserializeSessionSnapshot;
     type Parameters = Account.getResolver.Parameters & Client.getResolver.Parameters & {
+        /** Accept a noncanonical escrow contract advertised by the server. @default false */
+        allowCustomEscrow?: boolean | undefined;
         /** Automatically acquire the session currency from fallback stablecoins before open/top-up. */
         autoSwap?: sessionPlugin.Parameters['autoSwap'];
         /** Enables same-route HEAD bootstrap from a server session snapshot before opening a new channel. */
@@ -72,7 +74,7 @@ export declare namespace sessionManager {
         client?: import('viem').Client | undefined;
         /** Token decimals used to convert `maxDeposit` to raw units. Defaults to `6`. */
         decimals?: number | undefined;
-        /** TIP20EscrowChannel precompile address override. */
+        /** Exact TIP20EscrowChannel address pin. Takes precedence over `allowCustomEscrow`. */
         escrow?: Address | undefined;
         /** Fetch implementation used for HTTP probes, management posts, and paid retries. */
         fetch?: typeof globalThis.fetch | undefined;

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

@@ -9,6 +9,7 @@ import * as Account from '../../../viem/Account.js';
 import * as Client from '../../../viem/Client.js';
 import { charge as chargePlugin } from '../../client/Charge.js';
 import * as defaults from '../../internal/defaults.js';
+import { hasRewrittenScope, isMachineChannel } from '../client/ChannelOps.js';
 import { createChannelStore, entryKey } from '../client/ChannelStore.js';
 import { hydrateSessionSnapshot } from '../client/CredentialState.js';
 import { session as sessionPlugin } from '../client/Session.js';
@@ -83,6 +84,7 @@ function resolveSessionManagerConfig(parameters) {
  * `channelStore` can persist reusable channels between manager instances.
  */
 export function sessionManager(parameters) {
+    const allowCustomEscrow = parameters.allowCustomEscrow ?? false;
     const config = resolveSessionManagerConfig(parameters);
     const getClient = Client.getResolver({
         chain: tempo_chain,
@@ -191,6 +193,7 @@ export function sessionManager(parameters) {
     }
     const method = sessionPlugin({
         account: parameters.account,
+        allowCustomEscrow,
         autoSwap: parameters.autoSwap,
         getClient: parameters.client ? () => parameters.client : parameters.getClient,
         resolveAccount: parameters.resolveAccount,
@@ -271,7 +274,7 @@ export function sessionManager(parameters) {
         });
     }
     /** Persists a server snapshot into the channel store and returns the entry. */
-    async function storeSnapshotHeader(response) {
+    async function storeSnapshotHeader(response, paymentScope) {
         const header = response.headers.get(Constants.Headers.paymentSessionSnapshot);
         if (!header)
             return undefined;
@@ -286,11 +289,14 @@ export function sessionManager(parameters) {
                 kind: 'authorizePaymentChannel',
             },
         })) ?? defaultAccount;
-        const { entry, spent } = await hydrateSessionSnapshot({ account, client, snapshot });
+        const hydrated = await hydrateSessionSnapshot({ account, client, snapshot });
+        const entry = paymentScope && hasRewrittenScope({ descriptor: hydrated.entry.descriptor, paymentScope })
+            ? { ...hydrated.entry, paymentScope }
+            : hydrated.entry;
         assertVoucherWithinLocalLimit(entry.cumulativeAmount);
         await Promise.resolve(store.set(entry)).catch(() => undefined);
         runtime.channel = entry;
-        runtime.spent = spent;
+        runtime.spent = hydrated.spent;
         return entry;
     }
     async function bootstrapSession(input, init) {
@@ -331,7 +337,10 @@ export function sessionManager(parameters) {
                 },
             });
             if (response.ok)
-                return await storeSnapshotHeader(response);
+                return await storeSnapshotHeader(response, {
+                    payee: challenge.request.recipient,
+                    token: challenge.request.currency,
+                });
             return undefined;
         }
         catch {
@@ -372,8 +381,9 @@ export function sessionManager(parameters) {
             throw new Error('close snapshot payment scope does not match local session');
         }
         const acceptedCumulative = BigInt(snapshot.acceptedCumulative);
+        const settled = BigInt(snapshot.settled);
         const snapshotSpent = BigInt(snapshot.spent);
-        if (acceptedCumulative < 0n || snapshotSpent < 0n) {
+        if (acceptedCumulative < 0n || settled < 0n || snapshotSpent < 0n) {
             throw new Error('close snapshot amounts must not be negative');
         }
         if (snapshotSpent > acceptedCumulative) {
@@ -382,7 +392,7 @@ export function sessionManager(parameters) {
         if (acceptedCumulative > channel.cumulativeAmount) {
             throw new Error('close snapshot accepted cumulative exceeds local voucher state');
         }
-        return { acceptedCumulative, spent: snapshotSpent };
+        return { acceptedCumulative, settled, spent: snapshotSpent };
     }
     function applyCloseSnapshot(target, challenge) {
         const snapshot = validateCloseSnapshot(target.channel, challenge);
@@ -394,11 +404,20 @@ export function sessionManager(parameters) {
         }
         if (spent > runtime.spent)
             runtime.spent = spent;
+        return snapshot;
     }
     function getValidatedFallbackCloseAmount(target, challenge = target.challenge, applySnapshot = false) {
-        if (applySnapshot)
-            applyCloseSnapshot(target, challenge);
-        const closeAmount = getFallbackCloseAmount(challenge, target.channelId);
+        const snapshot = applySnapshot
+            ? applyCloseSnapshot(target, challenge)
+            : validateCloseSnapshot(target.channel, challenge);
+        const machineSession = isMachineChannel(target.channel);
+        const closeAmount = snapshot
+            ? machineSession
+                ? snapshot.spent > snapshot.settled
+                    ? snapshot.spent
+                    : snapshot.settled
+                : snapshot.acceptedCumulative
+            : getFallbackCloseAmount(challenge, target.channelId);
         if (closeAmount > target.channel.cumulativeAmount) {
             throw new Error('fallback close amount exceeds local voucher state');
         }
@@ -526,11 +545,10 @@ export function sessionManager(parameters) {
             trackCreates: false,
         };
         channelUse = use;
-        // Cold starts resume from `channelStore` after the 402 reveals the scope.
-        const liveHint = runtime.channel?.opened ? runtime.channel.channelId : undefined;
         try {
             await bootstrapSession(input, init);
             use.trackCreates = true;
+            const liveHint = runtime.channel?.opened ? runtime.channel.channelId : undefined;
             let effectiveInit = requestInitWithSessionHint(input, init, liveHint);
             // Stored channels may be stale, so retry once after evicting the resumed entry.
             let canRetryResumed = !previous.channel?.opened;
@@ -538,6 +556,11 @@ export function sessionManager(parameters) {
                 const resumed = use.resumed;
                 if (!canRetryResumed || !resumed)
                     return false;
+                // A machine-token entry holds the only local copy of its channel
+                // descriptor; evicting it would strand the deposit, so fail loudly
+                // instead of retrying without it.
+                if (resumed.opened && (isMachineChannel(resumed) || hasRewrittenScope(resumed)))
+                    return false;
                 canRetryResumed = false;
                 await ignoreChannel(resumed);
                 effectiveInit = requestInitWithSessionHint(input, init, undefined);
@@ -598,6 +621,7 @@ export function sessionManager(parameters) {
         const receipt = await closeHttpSession({
             createSessionCredential,
             fetch: config.fetch,
+            getMinimumSpent: () => runtime.spent,
             lastUrl: runtime.lastUrl,
             resolveSignedCloseAmount: (challenge) => getValidatedFallbackCloseAmount(target, challenge, true),
             signedCloseAmount: getValidatedFallbackCloseAmount(target),

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

@@ -246,6 +246,8 @@ export type CloseHttpSessionParameters = {
     fetch: typeof globalThis.fetch;
     /** Last paid resource URL; used as the management endpoint base. */
     lastUrl: RequestInfo | URL | null;
+    /** Returns the latest cumulative spend already confirmed by the client. */
+    getMinimumSpent?: (() => bigint) | undefined;
     /** Resolves the close amount again when the server refreshes the challenge. */
     resolveSignedCloseAmount?: ((challenge: TempoSessionChallenge) => string) | undefined;
     /** Final cumulative amount the client is willing to sign. */