mppx 0.6.27 → 0.6.29

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

@@ -1,9 +1,16 @@
-import type { Hex } from 'viem'
+import { createClient, type Hex, http } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { Account as TempoAccount } from 'viem/tempo'
 import { describe, expect, test, vi } from 'vp/test'
 
 import * as Challenge from '../../Challenge.js'
+import * as PaymentCredential from '../../Credential.js'
 import { formatNeedVoucherEvent, parseEvent } from '../session/Sse.js'
-import type { NeedVoucherEvent, SessionReceipt } from '../session/Types.js'
+import type {
+  NeedVoucherEvent,
+  SessionCredentialPayload,
+  SessionReceipt,
+} from '../session/Types.js'
 import { sessionManager } from './SessionManager.js'
 
 const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
@@ -82,6 +89,66 @@ describe('Session', () => {
       expect(s.cumulative).toBe(0n)
       expect(s.opened).toBe(false)
     })
+
+    test('uses voucherSigner for managed open credentials', async () => {
+      vi.resetModules()
+      vi.doMock('viem/actions', () => ({
+        prepareTransactionRequest: vi.fn(async () => ({})),
+        sendCallsSync: vi.fn(),
+        signTransaction: vi.fn(async () => '0xdeadbeef'),
+        signTypedData: vi.fn(),
+      }))
+
+      try {
+        const { sessionManager: sessionManagerWithMocks } = await import('./SessionManager.js')
+        const account = privateKeyToAccount(
+          '0x0000000000000000000000000000000000000000000000000000000000000001',
+        )
+        const voucherSigner = TempoAccount.fromSecp256k1(
+          '0x0000000000000000000000000000000000000000000000000000000000000002',
+          { access: account },
+        )
+        const client = createClient({
+          account,
+          transport: http('http://127.0.0.1'),
+        })
+        const challenge = makeChallenge({
+          recipient: '0x742d35cc6634c0532925a3b844bc9e7595f8fe00',
+          methodDetails: {
+            escrowContract: '0x9d136eea063ede5418a6bc7beaff009bbb6cfa70',
+            chainId: 4217,
+          },
+        })
+        const mockFetch = vi
+          .fn()
+          .mockResolvedValueOnce(make402Response(challenge))
+          .mockResolvedValueOnce(makeOkResponse())
+
+        const manager = sessionManagerWithMocks({
+          account,
+          client,
+          fetch: mockFetch as typeof globalThis.fetch,
+          maxDeposit: '10',
+          voucherSigner,
+        })
+
+        const response = await manager.fetch('https://api.example.com/data')
+        const authorization = new Headers((mockFetch.mock.calls[1]![1] as RequestInit).headers).get(
+          'Authorization',
+        )
+
+        expect(response.status).toBe(200)
+        expect(authorization).toBeDefined()
+        if (!authorization) throw new Error('missing authorization header')
+        const credential = PaymentCredential.deserialize<SessionCredentialPayload>(authorization)
+        expect(credential.payload.action).toBe('open')
+        if (credential.payload.action !== 'open') throw new Error('unexpected action')
+        expect(credential.payload.authorizedSigner).toBe(voucherSigner.accessKeyAddress)
+      } finally {
+        vi.doUnmock('viem/actions')
+        vi.resetModules()
+      }
+    })
   })
 
   describe('.fetch()', () => {

package/src/tempo/client/SessionManager.ts

@@ -1,5 +1,5 @@
 import type { Hex } from 'ox'
-import { parseUnits, type Address } from 'viem'
+import { parseUnits, type Account as viem_Account, type Address } from 'viem'
 
 import * as Challenge from '../../Challenge.js'
 import * as Fetch from '../../client/internal/Fetch.js'
@@ -124,7 +124,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
 
   const method = sessionPlugin({
     account: parameters.account,
-    authorizedSigner: parameters.authorizedSigner,
+    voucherSigner: parameters.voucherSigner,
     getClient: parameters.client ? () => parameters.client! : parameters.getClient,
     escrowContract: parameters.escrowContract,
     decimals: parameters.decimals,
@@ -853,8 +853,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
 export declare namespace sessionManager {
   type Parameters = Account.getResolver.Parameters &
     Client.getResolver.Parameters & {
-      /** Address authorized to sign vouchers. Defaults to the account address. */
-      authorizedSigner?: Address | undefined
+      /** Account that signs voucher digests. Defaults to `account`; access-key accounts sign raw vouchers as their access-key address. */
+      voucherSigner?: viem_Account | undefined
       /** Viem client instance. Shorthand for `getClient: () => client`. */
       client?: import('viem').Client | undefined
       /** Token decimals used to convert `maxDeposit` to raw units. Defaults to `6`. */

package/src/tempo/internal/account.ts

@@ -1,4 +1,17 @@
 import type { Account, Address } from 'viem'
+import type { Account as TempoAccount } from 'viem/tempo'
+
+/** Returns whether an account is a Tempo access-key account. */
+export function isAccessKeyAccount(
+  account: Account,
+): account is Account & TempoAccount.AccessKeyAccount {
+  return 'accessKeyAddress' in account
+}
+
+/** Returns the address that should authorize direct account signatures. */
+export function getAccountSignerAddress(account: Account): Address {
+  return isAccessKeyAccount(account) ? account.accessKeyAddress : account.address
+}
 
 /**
  * Resolves a recipient address and optional fee payer from flexible input parameters.

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

@@ -1,4 +1,4 @@
-import { encodeFunctionData } from 'viem'
+import { encodeFunctionData, maxUint256 } from 'viem'
 import { Abis, Addresses } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
 
@@ -443,7 +443,7 @@ describe('prepareSponsoredTransaction', () => {
     maxFeePerGas: 1_000_000_000n,
     maxPriorityFeePerGas: 1_000_000_000n,
     nonce: 1n,
-    nonceKey: 1n,
+    nonceKey: 'expiring',
     signature: { r: 1n, s: 1n, yParity: 0 } as any,
     validBefore: Math.floor(Date.now() / 1_000) + 300,
   } as const
@@ -460,6 +460,36 @@ describe('prepareSponsoredTransaction', () => {
     ).not.toThrow()
   })
 
+  test('accepts serialized expiring nonce key', () => {
+    expect(() =>
+      prepareSponsoredTransaction({
+        account: sponsor,
+        chainId: 42431,
+        details,
+        expectedFeeToken: bogus,
+        transaction: {
+          ...baseTransaction,
+          nonceKey: maxUint256,
+        } as any,
+      }),
+    ).not.toThrow()
+  })
+
+  test('error: rejects non-expiring nonce keys', () => {
+    expect(() =>
+      prepareSponsoredTransaction({
+        account: sponsor,
+        chainId: 42431,
+        details,
+        expectedFeeToken: bogus,
+        transaction: {
+          ...baseTransaction,
+          nonceKey: 1n,
+        } as any,
+      }),
+    ).toThrow('must use an expiring nonce')
+  })
+
   test('accepts higher Moderato priority fees by default', () => {
     expect(() =>
       prepareSponsoredTransaction({

package/src/tempo/internal/fee-payer.ts

@@ -2,7 +2,7 @@ import type { TempoAddress } from 'ox/tempo'
 import { TxEnvelopeTempo } from 'ox/tempo'
 import type { Hex } from 'viem'
 import type { Account } from 'viem'
-import { decodeFunctionData } from 'viem'
+import { decodeFunctionData, maxUint256 } from 'viem'
 import { Abis, Addresses, Transaction } from 'viem/tempo'
 
 import * as TempoAddress_internal from './address.js'
@@ -126,6 +126,10 @@ function getPolicy(chainId: number, overrides: Partial<Policy> | undefined): Pol
   }
 }
 
+function isExpiringNonceKey(nonceKey: SponsoredTransaction['nonceKey']): boolean {
+  return nonceKey === 'expiring' || nonceKey === maxUint256
+}
+
 /** Validates that a set of transaction calls matches an allowed fee-payer pattern. */
 export function validateCalls(
   calls: readonly { data?: `0x${string}` | undefined; to?: TempoAddress.Address | undefined }[],
@@ -358,7 +362,7 @@ export function prepareSponsoredTransaction(parameters: {
       maxPriorityFeePerGas: maxPriorityFeePerGas.toString(),
     })
 
-  if (nonceKey === undefined) fail('fee-sponsored transaction must use an expiring nonce')
+  if (!isExpiringNonceKey(nonceKey)) fail('fee-sponsored transaction must use an expiring nonce')
   if (validBefore === undefined)
     fail('fee-sponsored transaction must declare validBefore for the expiring nonce')
   const validBeforeValue = validBefore

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

@@ -286,6 +286,7 @@ describe('tempo', () => {
     })
 
     test('behavior: rejects replayed transaction hash', async () => {
+      const dedupStore = Store.memory()
       const dedupServer = Mppx_server.create({
         methods: [
           tempo_server.charge({
@@ -294,7 +295,8 @@ describe('tempo', () => {
             },
             currency: asset,
             account: accounts[0],
-            store: Store.memory(),
+            store: dedupStore,
+            storeKeyPrefix: 'tenant:',
           }),
         ],
         realm,
@@ -336,6 +338,8 @@ describe('tempo', () => {
         })
         expect(response.status).toBe(200)
       }
+      expect(await dedupStore.get(`tenant:mppx:charge:${receipt.transactionHash}`)).not.toBeNull()
+      expect(await dedupStore.get(`mppx:charge:${receipt.transactionHash}`)).toBeNull()
 
       const response2 = await fetch(httpServer.url)
       expect(response2.status).toBe(402)
@@ -1616,6 +1620,7 @@ describe('tempo', () => {
             currency: asset,
             account: accounts[0],
             store: sponsoredStore,
+            storeKeyPrefix: 'tenant:',
           }),
         ],
         realm,
@@ -1661,6 +1666,16 @@ describe('tempo', () => {
 
       const first = fetch(httpServer.url, { headers: { Authorization: credential1 } })
       await simulationStarted
+      expect(
+        await sponsoredStore.get(
+          `tenant:mppx:charge:sponsor:${chain.id}:${accounts[1].address.toLowerCase()}`,
+        ),
+      ).not.toBeNull()
+      expect(
+        await sponsoredStore.get(
+          `mppx:charge:sponsor:${chain.id}:${accounts[1].address.toLowerCase()}`,
+        ),
+      ).toBeNull()
       const second = fetch(httpServer.url, { headers: { Authorization: credential2 } })
 
       try {
@@ -2870,6 +2885,7 @@ describe('tempo', () => {
 
     test('behavior: store keys proof replay protection by challenge ID', async () => {
       const replayStore = Store.memory()
+      const storeKeyPrefix = 'tenant:'
       const server_ = Mppx_server.create({
         methods: [
           tempo_server.charge({
@@ -2879,6 +2895,7 @@ describe('tempo', () => {
             currency: asset,
             account: accounts[0],
             store: replayStore,
+            storeKeyPrefix,
           }),
         ],
         realm,
@@ -2918,6 +2935,10 @@ describe('tempo', () => {
         headers: { Authorization: Credential.serialize(credential1) },
       })
       expect(response2.status).toBe(200)
+      expect(
+        await replayStore.get(`${storeKeyPrefix}mppx:charge:proof:${challenge1.id}`),
+      ).not.toBeNull()
+      expect(await replayStore.get(`mppx:charge:proof:${challenge1.id}`)).toBeNull()
 
       const response3 = await fetch(httpServer.url)
       expect(response3.status).toBe(402)
@@ -3633,6 +3654,75 @@ describe('tempo', () => {
       })
       expect(challenge.request.methodDetails?.supportedModes).toEqual(['pull'])
     })
+
+    test('challenge contains supportedModes from method defaults', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            currency: asset,
+            supportedModes: ['pull'],
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await handler.charge({ amount: '1' })(new Request('https://example.com'))
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.methodDetails?.supportedModes).toEqual(['pull'])
+    })
+
+    test('stable binding contains supportedModes', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        currency: asset,
+      })
+      const request = method.schema.request.parse({
+        amount: '1',
+        currency: asset,
+        decimals: 6,
+        supportedModes: ['pull'],
+      })
+
+      expect(method.stableBinding?.(request)).toMatchObject({
+        supportedModes: ['pull'],
+      })
+    })
+
+    test('challenge contains splits from method defaults', async () => {
+      const split = { amount: '0.2', recipient: accounts[2].address }
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            currency: asset,
+            splits: [split],
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await handler.charge({ amount: '1' })(new Request('https://example.com'))
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.methodDetails?.splits).toEqual([
+        { amount: '200000', recipient: split.recipient },
+      ])
+    })
   })
 
   describe('attribution memo', () => {

package/src/tempo/server/Charge.ts

@@ -63,11 +63,21 @@ export function charge<const parameters extends charge.Parameters>(
     feePayerPolicy,
     html,
     memo,
+    splits,
+    supportedModes,
     validateSender,
     waitForConfirmation = true,
   } = parameters
-  const store = (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>
-  const proofStore = parameters.store as Store.AtomicStore<charge.StoreItemMap> | undefined
+  const storeKeyPrefix = parameters.storeKeyPrefix ?? ''
+  const store = Store.from(
+    (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>,
+    { keyPrefix: storeKeyPrefix },
+  )
+  const proofStore = parameters.store
+    ? Store.from(parameters.store as Store.AtomicStore<charge.StoreItemMap>, {
+        keyPrefix: storeKeyPrefix,
+      })
+    : undefined
 
   const { recipient, feePayer, feePayerUrl } = Account.resolve(parameters)
 
@@ -88,8 +98,12 @@ export function charge<const parameters extends charge.Parameters>(
       externalId,
       memo,
       recipient,
+      splits,
+      supportedModes,
     } as unknown as Defaults,
 
+    stableBinding: chargeBinding,
+
     html: html
       ? {
           config: {},
@@ -539,6 +553,12 @@ export declare namespace charge {
      * memo binding, transaction success, and replay protection.
      */
     validateSender?: ValidateSender | undefined
+    /**
+     * Prefix prepended to charge replay-protection store keys.
+     *
+     * By default, no prefix is applied.
+     */
+    storeKeyPrefix?: string | undefined
     /**
      * Whether to wait for the charge transaction to confirm on-chain before
      * responding. @default true
@@ -565,6 +585,32 @@ export declare namespace charge {
   type FeePayerPolicy = Partial<FeePayer.Policy>
 }
 
+type ChargeRequest = z.output<typeof Methods.charge.schema.request>
+
+function chargeBinding(request: ChargeRequest) {
+  // Exhaustively destructure so new charge request fields require an explicit binding decision.
+  const { amount, currency, description, externalId, methodDetails, recipient, ...requestRest } =
+    request
+  requestRest satisfies Record<string, never>
+
+  const { chainId, feePayer, memo, splits, supportedModes, ...methodDetailsRest } =
+    methodDetails ?? {}
+  methodDetailsRest satisfies Record<string, never>
+  void feePayer
+
+  return {
+    amount,
+    chainId,
+    currency,
+    description,
+    externalId,
+    memo,
+    recipient,
+    splits,
+    supportedModes,
+  }
+}
+
 type ExpectedTransfer = {
   amount: string
   allowAnyMemo?: boolean | undefined

package/src/tempo/server/Session.test.ts

@@ -668,6 +668,36 @@ describe.runIf(isLocalnet)('session', () => {
       expect(ch!.highestVoucherAmount).toBe(2000000n)
     })
 
+    test('rejects voucher signed for route escrow instead of stored channel escrow', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+      await openServerChannel(server, channelId, serializedTransaction)
+
+      const routeEscrow = '0x0000000000000000000000000000000000000999' as Address
+      const signature = await signVoucher(
+        client,
+        payer,
+        { channelId, cumulativeAmount: 2000000n },
+        routeEscrow,
+        chain.id,
+      )
+
+      await expect(
+        server.verify({
+          credential: {
+            challenge: makeChallenge({ id: 'route-escrow-replay', channelId }),
+            payload: {
+              action: 'voucher' as const,
+              channelId,
+              cumulativeAmount: '2000000',
+              signature,
+            },
+          },
+          request: makeRequest({ escrowContract: routeEscrow }),
+        }),
+      ).rejects.toThrow(InvalidSignatureError)
+    })
+
     test('rejects non-increasing voucher replay', async () => {
       const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
       const server = createServer()

package/src/tempo/server/Session.ts

@@ -104,7 +104,9 @@ export function session<const parameters extends session.Parameters>(
 
   const lastOnChainVerified = new Map<Hex, number>()
 
-  const store = ChannelStore.fromStore(rawStore)
+  const store = ChannelStore.fromStore(
+    Store.from(rawStore, { keyPrefix: parameters.storeKeyPrefix }),
+  )
 
   const { account, recipient, feePayer, feePayerUrl } = Account.resolve(parameters)
 
@@ -139,7 +141,7 @@ export function session<const parameters extends session.Parameters>(
       unitType,
     } as unknown as Defaults,
 
-    transport: transport as never,
+    transport,
 
     // TODO: dedupe `{charge,session}.request`
     async request({ credential, request }) {
@@ -224,6 +226,7 @@ export function session<const parameters extends session.Parameters>(
             payload,
             methodDetails,
             resolvedFeePayer,
+            methodDetails.feePayer === true,
             feePayerPolicy,
             waitForConfirmation,
           )
@@ -238,6 +241,7 @@ export function session<const parameters extends session.Parameters>(
             payload,
             methodDetails,
             resolvedFeePayer,
+            methodDetails.feePayer === true,
             feePayerPolicy,
           )
           lastOnChainVerified.set(sessionReceipt.channelId, Date.now())
@@ -357,6 +361,12 @@ export declare namespace session {
      * local single-process usage.
      */
     store?: Store.AtomicStore | undefined
+    /**
+     * Prefix prepended to channel state store keys.
+     *
+     * By default, no prefix is applied.
+     */
+    storeKeyPrefix?: string | undefined
     /**
      * Enable SSE streaming.
      *
@@ -522,10 +532,8 @@ async function verifyAndAcceptVoucher(parameters: {
   channelId: Hex
   voucher: SignedVoucher
   onChain: OnChainChannel
-  methodDetails: SessionMethodDetails
 }): Promise<SessionReceipt> {
-  const { store, minVoucherDelta, challenge, channel, channelId, voucher, onChain, methodDetails } =
-    parameters
+  const { store, minVoucherDelta, challenge, channel, channelId, voucher, onChain } = parameters
 
   if (onChain.finalized) {
     throw new ChannelClosedError({ reason: 'channel is finalized on-chain' })
@@ -560,8 +568,8 @@ async function verifyAndAcceptVoucher(parameters: {
   }
 
   const isValid = await verifyVoucher(
-    methodDetails.escrowContract,
-    methodDetails.chainId,
+    channel.escrowContract,
+    channel.chainId,
     voucher,
     channel.authorizedSigner,
   )
@@ -627,6 +635,7 @@ async function handleOpen(
   payload: SessionCredentialPayload & { action: 'open' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
+  isSponsored: boolean,
   feePayerPolicy: session.FeePayerPolicy | undefined,
   waitForConfirmation: boolean,
 ): Promise<SessionReceipt> {
@@ -679,6 +688,7 @@ async function handleOpen(
     challengeExpires: challenge.expires,
     feePayerPolicy,
     feePayer,
+    isSponsored,
     beforeBroadcast: async (pendingOnChain) => {
       await validateOpenVoucher(pendingOnChain)
     },
@@ -764,6 +774,7 @@ async function handleTopUp(
   payload: SessionCredentialPayload & { action: 'topUp' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
+  isSponsored: boolean,
   feePayerPolicy: session.FeePayerPolicy | undefined,
 ): Promise<SessionReceipt> {
   const channelId = ChannelStore.normalizeChannelId(payload.channelId)
@@ -785,6 +796,7 @@ async function handleTopUp(
     challengeExpires: challenge.expires,
     feePayerPolicy,
     feePayer,
+    isSponsored,
   })
 
   const updated = await store.updateChannel(channelId, (current) => {
@@ -840,11 +852,7 @@ async function handleVoucher(
 
   const onChain = await (async () => {
     if (isStale) {
-      const onChainChannel = await getOnChainChannel(
-        client,
-        methodDetails.escrowContract,
-        channelId,
-      )
+      const onChainChannel = await getOnChainChannel(client, channel.escrowContract, channelId)
       lastOnChainVerified.set(channelId, Date.now())
       // Persist closeRequestedAt so the cached path detects force-close
       // between re-queries.
@@ -875,7 +883,6 @@ async function handleVoucher(
     channelId,
     voucher,
     onChain,
-    methodDetails,
   })
 }
 
@@ -902,7 +909,7 @@ async function handleClose(
 
   const voucher = parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature)
 
-  const onChain = await getOnChainChannel(client, methodDetails.escrowContract, channelId)
+  const onChain = await getOnChainChannel(client, channel.escrowContract, channelId)
 
   if (onChain.finalized) {
     throw new ChannelClosedError({ reason: 'channel is finalized on-chain' })
@@ -928,8 +935,8 @@ async function handleClose(
   }
 
   const isValid = await verifyVoucher(
-    methodDetails.escrowContract,
-    methodDetails.chainId,
+    channel.escrowContract,
+    channel.chainId,
     voucher,
     channel.authorizedSigner,
   )
@@ -964,7 +971,7 @@ async function handleClose(
       sender: account?.address ?? client.account?.address,
     })
 
-    txHash = await closeOnChain(client, methodDetails.escrowContract, voucher, {
+    txHash = await closeOnChain(client, channel.escrowContract, voucher, {
       ...(feePayer && account ? { feePayer, account } : { account }),
       candidateFeeTokens: [channel.token],
     })

package/src/tempo/server/Subscription.ts

@@ -72,7 +72,7 @@ export function subscription<const parameters extends subscription.Parameters>(
 
   const { recipient } = Account.resolve(parameters)
   const context = createContext(parameters, {
-    store: rawStore,
+    store: Store.from(rawStore, { keyPrefix: parameters.storeKeyPrefix }),
     options: {
       activationTimeoutMs: parameters.activationTimeoutMs,
       renewalTimeoutMs: parameters.renewalTimeoutMs,
@@ -1110,6 +1110,12 @@ export declare namespace subscription {
         subscription: SubscriptionRecord
       }) => Promise<RenewalResult>
       store?: Store.AtomicStore<Record<string, unknown>> | undefined
+      /**
+       * Prefix prepended to all subscription store keys.
+       *
+       * By default, no prefix is applied.
+       */
+      storeKeyPrefix?: string | undefined
       testnet?: boolean | undefined
       waitForConfirmation?: boolean | undefined
     } & Defaults