mppx 0.8.13 → 0.8.15

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,
@@ -57,6 +58,7 @@ import { applyTopUpResult, resolveManualTopUp, type TopUpRequirement } from './T
 import {
   openWebSocketSession,
   prepareWebSocketSession,
+  probeWebSocketSession,
   type WebSocketDriverOptions,
 } from './Transports.js'
 
@@ -111,6 +113,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 +172,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 +207,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 +228,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
     },
@@ -237,11 +244,14 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
 
   /** Removes a failed channel from candidacy for the rest of this manager's life. */
   async function ignoreChannel(entry: ChannelEntry) {
+    const key = entryKey(entry)
     ignoredChannelIds.add(entry.channelId)
-    await Promise.resolve(backing.delete(entryKey(entry))).catch(() => undefined)
+    channelUse?.seenExisting.delete(key)
+    if (channelUse?.resumed === entry) channelUse.resumed = undefined
+    await Promise.resolve(backing.delete(key)).catch(() => undefined)
   }
 
-  async function rollbackCreatedChannelsForRetry() {
+  async function rollbackCreatedChannels() {
     const use = channelUse
     if (!use?.created.size) return
     for (const [key, entry] of use.created) {
@@ -249,19 +259,31 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       await Promise.resolve(backing.delete(key)).catch(() => undefined)
     }
     use.created.clear()
-    restoreRuntime(use.previous)
+    await restoreRuntime(use.committed ?? use.previous)
   }
 
-  function referencesCreatedChannel(challenge: Challenge.Challenge): boolean {
+  /** Commits a newly created channel once an authoritative server snapshot references it. */
+  function commitReferencedChannel(challenge: Challenge.Challenge): boolean {
     const snapshot = Constants.getMethodDetail<{ channelId?: unknown }>(
       challenge.request.methodDetails,
       Constants.MethodDetailKeys.sessionSnapshot,
     )
     if (typeof snapshot?.channelId !== 'string') return false
     const use = channelUse
-    if (!use?.created.size) return false
-    for (const entry of use.created.values()) {
-      if (entry.channelId.toLowerCase() === snapshot.channelId.toLowerCase()) return true
+    if (!use?.created.size || !runtime.channel) return false
+    for (const [key, entry] of use.created) {
+      if (
+        entry.channelId.toLowerCase() !== snapshot.channelId.toLowerCase() ||
+        runtime.channel.channelId.toLowerCase() !== snapshot.channelId.toLowerCase()
+      )
+        continue
+      use.created.delete(key)
+      use.committed = captureRuntimeStateSnapshot({
+        channel: runtime.channel,
+        spent: runtime.spent,
+        state: runtime.state,
+      })
+      return true
     }
     return false
   }
@@ -270,13 +292,40 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     return dispatchSessionEvent(runtime, event)
   }
 
+  function activeUnits() {
+    const state =
+      runtime.state.status === 'active'
+        ? runtime.state
+        : (channelUse?.committed?.state ?? channelUse?.previous.state)
+    return state?.status === 'active' ? state.units : 0
+  }
+
+  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
@@ -287,9 +336,10 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           challengeId: runtime.lastChallenge.id,
           entry,
           spent: runtime.spent.toString(),
-          units: 0,
+          units: activeUnits(),
         })
       }
+      commitDurableTopUp(entry)
     },
   })
   MethodResponse.unregister(method)
@@ -306,24 +356,17 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       const use = channelUse
       const isRepeatedRetryChallenge =
         use && use.challengesReceived > 0 && challenge.id === runtime.lastChallenge?.id
-      if (!referencesCreatedChannel(challenge)) {
-        if (use?.created.size) await rollbackCreatedChannelsForRetry()
-        else if (isRepeatedRetryChallenge) restoreRuntime(use.previous)
-      }
+      const isSameRetryChallenge =
+        isRepeatedRetryChallenge &&
+        Challenge.serialize(challenge) === Challenge.serialize(runtime.lastChallenge!)
       if (use) use.challengesReceived++
+      if (isSameRetryChallenge) return undefined
+      if (!commitReferencedChannel(challenge)) {
+        if (use?.created.size) await rollbackCreatedChannels()
+        else if (isRepeatedRetryChallenge) await restoreRuntime(use.committed ?? use.previous)
+      }
       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 +409,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 +559,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 +575,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       channelId: parameters.channelId,
       challengeId: runtime.lastChallenge?.id,
       currentState: runtime.state,
+      knownDeposit,
       receipt,
       spent: runtime.spent,
     })
@@ -544,24 +586,38 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         challengeId: runtime.lastChallenge.id,
         entry: applied.channel,
         spent: runtime.spent.toString(),
-        units: runtime.state.status === 'active' ? runtime.state.units : 0,
+        units: activeUnits(),
       })
+      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,
     })
   }
 
-  function restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint) {
+  async function restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint) {
     const restored = restoreCumulativeAuthorization({
       channel: runtime.channel,
       channelId,
@@ -578,14 +634,16 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         spent: restored.spent,
         units: restored.units,
       })
+      await backing.set(runtime.channel)
     }
   }
 
