mppx 0.8.17 → 0.8.18

package/src/tempo/AccessKeyAuthorization.test.ts

@@ -1,141 +0,0 @@
-import { Challenge, Credential } from 'mppx'
-import { type Address, createClient, custom, type Hex } from 'viem'
-import {
-  Account as TempoAccount,
-  KeyAuthorizationManager,
-  Secp256k1,
-  Transaction,
-} from 'viem/tempo'
-import { describe, expect, test } from 'vp/test'
-import { tempoNetwork } from '~test/config.js'
-import { asset as currency, chain, http } from '~test/tempo/viem.js'
-
-import { charge } from './client/Charge.js'
-import * as Methods from './Methods.js'
-
-type ChargeCredentialPayload =
-  | { hash: Hex; type: 'hash' }
-  | { signature: Hex; type: 'proof' | 'transaction' }
-
-const rootAccount = TempoAccount.fromSecp256k1(
-  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
-)
-const recipient = '0x2222222222222222222222222222222222222222' as Address
-const isLocalnet = tempoNetwork === 'localnet'
-
-type ChargeRequest = ReturnType<typeof Methods.charge.schema.request.parse>
-
-function createChargeChallenge(
-  overrides: Partial<Parameters<typeof Methods.charge.schema.request.parse>[0]> = {},
-): Challenge.Challenge<ChargeRequest, 'charge', 'tempo'> {
-  const request = Methods.charge.schema.request.parse({
-    amount: '1000000',
-    chainId: chain.id,
-    currency,
-    decimals: 6,
-    recipient,
-    ...overrides,
-  })
-  return Challenge.from({
-    id: 'test-challenge-id',
-    intent: 'charge',
-    method: 'tempo',
-    realm: 'api.example.com',
-    request,
-  }) as Challenge.Challenge<ChargeRequest, 'charge', 'tempo'>
-}
-
-async function createAccessKeyClient() {
-  const keyAuthorizationManager = KeyAuthorizationManager.memory()
-  const accessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey(), {
-    access: rootAccount,
-    keyAuthorizationManager,
-  })
-  const keyAuthorization = await rootAccount.signKeyAuthorization(
-    {
-      accessKeyAddress: accessKey.accessKeyAddress,
-      keyType: accessKey.keyType,
-    },
-    {
-      chainId: BigInt(chain.id),
-    },
-  )
-  await keyAuthorizationManager.set(
-    {
-      accessKey: accessKey.accessKeyAddress,
-      address: rootAccount.address,
-      chainId: chain.id,
-    },
-    keyAuthorization,
-  )
-
-  const signedTransactions: Transaction.TransactionSerializedTempo[] = []
-  const rpcClient = createClient({ chain, transport: http() })
-
-  const client = createClient({
-    account: accessKey,
-    chain,
-    transport: custom({
-      async request({ method, params }: { method: string; params?: readonly unknown[] }) {
-        if (method === 'eth_sendRawTransaction' || method === 'eth_sendRawTransactionSync')
-          signedTransactions.push(params?.[0] as Transaction.TransactionSerializedTempo)
-        return rpcClient.request({ method, params } as never)
-      },
-    }),
-  })
-
-  return { accessKey, client, keyAuthorization, signedTransactions }
-}
-
-function expectTransactionKeyAuthorization(
-  serializedTransaction: Hex,
-  keyAuthorization: Awaited<ReturnType<typeof rootAccount.signKeyAuthorization>>,
-) {
-  const transaction = Transaction.deserialize(
-    serializedTransaction as Transaction.TransactionSerializedTempo,
-  )
-  expect(transaction.keyAuthorization).toEqual(keyAuthorization)
-}
-
-describe.runIf(isLocalnet)('Tempo access-key authorization attachment', () => {
-  test('tempo.charge pull signs a prepared transaction with keyAuthorization', async () => {
-    const { accessKey, client, keyAuthorization } = await createAccessKeyClient()
-    const method = charge({
-      account: accessKey,
-      getClient: () => client,
-      mode: 'pull',
-    })
-
-    const credential = Credential.deserialize<ChargeCredentialPayload>(
-      await method.createCredential({
-        challenge: createChargeChallenge({ supportedModes: ['pull'] }),
-        context: {},
-      }),
-    )
-
-    expect(credential.payload.type).toBe('transaction')
-    if (credential.payload.type !== 'transaction') throw new Error('unexpected credential type')
-    expectTransactionKeyAuthorization(credential.payload.signature as Hex, keyAuthorization)
-  })
-
-  test('tempo.charge push fallback sends a prepared transaction with keyAuthorization', async () => {
-    const { accessKey, client, keyAuthorization, signedTransactions } =
-      await createAccessKeyClient()
-    const method = charge({
-      account: accessKey,
-      getClient: () => client,
-      mode: 'push',
-    })
-
-    const credential = Credential.deserialize<ChargeCredentialPayload>(
-      await method.createCredential({
-        challenge: createChargeChallenge({ supportedModes: ['push'] }),
-        context: {},
-      }),
-    )
-
-    expect(credential.payload.type).toBe('hash')
-    expect(signedTransactions).toHaveLength(1)
-    expectTransactionKeyAuthorization(signedTransactions[0]!, keyAuthorization)
-  })
-})

