mppx 0.6.30 → 0.7.0

package/src/tempo/session/precompile/index.ts

@@ -0,0 +1,33 @@
+/** TIP-1034 on-chain read/write helpers and transaction verification utilities. */
+export * as Chain from './Chain.js'
+/** TIP-1034 channel ID and expiring-nonce hashing helpers. */
+export * as Channel from './Channel.js'
+/** Canonical TIP-1034 precompile constants. */
+export * as Constants from './Protocol.js'
+/** Backend-neutral protocol helpers, types, and wire encoders. */
+export * as Protocol from './Protocol.js'
+/** Backend-neutral session receipt header helpers. */
+export * as Receipt from './Protocol.js'
+/** Backend-neutral session credential, voucher, event, and receipt types. */
+export * as SessionTypes from './Protocol.js'
+/** Backend-neutral session SSE wire protocol helpers. */
+export * as SseProtocol from './Protocol.js'
+/** TIP-1034 credential, voucher, descriptor, and amount types. */
+export * as Types from './Protocol.js'
+/** Public TIP-1034 credential and descriptor types. */
+export type {
+  CloseCredentialPayload,
+  OpenCredentialPayload,
+  RawAmountString,
+  SessionCredentialPayload,
+  SessionDescriptor,
+  SignedVoucher,
+  TopUpCredentialPayload,
+  VoucherCredentialPayload,
+  Voucher as SessionVoucher,
+} from './Protocol.js'
+/** TIP-1034 voucher EIP-712 helpers. */
+export * as Voucher from './Voucher.js'
+/** Backend-neutral session WebSocket wire protocol helpers. */
+export * as WsProtocol from './Protocol.js'
+export { escrowAbi } from './escrow.abi.js'

package/src/tempo/session/server/ChannelOps.test.ts

@@ -0,0 +1,129 @@
+import { encodeFunctionData, type Address, type Hex } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import * as Channel from '../precompile/Channel.js'
+import { escrowAbi } from '../precompile/escrow.abi.js'
+import { tip20ChannelEscrow } from '../precompile/Protocol.js'
+import { descriptorFromOpen, parseOpenCall, parseTopUpCall } from './ChannelOps.js'
+
+const chainId = 4217
+const payer = '0x0000000000000000000000000000000000000001' as Address
+const payee = '0x0000000000000000000000000000000000000002' as Address
+const operator = '0x0000000000000000000000000000000000000000' as Address
+const token = '0x20C0000000000000000000000000000000000001' as Address
+const authorizedSigner = '0x0000000000000000000000000000000000000003' as Address
+const salt = `0x${'11'.repeat(32)}` as Hex
+const expiringNonceHash = `0x${'22'.repeat(32)}` as Hex
+
+const descriptor = {
+  authorizedSigner,
+  expiringNonceHash,
+  operator,
+  payee,
+  payer,
+  salt,
+  token,
+} satisfies Channel.ChannelDescriptor
+
+describe('ChannelOps', () => {
+  test('parseOpenCall decodes and validates TIP-1034 open calldata', () => {
+    const data = encodeFunctionData({
+      abi: escrowAbi,
+      functionName: 'open',
+      args: [payee, operator, token, 500n, salt, authorizedSigner],
+    })
+
+    expect(
+      parseOpenCall({
+        data,
+        expected: { authorizedSigner, deposit: 500n, operator, payee, token },
+      }),
+    ).toEqual({
+      authorizedSigner,
+      deposit: 500n,
+      operator,
+      payee,
+      salt,
+      token,
+    })
+  })
+
+  test('parseOpenCall rejects mismatched challenge fields', () => {
+    const data = encodeFunctionData({
+      abi: escrowAbi,
+      functionName: 'open',
+      args: [payee, operator, token, 500n, salt, authorizedSigner],
+    })
+
+    expect(() =>
+      parseOpenCall({
+        data,
+        expected: { token: '0x0000000000000000000000000000000000000004' },
+      }),
+    ).toThrow('TIP-1034 open token does not match challenge.')
+  })
+
+  test('parseTopUpCall decodes and validates descriptor-based top-up calldata', () => {
+    const data = encodeFunctionData({
+      abi: escrowAbi,
+      functionName: 'topUp',
+      args: [descriptor, 700n],
+    })
+
+    expect(
+      parseTopUpCall({
+        data,
+        expected: { additionalDeposit: 700n, descriptor },
+      }),
+    ).toEqual({
+      additionalDeposit: 700n,
+      descriptor,
+    })
+  })
+
+  test('parseTopUpCall rejects mismatched descriptors', () => {
+    const data = encodeFunctionData({
+      abi: escrowAbi,
+      functionName: 'topUp',
+      args: [descriptor, 700n],
+    })
+
+    expect(() =>
+      parseTopUpCall({
+        data,
+        expected: {
+          descriptor: {
+            ...descriptor,
+            payee: '0x0000000000000000000000000000000000000004',
+          },
+        },
+      }),
+    ).toThrow('TIP-1034 topUp descriptor does not match stored channel.')
+  })
+
+  test('descriptorFromOpen validates computed channel identity', () => {
+    const open = {
+      authorizedSigner,
+      deposit: 500n,
+      operator,
+      payee,
+      salt,
+      token,
+    }
+    const channelId = Channel.computeId({
+      ...descriptor,
+      chainId,
+      escrow: tip20ChannelEscrow,
+    })
+
+    expect(
+      descriptorFromOpen({
+        chainId,
+        channelId,
+        expiringNonceHash,
+        open,
+        payer,
+      }),
+    ).toEqual(descriptor)
+  })
+})