-  function restoreRuntime(snapshot: RuntimeSnapshot) {
+  async function restoreRuntime(snapshot: RuntimeSnapshot) {
     const restored = restoreRuntimeStateSnapshot(snapshot, runtime.channel)
     runtime.channel = restored.channel
     runtime.spent = restored.spent
     runtime.state = restored.state
+    if (runtime.channel?.opened) await backing.set(runtime.channel)
   }
 
   function toPaymentResponse(response: Response): PaymentResponse {
@@ -617,6 +675,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
     const use: ChannelUse = {
       challengesReceived: 0,
+      committed: undefined,
       created: new Map(),
       previous,
       seenExisting: new Set(),
@@ -650,7 +709,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         try {
           response = await wrappedFetch(input, effectiveInit)
         } catch (error) {
-          restoreRuntime(previous)
+          if (use.created.size) await rollbackCreatedChannels()
+          else await restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           throw error
         }
@@ -677,7 +737,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           }
         }
         if (!attemptedHttpManagement && !paymentResponse.ok && !paymentResponse.receipt) {
-          restoreRuntime(previous)
+          if (use.created.size) await rollbackCreatedChannels()
+          else await restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           return paymentResponse
         }
@@ -719,7 +780,6 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     getChannel: () => runtime.channel,
     getChallenge: () => runtime.lastChallenge,
     assertVoucherWithinLocalLimit,
-    managementInput,
     acceptReceipt(receipt: SessionReceipt) {
       updateSpentFromReceipt(receipt)
     },
@@ -777,7 +837,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) {
@@ -801,6 +870,20 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         setSocketSession(session) {
           runtime.socketSession = session
         },
+        async refreshChallenge() {
+          const refreshed = await probeWebSocketSession({
+            fetch: config.fetch,
+            input: httpUrl,
+            probeInit: requestInitWithSessionHint(
+              httpUrl,
+              signalInit,
+              runtime.channel?.opened ? runtime.channel.channelId : undefined,
+            ),
+            signal: init?.signal,
+          })
+          runtime.lastChallenge = refreshed.challenge
+          return refreshed.challenge
+        },
         assertVoucherWithinLocalLimit,
         acceptReceipt: updateSpentFromReceipt,
         rejectCloseReady: receipts.rejectCloseReady,
@@ -884,6 +967,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 +981,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. */

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

@@ -85,6 +85,7 @@ describe('HttpManagement', () => {
         methodDetails: {
           chainId: 4217,
           escrowContract: undefined,
+          sessionProtocol: Constants.SessionProtocols.v2,
           ...(snapshot && { [Constants.MethodDetailKeys.sessionSnapshot]: snapshot }),
         },
       },
@@ -220,6 +221,36 @@ describe('HttpManagement', () => {
       expect(fetch).toHaveBeenCalledOnce()
     })
 
+    test('postTopUp retries once with the management route challenge', async () => {
+      const routeChallenge = { ...challenge(), id: 'management-challenge' } as TempoSessionChallenge
+      const createSessionCredential = vi.fn(async (challenge_) => `top-up-${challenge_.id}`)
+      const fetch = vi
+        .fn()
+        .mockResolvedValueOnce(response402(routeChallenge))
+        .mockResolvedValueOnce(
+          new Response(null, {
+            status: 204,
+            headers: {
+              [Constants.Headers.paymentReceipt]: receiptHeader(8n, 5n, routeChallenge.id),
+            },
+          }),
+        )
+
+      const receipt = await postTopUp({
+        additionalDeposit: 3n,
+        challenge: challenge(),
+        channel: channel(),
+        channelId,
+        createSessionCredential,
+        fetch,
+        input: 'https://example.test/resource',
+      })
+
+      expect(receipt?.challengeId).toBe(routeChallenge.id)
+      expect(createSessionCredential).toHaveBeenCalledTimes(2)
+      expect(authorizationHeader(fetch.mock.calls[1]?.[1])).toBe(`top-up-${routeChallenge.id}`)
+    })
+
     test('retryHttpPaymentRequired signs the server-required cumulative voucher', async () => {
       let entry = channel({ cumulativeAmount: 5n, deposit: 6n })
       const topUpIfNeeded = vi.fn(async () => {
@@ -279,6 +310,28 @@ describe('HttpManagement', () => {
       expect(restoreCumulative).toHaveBeenCalledWith(channelId, 5n)
     })
 
+    test('retryHttpPaymentRequired restores cumulative authorization when retry throws', async () => {
+      const entry = channel({ cumulativeAmount: 5n })
+      const restoreCumulative = vi.fn()
+
+      await expect(
+        retryHttpPaymentRequired({
+          createSessionCredential: async () => 'voucher-credential',
+          fetch: async () => {
+            throw new Error('network failed')
+          },
+          getChannel: () => entry,
+          input: 'https://example.test/resource',
+          response: response402(challenge(snapshot())),
+          restoreCumulative,
+          setChallenge() {},
+          topUpIfNeeded: async () => {},
+        }),
+      ).rejects.toThrow('network failed')
+
+      expect(restoreCumulative).toHaveBeenCalledWith(channelId, 5n)
+    })
+
     test('closeHttpSession posts a close credential and parses the receipt', async () => {
       const entry = channel()
       const createSessionCredential = vi.fn(async (_challenge, context: SessionContext) => {
@@ -874,7 +927,6 @@ describe('SseDriver', () => {
       fetch: vi.fn(async () => new Response(null, { status: 204 })),
       getChallenge: () => currentChallenge,
       getChannel: () => channel,
-      managementInput: (input) => input,
       async topUpIfNeeded() {},
     })
 
@@ -1011,6 +1063,7 @@ describe('WsDriver', () => {
         methodDetails: {
           chainId: 4217,
           escrowContract: tip20ChannelEscrow,
+          sessionProtocol: Constants.SessionProtocols.v2,
         },
         recipient: '0x742d35cc6634c0532925a3b844bc9e7595f8fe00',
       },