mppx 0.8.15 → 0.8.18

package/src/tempo/Attribution.ts

@@ -1,185 +0,0 @@
-import { Bytes, Hash, Hex } from 'ox'
-
-/**
- * MPP attribution memo encoding for TIP-20 `transferWithMemo`.
- *
- * When no user-provided memo is present, the SDK auto-generates an
- * attribution memo so MPP transactions are identifiable on-chain.
- *
- * ## Byte Layout (32 bytes)
- *
- * | Offset | Size | Field                                     |
- * |--------|------|-------------------------------------------|
- * | 0..3   | 4    | TAG = keccak256("mpp")[0..3]               |
- * | 4      | 1    | version (0x01)                            |
- * | 5..14  | 10   | serverId = keccak256(serverId)[0..9]       |
- * | 15..24 | 10   | clientId = keccak256(clientId)[0..9] or 0s |
- * | 25..31 | 7    | nonce = keccak256(challengeId)[0..6]      |
- *
- * The TAG prefix makes MPP transactions trivially distinguishable
- * from arbitrary memos via `TransferWithMemo` event topic filtering.
- *
- * @module
- */
-
-/** First 4 bytes of keccak256("mpp") — the on-chain MPP tag. */
-export const tag = Hex.slice(Hash.keccak256(Bytes.fromString('mpp'), { as: 'Hex' }), 0, 4)
-
-/** Current memo version. */
-const version = 0x01
-
-/** 10 zero bytes representing an anonymous (no clientId) client. */
-export const anonymous = '0x00000000000000000000' as const
-
-/**
- * Computes a 10-byte fingerprint from a string via keccak256.
- * @internal
- */
-function fingerprint(value: string): Uint8Array {
-  const hash = Hash.keccak256(Bytes.fromString(value), { as: 'Hex' })
-  return Hex.toBytes(Hex.slice(hash, 0, 10))
-}
-
-/**
- * Encodes an MPP attribution memo as a `bytes32` hex string.
- *
- * @param parameters - The serverId (server identity) and optional clientId.
- * @returns A `0x`-prefixed 64-char hex string (32 bytes).
- *
- * @example
- * ```ts
- * import * as Attribution from './Attribution.js'
- *
- * const memo = Attribution.encode({ challengeId: 'challenge-123', clientId: 'my-app', serverId: 'api.example.com' })
- * ```
- */
-export function encode(parameters: encode.Parameters) {
-  const { serverId, clientId, challengeId } = parameters
-  const buf = new Uint8Array(32)
-
-  buf.set(Hex.toBytes(tag), 0)
-  buf[4] = version
-  buf.set(fingerprint(serverId), 5)
-  if (clientId) buf.set(fingerprint(clientId), 15)
-
-  // Derive the nonce from keccak256(challengeId)[0..6] to bind the memo
-  // to the challenge and prevent transaction hash stealing.
-  // TODO: expand to full memo verification once the server tracks the complete attribution payload.
-  buf.set(challengeNonce(challengeId), 25)
-
-  return Hex.fromBytes(buf)
-}
-
-export declare namespace encode {
-  type Parameters = {
-    /** Challenge ID used to derive a deterministic nonce, binding the memo to the challenge. */
-    challengeId: string
-    /** Optional client identity used to derive the client fingerprint. */
-    clientId?: string | undefined
-    /** Server identity used to derive the server fingerprint. */
-    serverId: string
-  }
-}
-
-/**
- * Checks whether a memo was generated by the MPP attribution system.
- *
- * @param memo - A `0x`-prefixed hex string (bytes32).
- * @returns `true` if the memo starts with the MPP tag and version byte.
- *
- * @example
- * ```ts
- * import * as Attribution from './Attribution.js'
- *
- * Attribution.isMppMemo(Attribution.encode({ challengeId: 'challenge-123', serverId: 'api.example.com' })) // true
- * Attribution.isMppMemo('0x0000...0000')      // false
- * ```
- */
-export function isMppMemo(memo: `0x${string}`): boolean {
-  if (memo.length !== 66) return false
-  const memoTag = memo.slice(0, 10) as `0x${string}`
-  const memoVersion = Number.parseInt(memo.slice(10, 12), 16)
-  return memoTag.toLowerCase() === tag.toLowerCase() && memoVersion === version
-}
-
-/**
- * Verifies that a memo's server fingerprint matches the given serverId.
- *
- * Checks TAG, version byte, and that bytes 5–14 equal keccak256(serverId)[0..9].
- *
- * @param memo - A `0x`-prefixed hex string (bytes32).
- * @param serverId - The expected server identity.
- * @returns `true` if the memo has a valid MPP tag and matching server fingerprint.
- */
-export function verifyServer(memo: `0x${string}`, serverId: string): boolean {
-  if (!isMppMemo(memo)) return false
-  const memoServerHex = `0x${memo.slice(12, 32)}` as `0x${string}`
-  const expectedHex = Hex.fromBytes(fingerprint(serverId)) as `0x${string}`
-  return memoServerHex.toLowerCase() === expectedHex.toLowerCase()
-}
-
-/**
- * Decodes an MPP attribution memo into its constituent parts.
- *
- * @param memo - A `0x`-prefixed hex string (bytes32).
- * @returns The decoded fields, or `null` if the memo is not an MPP memo.
- *
- * @example
- * ```ts
- * import * as Attribution from './Attribution.js'
- *
- * const memo = Attribution.encode({ challengeId: 'challenge-123', clientId: 'my-app', serverId: 'api.example.com' })
- * const decoded = Attribution.decode(memo)
- * // { version: 1, serverFingerprint: '0x...', clientFingerprint: '0x...', nonce: '0x...' }
- * ```
- */
-export function decode(memo: `0x${string}`): decode.Result | null {
-  if (!isMppMemo(memo)) return null
-
-  const memoVersion = Number.parseInt(memo.slice(10, 12), 16)
-  const serverFingerprint = `0x${memo.slice(12, 32)}` as `0x${string}`
-  const clientHex = `0x${memo.slice(32, 52)}` as `0x${string}`
-  const nonce = `0x${memo.slice(52)}` as `0x${string}`
-
-  const clientFingerprint = clientHex.toLowerCase() === anonymous.toLowerCase() ? null : clientHex
-
-  return { version: memoVersion, serverFingerprint, clientFingerprint, nonce }
-}
-
-export declare namespace decode {
-  type Result = {
-    /** Memo version (currently always 1). */
-    version: number
-    /** 10-byte server fingerprint hex (keccak256(serverId)[0..9]). */
-    serverFingerprint: `0x${string}`
-    /** 10-byte client fingerprint hex, or `null` if anonymous. */
-    clientFingerprint: `0x${string}` | null
-    /** 7-byte challenge-bound nonce hex (keccak256(challengeId)[0..6]). */
-    nonce: `0x${string}`
-  }
-}
-
-/**
- * Computes the 7-byte challenge-bound nonce: keccak256(challengeId)[0..6].
- * @internal
- */
-export function challengeNonce(challengeId: string): Uint8Array {
-  const hash = Hash.keccak256(Bytes.fromString(challengeId), { as: 'Hex' })
-  return Hex.toBytes(Hex.slice(hash, 0, 7))
-}
-
-/**
- * Verifies that a memo's nonce is bound to the given challengeId.
- *
- * Checks TAG, version byte, and that bytes 25–31 equal keccak256(challengeId)[0..6].
- *
- * @param memo - A `0x`-prefixed hex string (bytes32).
- * @param challengeId - The expected challenge ID.
- * @returns `true` if the memo has a valid MPP tag and matching challenge nonce.
- */
-export function verifyChallengeBinding(memo: `0x${string}`, challengeId: string): boolean {
-  const decoded = decode(memo)
-  if (!decoded) return false
-  const expectedNonce = Hex.fromBytes(challengeNonce(challengeId))
-  return decoded.nonce.toLowerCase() === expectedNonce.toLowerCase()
-}

