mppx 0.6.30 → 0.7.0

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

@@ -20,6 +20,7 @@ import {
 } from 'viem'
 import { tempo as tempo_chain } from 'viem/tempo/chains'
 
+import * as Constants from '../../../Constants.js'
 import {
   AmountExceedsDepositError,
   BadRequestError,
@@ -29,18 +30,25 @@ import {
   InsufficientBalanceError,
   InvalidSignatureError,
   VerificationFailedError,
-} from '../../Errors.js'
-import type { Challenge, Credential } from '../../index.js'
-import type { LooseOmit, NoExtraKeys } from '../../internal/types.js'
-import * as Method from '../../Method.js'
-import * as Store from '../../Store.js'
-import * as Client from '../../viem/Client.js'
-import type * as z from '../../zod.js'
-import * as Account from '../internal/account.js'
-import * as defaults from '../internal/defaults.js'
-import * as FeePayer from '../internal/fee-payer.js'
-import type * as types from '../internal/types.js'
-import * as Methods from '../Methods.js'
+} from '../../../Errors.js'
+import type { Challenge, Credential } from '../../../index.js'
+import type { LooseOmit, NoExtraKeys } from '../../../internal/types.js'
+import * as Method from '../../../Method.js'
+import * as Store from '../../../Store.js'
+import * as Client from '../../../viem/Client.js'
+import type * as z from '../../../zod.js'
+import * as Account from '../../internal/account.js'
+import * as defaults from '../../internal/defaults.js'
+import * as FeePayer from '../../internal/fee-payer.js'
+import type * as types from '../../internal/types.js'
+import * as Methods from '../../Methods.js'
+import {
+  captureRequestBodyProbe,
+  isSessionContentRequest,
+} from '../../server/internal/request-body.js'
+import * as Transport from '../../server/internal/transport.js'
+import { createSessionReceipt } from '../../session/precompile/Protocol.js'
+import type { SessionReceipt } from '../../session/precompile/Protocol.js'
 import {
   broadcastOpenTransaction,
   broadcastTopUpTransaction,
@@ -50,11 +58,8 @@ import {
   settleOnChain,
 } from '../session/Chain.js'
 import * as ChannelStore from '../session/ChannelStore.js'
-import { createSessionReceipt } from '../session/Receipt.js'
-import type { SessionCredentialPayload, SessionReceipt, SignedVoucher } from '../session/Types.js'
+import type { LegacySessionCredentialPayload, LegacySignedVoucher } from '../session/Types.js'
 import { parseVoucherFromPayload, verifyVoucher } from '../session/Voucher.js'
-import { captureRequestBodyProbe, isSessionContentRequest } from './internal/request-body.js'
-import * as Transport from './internal/transport.js'
 
 /** Challenge methodDetails shape for session methods. */
 type SessionMethodDetails = {
@@ -63,6 +68,7 @@ type SessionMethodDetails = {
   channelId?: Hex | undefined
   minVoucherDelta?: string | undefined
   feePayer?: boolean | undefined
+  sessionProtocol?: Constants.SessionProtocol | undefined
 }
 
 /**
@@ -183,11 +189,13 @@ export function session<const parameters extends session.Parameters>(
         chainId,
         escrowContract: resolvedEscrow,
         feePayer: resolvedFeePayer,
+        sessionProtocol: Constants.SessionProtocols.v1,
       }
     },
 
     async verify({ credential, envelope, request }) {
-      const { challenge, payload } = credential as Credential.Credential<SessionCredentialPayload>
+      const { challenge, payload } =
+        credential as Credential.Credential<LegacySessionCredentialPayload>
 
       const resolvedRequest = (() => {
         const parsed = Methods.session.schema.request.safeParse(request)
@@ -285,7 +293,8 @@ export function session<const parameters extends session.Parameters>(
       if (
         envelope &&
         isSessionContentRequest(envelope.capturedRequest) &&
-        (payload.action === 'open' || payload.action === 'voucher')
+        (payload.action === 'open' ||
+          (payload.action === 'voucher' && !isSseNegotiationRequest(envelope.capturedRequest)))
       ) {
         const charged = await charge(
           store,
@@ -314,18 +323,25 @@ export function session<const parameters extends session.Parameters>(
     // during verification. Non-billable requests are treated as management
     // updates; billable requests fall through to the application handler.
     respond({ credential, envelope, input }) {
-      const { payload } = credential as Credential.Credential<SessionCredentialPayload>
+      const { payload } = credential as Credential.Credential<LegacySessionCredentialPayload>
+      const request = envelope?.capturedRequest ?? captureRequestBodyProbe(input)
 
       if (payload.action === 'close') return new Response(null, { status: 204 })
       if (payload.action === 'topUp') return new Response(null, { status: 204 })
+      if (parameters.sse && payload.action === 'voucher' && isSseNegotiationRequest(request))
+        return new Response(null, { status: 204 })
 
-      const request = envelope?.capturedRequest ?? captureRequestBodyProbe(input)
       if (isSessionContentRequest(request)) return undefined
       return new Response(null, { status: 204 })
     },
   })
 }
 
+function isSseNegotiationRequest(input: Pick<Method.CapturedRequest, 'headers'>): boolean {
+  return input.headers.get('Accept')?.includes('text/event-stream') ?? false
+}
+
+/** Type helpers for the legacy contract-backed session server method. */
 export declare namespace session {
   type Defaults = LooseOmit<
     Method.RequestDefaults<typeof Methods.session>,
@@ -530,7 +546,7 @@ async function verifyAndAcceptVoucher(parameters: {
   challenge: Challenge.Challenge
   channel: ChannelStore.State
   channelId: Hex
-  voucher: SignedVoucher
+  voucher: LegacySignedVoucher
   onChain: OnChainChannel
 }): Promise<SessionReceipt> {
   const { store, minVoucherDelta, challenge, channel, channelId, voucher, onChain } = parameters
@@ -553,7 +569,7 @@ async function verifyAndAcceptVoucher(parameters: {
 
   if (voucher.cumulativeAmount <= onChain.settled) {
     throw new VerificationFailedError({
-      reason: 'voucher cumulativeAmount is below on-chain settled amount',
+      reason: 'voucher cumulativeAmount is at or below on-chain settled amount',
     })
   }
 
@@ -561,12 +577,6 @@ async function verifyAndAcceptVoucher(parameters: {
     throw new AmountExceedsDepositError({ reason: 'voucher amount exceeds on-chain deposit' })
   }
 
-  if (voucher.cumulativeAmount < channel.highestVoucherAmount) {
-    throw new VerificationFailedError({
-      reason: 'voucher cumulativeAmount must be strictly greater than highest accepted voucher',
-    })
-  }
-
   const isValid = await verifyVoucher(
     channel.escrowContract,
     channel.chainId,
@@ -578,9 +588,11 @@ async function verifyAndAcceptVoucher(parameters: {
     throw new InvalidSignatureError({ reason: 'invalid voucher signature' })
   }
 
-  // Idempotent replay: equal cumulative voucher is accepted without
-  // advancing channel state or charging additional value.
-  if (voucher.cumulativeAmount === channel.highestVoucherAmount) {
+  // Idempotent replay: a non-advancing voucher (at or below the highest
+  // accepted amount, but above the on-chain settled amount checked above)
+  // returns 200 OK with the current highest amount without advancing state,
+  // per the session spec's idempotency requirement.
+  if (voucher.cumulativeAmount <= channel.highestVoucherAmount) {
     return createSessionReceipt({
       challengeId: challenge.id,
       channelId,
@@ -632,7 +644,7 @@ async function handleOpen(
   store: ChannelStore.ChannelStore,
   client: viem_Client,
   challenge: Challenge.Challenge,
-  payload: SessionCredentialPayload & { action: 'open' },
+  payload: LegacySessionCredentialPayload & { action: 'open' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
   isSponsored: boolean,
@@ -660,7 +672,7 @@ async function handleOpen(
 
     if (voucher.cumulativeAmount <= onChain.settled) {
       throw new VerificationFailedError({
-        reason: 'voucher cumulativeAmount is below on-chain settled amount',
+        reason: 'voucher cumulativeAmount is at or below on-chain settled amount',
       })
     }
 
@@ -701,7 +713,7 @@ async function handleOpen(
     if (existing) {
       if (voucher.cumulativeAmount <= existing.settledOnChain) {
         throw new VerificationFailedError({
-          reason: 'voucher amount is below settled on-chain amount',
+          reason: 'voucher amount is at or below settled on-chain amount',
         })
       }
 
@@ -771,7 +783,7 @@ async function handleTopUp(
   store: ChannelStore.ChannelStore,
   client: viem_Client,
   challenge: Challenge.Challenge,
-  payload: SessionCredentialPayload & { action: 'topUp' },
+  payload: LegacySessionCredentialPayload & { action: 'topUp' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
   isSponsored: boolean,
@@ -821,7 +833,7 @@ async function handleVoucher(
   client: viem_Client,
   minVoucherDelta: bigint,
   challenge: Challenge.Challenge,
-  payload: SessionCredentialPayload & { action: 'voucher' },
+  payload: LegacySessionCredentialPayload & { action: 'voucher' },
   methodDetails: SessionMethodDetails,
   channelStateTtl: number,
   lastOnChainVerified: Map<Hex, number>,
@@ -893,7 +905,7 @@ async function handleClose(
   store: ChannelStore.ChannelStore,
   client: viem_Client,
   challenge: Challenge.Challenge,
-  payload: SessionCredentialPayload & { action: 'close' },
+  payload: LegacySessionCredentialPayload & { action: 'close' },
   methodDetails: SessionMethodDetails,
   account?: viem_Account,
   feePayer?: viem_Account,

package/src/tempo/legacy/server/index.ts

@@ -0,0 +1,4 @@
+/** Legacy contract-backed session server method. */
+export { session } from './Session.js'
+/** Legacy contract-backed one-shot settle helper. */
+export { settle } from './Session.js'

package/src/tempo/{session → legacy/session}/Chain.test.ts

@@ -10,7 +10,7 @@ import {
 import { prepareTransactionRequest, signTransaction, waitForTransactionReceipt } from 'viem/actions'
 import { Addresses, Transaction } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
-import { nodeEnv } from '~test/config.js'
+import { tempoNetwork } from '~test/config.js'
 import {
   closeChannelOnChain,
   deployEscrow,
@@ -18,7 +18,7 @@ import {
   signOpenChannel,
   signTopUpChannel,
   topUpChannel,
-} from '~test/tempo/session.js'
+} from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 
 import {
@@ -33,9 +33,8 @@ import {
 import * as Channel from './Channel.js'
 import { signVoucher } from './Voucher.js'
 
-const isLocalnet = nodeEnv === 'localnet'
-
 const UINT128_MAX = 2n ** 128n - 1n
+const isLocalnet = tempoNetwork === 'localnet'
 
 describe('assertUint128 (via settleOnChain / closeOnChain)', () => {
   const mockClient = { chain: { id: 42431 } } as any

package/src/tempo/{session → legacy/session}/Chain.ts

@@ -20,23 +20,28 @@ import {
 } from 'viem/actions'
 import { Transaction } from 'viem/tempo'
 
-import { BadRequestError, ChannelClosedError, VerificationFailedError } from '../../Errors.js'
-import * as TempoAddress from '../internal/address.js'
-import * as defaults from '../internal/defaults.js'
-import * as FeePayer from '../internal/fee-payer.js'
-import { resolveFeeToken } from '../internal/fee-token.js'
+import { BadRequestError, ChannelClosedError, VerificationFailedError } from '../../../Errors.js'
+import * as TempoAddress from '../../internal/address.js'
+import * as defaults from '../../internal/defaults.js'
+import * as FeePayer from '../../internal/fee-payer.js'
+import { resolveFeeToken } from '../../internal/fee-token.js'
 import * as Channel from './Channel.js'
 import { escrowAbi } from './escrow.abi.js'
-import type { SignedVoucher } from './Types.js'
+import type { LegacySignedVoucher } from './Types.js'
 
 export { escrowAbi }
 
+type SenderSignedTransaction = {
+  from?: Address | undefined
+  signature?: unknown
+}
+
 /**
  * Asserts that a deserialized transaction has an existing sender signature —
  * required before fee payer co-signing to prevent the fee payer from becoming
  * the sender.
  */
-function assertSenderSigned(transaction: any): void {
+function assertSenderSigned(transaction: SenderSignedTransaction): void {
   if (!transaction.signature || !transaction.from)
     throw new BadRequestError({
       reason: 'Transaction must be signed by the sender before fee payer co-signing',
@@ -109,7 +114,7 @@ export type SettleOptions =
 export async function settleOnChain(
   client: Client,
   escrowContract: Address,
-  voucher: SignedVoucher,
+  voucher: LegacySignedVoucher,
   options?: SettleOptions,
 ): Promise<Hex> {
   assertUint128(voucher.cumulativeAmount)
@@ -160,7 +165,7 @@ export type CloseOptions =
 export async function closeOnChain(
   client: Client,
   escrowContract: Address,
-  voucher: SignedVoucher,
+  voucher: LegacySignedVoucher,
   options?: CloseOptions,
 ): Promise<Hex> {
   assertUint128(voucher.cumulativeAmount)
@@ -298,11 +303,75 @@ const erc20ApproveSelector = /*#__PURE__*/ toFunctionSelector(
   'function approve(address spender, uint256 amount)',
 )
 
+/** Result returned after a legacy open transaction is broadcast or recovered from on-chain state. */
 export type BroadcastResult = {
   txHash: Hex | undefined
   onChain: OnChainChannel
 }
 
+/** Inputs for validating an ERC-20 approve call inside a fee-sponsored legacy channel transaction. */
+type SponsoredApproveCallParameters = {
+  action: 'open' | 'topUp'
+  call: TempoCall
+  currency: Address
+  escrowContract: Address
+  expectedAmount: bigint
+}
+
+/** Inputs for extracting the escrow open call from a fee-sponsored legacy channel transaction. */
+type SponsoredOpenCallsParameters = {
+  calls: readonly TempoCall[]
+  currency: Address
+  deposit: bigint
+  escrowContract: Address
+}
+
+/** Inputs for extracting the escrow top-up call from a fee-sponsored legacy channel transaction. */
+type SponsoredTopUpCallsParameters = {
+  calls: readonly TempoCall[]
+  currency: Address
+  escrowContract: Address
+  topUpAmount: bigint
+}
+
+/** Inputs for broadcasting and validating a legacy contract-backed open transaction. */
+export type BroadcastOpenTransactionParameters = {
+  beforeBroadcast?: ((onChain: OnChainChannel) => Promise<void> | void) | undefined
+  challengeExpires?: string | undefined
+  channelId: Hex
+  client: Client
+  currency: Address
+  escrowContract: Address
+  feePayer?: Account | undefined
+  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
+  isSponsored?: boolean | undefined
+  recipient: Address
+  serializedTransaction: Hex
+  /** When false, simulates instead of waiting for confirmation and returns derived on-chain state. @default true */
+  waitForConfirmation?: boolean | undefined
+}
+
+/** Inputs for broadcasting and validating a legacy contract-backed top-up transaction. */
+export type BroadcastTopUpTransactionParameters = {
+  challengeExpires?: string | undefined
+  channelId: Hex
+  client: Client
+  currency: Address
+  declaredDeposit: bigint
+  escrowContract: Address
+  feePayer?: Account | undefined
+  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
+  isSponsored?: boolean | undefined
+  previousDeposit: bigint
+  serializedTransaction: Hex
+}
+
+/** Result returned after a legacy top-up transaction is broadcast and verified. */
+export type BroadcastTopUpTransactionResult = {
+  newDeposit: bigint
+  txHash: Hex
+}
+
 type TempoCall = NonNullable<ReturnType<(typeof Transaction)['deserialize']>['calls']>[number]
 
 function assertCallHasTargetAndData(call: TempoCall): { to: Address; data: Hex } {
@@ -314,13 +383,7 @@ function assertCallHasTargetAndData(call: TempoCall): { to: Address; data: Hex }
   return { to: call.to, data: call.data }
 }
 
-function validateSponsoredApproveCall(parameters: {
-  action: 'open' | 'topUp'
-  call: TempoCall
-  currency: Address
-  escrowContract: Address
-  expectedAmount: bigint
-}) {
+function validateSponsoredApproveCall(parameters: SponsoredApproveCallParameters) {
   const { action, call, currency, escrowContract, expectedAmount } = parameters
   const { to, data } = assertCallHasTargetAndData(call)
 
@@ -346,12 +409,7 @@ function validateSponsoredApproveCall(parameters: {
   }
 }
 
-function validateSponsoredOpenCalls(parameters: {
-  calls: readonly TempoCall[]
-  currency: Address
-  escrowContract: Address
-  deposit: bigint
-}) {
+function validateSponsoredOpenCalls(parameters: SponsoredOpenCallsParameters) {
   const { calls, currency, escrowContract, deposit } = parameters
 
   let openCall: TempoCall | undefined
@@ -401,12 +459,7 @@ function validateSponsoredOpenCalls(parameters: {
   return openCall
 }
 
-function validateSponsoredTopUpCalls(parameters: {
-  calls: readonly TempoCall[]
-  currency: Address
-  escrowContract: Address
-  topUpAmount: bigint
-}) {
+function validateSponsoredTopUpCalls(parameters: SponsoredTopUpCallsParameters) {
   const { calls, currency, escrowContract, topUpAmount } = parameters
 
   let topUpCall: TempoCall | undefined
@@ -456,21 +509,9 @@ function validateSponsoredTopUpCalls(parameters: {
   return topUpCall
 }
 
-export async function broadcastOpenTransaction(parameters: {
-  client: Client
-  serializedTransaction: Hex
-  escrowContract: Address
-  channelId: Hex
-  recipient: Address
-  currency: Address
-  challengeExpires?: string | undefined
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  feePayer?: Account | undefined
-  isSponsored?: boolean | undefined
-  beforeBroadcast?: ((onChain: OnChainChannel) => Promise<void> | void) | undefined
-  /** When false, simulates instead of waiting for confirmation and returns derived on-chain state. @default true */
-  waitForConfirmation?: boolean | undefined
-}): Promise<BroadcastResult> {
+export async function broadcastOpenTransaction(
+  parameters: BroadcastOpenTransactionParameters,
+): Promise<BroadcastResult> {
   const {
     client,
     serializedTransaction,
@@ -569,8 +610,8 @@ export async function broadcastOpenTransaction(parameters: {
       reason: 'open transaction does not match claimed channelId',
     })
 
-  const resolvedFeeToken =
-    transaction.feeToken ?? defaults.currency[client.chain?.id as keyof typeof defaults.currency]
+  const defaultFeeToken = defaults.currency[client.chain?.id as keyof typeof defaults.currency]
+  const resolvedFeeToken = transaction.feeToken ?? defaultFeeToken
 
   const pendingOnChain = {
     finalized: false,
@@ -594,10 +635,10 @@ export async function broadcastOpenTransaction(parameters: {
 
       const sponsored = FeePayer.prepareSponsoredTransaction({
         account: feePayer,
+        allowedFeeTokens: defaultFeeToken ? [defaultFeeToken] : undefined,
         challengeExpires,
         chainId: client.chain!.id,
         details: { channelId, currency, recipient },
-        expectedFeeToken: defaults.currency[client.chain?.id as keyof typeof defaults.currency],
         policy: feePayerPolicy,
         transaction: {
           ...transaction,
@@ -660,19 +701,9 @@ export async function broadcastOpenTransaction(parameters: {
   return { txHash, onChain }
 }
 
-export async function broadcastTopUpTransaction(parameters: {
-  client: Client
-  serializedTransaction: Hex
-  escrowContract: Address
-  channelId: Hex
-  currency: Address
-  declaredDeposit: bigint
-  previousDeposit: bigint
-  challengeExpires?: string | undefined
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  feePayer?: Account | undefined
-  isSponsored?: boolean | undefined
-}): Promise<{ txHash: Hex; newDeposit: bigint }> {
+export async function broadcastTopUpTransaction(
+  parameters: BroadcastTopUpTransactionParameters,
+): Promise<BroadcastTopUpTransactionResult> {
   const {
     client,
     serializedTransaction,
@@ -743,9 +774,10 @@ export async function broadcastTopUpTransaction(parameters: {
           reason: 'transaction does not contain a valid escrow topUp call',
         })
 
-      const expectedFeeToken = defaults.currency[client.chain?.id as keyof typeof defaults.currency]
+      const defaultFeeToken = defaults.currency[client.chain?.id as keyof typeof defaults.currency]
       const sponsored = FeePayer.prepareSponsoredTransaction({
         account: feePayer,
+        allowedFeeTokens: defaultFeeToken ? [defaultFeeToken] : undefined,
         challengeExpires,
         chainId: client.chain!.id,
         details: {
@@ -753,12 +785,11 @@ export async function broadcastTopUpTransaction(parameters: {
           channelId,
           currency,
         },
-        expectedFeeToken,
         policy: feePayerPolicy,
         transaction: {
           ...transaction,
-          ...((transaction.feeToken ?? expectedFeeToken)
-            ? { feeToken: transaction.feeToken ?? expectedFeeToken }
+          ...((transaction.feeToken ?? defaultFeeToken)
+            ? { feeToken: transaction.feeToken ?? defaultFeeToken }
             : {}),
         },
       })

package/src/tempo/{session → legacy/session}/Channel.ts

@@ -30,6 +30,7 @@ export function computeId(parameters: computeId.Parameters): Hex.Hex {
   return Hash.keccak256(encoded)
 }
 
+/** Type helpers for {@link computeId}. */
 export declare namespace computeId {
   type Parameters = {
     /** Address authorized to sign vouchers on behalf of the payer. */

package/src/tempo/legacy/session/ChannelStore.test.ts

@@ -0,0 +1,58 @@
+import type { Address, Hex } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import * as Store from '../../../Store.js'
+import { chainId, escrowContract as escrowContractDefaults } from '../../internal/defaults.js'
+import * as ChannelStore from './ChannelStore.js'
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+
+function legacyChannel(
+  overrides: Partial<ChannelStore.LegacyState> = {},
+): ChannelStore.LegacyState {
+  return {
+    channelId,
+    payer: '0x0000000000000000000000000000000000000001' as Address,
+    payee: '0x0000000000000000000000000000000000000002' as Address,
+    token: '0x0000000000000000000000000000000000000003' as Address,
+    authorizedSigner: '0x0000000000000000000000000000000000000004' as Address,
+    chainId: 42431,
+    escrowContract: escrowContractDefaults[chainId.testnet] as Address,
+    deposit: 10_000_000n,
+    settledOnChain: 0n,
+    highestVoucherAmount: 10_000_000n,
+    highestVoucher: null,
+    spent: 0n,
+    units: 0,
+    closeRequestedAt: 0n,
+    finalized: false,
+    createdAt: '2025-01-01T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+describe('legacy ChannelStore', () => {
+  test('keeps existing contract-backed channels compatible when backend fields are absent', async () => {
+    const store = ChannelStore.fromStore(Store.memory())
+    await store.updateChannel(channelId, () => legacyChannel())
+
+    const loaded = await store.getChannel(channelId)
+    expect(loaded).not.toBeNull()
+    expect(ChannelStore.isContractState(loaded!)).toBe(true)
+    expect(loaded!.backend).toBeUndefined()
+    expect('operator' in loaded!).toBe(false)
+    expect('salt' in loaded!).toBe(false)
+    expect('expiringNonceHash' in loaded!).toBe(false)
+    expect('descriptor' in loaded!).toBe(false)
+  })
+
+  test('supports explicit contract-backed channel state', async () => {
+    const store = ChannelStore.fromStore(Store.memory())
+    await store.updateChannel(channelId, () => legacyChannel({ backend: 'contract' }))
+
+    const loaded = await store.getChannel(channelId)
+    expect(loaded).not.toBeNull()
+    expect(ChannelStore.isContractState(loaded!)).toBe(true)
+    expect(loaded!.backend).toBe('contract')
+  })
+})

package/src/tempo/legacy/session/ChannelStore.ts

@@ -0,0 +1,39 @@
+/**
+ * Legacy contract-backed session channel-store facade.
+ *
+ * Legacy code imports channel-store types and helpers from this module so the
+ * contract-backed backend stays rooted under `tempo/legacy`. The underlying
+ * store adapter is shared with the TIP-1034 implementation because both
+ * backends persist the same accounting counters.
+ */
+import type * as SharedChannelStore from '../../session/server/ChannelStore.js'
+
+export {
+  deductFromChannel,
+  fromStore,
+  normalizeChannelId,
+  type BackendState,
+  type BaseState,
+  type ChannelStore,
+  type DeductResult,
+  type State,
+} from '../../session/server/ChannelStore.js'
+
+/** State for a legacy smart-contract-backed payment channel. */
+export interface LegacyContractBackendState {
+  /** Channel backend. Omitted for existing legacy records. */
+  backend?: 'contract' | undefined
+}
+
+/** @deprecated Use {@link LegacyContractBackendState}. */
+export type ContractBackendState = LegacyContractBackendState
+
+/** Legacy contract-backed channel state persisted by `tempo.sessionLegacy`. */
+export type LegacyState = SharedChannelStore.BaseState & LegacyContractBackendState
+
+/** Returns whether a channel is backed by the legacy smart contract escrow. */
+export function isContractState(
+  state: SharedChannelStore.State,
+): state is SharedChannelStore.BaseState & LegacyContractBackendState {
+  return state.backend === undefined || state.backend === 'contract'
+}