mppx 0.6.31 → 0.8.0

package/src/tempo/client/Charge.test.ts

@@ -2,6 +2,7 @@ import { Challenge, Credential } from 'mppx'
 import { createClient, http } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { tempoLocalnet } from 'viem/chains'
+import { Account, Secp256k1 } from 'viem/tempo'
 import { describe, expect, test, vi } from 'vp/test'
 
 import * as Methods from '../Methods.js'
@@ -83,6 +84,178 @@ describe('tempo.charge client', () => {
     expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
   })
 
+  test('resolveAccount selects the transaction account from executable calls', async () => {
+    vi.resetModules()
+    const selectedAccount = privateKeyToAccount(
+      '0x0000000000000000000000000000000000000000000000000000000000000002',
+    )
+    const chainId = 42431
+    const calls: charge.ResolveAccountInfo[] = []
+    const prepareTransactionRequest = vi.fn(async () => ({}))
+    const signTransaction = vi.fn(async () => '0xdeadbeef')
+    vi.doMock('viem/actions', () => ({
+      prepareTransactionRequest,
+      sendCallsSync: vi.fn(),
+      signTransaction,
+      signTypedData: vi.fn(),
+    }))
+
+    try {
+      const { charge: chargeWithMockedActions } = await import('./Charge.js')
+      const client = createClient({
+        account,
+        chain: tempoLocalnet,
+        transport: http('http://127.0.0.1'),
+      })
+      const method = chargeWithMockedActions({
+        account,
+        getClient: () => client,
+        resolveAccount(info) {
+          calls.push(info)
+          return selectedAccount
+        },
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge({ amount: '1', chainId, supportedModes: ['pull'] }),
+          context: {},
+        }),
+      )
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.account.address).toBe(account.address)
+      expect(calls[0]!.chainId).toBe(chainId)
+      expect(calls[0]!.operation.kind).toBe('executeCalls')
+      if (calls[0]!.operation.kind !== 'executeCalls') throw new Error('expected executeCalls')
+      expect(calls[0]!.operation.calls).toHaveLength(1)
+      expect(calls[0]!.operation.calls?.[0]?.to.toLowerCase()).toBe(currency.toLowerCase())
+      expect(prepareTransactionRequest).toHaveBeenCalledOnce()
+      expect(signTransaction).toHaveBeenCalledOnce()
+      expect(credential.payload).toEqual({ signature: '0xdeadbeef', type: 'transaction' })
+      expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${selectedAccount.address}`)
+    } finally {
+      vi.doUnmock('viem/actions')
+      vi.resetModules()
+    }
+  })
+
+  test('resolveAccount omits executable calls when auto-swap routing is account-dependent', async () => {
+    vi.resetModules()
+    const selectedAccount = privateKeyToAccount(
+      '0x0000000000000000000000000000000000000000000000000000000000000002',
+    )
+    const chainId = 42431
+    const calls: charge.ResolveAccountInfo[] = []
+    const prepareTransactionRequest = vi.fn(async () => ({}))
+    const signTransaction = vi.fn(async () => '0xdeadbeef')
+    const findCalls = vi.fn(async (_client: unknown, _parameters: { account: string }) => undefined)
+    vi.doMock('viem/actions', () => ({
+      prepareTransactionRequest,
+      sendCallsSync: vi.fn(),
+      signTransaction,
+      signTypedData: vi.fn(),
+    }))
+    vi.doMock('../internal/auto-swap.js', () => ({
+      defaultCurrencies: [currency],
+      findCalls,
+      resolve: vi.fn(() => ({ tokenIn: [currency], slippage: 1 })),
+    }))
+
+    try {
+      const { charge: chargeWithMockedActions } = await import('./Charge.js')
+      const client = createClient({
+        account,
+        chain: tempoLocalnet,
+        transport: http('http://127.0.0.1'),
+      })
+      const method = chargeWithMockedActions({
+        account,
+        autoSwap: true,
+        getClient: () => client,
+        resolveAccount(info) {
+          calls.push(info)
+          return selectedAccount
+        },
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge({ amount: '1', chainId, supportedModes: ['pull'] }),
+          context: {},
+        }),
+      )
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.operation.kind).toBe('executeCalls')
+      if (calls[0]!.operation.kind !== 'executeCalls') throw new Error('expected executeCalls')
+      expect(calls[0]!.operation.calls).toBeUndefined()
+      expect(findCalls).toHaveBeenCalledOnce()
+      expect(findCalls.mock.calls[0]?.[1].account).toBe(selectedAccount.address)
+      expect(credential.payload).toEqual({ signature: '0xdeadbeef', type: 'transaction' })
+    } finally {
+      vi.doUnmock('viem/actions')
+      vi.doUnmock('../internal/auto-swap.js')
+      vi.resetModules()
+    }
+  })
+
+  test('zero-amount proof binds to the root payer for an access-key account', async () => {
+    vi.resetModules()
+    // Capture the typed data so we can assert what the proof commits to.
+    let signedTypedData: { message: { account: string } } | undefined
+    const signTypedData = vi.fn(async (_client: unknown, parameters: typeof signedTypedData) => {
+      signedTypedData = parameters
+      return '0xdeadbeef'
+    })
+    vi.doMock('viem/actions', () => ({
+      prepareTransactionRequest: vi.fn(),
+      sendCallsSync: vi.fn(),
+      signTransaction: vi.fn(),
+      signTypedData,
+    }))
+
+    try {
+      const { charge: chargeWithMockedActions } = await import('./Charge.js')
+      const chainId = 42431
+      // An access-key account signs with its own key but reports the root
+      // account as `address`; the proof must bind to that root payer.
+      const accessKey = Account.fromSecp256k1(Secp256k1.randomPrivateKey(), {
+        access: account,
+      })
+      expect(accessKey.address).toBe(account.address)
+      expect(accessKey.accessKeyAddress).not.toBe(account.address)
+
+      const client = createClient({
+        account: accessKey,
+        chain: tempoLocalnet,
+        transport: http('http://127.0.0.1'),
+      })
+      const resolveAccount = vi.fn()
+      const method = chargeWithMockedActions({
+        account: accessKey,
+        getClient: () => client,
+        resolveAccount,
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge({ chainId }),
+          context: {},
+        }),
+      )
+
+      expect(signTypedData).toHaveBeenCalledOnce()
+      expect(resolveAccount).not.toHaveBeenCalled()
+      expect(signedTypedData?.message.account).toBe(account.address)
+      expect(credential.payload).toEqual({ signature: '0xdeadbeef', type: 'proof' })
+      expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    } finally {
+      vi.doUnmock('viem/actions')
+      vi.resetModules()
+    }
+  })
+
   test('uses challenge chainId for non-zero transaction source', async () => {
     vi.resetModules()
     const prepareTransactionRequest = vi.fn(async () => ({}))
@@ -123,4 +296,89 @@ describe('tempo.charge client', () => {
       vi.resetModules()
     }
   })
+
+  describe('chain pinning', () => {
+    const client = createClient({
+      account,
+      chain: tempoLocalnet,
+      transport: http('http://127.0.0.1'),
+    })
+
+    test('rejects a challenge whose chainId conflicts with the pin', async () => {
+      const getClient = vi.fn(() => client)
+      const method = charge({
+        account,
+        expectedChainId: 42431,
+        getClient,
+      })
+
+      await expect(
+        method.createCredential({
+          challenge: createChallenge({ chainId: 1 }),
+          context: {},
+        }),
+      ).rejects.toThrow('Chain ID mismatch: expected 42431, got 1.')
+
+      // The mismatch is rejected before resolving a client or signing.
+      expect(getClient).not.toHaveBeenCalled()
+    })
+
+    test('accepts a challenge whose chainId matches the pin', async () => {
+      const chainId = 42431
+      const method = charge({
+        account,
+        expectedChainId: chainId,
+        getClient: () => client,
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge({ chainId }),
+          context: {},
+        }),
+      )
+
+      expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    })
+
+    test('signs on the pin when the challenge omits chainId', async () => {
+      let requestedChainId: number | undefined
+      const chainId = 42431
+      const method = charge({
+        account,
+        expectedChainId: chainId,
+        getClient: (parameters) => {
+          requestedChainId = parameters.chainId
+          return client
+        },
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge(),
+          context: {},
+        }),
+      )
+
+      expect(requestedChainId).toBe(chainId)
+      expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    })
+
+    test('unpinned client accepts any challenge chainId', async () => {
+      const chainId = 1
+      const method = charge({
+        account,
+        getClient: () => client,
+      })
+
+      const credential = Credential.deserialize(
+        await method.createCredential({
+          challenge: createChallenge({ chainId }),
+          context: {},
+        }),
+      )
+
+      expect(credential.source).toBe(`did:pkh:eip155:${chainId}:${account.address}`)
+    })
+  })
 })

package/src/tempo/client/Charge.ts

@@ -20,6 +20,20 @@ import * as Charge_internal from '../internal/charge.js'
 import * as defaults from '../internal/defaults.js'
 import * as Proof from '../internal/proof.js'
 import * as Methods from '../Methods.js'
+import type * as AccountResolution from './ResolveAccount.js'
+
+/** Runtime context accepted by the Tempo charge client method. */
+export type ChargeContext = {
+  account?: Account.getResolver.Parameters['account'] | undefined
+  autoSwap?: AutoSwap.resolve.Value | undefined
+  mode?: Methods.ChargeMode | undefined
+}
+
+const chargeContextSchema = z.object({
+  account: z.optional(z.custom<ChargeContext['account']>()),
+  autoSwap: z.optional(z.custom<ChargeContext['autoSwap']>()),
+  mode: z.optional(z.enum(Methods.chargeModes)),
+})
 
 /**
  * Creates a Tempo charge method intent for usage on the client.
@@ -44,37 +58,50 @@ export function charge(parameters: charge.Parameters = {}) {
   const getAccount = Account.getResolver({ account: parameters.account })
 
   return Method.toClient(Methods.charge, {
-    context: z.object({
-      account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
-      autoSwap: z.optional(z.custom<charge.AutoSwap>()),
-      mode: z.optional(z.enum(Methods.chargeModes)),
-    }),
+    context: chargeContextSchema,
 
     async createCredential({ challenge, context }) {
+      // Chain pinning: reject a challenge whose chain ID conflicts with the
+      // pinned one, and sign on the pin when the challenge omits a chain ID.
       const challengeChainId = challenge.request.methodDetails?.chainId
-      const client = await getClient({ chainId: challengeChainId })
-      const chainId = challengeChainId ?? client.chain?.id
+      if (
+        parameters.expectedChainId !== undefined &&
+        challengeChainId !== undefined &&
+        challengeChainId !== parameters.expectedChainId
+      )
+        throw new Error(
+          `Chain ID mismatch: expected ${parameters.expectedChainId}, got ${challengeChainId}.`,
+        )
+      const resolvedChainId = challengeChainId ?? parameters.expectedChainId
+      const client = await getClient({ chainId: resolvedChainId })
+      const chainId = resolvedChainId ?? client.chain?.id
       if (chainId === undefined)
         throw new Error('No `chainId` provided. Pass a chain ID in the challenge or client.')
 
-      const account = getAccount(client, context)
-
       const { request } = challenge
       const { amount, methodDetails } = request
+      const supportedModes = (methodDetails?.supportedModes as
+        | readonly Methods.ChargeMode[]
+        | undefined) ?? ['pull', 'push']
+      const defaultAccount = getAccount(client, context)
 
       // Zero-amount: sign EIP-712 typed data instead of creating a transaction.
       if (BigInt(amount) === 0n) {
         const signature = await signTypedData(client, {
-          account,
-          domain: Proof.domain(chainId),
-          types: Proof.types,
-          primaryType: 'Proof',
-          message: Proof.message(challenge.id, challenge.realm),
+          account: defaultAccount,
+          // `account` here is the signing account; the proof's bound payer is
+          // `account.address` (echoed in the credential `source` below).
+          ...Proof.typedData({
+            account: defaultAccount.address,
+            chainId,
+            challengeId: challenge.id,
+            realm: challenge.realm,
+          }),
         })
         return Credential.serialize({
           challenge,
           payload: { signature, type: 'proof' },
-          source: Proof.proofSource({ address: account.address, chainId }),
+          source: Proof.proofSource({ address: defaultAccount.address, chainId }),
         })
       }
 
@@ -89,22 +116,6 @@ export function charge(parameters: charge.Parameters = {}) {
           }
         }
       }
-      const supportedModes = (methodDetails?.supportedModes as
-        | readonly Methods.ChargeMode[]
-        | undefined) ?? ['pull', 'push']
-      const mode = (() => {
-        const explicitMode = context?.mode ?? parameters.mode
-        if (explicitMode) {
-          if (!supportedModes.includes(explicitMode))
-            throw new Error(`Challenge does not support ${explicitMode} mode.`)
-          return explicitMode
-        }
-
-        const preferredMode = account.type === 'json-rpc' ? 'push' : 'pull'
-        if (supportedModes.includes(preferredMode)) return preferredMode
-        return supportedModes[0]!
-      })()
-
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
         : Attribution.encode({ challengeId: challenge.id, clientId, serverId: challenge.realm })
@@ -116,13 +127,14 @@ export function charge(parameters: charge.Parameters = {}) {
         },
         recipient: request.recipient as Address,
       })
-      const transferCalls = transfers.map((transfer) =>
-        Actions.token.transfer.call({
-          amount: BigInt(transfer.amount),
-          ...(transfer.memo && { memo: transfer.memo as Hex.Hex }),
-          to: transfer.recipient as Address,
-          token: currency,
-        }),
+      const transferCalls = transfers.map(
+        (transfer): AccountResolution.ResolveAccountCall =>
+          Actions.token.transfer.call({
+            amount: BigInt(transfer.amount),
+            ...(transfer.memo && { memo: transfer.memo as Hex.Hex }),
+            to: transfer.recipient as Address,
+            token: currency,
+          }) as AccountResolution.ResolveAccountCall,
       )
 
       const autoSwap = AutoSwap.resolve(
@@ -130,6 +142,29 @@ export function charge(parameters: charge.Parameters = {}) {
         AutoSwap.defaultCurrencies,
       )
 
+      const account =
+        (await parameters.resolveAccount?.({
+          account: defaultAccount,
+          chainId,
+          operation: {
+            kind: 'executeCalls',
+            ...(autoSwap ? {} : { calls: transferCalls }),
+          },
+        })) ?? defaultAccount
+
+      const mode = (() => {
+        const explicitMode = context?.mode ?? parameters.mode
+        if (explicitMode) {
+          if (!supportedModes.includes(explicitMode))
+            throw new Error(`Challenge does not support ${explicitMode} mode.`)
+          return explicitMode
+        }
+
+        const preferredMode = account.type === 'json-rpc' ? 'push' : 'pull'
+        if (supportedModes.includes(preferredMode)) return preferredMode
+        return supportedModes[0]!
+      })()
+
       const swapCalls = autoSwap
         ? await AutoSwap.findCalls(client, {
             account: account.address,
@@ -187,6 +222,9 @@ export function charge(parameters: charge.Parameters = {}) {
 
 export declare namespace charge {
   type AutoSwap = AutoSwap.resolve.Value
+  type Context = ChargeContext
+  type ResolveAccount = AccountResolution.ResolveAccount
+  type ResolveAccountInfo = AccountResolution.ResolveAccountInfo
 
   type Parameters = {
     /**
@@ -198,6 +236,12 @@ export declare namespace charge {
     autoSwap?: AutoSwap | undefined
     /** Client identifier used to derive the client fingerprint in attribution memos. */
     clientId?: string | undefined
+    /**
+     * Chain ID this client is willing to pay on. When set, the client rejects
+     * any challenge whose `methodDetails.chainId` differs, and signs on this
+     * chain when the challenge omits a chain ID.
+     */
+    expectedChainId?: number | undefined
     /**
      * Allowlist of expected split recipient addresses. When set, the client
      * rejects any challenge whose split recipients are not in this list.
@@ -215,6 +259,8 @@ export declare namespace charge {
      * @default `'push'` for JSON-RPC accounts, `'pull'` for local accounts.
      */
     mode?: Methods.ChargeMode | undefined
+    /** Selects the account that signs this charge after the challenge and chain are known. */
+    resolveAccount?: ResolveAccount | undefined
   } & Account.getResolver.Parameters &
     Client.getResolver.Parameters
 }

package/src/tempo/client/Methods.ts

@@ -1,31 +1,45 @@
+import {
+  session as sessionLegacyIntent_,
+  sessionManager as sessionLegacy_,
+} from '../legacy/client/index.js'
+import { session as sessionMethod_ } from '../session/client/Session.js'
+import { sessionManager as session_ } from '../session/client/SessionManager.js'
 import { charge as charge_ } from './Charge.js'
-import { session as sessionIntent_ } from './Session.js'
-import { sessionManager as session_ } from './SessionManager.js'
 import { subscription as subscription_ } from './Subscription.js'
 
+const sessionClient = Object.assign(sessionMethod_, { manager: session_ })
+const sessionLegacyClient = Object.assign(sessionLegacy_, { method: sessionLegacyIntent_ })
+
+/** Creates a TIP-1034 client method, with explicit managed lifecycle helpers attached. */
+export { sessionClient as session }
+
 /**
- * Creates both Tempo `charge` and `session` client methods from shared parameters.
+ * Creates the common Tempo `charge` and `session` client methods from shared parameters.
  *
  * @example
  * ```ts
  * import { Mppx, tempo } from 'mppx/client'
  *
  * const mppx = Mppx.create({
- *   methods: [tempo({ account })],
+ *   methods: [tempo.common({ account })],
  * })
  * ```
  */
 export function tempo(parameters: tempo.Parameters = {}) {
-  return [charge_(parameters), sessionIntent_(parameters)] as const
+  return [charge_(parameters), sessionClient(parameters)] as const
 }
 
 export namespace tempo {
-  export type Parameters = charge_.Parameters & sessionIntent_.Parameters
+  export type Parameters = charge_.Parameters & sessionMethod_.Parameters
 
   /** Creates a Tempo `charge` client method for one-time TIP-20 token transfers. */
   export const charge = charge_
-  /** Creates a client-side streaming session for managing payment channels. */
-  export const session = session_
+  /** Creates the common Tempo `charge` and `session` client methods from shared parameters. */
+  export const common = tempo
+  /** Creates a TIP-1034 client method for Mppx registration. Use `tempo.session.manager()` for direct lifecycle control. */
+  export const session = sessionClient
+  /** @deprecated Use `tempo.session()` for the TIP-1034 session client method. */
+  export const sessionLegacy = sessionLegacyClient
   /** Creates a Tempo `subscription` client method for recurring TIP-20 payments. */
   export const subscription = subscription_
 }

package/src/tempo/client/ResolveAccount.ts

@@ -0,0 +1,46 @@
+import type * as Hex from 'ox/Hex'
+import type { Account, Address } from 'viem'
+
+import type { MaybePromise } from '../../internal/types.js'
+
+/** Resolves the account that should satisfy an mppx account operation. */
+export type ResolveAccount = (info: ResolveAccountInfo) => MaybePromise<Account | undefined>
+
+/** Account-resolution details for a client credential operation. */
+export type ResolveAccountInfo = {
+  /** Account mppx will use when the hook returns `undefined`. */
+  account: Account
+  /** EIP-155 chain ID used for the operation. */
+  chainId: number
+  /** Capability the selected account must satisfy. */
+  operation: ResolveAccountOperation
+}
+
+/** Capability an mppx-selected account must satisfy. */
+export type ResolveAccountOperation =
+  | {
+      kind: 'executeCalls'
+      /**
+       * Exact EVM calls the selected account will execute.
+       *
+       * Omitted when the calls depend on which account is selected, such as
+       * account-balance-dependent auto-swap routing.
+       */
+      calls?: readonly ResolveAccountCall[] | undefined
+    }
+  | {
+      kind: 'authorizePaymentChannel'
+      /**
+       * Signer required by an existing reusable channel. Omitted when opening
+       * a new channel or when no existing channel has fixed a signer yet.
+       */
+      authority?: Address | undefined
+    }
+
+/** EVM call data used by account resolvers for scoped account selection. */
+export type ResolveAccountCall = {
+  /** Contract address being called. */
+  to: Address
+  /** Calldata being sent. */
+  data: Hex.Hex
+}

package/src/tempo/client/index.ts

@@ -1,6 +1,17 @@
 export { charge } from './Charge.js'
-export { tempo } from './Methods.js'
-export { session } from './Session.js'
+export { session, tempo } from './Methods.js'
+export { session as sessionLegacy } from '../legacy/client/index.js'
 export { subscription } from './Subscription.js'
-export type { PaymentResponse, SessionManager } from './SessionManager.js'
-export { sessionManager } from './SessionManager.js'
+export type {
+  PaymentResponse as SessionLegacyPaymentResponse,
+  SessionManager as SessionLegacyManager,
+} from '../legacy/client/index.js'
+export { sessionManager as sessionLegacyManager } from '../legacy/client/index.js'
+export { session as sessionMethod } from '../session/client/Session.js'
+export type {
+  PaymentResponse,
+  SessionManager,
+  SessionManagerSseOptions,
+  SessionManagerWebSocketOptions,
+} from '../session/client/SessionManager.js'
+export { sessionManager } from '../session/client/SessionManager.js'

package/src/tempo/index.ts

@@ -1,4 +1,5 @@
 export * as Proof from './Proof.js'
 export * as Methods from './Methods.js'
 export * as Session from './session/index.js'
+export * as SessionLegacy from './legacy/index.js'
 export * as Subscription from './subscription/index.js'