package/src/tempo/session/server/ChannelOps.ts

@@ -0,0 +1,157 @@
+import type { Address, Hex } from 'viem'
+import { decodeFunctionData, isAddressEqual } from 'viem'
+
+import * as Channel from '../precompile/Channel.js'
+import { escrowAbi } from '../precompile/escrow.abi.js'
+import { tip20ChannelEscrow } from '../precompile/Protocol.js'
+import type { Uint96 } from '../precompile/Protocol.js'
+import { uint96 } from '../precompile/Protocol.js'
+
+/** Optional expected values used to validate a TIP-1034 `open` calldata payload. */
+export type ParseOpenCallExpected = {
+  authorizedSigner?: Address | undefined
+  deposit?: Uint96 | undefined
+  operator?: Address | undefined
+  payee?: Address | undefined
+  token?: Address | undefined
+}
+
+/** Input for parsing and validating TIP-1034 `open` calldata. */
+export type ParseOpenCallParameters = {
+  data: Hex
+  expected?: ParseOpenCallExpected | undefined
+}
+
+/** Decoded and uint96-validated TIP-1034 `open` calldata fields. */
+export type ParsedOpenCall = {
+  authorizedSigner: Address
+  deposit: Uint96
+  operator: Address
+  payee: Address
+  salt: Hex
+  token: Address
+}
+
+/** Validates that calldata contains exactly one TIP-1034 approve-less `open` call. */
+export function parseOpenCall(parameters: ParseOpenCallParameters): ParsedOpenCall {
+  let decoded: ReturnType<typeof decodeFunctionData<typeof escrowAbi>>
+  try {
+    decoded = decodeFunctionData({ abi: escrowAbi, data: parameters.data })
+  } catch {
+    throw new Error('Expected TIP-1034 open calldata.')
+  }
+  if (decoded.functionName !== 'open') throw new Error('Expected TIP-1034 open calldata.')
+  const [payee, operator, token, deposit, salt, authorizedSigner] = decoded.args
+  const expected = parameters.expected
+  if (expected?.payee && !isAddressEqual(payee, expected.payee))
+    throw new Error('TIP-1034 open payee does not match challenge.')
+  if (expected?.operator && !isAddressEqual(operator, expected.operator))
+    throw new Error('TIP-1034 open operator does not match challenge.')
+  if (expected?.token && !isAddressEqual(token, expected.token))
+    throw new Error('TIP-1034 open token does not match challenge.')
+  if (expected?.authorizedSigner && !isAddressEqual(authorizedSigner, expected.authorizedSigner))
+    throw new Error('TIP-1034 open authorizedSigner does not match credential.')
+  const validatedDeposit = uint96(deposit)
+  if (expected?.deposit !== undefined && validatedDeposit !== expected.deposit)
+    throw new Error('TIP-1034 open deposit does not match challenge.')
+  return { payee, operator, token, deposit: validatedDeposit, salt, authorizedSigner }
+}
+
+/** Optional expected values used to validate a TIP-1034 `topUp` calldata payload. */
+export type ParseTopUpCallExpected = {
+  additionalDeposit?: Uint96 | undefined
+  descriptor?: Channel.ChannelDescriptor | undefined
+}
+
+/** Input for parsing and validating TIP-1034 `topUp` calldata. */
+export type ParseTopUpCallParameters = {
+  data: Hex
+  expected?: ParseTopUpCallExpected | undefined
+}
+
+/** Decoded and uint96-validated TIP-1034 `topUp` calldata fields. */
+export type ParsedTopUpCall = {
+  additionalDeposit: Uint96
+  descriptor: Channel.ChannelDescriptor
+}
+
+type ChannelDescriptorComparison = {
+  actual: Channel.ChannelDescriptor
+  expected: Channel.ChannelDescriptor
+}
+
+function isSameChannelDescriptor(parameters: ChannelDescriptorComparison): boolean {
+  const { actual, expected } = parameters
+  return (
+    isAddressEqual(actual.payer, expected.payer) &&
+    isAddressEqual(actual.payee, expected.payee) &&
+    isAddressEqual(actual.operator, expected.operator) &&
+    isAddressEqual(actual.token, expected.token) &&
+    isAddressEqual(actual.authorizedSigner, expected.authorizedSigner) &&
+    actual.salt.toLowerCase() === expected.salt.toLowerCase() &&
+    actual.expiringNonceHash.toLowerCase() === expected.expiringNonceHash.toLowerCase()
+  )
+}
+
+/** Validates that calldata contains exactly one TIP-1034 descriptor-based `topUp` call. */
+export function parseTopUpCall(parameters: ParseTopUpCallParameters): ParsedTopUpCall {
+  let decoded: ReturnType<typeof decodeFunctionData<typeof escrowAbi>>
+  try {
+    decoded = decodeFunctionData({ abi: escrowAbi, data: parameters.data })
+  } catch {
+    throw new Error('Expected TIP-1034 topUp calldata.')
+  }
+  if (decoded.functionName !== 'topUp') throw new Error('Expected TIP-1034 topUp calldata.')
+  const [descriptor, additionalDeposit] = decoded.args
+  const topUpDescriptor = descriptor as Channel.ChannelDescriptor
+  const expected = parameters.expected
+  if (expected?.descriptor) {
+    if (!isSameChannelDescriptor({ actual: topUpDescriptor, expected: expected.descriptor }))
+      throw new Error('TIP-1034 topUp descriptor does not match stored channel.')
+  }
+  const validatedAdditionalDeposit = uint96(additionalDeposit)
+  if (
+    expected?.additionalDeposit !== undefined &&
+    validatedAdditionalDeposit !== expected.additionalDeposit
+  )
+    throw new Error('TIP-1034 topUp deposit does not match credential.')
+  return {
+    descriptor: topUpDescriptor,
+    additionalDeposit: validatedAdditionalDeposit,
+  }
+}
+
+/** Input for deriving a TIP-1034 channel descriptor from an accepted open transaction. */
+export type DescriptorFromOpenParameters = {
+  chainId: number
+  channelId?: Hex | undefined
+  escrow?: Address | undefined
+  expiringNonceHash: Hex
+  open: ParsedOpenCall
+  payer: Address
+}
+
+/** Builds and validates a descriptor from an accepted open call and event expiring nonce hash. */
+export function descriptorFromOpen(
+  parameters: DescriptorFromOpenParameters,
+): Channel.ChannelDescriptor {
+  const descriptor = {
+    authorizedSigner: parameters.open.authorizedSigner,
+    expiringNonceHash: parameters.expiringNonceHash,
+    operator: parameters.open.operator,
+    payee: parameters.open.payee,
+    payer: parameters.payer,
+    salt: parameters.open.salt,
+    token: parameters.open.token,
+  } satisfies Channel.ChannelDescriptor
+  if (parameters.channelId) {
+    const computed = Channel.computeId({
+      ...descriptor,
+      chainId: parameters.chainId,
+      escrow: parameters.escrow ?? tip20ChannelEscrow,
+    })
+    if (computed.toLowerCase() !== parameters.channelId.toLowerCase())
+      throw new Error('TIP-1034 ChannelOpened channelId does not match descriptor.')
+  }
+  return descriptor
+}