mppx 0.6.31 → 0.7.0

package/src/tempo/Methods.test.ts

@@ -248,6 +248,51 @@ describe('session', () => {
     expect(request.amount).toBe('1000000')
     expect(request.methodDetails?.minVoucherDelta).toBe('100000')
   })
+
+  test('schema: preserves precompile session snapshots in method details', () => {
+    const sessionSnapshot = {
+      acceptedCumulative: '2',
+      channelId: `0x${'11'.repeat(32)}` as const,
+      deposit: '5',
+      descriptor: {
+        authorizedSigner: '0x0000000000000000000000000000000000000006',
+        expiringNonceHash: `0x${'22'.repeat(32)}` as const,
+        operator: '0x0000000000000000000000000000000000000000',
+        payee: '0x0000000000000000000000000000000000000002',
+        payer: '0x0000000000000000000000000000000000000001',
+        salt: `0x${'33'.repeat(32)}` as const,
+        token: '0x0000000000000000000000000000000000000003',
+      },
+      requiredCumulative: '3',
+      settled: '0',
+      spent: '2',
+      units: 2,
+    }
+    const request = Methods.session.schema.request.parse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      sessionSnapshot,
+      unitType: 'token',
+    })
+
+    expect(request.methodDetails?.sessionSnapshot).toEqual(sessionSnapshot)
+  })
+
+  test('schema: advertises precompile session operator in method details', () => {
+    const operator = '0x0000000000000000000000000000000000000006'
+    const request = Methods.session.schema.request.parse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      operator,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      unitType: 'token',
+    })
+
+    expect(request.methodDetails?.operator).toBe(operator)
+  })
 })
 
 describe('subscription', () => {
@@ -313,23 +358,6 @@ describe('subscription', () => {
     expect(request.periodCount).toBe(expected)
   })
 
-  test.each(['dev_second'] as const)(
-    'schema: accepts %s subscription periods for development and tests',
-    (periodUnit) => {
-      const request = Methods.subscription.schema.request.parse({
-        amount: '10',
-        currency: '0x20c0000000000000000000000000000000000001',
-        decimals: 6,
-        periodCount: '5',
-        periodUnit,
-        recipient: '0x1234567890abcdef1234567890abcdef12345678',
-        subscriptionExpires: '2026-01-01T00:00:00Z',
-      })
-
-      expect(request.periodUnit).toBe(periodUnit)
-    },
-  )
-
   test('schema: rejects non-numeric periodCount', () => {
     const result = Methods.subscription.schema.request.safeParse({
       amount: '10',

package/src/tempo/Methods.ts

@@ -1,8 +1,11 @@
 import type { Account, Address } from 'viem'
 import { parseUnits } from 'viem'
 
+import * as Constants from '../Constants.js'
 import * as Method from '../Method.js'
 import * as z from '../zod.js'
+import type { SessionSnapshot } from './session/client/Runtime.js'
+import type * as PrecompileChannel from './session/precompile/Channel.js'
 import type { SubscriptionPeriodUnit } from './subscription/Types.js'
 
 export const chargeModes = ['push', 'pull'] as const
@@ -196,6 +199,7 @@ export const session = Method.from({
           authorizedSigner: z.optional(z.string()),
           channelId: z.hash(),
           cumulativeAmount: z.amount(),
+          descriptor: z.optional(z.custom<PrecompileChannel.ChannelDescriptor>()),
           signature: z.signature(),
           transaction: z.signature(),
           type: z.literal('transaction'),
@@ -204,6 +208,7 @@ export const session = Method.from({
           action: z.literal('topUp'),
           additionalDeposit: z.amount(),
           channelId: z.hash(),
+          descriptor: z.optional(z.custom<PrecompileChannel.ChannelDescriptor>()),
           transaction: z.signature(),
           type: z.literal('transaction'),
         }),
@@ -211,12 +216,14 @@ export const session = Method.from({
           action: z.literal('voucher'),
           channelId: z.hash(),
           cumulativeAmount: z.amount(),
+          descriptor: z.optional(z.custom<PrecompileChannel.ChannelDescriptor>()),
           signature: z.signature(),
         }),
         z.object({
           action: z.literal('close'),
           channelId: z.hash(),
           cumulativeAmount: z.amount(),
+          descriptor: z.optional(z.custom<PrecompileChannel.ChannelDescriptor>()),
           signature: z.signature(),
         }),
       ]),
@@ -237,7 +244,12 @@ export const session = Method.from({
             ),
           ),
           minVoucherDelta: z.optional(z.amount()),
+          operator: z.optional(z.address()),
           recipient: z.optional(z.string()),
+          sessionProtocol: z.optional(
+            z.enum([Constants.SessionProtocols.v2, Constants.SessionProtocols.v1]),
+          ),
+          sessionSnapshot: z.optional(z.custom<SessionSnapshot>()),
           suggestedDeposit: z.optional(z.amount()),
           unitType: z.string(),
         })
@@ -256,6 +268,9 @@ export const session = Method.from({
           escrowContract,
           feePayer,
           minVoucherDelta,
+          operator,
+          sessionProtocol,
+          sessionSnapshot,
           suggestedDeposit,
           ...rest
         }) => ({
@@ -274,6 +289,13 @@ export const session = Method.from({
             }),
             ...(chainId !== undefined && { chainId }),
             ...(feePayer !== undefined && { feePayer }),
+            ...(operator !== undefined && { operator }),
+            ...(sessionProtocol !== undefined && {
+              [Constants.MethodDetailKeys.sessionProtocol]: sessionProtocol,
+            }),
+            ...(sessionSnapshot !== undefined && {
+              [Constants.MethodDetailKeys.sessionSnapshot]: sessionSnapshot,
+            }),
           },
         }),
       ),

package/src/tempo/PublicExports.test-d.ts

@@ -0,0 +1,105 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type {
+  PaymentResponse as ClientPaymentResponse,
+  SessionManager as ClientSessionManager,
+  SessionManagerSseOptions as ClientSessionManagerSseOptions,
+  SessionManagerWebSocketOptions as ClientSessionManagerWebSocketOptions,
+} from './client/index.js'
+import * as Tempo from './index.js'
+import type { SettlementSchedule as ServerSettlementSchedule } from './server/index.js'
+import type {
+  ActiveSessionState,
+  ClosedSessionState,
+  PaymentResponse as SessionPaymentResponse,
+  SessionManager,
+  SessionManagerSseOptions,
+  SessionManagerWebSocketOptions,
+  SessionTransition,
+  VoucherNeededSessionState,
+} from './session/client/index.js'
+import type { SessionTransition as MachineSessionTransition } from './session/client/index.js'
+import type { ChannelTransactionOptions } from './session/precompile/Chain.js'
+import type { RawAmountString } from './session/precompile/index.js'
+import type { SettlementSchedule as SessionSettlementSchedule } from './session/server/index.js'
+
+test('tempo session public barrels expose manager and schedule interfaces', () => {
+  expectTypeOf(Tempo.Session).toBeObject()
+  expectTypeOf(Tempo.Session.Client).toBeObject()
+  expectTypeOf(Tempo.Session.Precompile).toBeObject()
+  expectTypeOf(Tempo.Session.Server).toBeObject()
+  expectTypeOf<typeof Tempo>().not.toHaveProperty('Precompile')
+
+  expectTypeOf<ClientPaymentResponse>().toEqualTypeOf<SessionPaymentResponse>()
+  expectTypeOf<ClientSessionManager>().toEqualTypeOf<SessionManager>()
+  expectTypeOf<ClientSessionManagerSseOptions>().toEqualTypeOf<SessionManagerSseOptions>()
+  expectTypeOf<ClientSessionManagerWebSocketOptions>().toEqualTypeOf<SessionManagerWebSocketOptions>()
+
+  expectTypeOf<ServerSettlementSchedule>().toEqualTypeOf<SessionSettlementSchedule>()
+  expectTypeOf<MachineSessionTransition>().toEqualTypeOf<SessionTransition>()
+  expectTypeOf<ServerSettlementSchedule>().toEqualTypeOf<{
+    amount?: string | bigint | undefined
+    intervalMs?: number | undefined
+    units?: number | undefined
+  }>()
+  expectTypeOf<RawAmountString>().toEqualTypeOf<string>()
+  expectTypeOf<ActiveSessionState['status']>().toEqualTypeOf<'active'>()
+  expectTypeOf<VoucherNeededSessionState['status']>().toEqualTypeOf<'voucherNeeded'>()
+  expectTypeOf<ClosedSessionState['status']>().toEqualTypeOf<'closed'>()
+})
+
+test('tempo session chain exports canonical transaction options', () => {
+  expectTypeOf<ChannelTransactionOptions>().toEqualTypeOf<{
+    account?: import('viem').Account | undefined
+    candidateFeeTokens?: readonly import('viem').Address[] | undefined
+    feePayer?: import('viem').Account | undefined
+    feePayerPolicy?: Partial<import('./internal/fee-payer.js').Policy> | undefined
+    feeToken?: import('viem').Address | undefined
+  }>()
+})
+
+test('tempo session public barrel hides internal session drivers', () => {
+  type SessionNamespacePublic = typeof import('./session/index.js')
+  type SessionPublic = typeof import('./session/precompile/index.js')
+  type SessionClientPublic = typeof import('./session/client/index.js')
+  type SessionServerPublic = typeof import('./session/server/index.js')
+
+  expectTypeOf<SessionNamespacePublic>().toHaveProperty('Precompile')
+  expectTypeOf<SessionNamespacePublic>().toHaveProperty('Client')
+  expectTypeOf<SessionNamespacePublic>().toHaveProperty('Server')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('ChannelStore')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('Receipt')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('Sse')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('Types')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('Ws')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('session')
+  expectTypeOf<SessionNamespacePublic>().not.toHaveProperty('sessionManager')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('openSseSession')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('openWebSocketSession')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('Client')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('Server')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('session')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('sessionManager')
+  expectTypeOf<SessionPublic>().not.toHaveProperty('settle')
+  expectTypeOf<SessionClientPublic>().not.toHaveProperty('ChannelOps')
+  expectTypeOf<SessionClientPublic>().not.toHaveProperty('Chain')
+  expectTypeOf<SessionServerPublic>().not.toHaveProperty('ChannelOps')
+  expectTypeOf<SessionServerPublic>().not.toHaveProperty('Chain')
+})
+
+test('tempo legacy namespace keeps client, server, and channel primitives isolated', () => {
+  type LegacySessionPublic = typeof import('./legacy/session/index.js')
+
+  expectTypeOf(Tempo.SessionLegacy.Client.session).toBeFunction()
+  expectTypeOf(Tempo.SessionLegacy.Client.sessionManager).toBeFunction()
+  expectTypeOf(Tempo.SessionLegacy.Server.session).toBeFunction()
+  expectTypeOf(Tempo.SessionLegacy.Server.settle).toBeFunction()
+  expectTypeOf(Tempo.SessionLegacy.Session.Chain).toBeObject()
+  expectTypeOf(Tempo.SessionLegacy.Session.Channel).toBeObject()
+  expectTypeOf(Tempo.SessionLegacy.Session.Voucher).toBeObject()
+
+  expectTypeOf<LegacySessionPublic>().not.toHaveProperty('ChannelStore')
+  expectTypeOf<LegacySessionPublic>().not.toHaveProperty('Receipt')
+  expectTypeOf<LegacySessionPublic>().not.toHaveProperty('Sse')
+  expectTypeOf<LegacySessionPublic>().not.toHaveProperty('Ws')
+})

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

@@ -123,4 +123,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

@@ -51,9 +51,20 @@ export function charge(parameters: charge.Parameters = {}) {
     }),
 
     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.')
 
@@ -198,6 +209,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.

package/src/tempo/client/Methods.ts

@@ -1,8 +1,18 @@
+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.
  *
@@ -16,16 +26,18 @@ import { subscription as subscription_ } from './Subscription.js'
  * ```
  */
 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 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/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'