package/src/tempo/Methods.test.ts

@@ -1,425 +0,0 @@
-import { Methods } from 'mppx/tempo'
-import { describe, expect, expectTypeOf, test } from 'vp/test'
-
-const secondsPerDay = 86_400n
-
-describe('charge', () => {
-  test('has correct name and intent', () => {
-    expect(Methods.charge.intent).toBe('charge')
-    expect(Methods.charge.name).toBe('tempo')
-  })
-
-  test('types: intent is literal', () => {
-    expectTypeOf(Methods.charge.intent).toEqualTypeOf<'charge'>()
-  })
-
-  test('types: name is literal', () => {
-    expectTypeOf(Methods.charge.name).toEqualTypeOf<'tempo'>()
-  })
-
-  test('schema: validates valid request', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      expires: '2025-02-05T12:05:00Z',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: validates request with methodDetails', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      expires: '2025-02-05T12:05:00Z',
-      chainId: 42431,
-      feePayer: true,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: validates request with supportedModes', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      supportedModes: ['pull'],
-    })
-    expect(result.success).toBe(true)
-    if (!result.success) return
-
-    expect(result.data.methodDetails?.supportedModes).toEqual(['pull'])
-  })
-
-  test('schema: rejects empty supportedModes', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      supportedModes: [],
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: validates request with memo', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      expires: '2025-02-05T12:05:00Z',
-      memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: validates request with splits', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      splits: [
-        {
-          amount: '0.25',
-          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-        },
-        {
-          amount: '0.1',
-          memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
-          recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
-        },
-      ],
-    })
-    expect(result.success).toBe(true)
-    if (!result.success) return
-
-    expect(result.data.methodDetails?.splits).toEqual([
-      {
-        amount: '250000',
-        recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-      },
-      {
-        amount: '100000',
-        memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
-        recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
-      },
-    ])
-  })
-
-  test('schema: rejects empty splits', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      splits: [],
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects more than 10 splits', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '11',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      splits: Array.from({ length: 11 }, (_, index) => ({
-        amount: '0.1',
-        recipient: `0x${(index + 1).toString(16).padStart(40, '0')}`,
-      })),
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects split totals greater than or equal to amount', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      splits: [
-        {
-          amount: '0.5',
-          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-        },
-        {
-          amount: '0.5',
-          recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
-        },
-      ],
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects zero-amount with splits', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '0',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      splits: [
-        {
-          amount: '0.1',
-          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-        },
-      ],
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: accepts zero-amount without splits', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '0',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: rejects invalid request', () => {
-    const result = Methods.charge.schema.request.safeParse({
-      amount: '1',
-    })
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: validates transaction payload', () => {
-    const result = Methods.charge.schema.credential.payload.safeParse({
-      signature: '0x76f90100000000000000000000000000000000000000000000000000000000000000000000',
-      type: 'transaction',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: validates hash payload', () => {
-    const result = Methods.charge.schema.credential.payload.safeParse({
-      hash: '0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890',
-      type: 'hash',
-    })
-    expect(result.success).toBe(true)
-  })
-
-  test('schema: rejects invalid payload type', () => {
-    const result = Methods.charge.schema.credential.payload.safeParse({
-      signature: '0x...',
-      type: 'keyAuthorization',
-    })
-    expect(result.success).toBe(false)
-  })
-})
-
-describe('session', () => {
-  test('has correct name and intent', () => {
-    expect(Methods.session.intent).toBe('session')
-    expect(Methods.session.name).toBe('tempo')
-  })
-
-  test('schema: rejects zero-amount request', () => {
-    const result = Methods.session.schema.request.safeParse({
-      amount: '0',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      escrowContract: '0x1234567890abcdef1234567890abcdef12345678',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      unitType: 'token',
-    })
-
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: encodes minVoucherDelta in base units', () => {
-    const request = Methods.session.schema.request.parse({
-      amount: '1',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      escrowContract: '0x1234567890abcdef1234567890abcdef12345678',
-      minVoucherDelta: '0.1',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      unitType: 'token',
-    })
-
-    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', () => {
-  test('has correct name and intent', () => {
-    expect(Methods.subscription.intent).toBe('subscription')
-    expect(Methods.subscription.name).toBe('tempo')
-  })
-
-  test('schema: validates request and encodes amount in base units', () => {
-    const request = Methods.subscription.schema.request.parse({
-      accessKey: {
-        accessKeyAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-        keyType: 'secp256k1',
-      },
-      amount: '10',
-      chainId: 4217,
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: '1',
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(request.amount).toBe('10000000')
-    expect(request.methodDetails?.chainId).toBe(4217)
-    expect(request.methodDetails?.accessKey).toEqual({
-      accessKeyAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
-      keyType: 'secp256k1',
-    })
-    expect('accessKey' in request).toBe(false)
-  })
-
-  test('schema: accepts subscriptionExpires as a Date', () => {
-    const request = Methods.subscription.schema.request.parse({
-      amount: '10',
-      chainId: 4217,
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: '1',
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: new Date('2026-01-01T00:00:00Z'),
-    })
-
-    expect(request.subscriptionExpires).toBe('2026-01-01T00:00:00.000Z')
-  })
-
-  test.each([
-    { input: 1, expected: '1', desc: 'number' },
-    { input: 1n, expected: '1', desc: 'bigint' },
-  ])('schema: accepts periodCount as $desc', ({ input, expected }) => {
-    const request = Methods.subscription.schema.request.parse({
-      amount: '10',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: input,
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(request.periodCount).toBe(expected)
-  })
-
-  test('schema: rejects non-numeric periodCount', () => {
-    const result = Methods.subscription.schema.request.safeParse({
-      amount: '10',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: 'month',
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects unsafe number periodCount', () => {
-    const result = Methods.subscription.schema.request.safeParse({
-      amount: '10',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: Number.MAX_SAFE_INTEGER + 1,
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects calendar-month periods that Tempo cannot represent exactly', () => {
-    const result = Methods.subscription.schema.request.safeParse({
-      amount: '10',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: '1',
-      periodUnit: 'month',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: rejects periods whose mapped seconds exceed uint64', () => {
-    const result = Methods.subscription.schema.request.safeParse({
-      amount: '10',
-      currency: '0x20c0000000000000000000000000000000000001',
-      decimals: 6,
-      periodCount: String((1n << 64n) / secondsPerDay + 1n),
-      periodUnit: 'day',
-      recipient: '0x1234567890abcdef1234567890abcdef12345678',
-      subscriptionExpires: '2026-01-01T00:00:00Z',
-    })
-
-    expect(result.success).toBe(false)
-  })
-
-  test('schema: validates key authorization payload', () => {
-    const result = Methods.subscription.schema.credential.payload.safeParse({
-      signature: '0x1234',
-      type: 'keyAuthorization',
-    })
-
-    expect(result.success).toBe(true)
-  })
-})