mppx 0.8.13 → 0.8.14

package/src/tempo/session/client/Session.ts

@@ -1,8 +1,8 @@
 import { type Address, 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'
-import * as Constants from '../../../Constants.js'
 import * as Credential from '../../../Credential.js'
 import * as Method from '../../../Method.js'
 import * as Account from '../../../viem/Account.js'
@@ -11,26 +11,36 @@ import type {
   ResolveAccount as ResolveAccount_,
   ResolveAccountInfo as ResolveAccountInfo_,
 } from '../../client/ResolveAccount.js'
+import * as AutoSwap from '../../internal/auto-swap.js'
 import * as defaults from '../../internal/defaults.js'
 import * as Methods from '../../Methods.js'
-import { isEventStream, requireSessionCredentialContext } from '../precompile/Protocol.js'
+import * as Channel from '../precompile/Channel.js'
+import {
+  isEventStream,
+  readSessionChallengeAmount,
+  requireSessionCredentialContext,
+} from '../precompile/Protocol.js'
 import { serializeCredential, type ChannelEntry } from './ChannelOps.js'
 import { createChannelStore, type ChannelStore } from './ChannelStore.js'
 import {
+  canSignDescriptor,
   executeCredentialPlan,
+  hasSessionAction,
   planCredential,
   resolveChallengeContext,
   resolveRecoverContext,
   sessionContextSchema,
+  type ChallengeContext,
+  type SessionContext as CredentialContext,
 } from './CredentialState.js'
-import { assertWithinMaxDeposit } from './Runtime.js'
+import { assertWithinMaxDeposit, resolveAutomaticTopUp } from './Runtime.js'
 import {
   handleSseNeedVoucher,
-  isTempoSessionChallenge,
-  managementInput,
+  isTip1034SessionChallenge,
   postTopUp,
   wrapSseResponse,
   type SsePaymentDriver,
+  type TempoSessionChallenge,
 } from './Transports.js'
 
 export { sessionContextSchema, type SessionContext } from './CredentialState.js'
@@ -45,11 +55,13 @@ export { sessionContextSchema, type SessionContext } from './CredentialState.js'
 export function session(parameters: session.Parameters = {}) {
   const {
     account,
+    autoSwap: autoSwapParameter,
     channelStore,
     decimals = defaults.decimals,
     escrow: escrowOverride,
     getClient: getClientParameter,
     maxDeposit: maxDepositParameter,
+    topUpAmount: topUpAmountParameter,
     onChannelUpdate,
     resolveAccount,
   } = parameters
@@ -61,18 +73,35 @@ export function session(parameters: session.Parameters = {}) {
   const getAccount = Account.getResolver({ account })
   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: ChannelEntry) => onChannelUpdate?.(entry) }
 
+  const resolveCredentialAccount = async (
+    resolved: ChallengeContext,
+    context: CredentialContext | undefined,
+    entry: ChannelEntry | undefined,
+  ) => {
+    const defaultAccount = getAccount(resolved.client, context)
+    const descriptor = context?.action
+      ? context.descriptor
+      : (entry?.descriptor ??
+        resolveRecoverContext({ context, snapshot: resolved.snapshot })?.descriptor)
+    return (
+      (await resolveAccount?.({
+        account: defaultAccount,
+        chainId: resolved.chainId,
+        operation: {
+          kind: 'authorizePaymentChannel',
+          ...(descriptor ? { authority: Channel.resolveAuthorizedSigner(descriptor) } : {}),
+        },
+      })) ?? defaultAccount
+    )
+  }
+
   const method = Method.toClient(Methods.session, {
-    canHandleChallenge({ challenge }) {
-      return (
-        Constants.getMethodDetail(
-          challenge.request.methodDetails,
-          Constants.MethodDetailKeys.sessionProtocol,
-        ) === Constants.SessionProtocols.v2
-      )
-    },
+    canHandleChallenge: ({ challenge }) => isTip1034SessionChallenge(challenge),
     context: sessionContextSchema,
     async createCredential({ challenge, context }) {
       const resolved = await resolveChallengeContext({
@@ -80,22 +109,8 @@ export function session(parameters: session.Parameters = {}) {
         escrowOverride,
         getClient,
       })
-      const defaultAccount = getAccount(resolved.client, context)
       const entry = await store.get(resolved.key)
-      // Resolve recovery hints early so account selection can satisfy an existing channel authority.
-      const recoverContext = resolveRecoverContext({ context, snapshot: resolved.snapshot })
-      const descriptor = context?.action
-        ? context.descriptor
-        : (entry?.descriptor ?? recoverContext?.descriptor)
-      const account =
-        (await resolveAccount?.({
-          account: defaultAccount,
-          chainId: resolved.chainId,
-          operation: {
-            kind: 'authorizePaymentChannel',
-            ...(descriptor ? { authority: descriptor.authorizedSigner } : {}),
-          },
-        })) ?? defaultAccount
+      const account = await resolveCredentialAccount(resolved, context, entry)
       const payload = await executeCredentialPlan(
         planCredential({
           account,
@@ -106,15 +121,89 @@ export function session(parameters: session.Parameters = {}) {
           resolved,
         }),
         sink,
+        AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies),
       )
       return serializeCredential(challenge, payload, resolved.chainId, account)
     },
   })
 
+  const topUpChannelIfNeeded = async ({
+    challenge,
+    channel,
+    deposit,
+    fetch,
+    input,
+    requiredCumulative,
+  }: {
+    challenge: TempoSessionChallenge
+    channel: ChannelEntry
+    deposit: bigint
+    fetch: typeof globalThis.fetch
+    input: RequestInfo | URL
+    requiredCumulative: bigint
+  }) => {
+    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,
+      })
+    const nextDeposit = knownDeposit + additionalDeposit
+    if (nextDeposit === channel.deposit) return
+    const updated = { ...channel, deposit: nextDeposit }
+    await store.set(updated)
+    sink.notifyUpdate(updated)
+  }
+
+  MethodChallenge.register(method, async ({ challenge, context, fetch, input }) => {
+    if (!isTip1034SessionChallenge(challenge)) return
+    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)
+    if (!channel?.opened) return
+    const snapshot =
+      resolved.snapshot?.channelId.toLowerCase() === channel.channelId.toLowerCase()
+        ? resolved.snapshot
+        : undefined
+    const nextCumulative = channel.cumulativeAmount + readSessionChallengeAmount(challenge)
+    const snapshotRequired = snapshot ? BigInt(snapshot.requiredCumulative) : nextCumulative
+    const requiredCumulative = snapshotRequired > nextCumulative ? snapshotRequired : nextCumulative
+    const snapshotDeposit = snapshot ? BigInt(snapshot.deposit) : channel.deposit
+    const deposit = snapshotDeposit > channel.deposit ? snapshotDeposit : channel.deposit
+    if (requiredCumulative <= deposit && deposit === channel.deposit) return
+    const account = await resolveCredentialAccount(resolved, sessionContext, channel)
+    if (!canSignDescriptor(account, channel.descriptor)) return
+    await topUpChannelIfNeeded({
+      challenge,
+      channel,
+      deposit,
+      fetch,
+      input,
+      requiredCumulative,
+    })
+  })
+
   return MethodResponse.register(
     method,
     async ({ challenge, credential, fetch, headers, input, refetch, response, signal }) => {
-      if (!isTempoSessionChallenge(challenge)) return response
+      if (!isTip1034SessionChallenge(challenge)) return response
       if (!isEventStream(response)) {
         const credentialContext = requireSessionCredentialContext(
           Credential.deserialize(credential).payload,
@@ -142,23 +231,16 @@ export function session(parameters: session.Parameters = {}) {
           method.createCredential({ challenge, context }),
         fetch,
         getChannel: () => channel ?? null,
-        managementInput,
-        async topUpIfNeeded({ channelId, deposit, requiredCumulative }) {
-          if (requiredCumulative <= deposit || !channel) return
-          const additionalDeposit = requiredCumulative - deposit
-          await postTopUp({
-            additionalDeposit,
+        async topUpIfNeeded({ deposit, requiredCumulative }) {
+          if (!channel) return
+          await topUpChannelIfNeeded({
             challenge,
             channel,
-            channelId,
-            createSessionCredential: (challenge, context) =>
-              method.createCredential({ challenge, context }),
+            deposit: channel.deposit > deposit ? channel.deposit : deposit,
             fetch,
             input,
+            requiredCumulative,
           })
-          channel.deposit += additionalDeposit
-          await store.set(channel)
-          sink.notifyUpdate(channel)
         },
       } satisfies SsePaymentDriver
 
@@ -179,6 +261,8 @@ export declare namespace session {
 
   type Parameters = Account.getResolver.Parameters &
     Client.getResolver.Parameters & {
+      /** 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). */
@@ -187,6 +271,11 @@ export declare namespace session {
       escrow?: Address | undefined
       /** Maximum channel deposit in human-readable units. Caps server-suggested opens and automatic top-ups. */
       maxDeposit?: string | undefined
+      /**
+       * Preferred automatic top-up size in human-readable units. When omitted,
+       * a bounded server `suggestedDeposit` is preferred, then the exact shortfall.
+       */
+      topUpAmount?: string | undefined
       /** Called whenever channel state changes. */
       onChannelUpdate?: ((entry: ChannelEntry) => void) | undefined
       /** Selects the account that signs this session credential after the challenge is known. */

package/src/tempo/session/client/SessionManager.test.ts

@@ -609,6 +609,54 @@ describe('Session', () => {
       expect(s.channelId).not.toBe(storedChannelId)
     })
 
+    test('keeps a persisted channel after its committed top-up when the paid retry fails', async () => {
+      const seeded = channelEntry({ cumulativeAmount: 10_000_000n, deposit: 10_000_000n })
+      const { store, delete: remove, map } = makeChannelStore([seeded])
+      const postedPayloads: SessionCredentialPayload[] = []
+      let probes = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (!payload) {
+          probes++
+          if (probes > 1) throw new Error('unexpected fresh-channel retry')
+          return Promise.resolve(make402Response())
+        }
+
+        postedPayloads.push(payload)
+        if (payload.action === 'topUp') return Promise.resolve(new Response(null, { status: 204 }))
+        if (payload.action === 'voucher')
+          return Promise.resolve(new Response('upstream failed', { status: 500 }))
+        throw new Error(`unexpected ${payload.action} credential`)
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '20',
+        channelStore: store,
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(500)
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['topUp', 'voucher'])
+      expect(remove).not.toHaveBeenCalled()
+      expect(map.get(entryKey(seeded))).toMatchObject({
+        channelId: storedChannelId,
+        cumulativeAmount: 10_000_000n,
+        deposit: 11_000_000n,
+      })
+      expect(s.channelId).toBe(storedChannelId)
+      expect(s.state).toMatchObject({
+        status: 'active',
+        channelId: storedChannelId,
+        deposit: '11000000',
+      })
+    })
+
     test('rolls back an optimistic open when a replacement challenge does not reference it', async () => {
       const { store, delete: remove } = makeChannelStore()
       const postedPayloads: SessionCredentialPayload[] = []
@@ -753,10 +801,11 @@ describe('Session', () => {
       await restarted.fetch('https://api.example.com/data')
 
       // The first request carries no hint header; after the 402 the restarted
-      // manager resumes the persisted channel from the entry index with a
-      // voucher rather than opening a new one.
+      // manager tops up and resumes the full persisted channel rather than
+      // opening a new one.
       expect(new Headers(resumeFetch.mock.calls[0]?.[1]?.headers).get('Payment-Session')).toBeNull()
-      expect(posted[0]).toMatchObject({ action: 'voucher', channelId })
+      expect(posted.map((payload) => payload.action)).toEqual(['topUp', 'voucher'])
+      expect(posted[1]).toMatchObject({ channelId })
     })
 
     test('persists opened channels and deletes closed channels when supported', async () => {
@@ -987,6 +1036,7 @@ describe('Session', () => {
         client,
         fetch: mockFetch as typeof globalThis.fetch,
         maxDeposit: '10',
+        topUpAmount: '5',
       })
 
       await s.fetch('https://api.example.com/data')
@@ -994,10 +1044,13 @@ describe('Session', () => {
 
       expect(response.status).toBe(200)
       expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'topUp', 'voucher'])
+      const topUp = postedPayloads[1]
+      if (topUp?.action !== 'topUp') throw new Error('expected top-up payload')
+      expect(topUp.additionalDeposit).toBe('5000000')
       expect(s.state).toMatchObject({
         status: 'active',
         acceptedCumulative: '2000000',
-        deposit: '2000000',
+        deposit: '6000000',
         spent: '2000000',
         units: 2,
       })
@@ -1398,6 +1451,51 @@ describe('Session', () => {
     })
   })
 
+  describe('.ws()', () => {
+    test('tops up a full persisted channel before constructing the socket', async () => {
+      const events: string[] = []
+      const { map, set, store } = makeChannelStore([
+        channelEntry({ cumulativeAmount: 1_000_000n, deposit: 1_000_000n }),
+      ])
+      set.mockImplementation((entry) => {
+        map.set(entryKey(entry), entry)
+        events.push(`set:${entry.deposit}:${entry.cumulativeAmount}`)
+      })
+      const fetch = vi.fn(async (_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) {
+          events.push('probe')
+          return make402Response(makeChallenge({ suggestedDeposit: '1000000' }))
+        }
+        const payload = Credential.deserialize<SessionCredentialPayload>(authorization).payload
+        if (payload.action !== 'topUp') throw new Error(`unexpected ${payload.action} fetch`)
+        events.push('topUp')
+        return new Response(null, { status: 204 })
+      })
+      function WebSocket() {
+        events.push('socket')
+        throw new Error('stop after preparation')
+      }
+      const s = sessionManager({
+        account,
+        client,
+        fetch: fetch as typeof globalThis.fetch,
+        maxDeposit: '3',
+        channelStore: store,
+        webSocket: WebSocket as never,
+      })
+
+      await expect(s.ws('wss://api.example.com/socket')).rejects.toThrow('stop after preparation')
+      expect(events).toEqual([
+        'probe',
+        'topUp',
+        'set:2000000:1000000',
+        'set:2000000:2000000',
+        'socket',
+      ])
+    })
+  })
+
   describe('.close()', () => {
     test('is no-op when not opened', async () => {
       const mockFetch = vi.fn()

package/src/tempo/session/client/SessionManager.ts

@@ -4,6 +4,7 @@ import { tempo as tempo_chain } from 'viem/chains'
 
 import * as Challenge from '../../../Challenge.js'
 import * as Fetch from '../../../client/internal/Fetch.js'
+import * as MethodChallenge from '../../../client/internal/MethodChallenge.js'
 import * as MethodResponse from '../../../client/internal/MethodResponse.js'
 import * as Constants from '../../../Constants.js'
 import * as Account from '../../../viem/Account.js'
@@ -16,7 +17,7 @@ import { hydrateSessionSnapshot, type SessionContext } from '../client/Credentia
 import { session as sessionPlugin } from '../client/Session.js'
 import * as Channel from '../precompile/Channel.js'
 import { deserializeSessionReceipt } from '../precompile/Protocol.js'
-import { readSessionChallengeAmount, type SessionReceipt } from '../precompile/Protocol.js'
+import type { SessionReceipt } from '../precompile/Protocol.js'
 import {
   deserializeSnapshot as deserializeSessionSnapshot,
   serializeSnapshot as serializeSessionSnapshot,
@@ -34,6 +35,7 @@ import {
   dispatchSessionEvent,
   restoreCumulativeAuthorization,
   restoreRuntimeSnapshot as restoreRuntimeStateSnapshot,
+  resolveAutomaticTopUp,
   type RuntimeSnapshot,
 } from './Runtime.js'
 import { closeSocketSession } from './Runtime.js'
@@ -41,7 +43,6 @@ import {
   closeHttpSession,
   getSessionSnapshot,
   isTempoSessionChallenge,
-  managementInput,
   postTopUp,
   retryHttpPaymentRequired,
   type TempoSessionChallenge,
@@ -111,6 +112,8 @@ type SessionManagerConfig = {
   fetch: typeof globalThis.fetch
   /** Local maximum cumulative voucher authorization, or null when uncapped. */
   maxVoucherCumulative: bigint | null
+  /** Preferred top-up, or null to use a bounded server suggestion and then the exact shortfall. */
+  topUpAmount: bigint | null
   /** WebSocket constructor available in the current runtime, when configured. */
   WebSocket: WebSocketConstructor | undefined
 }
@@ -168,6 +171,8 @@ function resolveSessionManagerConfig(parameters: sessionManager.Parameters): Ses
     fetch: parameters.fetch ?? globalThis.fetch.bind(globalThis),
     maxVoucherCumulative:
       parameters.maxDeposit !== undefined ? parseUnits(parameters.maxDeposit, decimals) : null,
+    topUpAmount:
+      parameters.topUpAmount !== undefined ? parseUnits(parameters.topUpAmount, decimals) : null,
     WebSocket,
   }
 }
@@ -201,6 +206,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
   // Tracks one fetch's channel reuse so stale stored entries can be evicted once.
   type ChannelUse = {
     challengesReceived: number
+    committed: RuntimeSnapshot | undefined
     created: Map<string, ChannelEntry>
     seenExisting: Set<string>
     previous: RuntimeSnapshot
@@ -221,7 +227,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       const entry = await getReusable(key)
       if (entry && channelUse) {
         channelUse.seenExisting.add(key)
-        if (!channelUse.created.has(key)) channelUse.resumed ??= entry
+        if (!channelUse.committed && !channelUse.created.has(key)) channelUse.resumed ??= entry
       }
       return entry
     },
@@ -270,13 +276,32 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     return dispatchSessionEvent(runtime, event)
   }
 
+  function commitDurableTopUp(entry: ChannelEntry) {
+    const use = channelUse
+    const baseline = use?.committed?.channel?.entry ?? use?.resumed
+    if (
+      !use ||
+      baseline?.channelId.toLowerCase() !== entry.channelId.toLowerCase() ||
+      entry.deposit <= baseline.deposit
+    )
+      return
+    use.resumed = undefined
+    use.committed = captureRuntimeStateSnapshot({
+      channel: runtime.channel,
+      spent: runtime.spent,
+      state: runtime.state,
+    })
+  }
+
   const method = sessionPlugin({
     account: parameters.account,
+    autoSwap: parameters.autoSwap,
     getClient: parameters.client ? () => parameters.client! : parameters.getClient,
     resolveAccount: parameters.resolveAccount,
     escrow: parameters.escrow,
     decimals: config.decimals,
     maxDeposit: parameters.maxDeposit,
+    topUpAmount: parameters.topUpAmount,
     channelStore: store,
     onChannelUpdate(entry) {
       if (entry.channelId !== runtime.channel?.channelId) runtime.spent = 0n
@@ -290,6 +315,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           units: 0,
         })
       }
+      commitDurableTopUp(entry)
     },
   })
   MethodResponse.unregister(method)
@@ -313,17 +339,6 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       if (use) use.challengesReceived++
       runtime.lastChallenge = challenge
       dispatch({ type: 'challengeReceived', challengeId: challenge.id })
-      if (runtime.channel?.opened && runtime.lastUrl) {
-        const requiredCumulative =
-          runtime.channel.cumulativeAmount + readSessionChallengeAmount(challenge)
-        await topUpIfNeeded({
-          challenge,
-          input: runtime.lastUrl,
-          channelId: runtime.channel.channelId,
-          deposit: runtime.channel.deposit,
-          requiredCumulative,
-        })
-      }
       return undefined
     },
   })
@@ -366,16 +381,12 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     const snapshot = deserializeSessionSnapshot(header)
     const client = await getClient({ chainId: snapshot.chainId })
     const defaultAccount = getAccount(client)
-    const authority =
-      BigInt(snapshot.descriptor.authorizedSigner) === 0n
-        ? snapshot.descriptor.payer
-        : snapshot.descriptor.authorizedSigner
     const account =
       (await parameters.resolveAccount?.({
         account: defaultAccount,
         chainId: snapshot.chainId,
         operation: {
-          authority,
+          authority: Channel.resolveAuthorizedSigner(snapshot.descriptor),
           kind: 'authorizePaymentChannel',
         },
       })) ?? defaultAccount
@@ -520,9 +531,11 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     challenge: TempoSessionChallenge
     channelId: Hex.Hex
     input: RequestInfo | URL
+    knownDeposit?: bigint | undefined
   }) {
+    const { knownDeposit, ...topUp } = parameters
     const receipt = await postTopUp({
-      ...parameters,
+      ...topUp,
       channel: runtime.channel,
       createSessionCredential,
       fetch: config.fetch,
@@ -534,6 +547,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       channelId: parameters.channelId,
       challengeId: runtime.lastChallenge?.id,
       currentState: runtime.state,
+      knownDeposit,
       receipt,
       spent: runtime.spent,
     })
@@ -546,18 +560,32 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         spent: runtime.spent.toString(),
         units: runtime.state.status === 'active' ? runtime.state.units : 0,
       })
+      commitDurableTopUp(applied.channel)
     }
     return receipt
   }
 
   async function topUpIfNeeded(parameters: TopUpRequirement) {
-    if (parameters.requiredCumulative <= parameters.deposit) return
-    assertVoucherWithinLocalLimit(parameters.requiredCumulative)
+    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: parameters.requiredCumulative - parameters.deposit,
+      additionalDeposit,
+      knownDeposit: deposit,
     })
   }
 
