mppx 0.6.31 → 0.8.0

package/src/tempo/internal/fee-token.test.ts

@@ -1,13 +1,14 @@
 import type { Account } from 'viem'
 import { createClient } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions, Addresses } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
-import { nodeEnv } from '~test/config.js'
-import { accounts, asset, chain, fundAccount, http } from '~test/tempo/viem.js'
+import { tempoNetwork } from '~test/config.js'
+import { asset, chain, fundAccount, http } from '~test/tempo/viem.js'
 
 import { resolveFeeToken } from './fee-token.js'
 
-const isLocalnet = nodeEnv === 'localnet'
+const isLocalnet = tempoNetwork === 'localnet'
 
 function clientFor(account: Account) {
   return createClient({
@@ -21,9 +22,13 @@ function expectAddress(actual: string | undefined, expected: string) {
   expect(actual?.toLowerCase()).toBe(expected.toLowerCase())
 }
 
+function testAccount() {
+  return privateKeyToAccount(generatePrivateKey())
+}
+
 describe.runIf(isLocalnet)('resolveFeeToken', () => {
   test('uses the funded account fee preference first', async () => {
-    const account = accounts[11]
+    const account = testAccount()
     const client = clientFor(account)
     await fundAccount({ address: account.address, token: asset })
     await Actions.fee.setUserTokenSync(client, {
@@ -41,7 +46,7 @@ describe.runIf(isLocalnet)('resolveFeeToken', () => {
   })
 
   test('falls through to the first funded candidate token', async () => {
-    const account = accounts[12]
+    const account = testAccount()
     const client = clientFor(account)
     await fundAccount({ address: account.address, token: asset })
 
@@ -55,7 +60,7 @@ describe.runIf(isLocalnet)('resolveFeeToken', () => {
   })
 
   test('falls through from an unfunded account fee preference', async () => {
-    const account = accounts[13]
+    const account = testAccount()
     const client = clientFor(account)
     await fundAccount({ address: account.address, token: asset })
     await Actions.fee.setUserTokenSync(client, {
@@ -73,7 +78,7 @@ describe.runIf(isLocalnet)('resolveFeeToken', () => {
   })
 
   test('uses a funded chain fee token when configured', async () => {
-    const account = accounts[14]
+    const account = testAccount()
     const client = createClient({
       account,
       chain: { ...chain, feeToken: asset },
@@ -91,7 +96,7 @@ describe.runIf(isLocalnet)('resolveFeeToken', () => {
   })
 
   test('falls through from an unfunded chain fee token', async () => {
-    const account = accounts[15]
+    const account = testAccount()
     const client = createClient({
       account,
       chain: { ...chain, feeToken: Addresses.pathUsd },
@@ -109,7 +114,7 @@ describe.runIf(isLocalnet)('resolveFeeToken', () => {
   })
 
   test('falls back to the first known token when none are funded', async () => {
-    const account = accounts[16]
+    const account = testAccount()
     const client = clientFor(account)
 
     const feeToken = await resolveFeeToken({

package/src/tempo/internal/proof.test.ts

@@ -44,9 +44,10 @@ const parsePkhSourceCases = [
 ] as const
 
 describe('Proof', () => {
-  test('types has Proof with challengeId and realm fields', () => {
+  test('types has Proof with account, challengeId and realm fields', () => {
     expect(Proof.types).toEqual({
       Proof: [
+        { name: 'account', type: 'address' },
         { name: 'challengeId', type: 'string' },
         { name: 'realm', type: 'string' },
       ],
@@ -55,7 +56,7 @@ describe('Proof', () => {
 
   test('domain returns EIP-712 domain with name, version, chainId', () => {
     const d = Proof.domain(42431)
-    expect(d).toEqual({ name: 'MPP', version: '2', chainId: 42431 })
+    expect(d).toEqual({ name: 'MPP', version: '3', chainId: 42431 })
   })
 
   test('domain uses provided chainId', () => {
@@ -63,8 +64,15 @@ describe('Proof', () => {
     expect(Proof.domain(99999).chainId).toBe(99999)
   })
 
-  test('message wraps challengeId and realm', () => {
-    expect(Proof.message('abc123', 'api.example.com')).toEqual({
+  test('message wraps account, challengeId and realm', () => {
+    expect(
+      Proof.message({
+        account: '0xAbCdEf1234567890AbCdEf1234567890AbCdEf12',
+        challengeId: 'abc123',
+        realm: 'api.example.com',
+      }),
+    ).toEqual({
+      account: '0xAbCdEf1234567890AbCdEf1234567890AbCdEf12',
       challengeId: 'abc123',
       realm: 'api.example.com',
     })

package/src/tempo/internal/proof.ts

@@ -1,8 +1,18 @@
-import { isAddress, type Address } from 'viem'
+import { hashTypedData, isAddress, type Address, type Hex } from 'viem'
 
-/** EIP-712 typed data types for proof credentials. */
+/** EIP-712 primary type for proof credentials. */
+export const primaryType = 'Proof' as const
+
+/**
+ * EIP-712 typed-data field definitions for Tempo zero-amount proof credentials.
+ *
+ * The `account` field cryptographically binds the signature to the payer
+ * wallet, so a proof signed for one account cannot be replayed against another
+ * — including across an access key that is authorized for multiple accounts.
+ */
 export const types = {
   Proof: [
+    { name: 'account', type: 'address' },
     { name: 'challengeId', type: 'string' },
     { name: 'realm', type: 'string' },
   ],
@@ -10,12 +20,51 @@ export const types = {
 
 /** Constructs the EIP-712 domain for a proof credential. */
 export function domain(chainId: number) {
-  return { name: 'MPP', version: '2', chainId } as const
+  return { name: 'MPP', version: '3', chainId } as const
+}
+
+/**
+ * Constructs the EIP-712 message for a proof credential.
+ *
+ * @param parameters - Proof message parameters.
+ * @param parameters.account - Payer wallet address the proof is bound to.
+ * @param parameters.challengeId - Challenge `id` being proven.
+ * @param parameters.realm - Challenge `realm` being proven.
+ */
+export function message(parameters: { account: Address; challengeId: string; realm: string }) {
+  const { account, challengeId, realm } = parameters
+  return { account, challengeId, realm } as const
+}
+
+/**
+ * Constructs the complete EIP-712 typed-data payload for a proof credential.
+ *
+ * This is the canonical, wallet-bound proof contract: signing this payload
+ * commits the signer to a specific `account`, `challengeId`, and `realm`.
+ */
+export function typedData(parameters: {
+  account: Address
+  chainId: number
+  challengeId: string
+  realm: string
+}) {
+  const { account, chainId, challengeId, realm } = parameters
+  return {
+    domain: domain(chainId),
+    types,
+    primaryType,
+    message: message({ account, challengeId, realm }),
+  } as const
 }
 
-/** Constructs the EIP-712 message for a proof credential. */
-export function message(challengeId: string, realm: string) {
-  return { challengeId, realm } as const
+/** Computes the EIP-712 digest (signing payload) for a proof credential. */
+export function hash(parameters: {
+  account: Address
+  chainId: number
+  challengeId: string
+  realm: string
+}): Hex {
+  return hashTypedData(typedData(parameters))
 }
 
 /** Constructs the expected `did:pkh` source DID for a proof credential. */

package/src/tempo/legacy/AccessKeyAuthorization.test.ts

@@ -0,0 +1,162 @@
+import { type Address, createClient, custom, type Hex } from 'viem'
+import {
+  Account as TempoAccount,
+  KeyAuthorizationManager,
+  Secp256k1,
+  Transaction,
+} from 'viem/tempo'
+import { beforeAll, describe, expect, test } from 'vp/test'
+import { tempoNetwork } from '~test/config.js'
+import { deployEscrow, openChannel } from '~test/tempo/legacy/session.js'
+import { asset as currency, chain, http } from '~test/tempo/viem.js'
+
+import { createOpenPayload } from './client/ChannelOps.js'
+import { closeOnChain, settleOnChain } from './session/Chain.js'
+import { signVoucher } from './session/Voucher.js'
+
+const rootAccount = TempoAccount.fromSecp256k1(
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+)
+const recipient = '0x2222222222222222222222222222222222222222' as Address
+const isLocalnet = tempoNetwork === 'localnet'
+
+async function createAccessKeyClient() {
+  const keyAuthorizationManager = KeyAuthorizationManager.memory()
+  const accessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey(), {
+    access: rootAccount,
+    keyAuthorizationManager,
+  })
+  const keyAuthorization = await rootAccount.signKeyAuthorization(
+    {
+      accessKeyAddress: accessKey.accessKeyAddress,
+      keyType: accessKey.keyType,
+    },
+    {
+      chainId: BigInt(chain.id),
+    },
+  )
+  await keyAuthorizationManager.set(
+    {
+      accessKey: accessKey.accessKeyAddress,
+      address: rootAccount.address,
+      chainId: chain.id,
+    },
+    keyAuthorization,
+  )
+
+  const signedTransactions: Transaction.TransactionSerializedTempo[] = []
+  const rpcClient = createClient({ chain, transport: http() })
+
+  const client = createClient({
+    account: accessKey,
+    chain,
+    transport: custom({
+      async request({ method, params }: { method: string; params?: readonly unknown[] }) {
+        if (method === 'eth_sendRawTransaction' || method === 'eth_sendRawTransactionSync')
+          signedTransactions.push(params?.[0] as Transaction.TransactionSerializedTempo)
+        return rpcClient.request({ method, params } as never)
+      },
+    }),
+  })
+
+  return { accessKey, client, keyAuthorization, signedTransactions }
+}
+
+function expectTransactionKeyAuthorization(
+  serializedTransaction: Hex,
+  keyAuthorization: Awaited<ReturnType<typeof rootAccount.signKeyAuthorization>>,
+) {
+  const transaction = Transaction.deserialize(
+    serializedTransaction as Transaction.TransactionSerializedTempo,
+  )
+  expect(transaction.keyAuthorization).toEqual(keyAuthorization)
+}
+
+async function createChannelForPayee(payee: Address, escrowContract: Address) {
+  const payer = rootAccount
+  const { channelId } = await openChannel({
+    deposit: 10_000_000n,
+    escrow: escrowContract,
+    payee,
+    payer,
+    salt: Secp256k1.randomPrivateKey(),
+    token: currency,
+  })
+  const cumulativeAmount = 1_000_000n
+  const signature = await signVoucher(
+    createClient({ account: payer, chain, transport: http() }),
+    payer,
+    { channelId, cumulativeAmount },
+    escrowContract,
+    chain.id,
+  )
+
+  return { channelId, cumulativeAmount, escrowContract, signature }
+}
+
+describe.runIf(isLocalnet)('legacy Tempo session access-key authorization attachment', () => {
+  let escrowContract: Address
+
+  beforeAll(async () => {
+    escrowContract = await deployEscrow()
+  })
+
+  test('open signs a prepared transaction with keyAuthorization', async () => {
+    const { accessKey, client, keyAuthorization } = await createAccessKeyClient()
+
+    const { payload } = await createOpenPayload(client, accessKey, {
+      chainId: chain.id,
+      currency,
+      deposit: 5_000_000n,
+      escrowContract,
+      initialAmount: 1_000_000n,
+      payee: recipient,
+    })
+
+    expect(payload.action).toBe('open')
+    if (payload.action !== 'open') throw new Error('unexpected payload action')
+    expectTransactionKeyAuthorization(payload.transaction, keyAuthorization)
+  })
+
+  test('settle sends a prepared transaction with keyAuthorization', async () => {
+    const { accessKey, client, keyAuthorization, signedTransactions } =
+      await createAccessKeyClient()
+    const channel = await createChannelForPayee(rootAccount.address, escrowContract)
+
+    const hash = await settleOnChain(
+      client,
+      channel.escrowContract,
+      {
+        channelId: channel.channelId,
+        cumulativeAmount: channel.cumulativeAmount,
+        signature: channel.signature,
+      },
+      { account: accessKey },
+    )
+
+    expect(hash).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(signedTransactions).toHaveLength(1)
+    expectTransactionKeyAuthorization(signedTransactions[0]!, keyAuthorization)
+  })
+
+  test('close sends a prepared transaction with keyAuthorization', async () => {
+    const { accessKey, client, keyAuthorization, signedTransactions } =
+      await createAccessKeyClient()
+    const channel = await createChannelForPayee(rootAccount.address, escrowContract)
+
+    const hash = await closeOnChain(
+      client,
+      channel.escrowContract,
+      {
+        channelId: channel.channelId,
+        cumulativeAmount: channel.cumulativeAmount,
+        signature: channel.signature,
+      },
+      { account: accessKey },
+    )
+
+    expect(hash).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(signedTransactions).toHaveLength(1)
+    expectTransactionKeyAuthorization(signedTransactions[0]!, keyAuthorization)
+  })
+})

package/src/tempo/legacy/README.md

@@ -0,0 +1,9 @@
+# Tempo Legacy Session
+
+This directory contains the legacy smart-contract-backed `tempo/session`
+implementation.
+
+The default `tempo.session` implementation is TIP-1034 precompile-backed and
+lives under `src/tempo/session/precompile`. Legacy code may import shared transport and
+accounting helpers from `src/tempo/session`, but legacy chain, channel, voucher,
+client, and server implementations should stay inside this directory.

package/src/tempo/{client → legacy/client}/ChannelOps.test.ts

@@ -4,18 +4,16 @@ import { type Address, createClient, decodeFunctionData } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { Account as TempoAccount, Addresses, Transaction } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
-import { nodeEnv } from '~test/config.js'
-import { deployEscrow, openChannel } from '~test/tempo/session.js'
+import { tempoNetwork } from '~test/config.js'
+import { deployEscrow, openChannel } from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount, http } from '~test/tempo/viem.js'
 
-const isLocalnet = nodeEnv === 'localnet'
-
-import type { Challenge } from '../../Challenge.js'
-import * as Credential from '../../Credential.js'
+import type { Challenge } from '../../../Challenge.js'
+import * as Credential from '../../../Credential.js'
 import {
   chainId as chainIdDefaults,
   escrowContract as escrowContractDefaults,
-} from '../internal/defaults.js'
+} from '../../internal/defaults.js'
 import { escrowAbi } from '../session/Chain.js'
 import { verifyVoucher } from '../session/Voucher.js'
 import {
@@ -40,6 +38,7 @@ const localClient = createClient({
 const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex.Hex
 const escrowContract = '0x1234567890abcdef1234567890abcdef12345678' as Address
 const chainId = 42431
+const isLocalnet = tempoNetwork === 'localnet'
 
 function makeChallenge(overrides?: Partial<Challenge>): Challenge {
   return {

package/src/tempo/{client → legacy/client}/ChannelOps.ts

@@ -16,21 +16,28 @@ import {
 import { prepareTransactionRequest, signTransaction } from 'viem/actions'
 import { Abis } from 'viem/tempo'
 
-import type { Challenge } from '../../Challenge.js'
-import * as Credential from '../../Credential.js'
-import { getAccountSignerAddress } from '../internal/account.js'
-import * as defaults from '../internal/defaults.js'
+import type { Challenge } from '../../../Challenge.js'
+import * as Credential from '../../../Credential.js'
+import { getAccountSignerAddress } from '../../internal/account.js'
+import * as defaults from '../../internal/defaults.js'
 import { escrowAbi, getOnChainChannel } from '../session/Chain.js'
 import * as Channel from '../session/Channel.js'
-import type { SessionCredentialPayload } from '../session/Types.js'
+import type { LegacySessionCredentialPayload } from '../session/Types.js'
 import { signVoucher } from '../session/Voucher.js'
 
+/** Cached channel metadata used by the legacy auto-driving session client. */
 export type ChannelEntry = {
+  /** Legacy contract-backed channel ID. */
   channelId: Hex.Hex
+  /** Salt used to derive the channel ID. */
   salt: Hex.Hex
+  /** Highest cumulative voucher amount locally authorized. */
   cumulativeAmount: bigint
+  /** Escrow contract backing this channel. */
   escrowContract: Address
+  /** Chain ID used for channel ID and voucher domain separation. */
   chainId: number
+  /** Whether the client considers the channel reusable. */
   opened: boolean
 }
 
@@ -41,11 +48,13 @@ function resolveVoucherSigner(
   return voucherSigner ?? account
 }
 
+/** Resolves the chain ID embedded in a legacy session challenge. */
 export function resolveChainId(challenge: Challenge): number {
   const md = challenge.request.methodDetails as { chainId?: number } | undefined
   return md?.chainId ?? 0
 }
 
+/** Resolves the legacy escrow contract from local override, challenge hint, or defaults. */
 export function resolveEscrow(
   challenge: { request: { methodDetails?: unknown } },
   chainId: number,
@@ -64,9 +73,10 @@ export function resolveEscrow(
   return escrow
 }
 
+/** Serializes a legacy session credential with a payer DID source. */
 export function serializeCredential(
   challenge: Challenge,
-  payload: SessionCredentialPayload,
+  payload: LegacySessionCredentialPayload,
   chainId: number,
   account: viem_Account,
 ): string {
@@ -77,6 +87,7 @@ export function serializeCredential(
   })
 }
 
+/** Creates a legacy cumulative voucher credential payload. */
 export async function createVoucherPayload(
   client: viem_Client,
   account: viem_Account,
@@ -85,7 +96,7 @@ export async function createVoucherPayload(
   escrowContract: Address,
   chainId: number,
   voucherSigner?: viem_Account | undefined,
-): Promise<SessionCredentialPayload> {
+): Promise<LegacySessionCredentialPayload> {
   const signer = resolveVoucherSigner(account, voucherSigner)
   const signature = await signVoucher(
     client,
@@ -103,6 +114,7 @@ export async function createVoucherPayload(
   }
 }
 
+/** Creates a legacy cooperative close credential payload. */
 export async function createClosePayload(
   client: viem_Client,
   account: viem_Account,
@@ -111,7 +123,7 @@ export async function createClosePayload(
   escrowContract: Address,
   chainId: number,
   voucherSigner?: viem_Account | undefined,
-): Promise<SessionCredentialPayload> {
+): Promise<LegacySessionCredentialPayload> {
   const signer = resolveVoucherSigner(account, voucherSigner)
   const signature = await signVoucher(
     client,
@@ -129,6 +141,7 @@ export async function createClosePayload(
   }
 }
 
+/** Creates a legacy open transaction credential payload and local channel entry. */
 export async function createOpenPayload(
   client: viem_Client,
   account: viem_Account,
@@ -142,7 +155,7 @@ export async function createOpenPayload(
     chainId: number
     feePayer?: boolean | undefined
   },
-): Promise<{ entry: ChannelEntry; payload: SessionCredentialPayload }> {
+): Promise<{ entry: ChannelEntry; payload: LegacySessionCredentialPayload }> {
   const { escrowContract, payee, currency, deposit, initialAmount, chainId, feePayer } = options
   const voucherSigner = resolveVoucherSigner(account, options.voucherSigner)
   const authorizedSigner = getAccountSignerAddress(voucherSigner)

package/src/tempo/{client → legacy/client}/Session.test.ts

@@ -3,22 +3,21 @@ import { type Address, createClient, decodeFunctionData, erc20Abi, type Hex, htt
 import { privateKeyToAccount } from 'viem/accounts'
 import { Account as TempoAccount, Addresses, Transaction, WebCryptoP256 } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
-import { nodeEnv } from '~test/config.js'
-import { deployEscrow, openChannel } from '~test/tempo/session.js'
+import { tempoNetwork } from '~test/config.js'
+import { deployEscrow, openChannel } from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 
-const isLocalnet = nodeEnv === 'localnet'
-
-import * as Challenge from '../../Challenge.js'
-import * as Credential from '../../Credential.js'
-import { chainId, escrowContract as escrowContractDefaults } from '../internal/defaults.js'
+import * as Challenge from '../../../Challenge.js'
+import * as Constants from '../../../Constants.js'
+import * as Credential from '../../../Credential.js'
+import { chainId, escrowContract as escrowContractDefaults } from '../../internal/defaults.js'
 import { escrowAbi } from '../session/Chain.js'
-import type { SessionCredentialPayload } from '../session/Types.js'
+import type { LegacySessionCredentialPayload } from '../session/Types.js'
 import { verifyVoucher } from '../session/Voucher.js'
 import { session } from './Session.js'
 
 function deserializePayload(result: string) {
-  const cred = Credential.deserialize<SessionCredentialPayload>(result)
+  const cred = Credential.deserialize<LegacySessionCredentialPayload>(result)
   return cred
 }
 
@@ -33,6 +32,7 @@ const pureClient = createClient({
 const escrowAddress = escrowContractDefaults[chainId.testnet] as Address
 const recipient = '0x2222222222222222222222222222222222222222' as Address
 const currency = '0x3333333333333333333333333333333333333333' as Address
+const isLocalnet = tempoNetwork === 'localnet'
 
 function makeChallenge(overrides?: Record<string, unknown>) {
   return Challenge.from({
@@ -55,6 +55,48 @@ function makeChallenge(overrides?: Record<string, unknown>) {
 }
 
 describe('session (pure)', () => {
+  test('handles legacy and unmarked session challenges', () => {
+    const method = session({
+      getClient: () => pureClient,
+      account: pureAccount,
+    })
+
+    expect(method.canHandleChallenge?.({ challenge: makeChallenge() })).toBe(true)
+    expect(
+      method.canHandleChallenge?.({
+        challenge: makeChallenge({
+          methodDetails: {
+            chainId: 42431,
+            escrowContract: escrowAddress,
+            sessionProtocol: Constants.SessionProtocols.v1,
+          },
+        }),
+      }),
+    ).toBe(true)
+    expect(
+      method.canHandleChallenge?.({
+        challenge: makeChallenge({
+          methodDetails: {
+            chainId: 42431,
+            escrowContract: escrowAddress,
+            sessionProtocol: Constants.SessionProtocols.v2,
+          },
+        }),
+      }),
+    ).toBe(false)
+    expect(
+      method.canHandleChallenge?.({
+        challenge: makeChallenge({
+          methodDetails: {
+            chainId: 42431,
+            escrowContract: escrowAddress,
+            sessionProtocol: 'future' as never,
+          },
+        }),
+      }),
+    ).toBe(false)
+  })
+
   describe('error: no action and no deposit/maxDeposit', () => {
     test('throws when neither configured', async () => {
       const method = session({

package/src/tempo/{client → legacy/client}/Session.ts

@@ -2,15 +2,16 @@ import type { Hex } from 'ox'
 import { type Address, parseUnits, type Account as viem_Account } from 'viem'
 import { tempo as tempo_chain } from 'viem/tempo/chains'
 
-import type * as Challenge from '../../Challenge.js'
-import * as Method from '../../Method.js'
-import * as Account from '../../viem/Account.js'
-import * as Client from '../../viem/Client.js'
-import * as z from '../../zod.js'
-import { getAccountSignerAddress } from '../internal/account.js'
-import * as defaults from '../internal/defaults.js'
-import * as Methods from '../Methods.js'
-import type { SessionCredentialPayload } from '../session/Types.js'
+import type * as Challenge from '../../../Challenge.js'
+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 * as z from '../../../zod.js'
+import { getAccountSignerAddress } from '../../internal/account.js'
+import * as defaults from '../../internal/defaults.js'
+import * as Methods from '../../Methods.js'
+import type { LegacySessionCredentialPayload } from '../session/Types.js'
 import { signVoucher } from '../session/Voucher.js'
 import {
   type ChannelEntry,
@@ -21,6 +22,7 @@ import {
   tryRecoverChannel,
 } from './ChannelOps.js'
 
+/** Runtime schema for legacy low-level session credential context. */
 export const sessionContextSchema = z.object({
   account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
   action: z.optional(z.enum(['open', 'topUp', 'voucher', 'close'])),
@@ -33,6 +35,7 @@ export const sessionContextSchema = z.object({
   depositRaw: z.optional(z.string()),
 })
 
+/** Context accepted by the legacy low-level session client method. */
 export type SessionContext = z.infer<typeof sessionContextSchema>
 
 /**
@@ -172,7 +175,7 @@ export function session(parameters: session.Parameters = {}) {
       }
     }
 
-    let payload: SessionCredentialPayload
+    let payload: LegacySessionCredentialPayload
 
     if (entry?.opened) {
       entry.cumulativeAmount += amount
@@ -236,7 +239,7 @@ export function session(parameters: session.Parameters = {}) {
     const escrowContract = resolveEscrowCached(challenge, chainId, channelId)
     escrowContractMap.set(channelId, escrowContract)
 
-    let payload: SessionCredentialPayload
+    let payload: LegacySessionCredentialPayload
 
     switch (action) {
       case 'open': {
@@ -335,6 +338,16 @@ export function session(parameters: session.Parameters = {}) {
   }
 
   return Method.toClient(Methods.session, {
+    canHandleChallenge({ challenge }) {
+      const sessionProtocolMarker = Constants.getMethodDetail(
+        challenge.request.methodDetails,
+        Constants.MethodDetailKeys.sessionProtocol,
+      )
+      return (
+        sessionProtocolMarker === undefined ||
+        sessionProtocolMarker === Constants.SessionProtocols.v1
+      )
+    },
     context: sessionContextSchema,
 
     async createCredential({ challenge, context }) {
@@ -354,6 +367,7 @@ export function session(parameters: session.Parameters = {}) {
   })
 }
 
+/** Type helpers for the legacy low-level session client method. */
 export declare namespace session {
   type Parameters = Account.getResolver.Parameters &
     Client.getResolver.Parameters & {