mppx 0.8.12 → 0.8.14

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

@@ -1,23 +1,28 @@
 import type { Hex } from 'ox'
 import { parseUnits, type Address } from 'viem'
+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 type * as Account from '../../../viem/Account.js'
-import type * as Client from '../../../viem/Client.js'
+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 type { ChannelEntry } from '../client/ChannelOps.js'
 import { createChannelStore, entryKey, type ChannelStore } from '../client/ChannelStore.js'
-import type { SessionContext } from '../client/CredentialState.js'
+import { hydrateSessionSnapshot, type SessionContext } from '../client/CredentialState.js'
 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,
 } from '../Snapshot.js'
+import { registerSessionManagerInternals } from './internal/SessionManager.js'
 import { createSessionReceiptCoordinator } from './ReceiptCoordinator.js'
 import { resolveCloseTarget, type CloseTarget } from './Runtime.js'
 import { assertVoucherWithinLocalLimit as assertVoucherWithinLocalAuthorization } from './Runtime.js'
@@ -30,13 +35,14 @@ import {
   dispatchSessionEvent,
   restoreCumulativeAuthorization,
   restoreRuntimeSnapshot as restoreRuntimeStateSnapshot,
+  resolveAutomaticTopUp,
   type RuntimeSnapshot,
 } from './Runtime.js'
 import { closeSocketSession } from './Runtime.js'
 import {
   closeHttpSession,
+  getSessionSnapshot,
   isTempoSessionChallenge,
-  managementInput,
   postTopUp,
   retryHttpPaymentRequired,
   type TempoSessionChallenge,
@@ -47,7 +53,7 @@ import {
   type WebSocketConstructor,
   WebSocketReadyState,
 } from './Transports.js'
-import { openSseSession, type SseDriverOptions } from './Transports.js'
+import { consumeSseSessionResponse, openSseSession, type SseDriverOptions } from './Transports.js'
 import { applyTopUpResult, resolveManualTopUp, type TopUpRequirement } from './Transports.js'
 import {
   openWebSocketSession,
@@ -106,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
 }
@@ -126,19 +134,6 @@ function isZeroAmountChargeChallenge(challenge: Challenge.Challenge) {
   }
 }
 
-/** Builds a reusable channel entry from a server session snapshot header. */
-function entryFromSnapshot(snapshot: ReturnType<typeof deserializeSessionSnapshot>): ChannelEntry {
-  return {
-    channelId: snapshot.channelId,
-    cumulativeAmount: BigInt(snapshot.acceptedCumulative),
-    deposit: BigInt(snapshot.deposit),
-    descriptor: snapshot.descriptor,
-    escrow: snapshot.escrow,
-    chainId: snapshot.chainId,
-    opened: true,
-  }
-}
-
 function requestInitWithSessionHint(
   input: RequestInfo | URL,
   init: RequestInit | undefined,
@@ -176,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,
   }
 }
@@ -192,6 +189,12 @@ function resolveSessionManagerConfig(parameters: sessionManager.Parameters): Ses
  */
 export function sessionManager(parameters: sessionManager.Parameters): SessionManager {
   const config = resolveSessionManagerConfig(parameters)
+  const getClient = Client.getResolver({
+    chain: tempo_chain,
+    getClient: parameters.client ? () => parameters.client! : parameters.getClient,
+    rpcUrl: defaults.rpcUrl,
+  })
+  const getAccount = Account.getResolver({ account: parameters.account })
   const runtime = createSessionManagerRuntime()
   const receipts = createSessionReceiptCoordinator({
     getSocketSession: () => runtime.socketSession,
@@ -203,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
@@ -223,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
     },
@@ -272,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
@@ -292,6 +315,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           units: 0,
         })
       }
+      commitDurableTopUp(entry)
     },
   })
   MethodResponse.unregister(method)
@@ -315,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
     },
   })
@@ -365,8 +378,23 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
   async function storeSnapshotHeader(response: Response): Promise<ChannelEntry | undefined> {
     const header = response.headers.get(Constants.Headers.paymentSessionSnapshot)
     if (!header) return undefined
-    const entry = entryFromSnapshot(deserializeSessionSnapshot(header))
+    const snapshot = deserializeSessionSnapshot(header)
+    const client = await getClient({ chainId: snapshot.chainId })
+    const defaultAccount = getAccount(client)
+    const account =
+      (await parameters.resolveAccount?.({
+        account: defaultAccount,
+        chainId: snapshot.chainId,
+        operation: {
+          authority: Channel.resolveAuthorizedSigner(snapshot.descriptor),
+          kind: 'authorizePaymentChannel',
+        },
+      })) ?? defaultAccount
+    const { entry, spent } = await hydrateSessionSnapshot({ account, client, snapshot })
+    assertVoucherWithinLocalLimit(entry.cumulativeAmount)
     await Promise.resolve(store.set(entry)).catch(() => undefined)
+    runtime.channel = entry
+    runtime.spent = spent
     return entry
   }
 
@@ -430,8 +458,60 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
   }
 