package/src/tempo/Attribution.test.ts

@@ -1,294 +0,0 @@
-import { Bytes, Hash, Hex } from 'ox'
-import { describe, expect, test } from 'vp/test'
-
-import * as Attribution from './Attribution.js'
-
-describe('Attribution', () => {
-  describe('tag', () => {
-    test('is a 4-byte hex string', () => {
-      expect(Attribution.tag).toMatch(/^0x[0-9a-f]{8}$/i)
-    })
-
-    test('is deterministic (keccak256("mpp")[0..3])', () => {
-      expect(Attribution.tag).toBe('0xef1ed712')
-    })
-  })
-
-  describe('encode', () => {
-    test('returns a 32-byte hex string', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      // 0x prefix + 64 hex chars = 32 bytes
-      expect(memo).toMatch(/^0x[0-9a-f]{64}$/i)
-    })
-
-    test('starts with TAG + version byte', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const tag = memo.slice(0, 10) // 0x + 8 hex chars
-      expect(tag.toLowerCase()).toBe(Attribution.tag.toLowerCase())
-      const version = memo.slice(10, 12)
-      expect(version).toBe('01')
-    })
-
-    test('produces deterministic memos (challenge-bound nonce)', () => {
-      const a = Attribution.encode({ challengeId: 'challenge-a', serverId: 'api.example.com' })
-      const b = Attribution.encode({ challengeId: 'challenge-b', serverId: 'api.example.com' })
-      expect(a).not.toBe(b)
-      const c = Attribution.encode({ challengeId: 'challenge-a', serverId: 'api.example.com' })
-      expect(a).toBe(c)
-    })
-
-    test('encodes server fingerprint from serverId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const expectedFingerprint = Hex.slice(
-        Hash.keccak256(Bytes.fromString('api.example.com'), { as: 'Hex' }),
-        0,
-        10,
-      )
-      const serverHex = `0x${memo.slice(12, 32)}` as `0x${string}`
-      expect(serverHex.toLowerCase()).toBe(expectedFingerprint.toLowerCase())
-    })
-
-    test('encodes client fingerprint from clientId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: 'my-app',
-        serverId: 'api.example.com',
-      })
-      const expectedFingerprint = Hex.slice(
-        Hash.keccak256(Bytes.fromString('my-app'), { as: 'Hex' }),
-        0,
-        10,
-      )
-      const clientHex = `0x${memo.slice(32, 52)}` as `0x${string}`
-      expect(clientHex.toLowerCase()).toBe(expectedFingerprint.toLowerCase())
-    })
-
-    test('encodes zero client bytes when no clientId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const clientHex = `0x${memo.slice(32, 52)}` as `0x${string}`
-      expect(clientHex).toBe(Attribution.anonymous)
-    })
-
-    test('treats empty string clientId as anonymous', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: '',
-        serverId: 'api.example.com',
-      })
-      const clientHex = `0x${memo.slice(32, 52)}` as `0x${string}`
-      expect(clientHex).toBe(Attribution.anonymous)
-      const decoded = Attribution.decode(memo)
-      expect(decoded).not.toBeNull()
-      expect(decoded!.clientFingerprint).toBeNull()
-    })
-  })
-
-  describe('isMppMemo', () => {
-    test('returns true for encoded memos', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.isMppMemo(memo)).toBe(true)
-    })
-
-    test('returns true for encoded memos with clientId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: 'my-app',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.isMppMemo(memo)).toBe(true)
-    })
-
-    test('returns false for zero memo', () => {
-      const zero =
-        '0x0000000000000000000000000000000000000000000000000000000000000000' as `0x${string}`
-      expect(Attribution.isMppMemo(zero)).toBe(false)
-    })
-
-    test('returns false for arbitrary memo', () => {
-      const arbitrary =
-        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' as `0x${string}`
-      expect(Attribution.isMppMemo(arbitrary)).toBe(false)
-    })
-
-    test('returns false for short hex', () => {
-      expect(Attribution.isMppMemo('0x1234' as `0x${string}`)).toBe(false)
-    })
-
-    test('returns false for wrong version', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const wrongVersion = `${memo.slice(0, 10)}ff${memo.slice(12)}` as `0x${string}`
-      expect(Attribution.isMppMemo(wrongVersion)).toBe(false)
-    })
-
-    test('handles mixed case hex', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const tagUpper = memo.slice(0, 10).toUpperCase()
-      const mixed = `0x${tagUpper.slice(2)}${memo.slice(10)}` as `0x${string}`
-      expect(Attribution.isMppMemo(mixed)).toBe(true)
-    })
-  })
-
-  describe('verifyServer', () => {
-    test('returns true for matching serverId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.verifyServer(memo, 'api.example.com')).toBe(true)
-    })
-
-    test('returns true for matching serverId with clientId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: 'my-app',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.verifyServer(memo, 'api.example.com')).toBe(true)
-    })
-
-    test('returns false for wrong serverId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.verifyServer(memo, 'other.example.com')).toBe(false)
-    })
-
-    test('returns false for non-MPP memo', () => {
-      const arbitrary =
-        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' as `0x${string}`
-      expect(Attribution.verifyServer(arbitrary, 'api.example.com')).toBe(false)
-    })
-  })
-
-  describe('decode', () => {
-    test('decodes an encoded memo with serverId and clientId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: 'my-app',
-        serverId: 'api.example.com',
-      })
-      const result = Attribution.decode(memo)
-      expect(result).not.toBeNull()
-      expect(result!.version).toBe(1)
-      expect(result!.serverFingerprint).toMatch(/^0x[0-9a-f]{20}$/i) // 10 bytes = 20 hex chars
-      expect(result!.clientFingerprint).toMatch(/^0x[0-9a-f]{20}$/i)
-      expect(result!.clientFingerprint).not.toBeNull()
-      expect(result!.nonce).toMatch(/^0x[0-9a-f]{14}$/i) // 7 bytes = 14 hex chars
-    })
-
-    test('decodes anonymous client as null', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const result = Attribution.decode(memo)
-      expect(result).not.toBeNull()
-      expect(result!.clientFingerprint).toBeNull()
-    })
-
-    test('returns null for non-MPP memo', () => {
-      const arbitrary =
-        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' as `0x${string}`
-      expect(Attribution.decode(arbitrary)).toBeNull()
-    })
-
-    test('different challengeIds produce different nonces', () => {
-      const a = Attribution.decode(
-        Attribution.encode({ challengeId: 'challenge-a', serverId: 'api.example.com' }),
-      )
-      const b = Attribution.decode(
-        Attribution.encode({ challengeId: 'challenge-b', serverId: 'api.example.com' }),
-      )
-      expect(a!.nonce).not.toBe(b!.nonce)
-    })
-
-    test('serverId fingerprint matches expected keccak hash', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        clientId: 'my-app',
-        serverId: 'api.example.com',
-      })
-      const result = Attribution.decode(memo)!
-      const expectedServer = Hex.slice(
-        Hash.keccak256(Bytes.fromString('api.example.com'), { as: 'Hex' }),
-        0,
-        10,
-      )
-      expect(result.serverFingerprint.toLowerCase()).toBe(expectedServer.toLowerCase())
-    })
-
-    test('returns null for wrong version via decode', () => {
-      const memo = Attribution.encode({
-        challengeId: 'test-challenge-1',
-        serverId: 'api.example.com',
-      })
-      const corrupted = `${memo.slice(0, 10)}ff${memo.slice(12)}` as `0x${string}`
-      expect(Attribution.decode(corrupted)).toBeNull()
-    })
-  })
-
-  describe('challengeNonce', () => {
-    test('returns 7 bytes', () => {
-      const nonce = Attribution.challengeNonce('challenge-123')
-      expect(nonce.length).toBe(7)
-    })
-
-    test('is deterministic', () => {
-      const a = Attribution.challengeNonce('challenge-123')
-      const b = Attribution.challengeNonce('challenge-123')
-      expect(Hex.fromBytes(a)).toBe(Hex.fromBytes(b))
-    })
-
-    test('differs for different challengeIds', () => {
-      const a = Attribution.challengeNonce('challenge-123')
-      const b = Attribution.challengeNonce('challenge-456')
-      expect(Hex.fromBytes(a)).not.toBe(Hex.fromBytes(b))
-    })
-  })
-
-  describe('verifyChallengeBinding', () => {
-    test('returns true for matching challengeId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'challenge-123',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.verifyChallengeBinding(memo, 'challenge-123')).toBe(true)
-    })
-
-    test('returns false for wrong challengeId', () => {
-      const memo = Attribution.encode({
-        challengeId: 'challenge-123',
-        serverId: 'api.example.com',
-      })
-      expect(Attribution.verifyChallengeBinding(memo, 'challenge-456')).toBe(false)
-    })
-
-    test('returns false for non-MPP memo', () => {
-      const arbitrary =
-        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' as `0x${string}`
-      expect(Attribution.verifyChallengeBinding(arbitrary, 'challenge-123')).toBe(false)
-    })
-  })
-})

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()
-}