mppx 0.6.31 → 0.7.0

package/src/tempo/session/precompile/Channel.test.ts

@@ -0,0 +1,138 @@
+import { AbiParameters, Hash } from 'ox'
+import { describe, expect, test } from 'vp/test'
+
+import * as Channel from './Channel.js'
+import { tip20ChannelEscrow } from './Protocol.js'
+
+const descriptor = {
+  payer: '0x1111111111111111111111111111111111111111',
+  payee: '0x2222222222222222222222222222222222222222',
+  operator: '0x3333333333333333333333333333333333333333',
+  token: '0x4444444444444444444444444444444444444444',
+  salt: '0x0000000000000000000000000000000000000000000000000000000000000001',
+  authorizedSigner: '0x5555555555555555555555555555555555555555',
+  expiringNonceHash: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+} as const satisfies Channel.ChannelDescriptor
+
+const chainId = 42431
+const transaction = {
+  chainId,
+  calls: [],
+  feePayerSignature: {
+    r: `0x${'01'.repeat(32)}`,
+    s: `0x${'02'.repeat(32)}`,
+    yParity: 0,
+  },
+  nonce: 1,
+} as const satisfies Channel.ExpiringNonceTransaction
+
+describe('precompile Channel.computeId', () => {
+  test('returns deterministic 32-byte hash for fixed inputs', () => {
+    const id = Channel.computeId({ ...descriptor, chainId })
+    expect(Channel.computeId({ ...descriptor, chainId })).toBe(id)
+    expect(id).toMatch(/^0x[0-9a-f]{64}$/)
+  })
+
+  test('matches manual keccak256(abi.encode(...))', () => {
+    const encoded = AbiParameters.encode(
+      AbiParameters.from([
+        'address payer',
+        'address payee',
+        'address operator',
+        'address token',
+        'bytes32 salt',
+        'address authorizedSigner',
+        'bytes32 expiringNonceHash',
+        'address escrow',
+        'uint256 chainId',
+      ]),
+      [
+        descriptor.payer,
+        descriptor.payee,
+        descriptor.operator,
+        descriptor.token,
+        descriptor.salt,
+        descriptor.authorizedSigner,
+        descriptor.expiringNonceHash,
+        tip20ChannelEscrow,
+        BigInt(chainId),
+      ],
+    )
+    expect(Channel.computeId({ ...descriptor, chainId })).toBe(Hash.keccak256(encoded))
+  })
+
+  test.each([
+    ['payer', '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'],
+    ['payee', '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
+    ['operator', '0xcccccccccccccccccccccccccccccccccccccccc'],
+    ['token', '0xdddddddddddddddddddddddddddddddddddddddd'],
+    ['salt', '0x0000000000000000000000000000000000000000000000000000000000000002'],
+    ['authorizedSigner', '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'],
+    ['expiringNonceHash', '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
+  ] as const)('changes when %s changes', (key, value) => {
+    expect(Channel.computeId({ ...descriptor, [key]: value, chainId })).not.toBe(
+      Channel.computeId({ ...descriptor, chainId }),
+    )
+  })
+
+  test('changes when escrow or chainId changes', () => {
+    expect(
+      Channel.computeId({
+        ...descriptor,
+        chainId,
+        escrow: '0xffffffffffffffffffffffffffffffffffffffff',
+      }),
+    ).not.toBe(Channel.computeId({ ...descriptor, chainId }))
+    expect(Channel.computeId({ ...descriptor, chainId: 1 })).not.toBe(
+      Channel.computeId({ ...descriptor, chainId }),
+    )
+  })
+
+  test('encodes chainId as uint256', () => {
+    const largeChainId = 2 ** 32
+    const id = Channel.computeId({ ...descriptor, chainId: largeChainId })
+    const encoded = AbiParameters.encode(
+      AbiParameters.from([
+        'address payer',
+        'address payee',
+        'address operator',
+        'address token',
+        'bytes32 salt',
+        'address authorizedSigner',
+        'bytes32 expiringNonceHash',
+        'address escrow',
+        'uint256 chainId',
+      ]),
+      [
+        descriptor.payer,
+        descriptor.payee,
+        descriptor.operator,
+        descriptor.token,
+        descriptor.salt,
+        descriptor.authorizedSigner,
+        descriptor.expiringNonceHash,
+        tip20ChannelEscrow,
+        BigInt(largeChainId),
+      ],
+    )
+    expect(id).toBe(Hash.keccak256(encoded))
+  })
+})
+
+describe('precompile Channel.transactionForExpiringNonceHash', () => {
+  test('returns transaction unchanged when no fee payer is used', () => {
+    expect(Channel.transactionForExpiringNonceHash({ transaction })).toBe(transaction)
+  })
+
+  test('strips fee-payer signature from the hash preimage transaction', () => {
+    expect(
+      Channel.transactionForExpiringNonceHash({
+        feePayer: true,
+        transaction,
+      }),
+    ).toEqual({
+      ...transaction,
+      feePayerSignature: null,
+    })
+  })
+})

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

@@ -0,0 +1,103 @@
+import { AbiParameters, Hash, Hex as OxHex } from 'ox'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import type { Account, Address, Hex } from 'viem'
+import type { z_TransactionRequestTempo, z_TransactionSerializableTempo } from 'viem/tempo'
+
+import { tip20ChannelEscrow } from './Protocol.js'
+import type { ChannelDescriptor } from './Protocol.js'
+
+/** Re-export of the TIP-1034 channel descriptor shape. */
+export type { ChannelDescriptor } from './Protocol.js'
+
+/** Tempo transaction shape used to derive the TIP-1034 `expiringNonceHash`. */
+export type ExpiringNonceTransaction = (
+  | z_TransactionSerializableTempo
+  | z_TransactionRequestTempo
+) & {
+  /** Fee-payer metadata may be present on fee-sponsored open transactions. */
+  feePayer?: Account | true | undefined
+}
+
+/** Computes the TIP-1034 channel ID for a precompile channel descriptor. */
+export function computeId(parameters: computeId.Parameters): Hex {
+  const encoded = AbiParameters.encode(
+    AbiParameters.from([
+      'address payer',
+      'address payee',
+      'address operator',
+      'address token',
+      'bytes32 salt',
+      'address authorizedSigner',
+      'bytes32 expiringNonceHash',
+      'address escrow',
+      'uint256 chainId',
+    ]),
+    [
+      parameters.payer,
+      parameters.payee,
+      parameters.operator,
+      parameters.token,
+      parameters.salt,
+      parameters.authorizedSigner,
+      parameters.expiringNonceHash,
+      parameters.escrow ?? tip20ChannelEscrow,
+      BigInt(parameters.chainId),
+    ],
+  )
+  return Hash.keccak256(encoded)
+}
+
+/** Type helpers for `computeId()`. */
+export declare namespace computeId {
+  /** Parameters that uniquely identify a TIP-1034 precompile channel. */
+  type Parameters = ChannelDescriptor & {
+    /** Chain ID included in the channel ID preimage. */
+    chainId: number
+    /** Escrow contract/precompile address. Defaults to the canonical TIP-1034 address. */
+    escrow?: Address | undefined
+  }
+}
+
+function encodeTempoTransactionForSigning(transaction: ExpiringNonceTransaction) {
+  // ox exposes the exact Tempo signing encoder we need, but its public type
+  // does not include viem's request-time fee-payer fields. Keep the bridge at
+  // the encoder boundary so channel ID derivation stays explicit.
+  return TxEnvelopeTempo.encodeForSigning(transaction as never)
+}
+
+/** Input for deriving the transaction body used by TIP-1034 channel identity hashing. */
+export type ExpiringNonceHashTransactionParameters = {
+  /** Deserialized Tempo transaction that opened the channel. */
+  transaction: ExpiringNonceTransaction
+  /** Whether the transaction will receive a fee-payer co-signature after payer signing. */
+  feePayer?: Account | true | undefined
+}
+
+/**
+ * Returns the sender-signed transaction body used for TIP-1034 `expiringNonceHash`.
+ *
+ * Fee-payer co-signing happens after payer signing and must not affect the channel ID preimage.
+ */
+export function transactionForExpiringNonceHash(
+  parameters: ExpiringNonceHashTransactionParameters,
+): ExpiringNonceTransaction {
+  const { feePayer, transaction } = parameters
+  if (!feePayer) return transaction
+  return { ...transaction, feePayerSignature: null } as ExpiringNonceTransaction
+}
+
+/**
+ * Computes the TIP-1034 `expiringNonceHash` for a channel-opening Tempo transaction.
+ *
+ * This delegates to viem's Tempo sender-scoped hash helper, which matches the node's
+ * `keccak256(encodeForSigning || sender)` consensus preimage. mppx intentionally does
+ * not duplicate Tempo transaction encoding logic here.
+ */
+export function computeExpiringNonceHash(
+  transaction: ExpiringNonceTransaction,
+  parameters: { sender: Address },
+): Hex {
+  return Hash.keccak256(
+    OxHex.concat(encodeTempoTransactionForSigning(transaction), parameters.sender),
+  ) as Hex
+}

package/src/tempo/session/precompile/Protocol.test.ts

@@ -0,0 +1,358 @@
+import { Base64 } from 'ox'
+import type { Hex } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import {
+  createSessionReceipt,
+  deserializeSessionReceipt,
+  extractData,
+  formatApplicationMessage,
+  formatAuthorizationMessage,
+  formatCloseReadyMessage,
+  formatCloseRequestMessage,
+  formatErrorMessage,
+  formatMessageEvent,
+  formatNeedVoucherEvent,
+  formatNeedVoucherMessage,
+  formatReceiptEvent,
+  formatReceiptMessage,
+  isNeedVoucherEvent,
+  isSessionCredentialAction,
+  isSessionCredentialContext,
+  isSessionReceipt,
+  parseEvent,
+  parseMessage,
+  readSessionChallengeAmount,
+  requireSessionCredentialContext,
+  serializeSessionReceipt,
+  type NeedVoucherEvent,
+  type SessionReceipt,
+} from './Protocol.js'
+import * as Types from './Protocol.js'
+
+const maxUint96 = (1n << 96n) - 1n
+
+describe('precompile Uint96', () => {
+  test('accepts lower and upper bounds', () => {
+    expect(Types.uint96(0n)).toBe(0n)
+    expect(Types.uint96(maxUint96)).toBe(maxUint96)
+    expect(Types.isUint96(0n)).toBe(true)
+    expect(Types.isUint96(maxUint96)).toBe(true)
+  })
+
+  test('rejects values outside uint96 bounds', () => {
+    expect(() => Types.uint96(-1n)).toThrow('outside uint96 bounds')
+    expect(() => Types.uint96(maxUint96 + 1n)).toThrow('outside uint96 bounds')
+    expect(Types.isUint96(-1n)).toBe(false)
+    expect(Types.isUint96(maxUint96 + 1n)).toBe(false)
+  })
+
+  test('assertUint96 validates valid values and throws for invalid values', () => {
+    const amount: bigint = 1n
+    Types.assertUint96(amount)
+    expect(amount).toBe(1n)
+    expect(() => Types.assertUint96(maxUint96 + 1n)).toThrow('outside uint96 bounds')
+  })
+})
+
+const credentialContextChannelId = `0x${'11'.repeat(32)}` as const
+
+describe('session credential context guards', () => {
+  test('accepts transport context with a channel ID and known action', () => {
+    expect(isSessionCredentialContext({ channelId: credentialContextChannelId })).toBe(true)
+    expect(
+      isSessionCredentialContext({ action: 'voucher', channelId: credentialContextChannelId }),
+    ).toBe(true)
+  })
+
+  test('rejects missing channel IDs and unknown actions', () => {
+    expect(isSessionCredentialContext({ action: 'voucher' })).toBe(false)
+    expect(
+      isSessionCredentialContext({ action: 'refund', channelId: credentialContextChannelId }),
+    ).toBe(false)
+    expect(isSessionCredentialContext(null)).toBe(false)
+  })
+
+  test('narrows supported action names', () => {
+    expect(isSessionCredentialAction('open')).toBe(true)
+    expect(isSessionCredentialAction('topUp')).toBe(true)
+    expect(isSessionCredentialAction('voucher')).toBe(true)
+    expect(isSessionCredentialAction('close')).toBe(true)
+    expect(isSessionCredentialAction('refund')).toBe(false)
+  })
+
+  test('requires context with custom error message', () => {
+    expect(requireSessionCredentialContext({ channelId: credentialContextChannelId })).toEqual({
+      channelId: credentialContextChannelId,
+    })
+    expect(() => requireSessionCredentialContext({}, 'missing context')).toThrow('missing context')
+  })
+
+  test('reads raw session challenge amount', () => {
+    expect(
+      readSessionChallengeAmount({
+        id: 'challenge-1',
+        realm: 'test',
+        method: 'tempo',
+        intent: 'session',
+        request: { amount: '25' },
+      }),
+    ).toBe(25n)
+  })
+
+  test('rejects missing session challenge amount', () => {
+    expect(() =>
+      readSessionChallengeAmount({
+        id: 'challenge-1',
+        realm: 'test',
+        method: 'tempo',
+        intent: 'session',
+        request: {},
+      }),
+    ).toThrow('Session challenge is missing amount.')
+  })
+})
+
+describe('session transport payload guards', () => {
+  test('accepts complete need-voucher events', () => {
+    expect(
+      isNeedVoucherEvent({
+        channelId: credentialContextChannelId,
+        requiredCumulative: '200',
+        acceptedCumulative: '100',
+        deposit: '1000',
+      }),
+    ).toBe(true)
+  })
+
+  test('rejects incomplete need-voucher events', () => {
+    expect(
+      isNeedVoucherEvent({ channelId: credentialContextChannelId, requiredCumulative: '200' }),
+    ).toBe(false)
+  })
+
+  test('accepts complete session receipts', () => {
+    expect(
+      isSessionReceipt({
+        method: 'tempo',
+        intent: 'session',
+        status: 'success',
+        timestamp: '2026-01-01T00:00:00.000Z',
+        reference: credentialContextChannelId,
+        challengeId: 'challenge-1',
+        channelId: credentialContextChannelId,
+        acceptedCumulative: '100',
+        spent: '50',
+        units: 1,
+      }),
+    ).toBe(true)
+  })
+
+  test('rejects incomplete session receipts', () => {
+    expect(
+      isSessionReceipt({
+        challengeId: 'challenge-1',
+        channelId: credentialContextChannelId,
+      }),
+    ).toBe(false)
+  })
+})
+
+const receiptChannelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+
+describe('Receipt', () => {
+  test('createSessionReceipt', () => {
+    const receipt = createSessionReceipt({
+      challengeId: 'test-challenge-id',
+      channelId: receiptChannelId,
+      acceptedCumulative: 5000000n,
+      spent: 3000000n,
+      units: 42,
+    })
+
+    expect(receipt.method).toBe('tempo')
+    expect(receipt.intent).toBe('session')
+    expect(receipt.status).toBe('success')
+    expect(receipt.reference).toBe(receiptChannelId)
+    expect(receipt.challengeId).toBe('test-challenge-id')
+    expect(receipt.channelId).toBe(receiptChannelId)
+    expect(receipt.acceptedCumulative).toBe('5000000')
+    expect(receipt.spent).toBe('3000000')
+    expect(receipt.units).toBe(42)
+    expect(receipt.timestamp).toBeTruthy()
+    expect(receipt.txHash).toBeUndefined()
+  })
+
+  test('createSessionReceipt with txHash', () => {
+    const txHash = '0xabcdef' as Hex
+    const receipt = createSessionReceipt({
+      challengeId: 'test-challenge-id',
+      channelId: receiptChannelId,
+      acceptedCumulative: 5000000n,
+      spent: 3000000n,
+      txHash,
+    })
+
+    expect(receipt.txHash).toBe(txHash)
+    expect(receipt.units).toBeUndefined()
+  })
+
+  test('createSessionReceipt omits optional fields when undefined', () => {
+    const receipt = createSessionReceipt({
+      challengeId: 'test-challenge-id',
+      channelId: receiptChannelId,
+      acceptedCumulative: 1000n,
+      spent: 0n,
+    })
+
+    expect('units' in receipt).toBe(false)
+    expect('txHash' in receipt).toBe(false)
+  })
+
+  test('serialize and deserialize round-trip', () => {
+    const receipt = createSessionReceipt({
+      challengeId: 'test-challenge-id',
+      channelId: receiptChannelId,
+      acceptedCumulative: 5000000n,
+      spent: 3000000n,
+      units: 42,
+    })
+
+    const encoded = serializeSessionReceipt(receipt)
+    expect(typeof encoded).toBe('string')
+
+    const decoded = deserializeSessionReceipt(encoded)
+    expect(decoded).toEqual(receipt)
+  })
+
+  test('serialize produces base64url without padding', () => {
+    const receipt = createSessionReceipt({
+      challengeId: 'test-challenge-id',
+      channelId: receiptChannelId,
+      acceptedCumulative: 1n,
+      spent: 0n,
+    })
+
+    const encoded = serializeSessionReceipt(receipt)
+    // base64url uses - and _ instead of + and /, no = padding
+    expect(encoded).not.toMatch(/[+/=]/)
+  })
+
+  test('deserialize rejects incomplete receipts', () => {
+    const malformed = Base64.fromString(JSON.stringify({ channelId: receiptChannelId }), {
+      pad: false,
+      url: true,
+    })
+
+    expect(() => deserializeSessionReceipt(malformed)).toThrow('Invalid session receipt.')
+  })
+})
+
+const sseChannelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+
+const sseReceipt: SessionReceipt = {
+  method: 'tempo',
+  intent: 'session',
+  status: 'success',
+  timestamp: '2026-01-01T00:00:00.000Z',
+  reference: sseChannelId,
+  challengeId: 'challenge-1',
+  channelId: sseChannelId,
+  acceptedCumulative: '100',
+  spent: '50',
+  units: 2,
+}
+
+const sseNeedVoucher: NeedVoucherEvent = {
+  channelId: sseChannelId,
+  requiredCumulative: '200',
+  acceptedCumulative: '100',
+  deposit: '1000',
+}
+
+describe('SseProtocol', () => {
+  test('round-trips built-in payment events', () => {
+    expect(parseEvent(formatReceiptEvent(sseReceipt))).toEqual({
+      type: 'payment-receipt',
+      data: sseReceipt,
+    })
+    expect(parseEvent(formatNeedVoucherEvent(sseNeedVoucher))).toEqual({
+      type: 'payment-need-voucher',
+      data: sseNeedVoucher,
+    })
+  })
+
+  test('formats multiline application messages as one event', () => {
+    const formatted = formatMessageEvent('first\n\nthird')
+
+    expect(formatted).toBe('event: message\ndata: first\ndata: \ndata: third\n\n')
+    expect(parseEvent(formatted)).toEqual({ type: 'message', data: 'first\n\nthird' })
+  })
+
+  test('treats unknown event types as application messages', () => {
+    expect(parseEvent('event: custom\ndata: payload\n\n')).toEqual({
+      type: 'message',
+      data: 'payload',
+    })
+  })
+
+  test('extractData returns joined data lines or null', () => {
+    expect(extractData('event: message\ndata: a\ndata: b\n')).toBe('a\nb')
+    expect(extractData(': comment only')).toBeNull()
+  })
+
+  test('rejects malformed payment events', () => {
+    expect(parseEvent('event: payment-receipt\ndata: {"channelId":"0x01"}\n\n')).toBeNull()
+    expect(parseEvent('event: payment-need-voucher\ndata: not json\n\n')).toBeNull()
+  })
+})
+
+const wsReceipt: SessionReceipt = {
+  method: 'tempo',
+  intent: 'session',
+  status: 'success',
+  timestamp: '2026-01-01T00:00:00.000Z',
+  reference: '0x01',
+  challengeId: 'challenge-1',
+  channelId: '0x02',
+  acceptedCumulative: '100',
+  spent: '50',
+  units: 1,
+}
+
+const wsNeedVoucher: NeedVoucherEvent = {
+  channelId: '0x01',
+  requiredCumulative: '200',
+  acceptedCumulative: '100',
+  deposit: '1000',
+}
+
+describe('WsProtocol', () => {
+  test.each([
+    ['authorization', formatAuthorizationMessage('credential'), { mpp: 'authorization' }],
+    ['message', formatApplicationMessage('payload'), { mpp: 'message', data: 'payload' }],
+    ['close request', formatCloseRequestMessage(), { mpp: 'payment-close-request' }],
+    [
+      'close ready',
+      formatCloseReadyMessage(wsReceipt),
+      { mpp: 'payment-close-ready', data: wsReceipt },
+    ],
+    ['error', formatErrorMessage({ status: 402, message: 'pay' }), { mpp: 'payment-error' }],
+    [
+      'need voucher',
+      formatNeedVoucherMessage(wsNeedVoucher),
+      { mpp: 'payment-need-voucher', data: wsNeedVoucher },
+    ],
+    ['receipt', formatReceiptMessage(wsReceipt), { mpp: 'payment-receipt', data: wsReceipt }],
+  ])('round-trips %s frames', (_name, raw, expected) => {
+    expect(parseMessage(raw)).toMatchObject(expected)
+  })
+
+  test('rejects malformed or application-only frames', () => {
+    expect(parseMessage('not json')).toBeNull()
+    expect(parseMessage('{"hello":"world"}')).toBeNull()
+    expect(parseMessage('{"mpp":"payment-receipt","data":true}')).toBeNull()
+    expect(parseMessage('{"mpp":"payment-receipt","data":{"channelId":"0x01"}}')).toBeNull()
+    expect(parseMessage('{"mpp":"payment-need-voucher","data":{"channelId":"0x01"}}')).toBeNull()
+  })
+})