-  function getValidatedFallbackCloseAmount(target: CloseTarget) {
-    const closeAmount = getFallbackCloseAmount(target.challenge, target.channelId)
+  function validateCloseSnapshot(channel: ChannelEntry, challenge: TempoSessionChallenge) {
+    const snapshot = getSessionSnapshot(challenge)
+    if (!snapshot) return undefined
+
+    const computedSnapshotId = Channel.computeId({
+      ...snapshot.descriptor,
+      chainId: snapshot.chainId,
+      escrow: snapshot.escrow,
+    })
+    if (computedSnapshotId.toLowerCase() !== snapshot.channelId.toLowerCase()) {
+      throw new Error('close snapshot descriptor does not match its channel ID')
+    }
+    if (snapshot.channelId.toLowerCase() !== channel.channelId.toLowerCase()) {
+      throw new Error('close snapshot channel ID does not match local session')
+    }
+    if (
+      snapshot.chainId !== channel.chainId ||
+      snapshot.escrow.toLowerCase() !== channel.escrow.toLowerCase()
+    ) {
+      throw new Error('close snapshot payment scope does not match local session')
+    }
+
+    const acceptedCumulative = BigInt(snapshot.acceptedCumulative)
+    const snapshotSpent = BigInt(snapshot.spent)
+    if (acceptedCumulative < 0n || snapshotSpent < 0n) {
+      throw new Error('close snapshot amounts must not be negative')
+    }
+    if (snapshotSpent > acceptedCumulative) {
+      throw new Error('close snapshot spent exceeds accepted cumulative amount')
+    }
+    if (acceptedCumulative > channel.cumulativeAmount) {
+      throw new Error('close snapshot accepted cumulative exceeds local voucher state')
+    }
+    return { acceptedCumulative, spent: snapshotSpent }
+  }
+
+  function applyCloseSnapshot(target: CloseTarget, challenge: TempoSessionChallenge) {
+    const snapshot = validateCloseSnapshot(target.channel, challenge)
+    if (!snapshot) return
+
+    const { acceptedCumulative, spent } = snapshot
+    if (runtime.spent > acceptedCumulative) {
+      throw new Error('close snapshot accepted cumulative is below locally confirmed spend')
+    }
+    if (spent > runtime.spent) runtime.spent = spent
+  }
+
+  function getValidatedFallbackCloseAmount(
+    target: CloseTarget,
+    challenge: TempoSessionChallenge = target.challenge,
+    applySnapshot = false,
+  ) {
+    if (applySnapshot) applyCloseSnapshot(target, challenge)
+    const closeAmount = getFallbackCloseAmount(challenge, target.channelId)
     if (closeAmount > target.channel.cumulativeAmount) {
       throw new Error('fallback close amount exceeds local voucher state')
     }
@@ -451,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,
@@ -465,10 +547,12 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       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,
@@ -476,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,
     })
   }
 
@@ -547,6 +645,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
     const use: ChannelUse = {
       challengesReceived: 0,
+      committed: undefined,
       created: new Map(),
       previous,
       seenExisting: new Set(),
@@ -580,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
         }
@@ -607,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
         }
@@ -625,6 +724,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       createSessionCredential,
       fetch: config.fetch,
       lastUrl: runtime.lastUrl,
+      resolveSignedCloseAmount: (challenge) =>
+        getValidatedFallbackCloseAmount(target, challenge, true),
       signedCloseAmount: getValidatedFallbackCloseAmount(target),
       setChallenge(challenge) {
         runtime.lastChallenge = challenge
@@ -640,6 +741,19 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     return receipt
   }
 
+  const sseDriver = {
+    createSessionCredential,
+    doFetch,
+    fetch: config.fetch,
+    getChannel: () => runtime.channel,
+    getChallenge: () => runtime.lastChallenge,
+    assertVoucherWithinLocalLimit,
+    acceptReceipt(receipt: SessionReceipt) {
+      updateSpentFromReceipt(receipt)
+    },
+    topUpIfNeeded,
+  }
+
   const self: SessionManager = {
     get channelId() {
       return runtime.channel?.channelId
@@ -675,19 +789,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     },
 
     async sse(input, init) {
-      return openSseSession(input, init, {
-        createSessionCredential,
-        doFetch,
-        fetch: config.fetch,
-        getChannel: () => runtime.channel,
-        getChallenge: () => runtime.lastChallenge,
-        assertVoucherWithinLocalLimit,
-        managementInput,
-        acceptReceipt(receipt) {
-          updateSpentFromReceipt(receipt)
-        },
-        topUpIfNeeded,
-      })
+      return openSseSession(input, init, sseDriver)
     },
 
     async ws(input, init) {
@@ -703,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) {
@@ -768,6 +879,38 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     },
   }
 
+  registerSessionManagerInternals(self, {
+    consumeSseResponse(input, response, options) {
+      return consumeSseSessionResponse(input, response, options, sseDriver)
+    },
+    rehydrate({ channel, challenge, input, spent }) {
+      if (!channel.opened) throw new Error('Cannot restore a closed session channel.')
+      if (!isTempoSessionChallenge(challenge)) {
+        throw new Error('Cannot restore session: challenge is not tempo/session.')
+      }
+      if (spent < 0n) throw new Error('Cannot restore session: spent must not be negative.')
+      if (spent > channel.cumulativeAmount) {
+        throw new Error('Cannot restore session: spent exceeds local voucher state.')
+      }
+      assertVoucherWithinLocalLimit(channel.cumulativeAmount)
+      const snapshot = validateCloseSnapshot(channel, challenge)
+      const restoredSpent = snapshot && snapshot.spent > spent ? snapshot.spent : spent
+
+      runtime.lastUrl = input
+      runtime.lastChallenge = challenge
+      runtime.channel = channel
+      runtime.spent = restoredSpent
+      dispatch({ type: 'challengeReceived', challengeId: challenge.id })
+      dispatch({
+        type: 'activated',
+        challengeId: challenge.id,
+        entry: channel,
+        spent: restoredSpent.toString(),
+        units: 0,
+      })
+    },
+  })
+
   return self
 }
 
@@ -778,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`. */
@@ -790,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. */