mppx 0.0.1 → 0.1.0

package/src/stripe/server/MethodIntents.ts

@@ -0,0 +1,24 @@
+import { charge as charge_ } from './Charge.js'
+
+/**
+ * Creates a Stripe `charge` method intent for usage on the server.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, stripe } from 'mppx/server'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [stripe({ secretKey: 'sk_...' })],
+ * })
+ * ```
+ */
+export function stripe<const parameters extends stripe.Parameters>(parameters: parameters) {
+  return [stripe.charge(parameters)] as const
+}
+
+export namespace stripe {
+  export type Parameters = charge_.Parameters
+
+  /** Creates a Stripe `charge` method intent for SPT-based payments. */
+  export const charge = charge_
+}

package/src/stripe/server/index.ts

@@ -0,0 +1,2 @@
+export { charge } from './Charge.js'
+export { stripe } from './MethodIntents.js'

package/src/tempo/Attribution.test.ts

@@ -0,0 +1,187 @@
+import { Bytes, Hash, Hex } from 'ox'
+import { describe, expect, test } from 'vitest'
+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({ 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({ 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('generates unique memos (random nonce)', () => {
+      const a = Attribution.encode({ serverId: 'api.example.com' })
+      const b = Attribution.encode({ serverId: 'api.example.com' })
+      expect(a).not.toBe(b)
+    })
+
+    test('encodes server fingerprint from serverId', () => {
+      const memo = Attribution.encode({ 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({ serverId: 'api.example.com', clientId: 'my-app' })
+      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({ 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({ serverId: 'api.example.com', clientId: '' })
+      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({ serverId: 'api.example.com' })
+      expect(Attribution.isMppMemo(memo)).toBe(true)
+    })
+
+    test('returns true for encoded memos with clientId', () => {
+      const memo = Attribution.encode({ serverId: 'api.example.com', clientId: 'my-app' })
+      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({ 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({ 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({ 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({ serverId: 'api.example.com', clientId: 'my-app' })
+      expect(Attribution.verifyServer(memo, 'api.example.com')).toBe(true)
+    })
+
+    test('returns false for wrong serverId', () => {
+      const memo = Attribution.encode({ 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({ serverId: 'api.example.com', clientId: 'my-app' })
+      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({ 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 encodes produce different nonces', () => {
+      const a = Attribution.decode(Attribution.encode({ serverId: 'api.example.com' }))
+      const b = Attribution.decode(Attribution.encode({ serverId: 'api.example.com' }))
+      expect(a!.nonce).not.toBe(b!.nonce)
+    })
+
+    test('serverId fingerprint matches expected keccak hash', () => {
+      const memo = Attribution.encode({ serverId: 'api.example.com', clientId: 'my-app' })
+      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({ serverId: 'api.example.com' })
+      const corrupted = `${memo.slice(0, 10)}ff${memo.slice(12)}` as `0x${string}`
+      expect(Attribution.decode(corrupted)).toBeNull()
+    })
+  })
+})

package/src/tempo/Attribution.ts

@@ -0,0 +1,156 @@
+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 (random bytes)                      |
+ *
+ * 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({ serverId: 'api.example.com', clientId: 'my-app' })
+ * ```
+ */
+export function encode(parameters: encode.Parameters) {
+  const { serverId, clientId } = 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)
+
+  const nonce = crypto.getRandomValues(new Uint8Array(7))
+  buf.set(nonce, 25)
+
+  return Hex.fromBytes(buf)
+}
+
+export declare namespace encode {
+  type Parameters = {
+    /** Server identity used to derive the server fingerprint. */
+    serverId: string
+    /** Optional client identity used to derive the client fingerprint. */
+    clientId?: string | undefined
+  }
+}
+
+/**
+ * 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({ 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({ serverId: 'api.example.com', clientId: 'my-app' })
+ * 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 random nonce hex. */
+    nonce: `0x${string}`
+  }
+}

package/src/tempo/Intents.test.ts

@@ -0,0 +1,84 @@
+import { MethodIntents } from 'mppx/tempo'
+import { describe, expect, expectTypeOf, test } from 'vitest'
+
+describe('charge', () => {
+  test('has correct name and method', () => {
+    expect(MethodIntents.charge.name).toBe('charge')
+    expect(MethodIntents.charge.method).toBe('tempo')
+  })
+
+  test('types: name is literal', () => {
+    expectTypeOf(MethodIntents.charge.name).toEqualTypeOf<'charge'>()
+  })
+
+  test('types: method is literal', () => {
+    expectTypeOf(MethodIntents.charge.method).toEqualTypeOf<'tempo'>()
+  })
+
+  test('schema: validates valid request', () => {
+    const result = MethodIntents.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 = MethodIntents.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 memo', () => {
+    const result = MethodIntents.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: rejects invalid request', () => {
+    const result = MethodIntents.charge.schema.request.safeParse({
+      amount: '1',
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: validates transaction payload', () => {
+    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+      signature: '0x76f90100000000000000000000000000000000000000000000000000000000000000000000',
+      type: 'transaction',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('schema: validates hash payload', () => {
+    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+      hash: '0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890',
+      type: 'hash',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('schema: rejects invalid payload type', () => {
+    const result = MethodIntents.charge.schema.credential.payload.safeParse({
+      signature: '0x...',
+      type: 'keyAuthorization',
+    })
+    expect(result.success).toBe(false)
+  })
+})

package/src/tempo/Intents.ts

@@ -0,0 +1,93 @@
+import type { Account } from 'viem'
+import * as Intent from '../Intent.js'
+import * as MethodIntent from '../MethodIntent.js'
+import * as z from '../zod.js'
+
+/**
+ * Tempo charge intent for one-time TIP-20 token transfers.
+ *
+ * @see https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/methods/tempo/draft-tempo-charge-00.md
+ */
+export const charge = MethodIntent.fromIntent(Intent.charge, {
+  method: 'tempo',
+  schema: {
+    credential: {
+      payload: z.discriminatedUnion('type', [
+        z.object({ hash: z.hash(), type: z.literal('hash') }),
+        z.object({ signature: z.signature(), type: z.literal('transaction') }),
+      ]),
+    },
+    request: {
+      methodDetails: z.object({
+        chainId: z.optional(z.number()),
+        feePayer: z.optional(
+          z.pipe(
+            z.union([z.boolean(), z.custom<Account>()]),
+            z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+          ),
+        ),
+        memo: z.optional(z.hash()),
+      }),
+      requires: ['decimals', 'recipient'],
+    },
+  },
+})
+
+/**
+ * Tempo session intent for pay-as-you-go streaming payments.
+ *
+ * Uses cumulative vouchers over a payment channel. Credential payloads
+ * are a discriminated union on `action`: open, topUp, voucher, close.
+ */
+export const session = MethodIntent.fromIntent(Intent.session, {
+  method: 'tempo',
+  schema: {
+    credential: {
+      payload: z.discriminatedUnion('action', [
+        z.object({
+          action: z.literal('open'),
+          type: z.literal('transaction'),
+          channelId: z.hash(),
+          transaction: z.signature(),
+          authorizedSigner: z.optional(z.string()),
+          cumulativeAmount: z.amount(),
+          signature: z.signature(),
+        }),
+        z.object({
+          action: z.literal('topUp'),
+          type: z.literal('transaction'),
+          channelId: z.hash(),
+          transaction: z.signature(),
+          additionalDeposit: z.amount(),
+        }),
+        z.object({
+          action: z.literal('voucher'),
+          channelId: z.hash(),
+          cumulativeAmount: z.amount(),
+          signature: z.signature(),
+        }),
+        z.object({
+          action: z.literal('close'),
+          channelId: z.hash(),
+          cumulativeAmount: z.amount(),
+          signature: z.signature(),
+        }),
+      ]),
+    },
+    request: {
+      methodDetails: z.object({
+        escrowContract: z.string(),
+        channelId: z.optional(z.hash()),
+        minVoucherDelta: z.optional(z.amount()),
+        chainId: z.optional(z.number()),
+        feePayer: z.optional(
+          z.pipe(
+            z.union([z.boolean(), z.custom<Account>()]),
+            z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+          ),
+        ),
+      }),
+      requires: ['decimals', 'recipient', 'currency'],
+    },
+  },
+})