@@ -617,6 +645,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
     const use: ChannelUse = {
       challengesReceived: 0,
+      committed: undefined,
       created: new Map(),
       previous,
       seenExisting: new Set(),
@@ -650,7 +679,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         try {
           response = await wrappedFetch(input, effectiveInit)
         } catch (error) {
-          restoreRuntime(previous)
+          restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           throw error
         }
@@ -677,7 +706,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           }
         }
         if (!attemptedHttpManagement && !paymentResponse.ok && !paymentResponse.receipt) {
-          restoreRuntime(previous)
+          restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           return paymentResponse
         }
@@ -719,7 +748,6 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     getChannel: () => runtime.channel,
     getChallenge: () => runtime.lastChallenge,
     assertVoucherWithinLocalLimit,
-    managementInput,
     acceptReceipt(receipt: SessionReceipt) {
       updateSpentFromReceipt(receipt)
     },
@@ -777,7 +805,16 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       const liveHint = runtime.channel?.opened ? runtime.channel.channelId : undefined
 
       const prepared = await prepareWebSocketSession({
-        createSessionCredential,
+        async createSessionCredential(challenge, context) {
+          runtime.lastChallenge = challenge
+          await MethodChallenge.handle(method, {
+            challenge,
+            context,
+            fetch: config.fetch,
+            input: probeUrl,
+          })
+          return createSessionCredential(challenge, context)
+        },
         fetch: config.fetch,
         input,
         onProbeUrl(httpUrl) {
@@ -884,6 +921,8 @@ export namespace sessionManager {
 
   export type Parameters = Account.getResolver.Parameters &
     Client.getResolver.Parameters & {
+      /** 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. */
       bootstrap?: boolean | undefined
       /** Viem client instance. Shorthand for `getClient: () => client`. */
@@ -896,6 +935,11 @@ export namespace sessionManager {
       fetch?: typeof globalThis.fetch | undefined
       /** Maximum deposit in human-readable units (e.g. `'10'` for 10 tokens). Converted to raw units via `decimals`. */
       maxDeposit?: string | undefined
+      /**
+       * Preferred automatic top-up size in human-readable units. When omitted,
+       * a bounded server `suggestedDeposit` is preferred, then the exact shortfall.
+       */
+      topUpAmount?: string | undefined
       /** Selects the account that signs session credentials. */
       resolveAccount?: sessionPlugin.ResolveAccount | undefined
       /** Store for reusable session channels. Defaults to in-memory. */