mppx 0.13.5 → 0.14.0

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

@@ -22,6 +22,9 @@ export declare function markPrepaidSessionTick(receipt: SessionReceipt): Session
  * - Fallback to standard HTTP receipt handling for plain Response
  */
 export declare function sse(options: sse.Options & {
+    beforeCharge?: ((channelId: `0x${string}`) => Promise<void>) | undefined;
+    /** Charges the verified route's price: reusable challenges are not bound to their quoted amount. */
+    reusableChallenges?: boolean | undefined;
     settleCharged?: SettleChargedSessionChannel | undefined;
     store: ChannelStore.ChannelStore;
 }): Sse;

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

@@ -70,7 +70,10 @@ export function sse(options) {
             const verifiedRequest = envelope?.request ?? verifiedCredential.challenge.request;
             const payload = requireSessionCredentialContext(verifiedCredential.payload, 'No SSE context available');
             const channelId = payload.channelId;
-            const tickCost = BigInt(verifiedCredential.challenge.request.amount);
+            // A reusable challenge may have quoted another request's price, so charge the verified route's
+            // canonical price. Otherwise the challenge amount is canonical and bound to the route.
+            const tickCost = BigInt((options.reusableChallenges ? verifiedRequest : verifiedCredential.challenge.request)
+                .amount);
             const unitType = typeof verifiedRequest.unitType === 'string' ? verifiedRequest.unitType : undefined;
             // Auto-detect upstream SSE responses and parse them into an
             // AsyncIterable so they flow through the metered pipeline.
@@ -91,6 +94,7 @@ export function sse(options) {
                     tickCost,
                     pollIntervalMs: pollingInterval,
                     generate,
+                    beforeCharge: () => options.beforeCharge?.(channelId),
                     onChargeCommitted: options.settleCharged,
                     prepaidUnits: hasPrepaidSessionTick(receipt) ? 1 : 0,
                     signal: input.signal,

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

@@ -23,6 +23,8 @@ export type ChannelEntry = {
     channelId: Hex.Hex;
     /** Highest cumulative amount this client has locally authorized. */
     cumulativeAmount: bigint;
+    /** Blocks new deposits until an uncertain top-up has been reconciled against trusted chain state. */
+    uncertainTopUp?: boolean | undefined;
     /** Latest channel deposit known by the client. */
     deposit: bigint;
     /** TIP-1034 descriptor required for vouchers, top-ups, and close credentials. */

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

@@ -1,7 +1,10 @@
 import type { Address } from 'viem';
 import type { MaybePromise } from '../../../internal/types.js';
 import type { ChannelEntry } from './ChannelOps.js';
-/** Store of reusable payer session channels keyed by payment scope. */
+/**
+ * Store of reusable payer session channels keyed by payment scope.
+ * Callers sharing a backend across processes must coordinate funding and writes externally.
+ */
 export type ChannelStore = {
     /** Returns the channel cached for `key`, when present. */
     get(key: string): MaybePromise<ChannelEntry | undefined>;
@@ -48,4 +51,12 @@ export type JsonChannelKv = {
 };
 /** Wraps a string KV backend as a bigint-safe channel store. */
 export declare function createJsonChannelStore(kv: JsonChannelKv): ChannelStore;
+/** @internal Shares funding coordination between a manager's store view and its backing store. */
+export declare function registerFundingStore(view: ChannelStore, backing: ChannelStore): void;
+/** @internal Serializes funding decisions for callers sharing one backing store in this process. */
+export declare function withFundingLock<T>(store: ChannelStore, key: string, operation: () => Promise<T>): Promise<T>;
+/** @internal Serializes writes and preserves unresolved funding across stale channel copies. */
+export declare function persistChannel(store: ChannelStore, entry: ChannelEntry): Promise<void>;
+/** @internal Retains unresolved funding records through close and stale-entry cleanup. */
+export declare function deleteChannel(store: ChannelStore, key: string): Promise<void>;
 //# sourceMappingURL=ChannelStore.d.ts.map

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

@@ -60,4 +60,51 @@ export function createJsonChannelStore(kv) {
         },
     };
 }
+const pendingOperations = new WeakMap();
+const fundingStores = new WeakMap();
+/** @internal Shares funding coordination between a manager's store view and its backing store. */
+export function registerFundingStore(view, backing) {
+    fundingStores.set(view, fundingStores.get(backing) ?? backing);
+}
+async function exclusive(store, key, operation) {
+    let pending = pendingOperations.get(store);
+    if (!pending) {
+        pending = new Map();
+        pendingOperations.set(store, pending);
+    }
+    const previous = pending.get(key) ?? Promise.resolve();
+    const result = previous.catch(() => { }).then(operation);
+    pending.set(key, result);
+    try {
+        return await result;
+    }
+    finally {
+        if (pending.get(key) === result)
+            pending.delete(key);
+    }
+}
+/** @internal Serializes funding decisions for callers sharing one backing store in this process. */
+export function withFundingLock(store, key, operation) {
+    return exclusive(fundingStores.get(store) ?? store, `funding:${key}`, operation);
+}
+/** @internal Serializes writes and preserves unresolved funding across stale channel copies. */
+export async function persistChannel(store, entry) {
+    await exclusive(store, `write:${entryKey(entry)}`, async () => {
+        const current = await store.get(entryKey(entry));
+        if (current?.uncertainTopUp) {
+            if (current.channelId !== entry.channelId)
+                throw new Error('Session funding outcome is unknown; reconcile the pending payment before replacing the channel.');
+            entry.uncertainTopUp = true;
+        }
+        await store.set(entry);
+    });
+}
+/** @internal Retains unresolved funding records through close and stale-entry cleanup. */
+export async function deleteChannel(store, key) {
+    await exclusive(store, `write:${key}`, async () => {
+        if ((await store.get(key))?.uncertainTopUp)
+            return;
+        await store.delete(key);
+    });
+}
 //# sourceMappingURL=ChannelStore.js.map

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

@@ -7,7 +7,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, entryKey, persistChannel, deleteChannel, } from './ChannelStore.js';
 import { assertWithinMaxDeposit, resolveOpeningDeposit } from './Runtime.js';
 /** Returns whether a credential payload carries cumulative voucher authorization. */
 export function hasCredentialCumulativeAmount(payload) {
@@ -26,9 +26,9 @@ export function readCredentialCumulativeAmount(payload) {
  */
 async function storeChannelEntry(sink, entry) {
     if (entry.opened)
-        await sink.store.set(entry);
+        await persistChannel(sink.store, entry);
     else
-        await sink.store.delete(entryKey(entry));
+        await deleteChannel(sink.store, entryKey(entry));
     sink.notifyUpdate(entry);
 }
 /** Applies a credential payload's cumulative amount to the stored channel at `key`. */
@@ -338,6 +338,7 @@ async function resolveAutoSwapCalls(autoSwap, parameters) {
         tokenOut: parameters.tokenOut,
         tokenIn: autoSwap.tokenIn,
         slippage: autoSwap.slippage,
+        maxAmountIn: autoSwap.maxAmountIn,
     }));
 }
 async function open(plan, sink, autoSwap) {
@@ -403,7 +404,11 @@ 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);
+    const current = await sink.store.get(resolved.key);
     await storeChannelEntry(sink, {
+        ...(current?.channelId === reusable.channelId && current.uncertainTopUp
+            ? { uncertainTopUp: true }
+            : {}),
         channelId: reusable.channelId,
         cumulativeAmount,
         deposit: reusable.state.deposit,

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

@@ -13,7 +13,7 @@ import * as Methods from '../../Methods.js';
 import * as Channel from '../precompile/Channel.js';
 import { deserializeSessionReceipt, isEventStream, readSessionChallengeAmount, requireSessionCredentialContext, } from '../precompile/Protocol.js';
 import { serializeCredential } from './ChannelOps.js';
-import { createChannelStore, entryKey } from './ChannelStore.js';
+import { createChannelStore, entryKey, persistChannel, withFundingLock, } from './ChannelStore.js';
 import { canSignDescriptor, executeCredentialPlan, hasSessionAction, planCredential, resolveChallengeContext, resolveRecoverContext, sessionContextSchema, } from './CredentialState.js';
 import { assertWithinMaxDeposit, resolveAutomaticTopUp } from './Runtime.js';
 import { getSessionSnapshot, handleSseNeedVoucher, isTip1034SessionChallenge, postTopUp, wrapSseResponse, } from './Transports.js';
@@ -174,7 +174,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);
+                                    await persistChannel(store, opened);
                                     sink.notifyUpdate(opened);
                                 }
                             }
