mppx 0.6.31 → 0.8.0

package/src/tempo/session/precompile/escrow.abi.ts

@@ -0,0 +1,226 @@
+const channelDescriptorComponents = [
+  { name: 'payer', type: 'address' },
+  { name: 'payee', type: 'address' },
+  { name: 'operator', type: 'address' },
+  { name: 'token', type: 'address' },
+  { name: 'salt', type: 'bytes32' },
+  { name: 'authorizedSigner', type: 'address' },
+  { name: 'expiringNonceHash', type: 'bytes32' },
+] as const
+
+const channelStateComponents = [
+  { name: 'settled', type: 'uint96' },
+  { name: 'deposit', type: 'uint96' },
+  { name: 'closeRequestedAt', type: 'uint32' },
+] as const
+
+const channelDescriptorInput = {
+  name: 'descriptor',
+  type: 'tuple',
+  components: channelDescriptorComponents,
+} as const
+
+/** ABI for the TIP-1034 TIP-20 Channel Escrow precompile. */
+export const escrowAbi = [
+  {
+    type: 'function',
+    name: 'CLOSE_GRACE_PERIOD',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ type: 'uint64' }],
+  },
+  {
+    type: 'function',
+    name: 'VOUCHER_TYPEHASH',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ type: 'bytes32' }],
+  },
+  {
+    type: 'function',
+    name: 'open',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'payee', type: 'address' },
+      { name: 'operator', type: 'address' },
+      { name: 'token', type: 'address' },
+      { name: 'deposit', type: 'uint96' },
+      { name: 'salt', type: 'bytes32' },
+      { name: 'authorizedSigner', type: 'address' },
+    ],
+    outputs: [{ name: 'channelId', type: 'bytes32' }],
+  },
+  {
+    type: 'function',
+    name: 'settle',
+    stateMutability: 'nonpayable',
+    inputs: [
+      channelDescriptorInput,
+      { name: 'cumulativeAmount', type: 'uint96' },
+      { name: 'signature', type: 'bytes' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'topUp',
+    stateMutability: 'nonpayable',
+    inputs: [channelDescriptorInput, { name: 'additionalDeposit', type: 'uint96' }],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'close',
+    stateMutability: 'nonpayable',
+    inputs: [
+      channelDescriptorInput,
+      { name: 'cumulativeAmount', type: 'uint96' },
+      { name: 'captureAmount', type: 'uint96' },
+      { name: 'signature', type: 'bytes' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'requestClose',
+    stateMutability: 'nonpayable',
+    inputs: [channelDescriptorInput],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'withdraw',
+    stateMutability: 'nonpayable',
+    inputs: [channelDescriptorInput],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'getChannel',
+    stateMutability: 'view',
+    inputs: [channelDescriptorInput],
+    outputs: [
+      {
+        type: 'tuple',
+        components: [
+          { name: 'descriptor', type: 'tuple', components: channelDescriptorComponents },
+          { name: 'state', type: 'tuple', components: channelStateComponents },
+        ],
+      },
+    ],
+  },
+  {
+    type: 'function',
+    name: 'getChannelState',
+    stateMutability: 'view',
+    inputs: [{ name: 'channelId', type: 'bytes32' }],
+    outputs: [{ type: 'tuple', components: channelStateComponents }],
+  },
+  {
+    type: 'function',
+    name: 'getChannelStatesBatch',
+    stateMutability: 'view',
+    inputs: [{ name: 'channelIds', type: 'bytes32[]' }],
+    outputs: [{ type: 'tuple[]', components: channelStateComponents }],
+  },
+  {
+    type: 'function',
+    name: 'computeChannelId',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'payer', type: 'address' },
+      { name: 'payee', type: 'address' },
+      { name: 'operator', type: 'address' },
+      { name: 'token', type: 'address' },
+      { name: 'salt', type: 'bytes32' },
+      { name: 'authorizedSigner', type: 'address' },
+      { name: 'expiringNonceHash', type: 'bytes32' },
+    ],
+    outputs: [{ type: 'bytes32' }],
+  },
+  {
+    type: 'function',
+    name: 'getVoucherDigest',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'channelId', type: 'bytes32' },
+      { name: 'cumulativeAmount', type: 'uint96' },
+    ],
+    outputs: [{ type: 'bytes32' }],
+  },
+  {
+    type: 'function',
+    name: 'domainSeparator',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ type: 'bytes32' }],
+  },
+  {
+    type: 'event',
+    name: 'ChannelOpened',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+      { name: 'operator', type: 'address' },
+      { name: 'token', type: 'address' },
+      { name: 'authorizedSigner', type: 'address' },
+      { name: 'salt', type: 'bytes32' },
+      { name: 'expiringNonceHash', type: 'bytes32' },
+      { name: 'deposit', type: 'uint96' },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'Settled',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+      { name: 'cumulativeAmount', type: 'uint96' },
+      { name: 'deltaPaid', type: 'uint96' },
+      { name: 'newSettled', type: 'uint96' },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'TopUp',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+      { name: 'additionalDeposit', type: 'uint96' },
+      { name: 'newDeposit', type: 'uint96' },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'CloseRequested',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+      { name: 'closeGraceEnd', type: 'uint256' },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'ChannelClosed',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+      { name: 'settledToPayee', type: 'uint96' },
+      { name: 'refundedToPayer', type: 'uint96' },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'CloseRequestCancelled',
+    inputs: [
+      { name: 'channelId', type: 'bytes32', indexed: true },
+      { name: 'payer', type: 'address', indexed: true },
+      { name: 'payee', type: 'address', indexed: true },
+    ],
+  },
+] as const

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
+}