mppx 0.7.0 → 0.8.1

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

@@ -25,6 +25,7 @@ import {
   resolveEscrow,
   type ChannelEntry,
 } from './ChannelOps.js'
+import { channelKey, entryKey, type ChannelSink } from './ChannelStore.js'
 import { assertWithinMaxDeposit, resolveOpeningDeposit } from './Runtime.js'
 
 /** Credential payload variants that carry cumulative voucher authorization. */
@@ -33,39 +34,6 @@ export type CumulativeCredentialPayload = Extract<
   { cumulativeAmount: string }
 >
 
-/** In-memory client channel cache used by automatic precompile session credential planning. */
-export type ChannelCache = {
-  /** Maps reusable channel keys to cached channel metadata. */
-  channels: Map<string, ChannelEntry>
-  /** Maps channel IDs back to reusable channel keys for manual credential cache updates. */
-  channelIdToKey: Map<string, string>
-  /** Emits cache updates to the public `onChannelUpdate` callback. */
-  notifyUpdate(entry: ChannelEntry): void
-}
-
-/** Creates an empty client channel cache with an optional update callback. */
-export function createChannelCache(
-  onUpdate?: ((entry: ChannelEntry) => void) | undefined,
-): ChannelCache {
-  return {
-    channels: new Map(),
-    channelIdToKey: new Map(),
-    notifyUpdate: (entry) => onUpdate?.(entry),
-  } satisfies ChannelCache
-}
-
-/** Returns the cache key for a reusable payer session channel. */
-export function channelKey(payee: Address, token: Address, escrow: Address): string {
-  return `${payee.toLowerCase()}:${token.toLowerCase()}:${escrow.toLowerCase()}`
-}
-
-/** Stores a channel entry and notifies observers. */
-export function storeChannelEntry(cache: ChannelCache, key: string, entry: ChannelEntry): void {
-  cache.channels.set(key, entry)
-  cache.channelIdToKey.set(entry.channelId, key)
-  cache.notifyUpdate(entry)
-}
-
 /** Returns whether a credential payload carries cumulative voucher authorization. */
 export function hasCredentialCumulativeAmount(
   payload: SessionCredentialPayload,
@@ -81,21 +49,32 @@ export function readCredentialCumulativeAmount(
   return BigInt(payload.cumulativeAmount)
 }
 
-/** Applies a credential payload's cumulative amount to an existing cached channel. */
-export function updateCachedCumulative(
-  cache: ChannelCache,
-  channelId: Hex,
+/**
+ * Persists a channel entry through the sink and notifies observers. Closed
+ * channels are removed from the store but still reported to observers so callers
+ * can react to the close.
+ */
+async function storeChannelEntry(sink: ChannelSink, entry: ChannelEntry): Promise<void> {
+  if (entry.opened) await sink.store.set(entry)
+  else await sink.store.delete(entryKey(entry))
+  sink.notifyUpdate(entry)
+}
+
+/** Applies a credential payload's cumulative amount to the stored channel at `key`. */
+async function applyCumulative(
+  sink: ChannelSink,
+  key: string,
   payload: SessionCredentialPayload,
-): void {
-  const key = cache.channelIdToKey.get(channelId)
+): Promise<void> {
   const cumulativeAmount = readCredentialCumulativeAmount(payload)
-  if (!key || cumulativeAmount === undefined) return
-  const entry = cache.channels.get(key)
+  if (cumulativeAmount === undefined) return
+  const entry = await sink.store.get(key)
   if (!entry) return
+  if (entry.channelId.toLowerCase() !== payload.channelId.toLowerCase()) return
   entry.cumulativeAmount =
     entry.cumulativeAmount > cumulativeAmount ? entry.cumulativeAmount : cumulativeAmount
   if (payload.action === 'close') entry.opened = false
-  cache.notifyUpdate(entry)
+  await storeChannelEntry(sink, entry)
 }
 
 const hexSchema = z.custom<Hex>(
@@ -252,7 +231,7 @@ export type ReusableChannelExpectation = {
   payee: Address
   /** Payer address controlled by the local account. */
   payer: Address
-  /** Voucher signer resolved from local account configuration. */
+  /** Voucher authority resolved from the local account. */
   authorizedSigner: Address
   /** Token expected by the current challenge. */
   token: Address
@@ -300,8 +279,8 @@ export type ChallengeContext = {
 /** Inputs used to choose the next client-side session credential operation. */
 export type PlanCredentialParameters = {
   account: ViemAccount
-  authorizedSigner?: Address | undefined
-  cache: ChannelCache
+  /** Channel previously stored for this challenge scope, fetched by the caller. */
+  entry: ChannelEntry | undefined
   context?: SessionContext | undefined
   decimals: number
   maxDeposit?: bigint | undefined
@@ -336,7 +315,6 @@ export type CredentialPlan =
   | {
       type: 'open'
       account: ViemAccount
-      authorizedSigner?: Address | undefined
       context?: SessionContext | undefined
       maxDeposit?: bigint | undefined
       resolved: ChallengeContext
@@ -345,7 +323,6 @@ export type CredentialPlan =
   | {
       type: 'recover'
       account: ViemAccount
-      authorizedSigner?: Address | undefined
       context: DescriptorSessionContext
       decimals: number
       maxDeposit?: bigint | undefined
@@ -363,7 +340,6 @@ export type CredentialPlan =
   | {
       type: 'manual'
       account: ViemAccount
-      authorizedSigner?: Address | undefined
       context: ManualSessionDescriptorContext
       decimals: number
       resolved: ChallengeContext
@@ -436,7 +412,7 @@ export async function resolveChallengeContext(
     client,
     escrow,
     feePayer: methodDetails.feePayer,
-    key: channelKey(payee, token, escrow),
+    key: channelKey({ payee, token, escrow, chainId }),
     operator: methodDetails.operator,
     payee,
     snapshot: methodDetails.sessionSnapshot,
@@ -533,9 +509,21 @@ export function resolveRecoveredCumulative(
   return settled + requestAmount
 }
 
+/** Returns whether `account` can satisfy the descriptor's voucher authority. */
+export function canSignDescriptor(
+  account: ViemAccount,
+  descriptor: Channel.ChannelDescriptor,
+): boolean {
+  // Only the payer can deposit into and voucher against its own channel.
+  if (!isSameAddress(account.address, descriptor.payer)) return false
+  const authority = descriptor.authorizedSigner
+  if (BigInt(authority) === 0n || isSameAddress(authority, descriptor.payer)) return true
+  return isSameAddress(resolveAuthorizedSigner(account), authority)
+}
+
 /** Chooses the next credential plan from local channel cache and optional caller context. */
 export function planCredential(parameters: PlanCredentialParameters): CredentialPlan {
-  const { account, authorizedSigner, cache, context, decimals, maxDeposit, resolved } = parameters
+  const { account, entry, context, decimals, maxDeposit, resolved } = parameters
 
   if (hasSessionAction(context)) {
     if (!hasManualSessionDescriptor(context))
@@ -543,54 +531,52 @@ export function planCredential(parameters: PlanCredentialParameters): Credential
     return {
       type: 'manual',
       account,
-      authorizedSigner,
       context,
       decimals,
       resolved,
     }
   }
 
-  const entry = cache.channels.get(resolved.key)
   if (!entry && context?.channelId && !context.descriptor)
     throw new Error('descriptor required to reuse TIP-1034 channel')
   const recoverContext = resolveRecoverContext({ context, snapshot: resolved.snapshot })
-  if (!entry && recoverContext) {
+  if (!entry && recoverContext && canSignDescriptor(account, recoverContext.descriptor)) {
     return {
       type: 'recover',
       account,
-      authorizedSigner,
       context: recoverContext,
       decimals,
       maxDeposit,
       resolved,
     }
   }
-  if (entry?.opened) return { type: 'voucher', account, entry, maxDeposit, resolved }
-  return { type: 'open', account, authorizedSigner, context, maxDeposit, resolved }
+  if (entry?.opened && canSignDescriptor(account, entry.descriptor))
+    return { type: 'voucher', account, entry, maxDeposit, resolved }
+  return { type: 'open', account, context, maxDeposit, resolved }
 }
 
 /** Executes a credential plan and returns the concrete session credential payload. */
 export async function executeCredentialPlan(
   plan: CredentialPlan,
-  cache: ChannelCache,
+  sink: ChannelSink,
 ): Promise<SessionCredentialPayload> {
   switch (plan.type) {
     case 'open':
-      return open(plan, cache)
+      return open(plan, sink)
     case 'recover':
-      return recover(plan, cache)
+      return recover(plan, sink)
     case 'voucher':
-      return voucher(plan, cache)
+      return voucher(plan, sink)
     case 'manual':
-      return manual(plan, cache)
+      return manual(plan, sink)
   }
 }
 
 async function open(
   plan: Extract<CredentialPlan, { type: 'open' }>,
-  cache: ChannelCache,
+  sink: ChannelSink,
 ): Promise<SessionCredentialPayload> {
-  const { account, authorizedSigner, resolved } = plan
+  const { account, resolved } = plan
   const deposit = resolveOpeningDeposit({
     contextDepositRaw: plan.context?.depositRaw,
     maxDeposit: plan.maxDeposit,
@@ -598,7 +584,6 @@ async function open(
     suggestedDepositRaw: resolved.suggestedDepositRaw,
   })
   const payload = await createOpenPayload(resolved.client, account, {
-    authorizedSigner,
     chainId: resolved.chainId,
     deposit,
     escrow: resolved.escrow,
@@ -608,7 +593,7 @@ async function open(
     payee: resolved.payee,
     token: resolved.token,
   })
-  storeChannelEntry(cache, resolved.key, {
+  await storeChannelEntry(sink, {
     channelId: payload.channelId,
     cumulativeAmount: resolved.amount,
     deposit,
@@ -622,7 +607,7 @@ async function open(
 
 async function recover(
   plan: Extract<CredentialPlan, { type: 'recover' }>,
-  cache: ChannelCache,
+  sink: ChannelSink,
 ): Promise<SessionCredentialPayload> {
   const { account, context, decimals, maxDeposit, resolved } = plan
   const { descriptor } = context
@@ -635,7 +620,7 @@ async function recover(
       escrow: resolved.escrow,
       payee: resolved.payee,
       payer: account.address,
-      authorizedSigner: resolveAuthorizedSigner(account, plan.authorizedSigner),
+      authorizedSigner: resolveAuthorizedSigner(account),
       token: resolved.token,
     },
   })
@@ -657,7 +642,7 @@ async function recover(
     resolved.chainId,
     resolved.escrow,
   )
-  storeChannelEntry(cache, resolved.key, {
+  await storeChannelEntry(sink, {
     channelId: reusable.channelId,
     cumulativeAmount,
     deposit: reusable.state.deposit,
@@ -671,7 +656,7 @@ async function recover(
 
 async function voucher(
   plan: Extract<CredentialPlan, { type: 'voucher' }>,
-  cache: ChannelCache,
+  sink: ChannelSink,
 ): Promise<SessionCredentialPayload> {
   const { account, entry, resolved } = plan
   const cumulativeAmount = entry.cumulativeAmount + resolved.amount
@@ -685,13 +670,13 @@ async function voucher(
     resolved.escrow,
   )
   entry.cumulativeAmount = cumulativeAmount
-  cache.notifyUpdate(entry)
+  await storeChannelEntry(sink, entry)
   return payload
 }
 
 async function manual(
   plan: Extract<CredentialPlan, { type: 'manual' }>,
-  cache: ChannelCache,
+  sink: ChannelSink,
 ): Promise<SessionCredentialPayload> {
   const { account, context, decimals, resolved } = plan
   const { descriptor } = context
@@ -706,7 +691,7 @@ async function manual(
     expectedChannelId: channelId,
     payee: resolved.payee,
     payer: account.address,
-    authorizedSigner: resolveAuthorizedSigner(account, plan.authorizedSigner),
+    authorizedSigner: resolveAuthorizedSigner(account),
     token: resolved.token,
   })
 
@@ -718,7 +703,7 @@ async function manual(
     descriptor,
     resolved,
   })
-  updateCachedCumulative(cache, channelId, payload)
+  await applyCumulative(sink, resolved.key, payload)
   return payload
 }
 

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

@@ -1,6 +1,6 @@
 import { type Address, createClient, custom, decodeFunctionData, encodeFunctionResult } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
-import { Transaction } from 'viem/tempo'
+import { Account as TempoAccount, Secp256k1, Transaction } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
 
 import type { Challenge } from '../../../Challenge.js'
@@ -286,6 +286,46 @@ describe('precompile client session', () => {
     expect(updates).toEqual([100n, 200n])
   })
 
+  test('passes existing channel authority to resolveAccount before reusing session channel', async () => {
+    const accessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey(), {
+      access: account,
+    })
+    const calls: session.ResolveAccountInfo[] = []
+    const method = session({
+      account,
+      decimals: 0,
+      maxDeposit: '1000',
+      getClient: () => client,
+      resolveAccount(info) {
+        calls.push(info)
+        return accessKey
+      },
+    })
+    const first = deserializeCredential(
+      await method.createCredential({ challenge: makeChallenge(), context: {} }),
+    )
+    const second = deserializeCredential(
+      await method.createCredential({ challenge: makeChallenge(), context: {} }),
+    )
+
+    expect(calls).toHaveLength(2)
+    expect(calls[0]!.account.address).toBe(account.address)
+    expect(calls[0]!.operation).toEqual({ kind: 'authorizePaymentChannel' })
+    expect(calls[1]!.operation).toEqual({
+      kind: 'authorizePaymentChannel',
+      authority: accessKey.accessKeyAddress,
+    })
+    expect(first.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    expect(second.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    expect(first.payload.action).toBe('open')
+    if (first.payload.action !== 'open' || second.payload.action !== 'voucher')
+      throw new Error('expected open then voucher payloads')
+    expect(first.payload.descriptor.payer).toBe(account.address)
+    expect(first.payload.descriptor.authorizedSigner).toBe(accessKey.accessKeyAddress)
+    expect(second.payload.channelId).toBe(first.payload.channelId)
+    expect(second.payload.cumulativeAmount).toBe('200')
+  })
+
   test('enforces maxDeposit when reusing a cached auto-mode channel', async () => {
     const updates: bigint[] = []
     const method = session({

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

@@ -5,15 +5,20 @@ import * as Constants from '../../../Constants.js'
 import * as Method from '../../../Method.js'
 import * as Account from '../../../viem/Account.js'
 import * as Client from '../../../viem/Client.js'
+import type {
+  ResolveAccount as ResolveAccount_,
+  ResolveAccountInfo as ResolveAccountInfo_,
+} from '../../client/ResolveAccount.js'
 import * as defaults from '../../internal/defaults.js'
 import * as Methods from '../../Methods.js'
 import { serializeCredential, type ChannelEntry } from './ChannelOps.js'
-import { sessionContextSchema } from './CredentialState.js'
+import { createChannelStore, type ChannelStore } from './ChannelStore.js'
 import {
-  createChannelCache,
   executeCredentialPlan,
   planCredential,
   resolveChallengeContext,
+  resolveRecoverContext,
+  sessionContextSchema,
 } from './CredentialState.js'
 
 export { sessionContextSchema, type SessionContext } from './CredentialState.js'
@@ -28,12 +33,13 @@ export { sessionContextSchema, type SessionContext } from './CredentialState.js'
 export function session(parameters: session.Parameters = {}) {
   const {
     account,
-    authorizedSigner,
+    channelStore,
     decimals = defaults.decimals,
     escrow: escrowOverride,
     getClient: getClientParameter,
     maxDeposit: maxDepositParameter,
     onChannelUpdate,
+    resolveAccount,
   } = parameters
   const getClient = Client.getResolver({
     chain: tempo_chain,
@@ -43,7 +49,8 @@ export function session(parameters: session.Parameters = {}) {
   const getAccount = Account.getResolver({ account })
   const maxDeposit =
     maxDepositParameter !== undefined ? parseUnits(maxDepositParameter, decimals) : undefined
-  const cache = createChannelCache(onChannelUpdate)
+  const store = channelStore ?? createChannelStore()
+  const sink = { store, notifyUpdate: (entry: ChannelEntry) => onChannelUpdate?.(entry) }
 
   return Method.toClient(Methods.session, {
     canHandleChallenge({ challenge }) {
@@ -61,18 +68,32 @@ export function session(parameters: session.Parameters = {}) {
         escrowOverride,
         getClient,
       })
-      const account = getAccount(resolved.client, context)
+      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 payload = await executeCredentialPlan(
         planCredential({
           account,
-          authorizedSigner,
-          cache,
+          entry,
           context,
           decimals,
           maxDeposit,
           resolved,
         }),
-        cache,
+        sink,
       )
       return serializeCredential(challenge, payload, resolved.chainId, account)
     },
@@ -81,10 +102,13 @@ export function session(parameters: session.Parameters = {}) {
 
 /** Type helpers for the low-level TIP-1034 session client method. */
 export declare namespace session {
+  type ResolveAccount = ResolveAccount_
+  type ResolveAccountInfo = ResolveAccountInfo_
+
   type Parameters = Account.getResolver.Parameters &
     Client.getResolver.Parameters & {
-      /** Address authorized to sign vouchers on behalf of the payer. Defaults to the account access key address when available, otherwise the account address. */
-      authorizedSigner?: Address | undefined
+      /** Pluggable persistence for reusable channels. Defaults to an in-memory store. */
+      channelStore?: ChannelStore | undefined
       /** Token decimals for parsing human-readable amounts (default: 6). */
       decimals?: number | undefined
       /** TIP20EscrowChannel address override. */
@@ -93,5 +117,7 @@ export declare namespace session {
       maxDeposit?: 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. */
+      resolveAccount?: ResolveAccount | undefined
     }
 }