@@ -196,38 +196,55 @@ export function session(parameters = {}) {
         },
     });
     const topUpChannelIfNeeded = async ({ challenge, channel, deposit, fetch, input, requiredCumulative, signal, }) => {
-        const knownDeposit = channel.deposit > deposit ? channel.deposit : deposit;
-        const additionalDeposit = resolveAutomaticTopUp({
-            deposit: knownDeposit,
-            maxDeposit,
-            requiredCumulative,
-            suggestedDeposit: challenge.request.suggestedDeposit === undefined
-                ? undefined
-                : BigInt(challenge.request.suggestedDeposit),
-            topUpAmount,
-        });
-        if (additionalDeposit > 0n)
-            await postTopUp({
-                additionalDeposit,
-                challenge,
-                channel,
-                channelId: channel.channelId,
-                createSessionCredential: (challenge, context) => method.createCredential({ challenge, context }),
-                fetch,
-                input,
-                signal,
+        return withFundingLock(store, entryKey(channel), async () => {
+            signal?.throwIfAborted();
+            const fundingChannel = await store.get(entryKey(channel));
+            if (fundingChannel?.channelId === channel.channelId)
+                channel = fundingChannel;
+            if (channel.uncertainTopUp)
+                throw new Error('Session funding outcome is unknown; reconcile the pending payment before another top-up.');
+            const knownDeposit = channel.deposit > deposit ? channel.deposit : deposit;
+            const additionalDeposit = resolveAutomaticTopUp({
+                deposit: knownDeposit,
+                maxDeposit,
+                requiredCumulative,
+                suggestedDeposit: challenge.request.suggestedDeposit === undefined
+                    ? undefined
+                    : BigInt(challenge.request.suggestedDeposit),
+                topUpAmount,
             });
-        const nextDeposit = knownDeposit + additionalDeposit;
-        if (nextDeposit === channel.deposit)
-            return;
-        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);
+            if (additionalDeposit > 0n)
+                await postTopUp({
+                    additionalDeposit,
+                    challenge,
+                    channel,
+                    channelId: channel.channelId,
+                    createSessionCredential: (challenge, context) => method.createCredential({ challenge, context }),
+                    onUncertainFunding: async (entry) => {
+                        const current = await store.get(entryKey(entry));
+                        const unresolved = {
+                            ...(current?.channelId === entry.channelId ? current : entry),
+                            uncertainTopUp: true,
+                        };
+                        await persistChannel(store, unresolved);
+                        sink.notifyUpdate(unresolved);
+                    },
+                    fetch,
+                    input,
+                    signal,
+                });
+            const nextDeposit = knownDeposit + additionalDeposit;
+            if (nextDeposit === channel.deposit)
+                return;
+            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 persistChannel(store, updated);
+            sink.notifyUpdate(updated);
+        });
     };
     MethodChallenge.register(method, async ({ challenge, context, fetch, input, signal }) => {
         if (!isTip1034SessionChallenge(challenge))

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

@@ -9,7 +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 { createChannelStore, entryKey } from '../client/ChannelStore.js';
+import { createChannelStore, deleteChannel, entryKey, persistChannel as persistStoredChannel, registerFundingStore, withFundingLock, } from '../client/ChannelStore.js';
 import { hydrateSessionSnapshot, sessionContextSchema, } from '../client/CredentialState.js';
 import { session as sessionPlugin } from '../client/Session.js';
 import * as Channel from '../precompile/Channel.js';
@@ -24,7 +24,7 @@ import { closeSocketSession } from './Runtime.js';
 import { closeHttpSession, getSessionSnapshot, isTempoSessionChallenge, postTopUp, retryHttpPaymentRequired, webSocketProbeUrl, } from './Transports.js';
 import { WebSocketReadyState, } from './Transports.js';
 import { consumeSseSessionResponse, openSseSession } from './Transports.js';
-import { applyTopUpResult, resolveManualTopUp } from './Transports.js';
+import { UncertainFundingError, applyTopUpResult, resolveManualTopUp, } from './Transports.js';
 import { openWebSocketSession, prepareWebSocketSession, probeWebSocketSession, } from './Transports.js';
 export { computeFallbackCloseAmount } from './Runtime.js';
 function isTempoChargeChallenge(challenge) {
@@ -117,6 +117,7 @@ export function sessionManager(parameters) {
             return entry;
         return undefined;
     }
+    const persistChannel = (entry) => persistStoredChannel(backing, entry);
     const store = {
         async get(key) {
             const entry = await getReusable(key);
@@ -133,26 +134,34 @@ export function sessionManager(parameters) {
                 ignoredChannelIds.delete(entry.channelId);
             if (channelUse?.trackCreates && !channelUse.seenExisting.has(key))
                 channelUse.created.set(key, entry);
-            await backing.set(entry);
+            await persistChannel(entry);
         },
-        delete: (key) => backing.delete(key),
+        delete: (key) => deleteChannel(backing, key),
     };
+    registerFundingStore(store, backing);
     /** Removes a failed channel from candidacy for the rest of this manager's life. */
     async function ignoreChannel(entry) {
         const key = entryKey(entry);
+        const current = await backing.get(key);
+        if (entry.uncertainTopUp || current?.uncertainTopUp)
+            throw new Error('Session funding outcome is unknown; reconcile the pending payment before replacing the channel.');
         ignoredChannelIds.add(entry.channelId);
         channelUse?.seenExisting.delete(key);
         if (channelUse?.resumed === entry)
             channelUse.resumed = undefined;
-        await Promise.resolve(backing.delete(key)).catch(() => undefined);
+        await Promise.resolve(deleteChannel(backing, key)).catch(() => undefined);
     }
     async function rollbackCreatedChannels() {
         const use = channelUse;
         if (!use?.created.size)
             return;
         for (const [key, entry] of use.created) {
+            const current = await backing.get(key);
+            if (entry.uncertainTopUp ||
+                (current?.channelId === entry.channelId && current.uncertainTopUp))
+                throw new Error('Session funding outcome is unknown; reconcile the pending payment before discarding the channel.');
             ignoredChannelIds.add(entry.channelId);
-            await Promise.resolve(backing.delete(key)).catch(() => undefined);
+            await Promise.resolve(deleteChannel(backing, key)).catch(() => undefined);
         }
         use.created.clear();
         await restoreRuntime(use.committed ?? use.previous);
@@ -193,7 +202,7 @@ export function sessionManager(parameters) {
         const baseline = use?.committed?.channel?.entry ?? use?.resumed;
         if (!use ||
             baseline?.channelId.toLowerCase() !== entry.channelId.toLowerCase() ||
-            entry.deposit <= baseline.deposit)
+            (entry.deposit <= baseline.deposit && !entry.uncertainTopUp))
             return;
         use.resumed = undefined;
         use.committed = captureRuntimeStateSnapshot({
@@ -230,6 +239,9 @@ export function sessionManager(parameters) {
             commitDurableTopUp(entry);
         },
     });
+    const handleMethodChallenge = MethodChallenge.get(method);
+    if (handleMethodChallenge)
+        MethodChallenge.register(method, (parameters) => withTopUpLock(() => Promise.resolve(handleMethodChallenge(parameters)), parameters.signal));
     MethodResponse.unregister(method);
     const chargeMethod = chargePlugin({
         allowedChainIds: parameters.allowedChainIds,
@@ -435,60 +447,155 @@ export function sessionManager(parameters) {
             maxVoucherCumulative: config.maxVoucherCumulative,
         });
     }
+    let pendingTopUp;
+    let uncertainFunding;
+    // Keep funding decisions and their deposit updates atomic within this manager.
+    // Waiters share failures instead of immediately retrying an uncertain payment.
+    async function withTopUpLock(operation, signal) {
+        if (uncertainFunding)
+            throw uncertainFunding;
+        for (;;) {
+            const pending = pendingTopUp;
+            if (!pending)
+                break;
+            if (!signal)
+                await pending;
+            else {
+                signal.throwIfAborted();
+                let abort;
+                try {
+                    await Promise.race([
+                        pending,
+                        new Promise((_, reject) => {
+                            abort = () => reject(signal.reason);
+                            signal.addEventListener('abort', abort, { once: true });
+                        }),
+                    ]);
+                }
+                finally {
+                    signal.removeEventListener('abort', abort);
+                }
+            }
+        }
+        signal?.throwIfAborted();
+        if (uncertainFunding)
+            throw uncertainFunding;
+        const pending = operation();
+        pendingTopUp = pending;
+        try {
+            return await pending;
+        }
+        catch (error) {
+            if (error instanceof UncertainFundingError)
+                uncertainFunding = new Error('Session funding outcome is unknown; reconcile the pending payment before creating a new session manager.');
+            throw error;
+        }
+        finally {
+            if (pendingTopUp === pending)
+                pendingTopUp = undefined;
+        }
+    }
     async function postTopUpAndApply(parameters) {
-        const { knownDeposit, ...topUp } = parameters;
-        const receipt = await postTopUp({
-            ...topUp,
-            channel: runtime.channel,
-            createSessionCredential,
-            fetch: config.fetch,
-        });
-        updateSpentFromReceipt(receipt);
-        const applied = applyTopUpResult({
-            additionalDeposit: parameters.additionalDeposit,
-            channel: runtime.channel,
-            channelId: parameters.channelId,
-            challengeId: runtime.lastChallenge?.id,
-            currentState: runtime.state,
-            knownDeposit,
-            receipt,
-            spent: runtime.spent,
-        });
-        if (applied?.channel && runtime.lastChallenge) {
-            await store.set(applied.channel);
-            dispatch({
-                type: 'activated',
-                challengeId: runtime.lastChallenge.id,
-                entry: applied.channel,
-                spent: runtime.spent.toString(),
-                units: activeUnits(),
+        if (!runtime.channel)
+            throw new Error('Cannot top up session: no active channel');
+        return withFundingLock(backing, entryKey(runtime.channel), async () => {
+            const { knownDeposit, ...topUp } = parameters;
+            const stored = runtime.channel ? await store.get(entryKey(runtime.channel)) : undefined;
+            if (stored?.channelId === parameters.channelId && stored.uncertainTopUp)
+                throw new Error('Session funding outcome is unknown; reconcile the pending payment before another top-up.');
+            const receipt = await postTopUp({
+                ...topUp,
+                channel: runtime.channel,
+                createSessionCredential,
+                fetch: config.fetch,
+                onUncertainFunding: async (channel) => {
+                    const current = await store.get(entryKey(channel));
+                    const unresolved = {
+                        ...(current?.channelId === channel.channelId ? current : channel),
+                        uncertainTopUp: true,
+                    };
+                    if (runtime.channel?.channelId === channel.channelId)
+                        runtime.channel = unresolved;
+                    await store.set(unresolved);
+                    commitDurableTopUp(unresolved);
+                },
             });
-            commitDurableTopUp(applied.channel);
-        }
-        return receipt;
+            updateSpentFromReceipt(receipt);
+            let baseline = runtime.channel;
+            const applied = applyTopUpResult({
+                additionalDeposit: parameters.additionalDeposit,
+                channel: runtime.channel,
+                channelId: parameters.channelId,
+                challengeId: runtime.lastChallenge?.id,
+                currentState: runtime.state,
+                knownDeposit,
+                receipt,
+                spent: runtime.spent,
+            });
+            if (applied?.channel && runtime.lastChallenge) {
+                let entry = applied.channel;
+                for (;;) {
+                    await store.set(entry);
+                    const current = runtime.channel;
+                    if (current === baseline)
+                        break;
+                    // A completed deposit must not restore a replaced session. For the same
+                    // channel retain newer vouchers while recording the confirmed funding.
+                    if (!current)
+                        return receipt;
+                    const funded = applied.channel;
+                    entry =
+                        current.channelId !== funded.channelId
+                            ? current
+                            : {
+                                ...current,
+                                deposit: current.deposit > funded.deposit ? current.deposit : funded.deposit,
+                                cumulativeAmount: current.cumulativeAmount > funded.cumulativeAmount
+                                    ? current.cumulativeAmount
+                                    : funded.cumulativeAmount,
+                            };
+                    baseline = current;
+                }
+                if (entry.channelId !== applied.channel.channelId)
+                    return receipt;
+                runtime.channel = entry;
+                dispatch({
+                    type: 'activated',
+                    challengeId: runtime.lastChallenge.id,
+                    entry,
+                    spent: runtime.spent.toString(),
+                    units: activeUnits(),
+                });
+                commitDurableTopUp(entry);
+            }
+            return receipt;
+        });
     }
     async function topUpIfNeeded(parameters) {
-        const channelDeposit = runtime.channel?.channelId === parameters.channelId ? runtime.channel.deposit : 0n;
-        const deposit = channelDeposit > parameters.deposit ? channelDeposit : parameters.deposit;
-        const additionalDeposit = resolveAutomaticTopUp({
-            deposit,
-            maxDeposit: config.maxVoucherCumulative,
-            requiredCumulative: parameters.requiredCumulative,
-            suggestedDeposit: parameters.challenge.request.suggestedDeposit === undefined
-                ? undefined
-                : BigInt(parameters.challenge.request.suggestedDeposit),
-            topUpAmount: config.topUpAmount,
-        });
-        if (additionalDeposit === 0n)
-            return;
-        await postTopUpAndApply({
-            challenge: parameters.challenge,
-            input: parameters.input,
-            channelId: parameters.channelId,
-            additionalDeposit,
-            knownDeposit: deposit,
-            signal: parameters.signal,
-        });
+        return withTopUpLock(async () => {
+            parameters.signal?.throwIfAborted();
+            const channelDeposit = runtime.channel?.channelId === parameters.channelId ? runtime.channel.deposit : 0n;
+            const deposit = channelDeposit > parameters.deposit ? channelDeposit : parameters.deposit;
+            const additionalDeposit = resolveAutomaticTopUp({
+                deposit,
+                maxDeposit: config.maxVoucherCumulative,
+                requiredCumulative: parameters.requiredCumulative,
+                suggestedDeposit: parameters.challenge.request.suggestedDeposit === undefined
+                    ? undefined
+                    : BigInt(parameters.challenge.request.suggestedDeposit),
+                topUpAmount: config.topUpAmount,
+            });
+            if (additionalDeposit === 0n)
+                return;
+            await postTopUpAndApply({
+                challenge: parameters.challenge,
+                input: parameters.input,
+                channelId: parameters.channelId,
+                additionalDeposit,
+                knownDeposit: deposit,
+                signal: parameters.signal,
+            });
+        }, parameters.signal);
     }
     async function restoreCumulative(channelId, cumulativeAmount) {
         const restored = restoreCumulativeAuthorization({
@@ -507,7 +614,7 @@ export function sessionManager(parameters) {
                 spent: restored.spent,
                 units: restored.units,
             });
-            await backing.set(runtime.channel);
+            await persistChannel(runtime.channel);
         }
     }
     async function restoreRuntime(snapshot) {
@@ -516,7 +623,7 @@ export function sessionManager(parameters) {
         runtime.spent = restored.spent;
         runtime.state = restored.state;
         if (runtime.channel?.opened)
-            await backing.set(runtime.channel);
+            await persistChannel(runtime.channel);
     }
     function toPaymentResponse(response) {
         const receiptHeader = response.headers.get(Constants.Headers.paymentReceipt);
@@ -667,7 +774,7 @@ export function sessionManager(parameters) {
         },
         fetch: doFetch,
         async topUp(amount) {
-            const target = resolveManualTopUp({
+            const intended = resolveManualTopUp({
                 amount,
                 assertVoucherWithinLocalLimit,
                 channel: runtime.channel,
@@ -675,11 +782,25 @@ export function sessionManager(parameters) {
                 lastChallenge: runtime.lastChallenge,
                 lastUrl: runtime.lastUrl,
             });
-            return postTopUpAndApply({
-                additionalDeposit: target.additionalDeposit,
-                challenge: target.challenge,
-                channelId: target.channelId,
-                input: target.input,
+            return withTopUpLock(async () => {
+                if (runtime.channel?.channelId !== intended.channelId ||
+                    runtime.lastChallenge !== intended.challenge ||
+                    runtime.lastUrl !== intended.input)
+                    throw new Error('Session changed while waiting to top up');
+                const target = resolveManualTopUp({
+                    amount,
+                    assertVoucherWithinLocalLimit,
+                    channel: runtime.channel,
+                    decimals: config.decimals,
+                    lastChallenge: intended.challenge,
+                    lastUrl: intended.input,
+                });
+                return postTopUpAndApply({
+                    additionalDeposit: target.additionalDeposit,
+                    challenge: target.challenge,
+                    channelId: target.channelId,
+                    input: target.input,
+                });
             });
         },
         async sse(input, init) {

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

@@ -213,6 +213,8 @@ export type PostTopUpParameters = {
     input: RequestInfo | URL;
     /** Cancels the top-up management request. */
     signal?: AbortSignal | undefined;
+    /** Persists an unresolved funding outcome before another caller can reuse the channel. */
+    onUncertainFunding?: ((channel: ChannelEntry) => Promise<void>) | undefined;
 };
 /** Inputs for retrying an HTTP 402 with a top-up/voucher management round trip. */
 export type RetryHttpPaymentRequiredParameters = {
@@ -277,6 +279,10 @@ export declare function managementInput(input: RequestInfo | URL): RequestInfo |
 export declare function webSocketProbeUrl(input: string | URL): URL;
 /** Reads an HTTP problem detail body, falling back to raw text for non-problem responses. */
 export declare function readProblemDetail(response: Response): Promise<string>;
+/** A dispatched deposit may have executed despite a failed or cancelled response. */
+export declare class UncertainFundingError extends Error {
+    constructor(reason: unknown);
+}
 /** Posts a top-up management credential and returns its receipt, when present. */
 export declare function postTopUp(parameters: PostTopUpParameters): Promise<SessionReceipt | undefined>;
 /** Retries an HTTP 402 when the server snapshot asks for more voucher headroom. */