mppx 0.0.1 → 0.1.0

package/src/tempo/stream/ChannelStore.test.ts

@@ -0,0 +1,473 @@
+import type { Address, Hex } from 'viem'
+import { describe, expect, test } from 'vitest'
+import * as Store from '../../Store.js'
+import * as ChannelStore from './ChannelStore.js'
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+const channelId2 = '0x0000000000000000000000000000000000000000000000000000000000000002' as Hex
+
+function makeChannel(overrides?: Partial<ChannelStore.State>): ChannelStore.State {
+  return {
+    channelId,
+    payer: '0x0000000000000000000000000000000000000001' as Address,
+    payee: '0x0000000000000000000000000000000000000002' as Address,
+    token: '0x0000000000000000000000000000000000000003' as Address,
+    authorizedSigner: '0x0000000000000000000000000000000000000004' as Address,
+    chainId: 42431,
+    escrowContract: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787' as Address,
+    deposit: 10_000_000n,
+    settledOnChain: 0n,
+    highestVoucherAmount: 10_000_000n,
+    highestVoucher: null,
+    spent: 0n,
+    units: 0,
+    finalized: false,
+    createdAt: '2025-01-01T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+function seedChannel(
+  store: ChannelStore.ChannelStore,
+  overrides?: Partial<ChannelStore.State>,
+): Promise<ChannelStore.State | null> {
+  return store.updateChannel(channelId, () => makeChannel(overrides))
+}
+
+function stripUpdateMethod(store: Store.Store): Store.Store {
+  return {
+    get: store.get.bind(store),
+    put: store.put.bind(store),
+    delete: store.delete.bind(store),
+  }
+}
+
+function delayedStore(delayMs: number): Store.Store {
+  const store = new Map<string, unknown>()
+  return {
+    async get(key) {
+      await sleep(delayMs)
+      return (store.get(key) ?? null) as any
+    },
+    async put(key, value) {
+      await sleep(delayMs)
+      store.set(key, value)
+    },
+    async delete(key) {
+      await sleep(delayMs)
+      store.delete(key)
+    },
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
+// ---------- Store.memory ----------
+
+describe('Store.memory', () => {
+  test('get returns null for missing key', async () => {
+    const s = Store.memory()
+    expect(await s.get('missing')).toBeNull()
+  })
+
+  test('put then get returns value', async () => {
+    const s = Store.memory()
+    const ch = makeChannel()
+    await s.put('k', ch)
+    const result = await s.get('k')
+    expect(result).toEqual(ch)
+  })
+
+  test('delete removes key', async () => {
+    const s = Store.memory()
+    await s.put('k', makeChannel())
+    await s.delete('k')
+    expect(await s.get('k')).toBeNull()
+  })
+})
+
+// ---------- channelStore ----------
+
+describe('channelStore', () => {
+  describe('getChannel', () => {
+    test('returns null for missing channel', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      expect(await cs.getChannel(channelId)).toBeNull()
+    })
+
+    test('returns channel after update', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      const ch = makeChannel()
+      await cs.updateChannel(channelId, () => ch)
+
+      const loaded = await cs.getChannel(channelId)
+      expect(loaded).not.toBeNull()
+      expect(loaded!.channelId).toBe(channelId)
+      expect(loaded!.deposit).toBe(10_000_000n)
+      expect(typeof loaded!.deposit).toBe('bigint')
+      expect(typeof loaded!.createdAt).toBe('string')
+    })
+  })
+
+  describe('updateChannel', () => {
+    test('creates channel from null', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      const result = await cs.updateChannel(channelId, (current) => {
+        expect(current).toBeNull()
+        return makeChannel()
+      })
+      expect(result).not.toBeNull()
+      expect(result!.deposit).toBe(10_000_000n)
+    })
+
+    test('updates existing channel', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs)
+
+      const result = await cs.updateChannel(channelId, (current) => {
+        return { ...current!, spent: current!.spent + 1_000_000n, units: current!.units + 1 }
+      })
+      expect(result!.spent).toBe(1_000_000n)
+      expect(result!.units).toBe(1)
+    })
+
+    test('returning null deletes channel', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs)
+
+      const result = await cs.updateChannel(channelId, () => null)
+      expect(result).toBeNull()
+      expect(await cs.getChannel(channelId)).toBeNull()
+    })
+
+    test('preserves bigint fields', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      const ch = makeChannel({
+        deposit: 999_999_999_999_999_999n,
+        settledOnChain: 123_456_789n,
+        highestVoucherAmount: 888_888_888n,
+        spent: 42n,
+      })
+      await cs.updateChannel(channelId, () => ch)
+
+      const loaded = await cs.getChannel(channelId)
+      expect(loaded!.deposit).toBe(999_999_999_999_999_999n)
+      expect(loaded!.settledOnChain).toBe(123_456_789n)
+      expect(loaded!.highestVoucherAmount).toBe(888_888_888n)
+      expect(loaded!.spent).toBe(42n)
+    })
+  })
+
+  describe('waitForUpdate', () => {
+    test('resolves on next updateChannel call', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs)
+
+      let resolved = false
+      const waiter = cs.waitForUpdate!(channelId).then(() => {
+        resolved = true
+      })
+
+      await sleep(10)
+      expect(resolved).toBe(false)
+
+      await cs.updateChannel(channelId, (c) => (c ? { ...c, spent: 1n } : null))
+      await waiter
+      expect(resolved).toBe(true)
+    })
+
+    test('multiple waiters all resolve', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs)
+
+      let count = 0
+      const w1 = cs.waitForUpdate!(channelId).then(() => count++)
+      const w2 = cs.waitForUpdate!(channelId).then(() => count++)
+      const w3 = cs.waitForUpdate!(channelId).then(() => count++)
+
+      await cs.updateChannel(channelId, (c) => (c ? { ...c, spent: 1n } : null))
+      await Promise.all([w1, w2, w3])
+      expect(count).toBe(3)
+    })
+
+    test('different channels are independent', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs)
+      await cs.updateChannel(channelId2, () => makeChannel({ channelId: channelId2 }))
+
+      let ch1Resolved = false
+      cs.waitForUpdate!(channelId).then(() => {
+        ch1Resolved = true
+      })
+
+      await cs.updateChannel(channelId2, (c) => (c ? { ...c, spent: 1n } : null))
+      await sleep(10)
+      expect(ch1Resolved).toBe(false)
+    })
+  })
+})
+
+// ---------- ChannelStore.deductFromChannel ----------
+
+describe('ChannelStore.deductFromChannel', () => {
+  test('deducts when balance is sufficient', async () => {
+    const cs = ChannelStore.fromStore(Store.memory())
+    await seedChannel(cs, { highestVoucherAmount: 5_000_000n, spent: 0n })
+
+    const result = await ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)
+    expect(result.ok).toBe(true)
+    expect(result.channel.spent).toBe(1_000_000n)
+    expect(result.channel.units).toBe(1)
+  })
+
+  test('returns ok: false when balance insufficient', async () => {
+    const cs = ChannelStore.fromStore(Store.memory())
+    await seedChannel(cs, { highestVoucherAmount: 1_000_000n, spent: 500_000n })
+
+    const result = await ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)
+    expect(result.ok).toBe(false)
+    expect(result.channel.spent).toBe(500_000n)
+  })
+
+  test('throws when channel does not exist', async () => {
+    const cs = ChannelStore.fromStore(Store.memory())
+    await expect(ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)).rejects.toThrow(
+      'channel not found',
+    )
+  })
+
+  test('exact balance succeeds', async () => {
+    const cs = ChannelStore.fromStore(Store.memory())
+    await seedChannel(cs, { highestVoucherAmount: 1_000_000n, spent: 0n })
+
+    const result = await ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)
+    expect(result.ok).toBe(true)
+    expect(result.channel.spent).toBe(1_000_000n)
+  })
+
+  test('sequential deductions accumulate correctly', async () => {
+    const cs = ChannelStore.fromStore(Store.memory())
+    await seedChannel(cs, { highestVoucherAmount: 5_000_000n, spent: 0n })
+
+    for (let i = 0; i < 5; i++) {
+      const result = await ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)
+      expect(result.ok).toBe(true)
+      expect(result.channel.spent).toBe(BigInt((i + 1) * 1_000_000))
+      expect(result.channel.units).toBe(i + 1)
+    }
+
+    const final = await ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)
+    expect(final.ok).toBe(false)
+  })
+})
+
+// ---------- Concurrency ----------
+
+describe('concurrency', () => {
+  describe('with update (atomic backend)', () => {
+    test('concurrent deductions do not lose updates', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs, { highestVoucherAmount: 100_000_000n, spent: 0n })
+
+      const N = 50
+      const results = await Promise.all(
+        Array.from({ length: N }, () => ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)),
+      )
+
+      const successes = results.filter((r) => r.ok).length
+      expect(successes).toBe(N)
+
+      const channel = await cs.getChannel(channelId)
+      expect(channel!.spent).toBe(BigInt(N * 1_000_000))
+      expect(channel!.units).toBe(N)
+    })
+
+    test('concurrent deductions respect balance limit', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs, { highestVoucherAmount: 3_000_000n, spent: 0n })
+
+      const N = 10
+      const results = await Promise.all(
+        Array.from({ length: N }, () => ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)),
+      )
+
+      const successes = results.filter((r) => r.ok).length
+      const failures = results.filter((r) => !r.ok).length
+      expect(successes).toBe(3)
+      expect(failures).toBe(7)
+
+      const channel = await cs.getChannel(channelId)
+      expect(channel!.spent).toBe(3_000_000n)
+      expect(channel!.units).toBe(3)
+    })
+
+    test('concurrent updates to different channels are independent', async () => {
+      const cs = ChannelStore.fromStore(Store.memory())
+      await seedChannel(cs, { highestVoucherAmount: 10_000_000n, spent: 0n })
+      await cs.updateChannel(channelId2, () =>
+        makeChannel({ channelId: channelId2, highestVoucherAmount: 10_000_000n, spent: 0n }),
+      )
+
+      const N = 20
+      const [results1, results2] = await Promise.all([
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(cs, channelId, 1_000_000n),
+          ),
+        ),
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(cs, channelId2, 1_000_000n),
+          ),
+        ),
+      ])
+
+      expect(results1.filter((r) => r.ok).length).toBe(10)
+      expect(results2.filter((r) => r.ok).length).toBe(10)
+
+      const ch1 = await cs.getChannel(channelId)
+      const ch2 = await cs.getChannel(channelId2)
+      expect(ch1!.spent).toBe(10_000_000n)
+      expect(ch2!.spent).toBe(10_000_000n)
+    })
+  })
+
+  describe('with mutex fallback (no update method)', () => {
+    test('concurrent deductions do not lose updates', async () => {
+      const cs = ChannelStore.fromStore(stripUpdateMethod(Store.memory()))
+      await seedChannel(cs, { highestVoucherAmount: 100_000_000n, spent: 0n })
+
+      const N = 50
+      const results = await Promise.all(
+        Array.from({ length: N }, () => ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)),
+      )
+
+      const successes = results.filter((r) => r.ok).length
+      expect(successes).toBe(N)
+
+      const channel = await cs.getChannel(channelId)
+      expect(channel!.spent).toBe(BigInt(N * 1_000_000))
+      expect(channel!.units).toBe(N)
+    })
+
+    test('concurrent deductions respect balance limit', async () => {
+      const cs = ChannelStore.fromStore(stripUpdateMethod(Store.memory()))
+      await seedChannel(cs, { highestVoucherAmount: 3_000_000n, spent: 0n })
+
+      const N = 10
+      const results = await Promise.all(
+        Array.from({ length: N }, () => ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)),
+      )
+
+      const successes = results.filter((r) => r.ok).length
+      const failures = results.filter((r) => !r.ok).length
+      expect(successes).toBe(3)
+      expect(failures).toBe(7)
+
+      const channel = await cs.getChannel(channelId)
+      expect(channel!.spent).toBe(3_000_000n)
+      expect(channel!.units).toBe(3)
+    })
+
+    test('mutex serializes async operations', async () => {
+      const s = delayedStore(5)
+      const cs = ChannelStore.fromStore(s)
+      await seedChannel(cs, { highestVoucherAmount: 100_000_000n, spent: 0n })
+
+      const N = 10
+      const results = await Promise.all(
+        Array.from({ length: N }, () => ChannelStore.deductFromChannel(cs, channelId, 1_000_000n)),
+      )
+
+      const successes = results.filter((r) => r.ok).length
+      expect(successes).toBe(N)
+
+      const channel = await cs.getChannel(channelId)
+      expect(channel!.spent).toBe(BigInt(N * 1_000_000))
+      expect(channel!.units).toBe(N)
+    })
+
+    test('mutex does not block different channels', async () => {
+      const cs = ChannelStore.fromStore(stripUpdateMethod(Store.memory()))
+      await seedChannel(cs, { highestVoucherAmount: 10_000_000n, spent: 0n })
+      await cs.updateChannel(channelId2, () =>
+        makeChannel({ channelId: channelId2, highestVoucherAmount: 10_000_000n, spent: 0n }),
+      )
+
+      const N = 20
+      const [results1, results2] = await Promise.all([
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(cs, channelId, 1_000_000n),
+          ),
+        ),
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(cs, channelId2, 1_000_000n),
+          ),
+        ),
+      ])
+
+      expect(results1.filter((r) => r.ok).length).toBe(10)
+      expect(results2.filter((r) => r.ok).length).toBe(10)
+    })
+
+    test('mutex releases on callback error', async () => {
+      const cs = ChannelStore.fromStore(stripUpdateMethod(Store.memory()))
+      await seedChannel(cs)
+
+      await expect(
+        cs.updateChannel(channelId, () => {
+          throw new Error('callback error')
+        }),
+      ).rejects.toThrow('callback error')
+
+      const result = await cs.updateChannel(channelId, (c) => (c ? { ...c, spent: 1n } : null))
+      expect(result!.spent).toBe(1n)
+    })
+  })
+
+  describe('parity: atomic vs mutex produce same results', () => {
+    test('same final state after N concurrent deductions', async () => {
+      const N = 30
+      const balance = 20_000_000n
+      const deduction = 1_000_000n
+
+      const atomicCs = ChannelStore.fromStore(Store.memory())
+      await atomicCs.updateChannel(channelId, () =>
+        makeChannel({ highestVoucherAmount: balance, spent: 0n }),
+      )
+
+      const mutexCs = ChannelStore.fromStore(stripUpdateMethod(Store.memory()))
+      await mutexCs.updateChannel(channelId, () =>
+        makeChannel({ highestVoucherAmount: balance, spent: 0n }),
+      )
+
+      const [atomicResults, mutexResults] = await Promise.all([
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(atomicCs, channelId, deduction),
+          ),
+        ),
+        Promise.all(
+          Array.from({ length: N }, () =>
+            ChannelStore.deductFromChannel(mutexCs, channelId, deduction),
+          ),
+        ),
+      ])
+
+      const atomicSuccesses = atomicResults.filter((r) => r.ok).length
+      const mutexSuccesses = mutexResults.filter((r) => r.ok).length
+      expect(atomicSuccesses).toBe(mutexSuccesses)
+      expect(atomicSuccesses).toBe(20)
+
+      const atomicChannel = await atomicCs.getChannel(channelId)
+      const mutexChannel = await mutexCs.getChannel(channelId)
+      expect(atomicChannel!.spent).toBe(mutexChannel!.spent)
+      expect(atomicChannel!.units).toBe(mutexChannel!.units)
+      expect(atomicChannel!.spent).toBe(balance)
+    })
+  })
+})

package/src/tempo/stream/ChannelStore.ts

@@ -0,0 +1,202 @@
+import type { Address, Hex } from 'viem'
+import type * as Store from '../../Store.js'
+import type { SignedVoucher } from './Types.js'
+
+/**
+ * State for an on-chain payment channel, including per-session accounting.
+ *
+ * Tracks the channel's identity, on-chain balance, the highest voucher
+ * the server has accepted, and the current session's spend counters.
+ * A channel is created when a payer opens an escrow on-chain and persists
+ * until the channel is finalized (closed/settled).
+ *
+ * One channel = one session. The client owns the key and can't race with
+ * itself, so concurrent session support is unnecessary.
+ *
+ * Monotonicity invariants (enforced by update callbacks):
+ * - `highestVoucherAmount` only increases
+ * - `settledOnChain` only increases
+ * - `deposit` reflects the latest on-chain value
+ */
+export interface State {
+  /** Address authorized to sign vouchers on behalf of the payer. */
+  authorizedSigner: Address
+  /** Chain ID the channel was opened on. */
+  chainId: number
+  /** Escrow contract address the channel was opened on. */
+  escrowContract: Address
+  /** Unique identifier for this payment channel. */
+  channelId: Hex
+  /** ISO 8601 timestamp when the channel was created. */
+  createdAt: string
+  /** Current on-chain deposit in the escrow contract. */
+  deposit: bigint
+  /** Whether the channel has been finalized (closed) on-chain. */
+  finalized: boolean
+  /** The signed voucher corresponding to `highestVoucherAmount`. */
+  highestVoucher: SignedVoucher | null
+  /** Highest cumulative voucher amount accepted by the server. */
+  highestVoucherAmount: bigint
+  /** Address of the payment recipient. */
+  payee: Address
+  /** Address of the payment sender. */
+  payer: Address
+  /** Cumulative amount settled on-chain so far. */
+  settledOnChain: bigint
+  /** Cumulative amount spent (charged) against this channel's current session. */
+  spent: bigint
+  /** Token contract address used for payments. */
+  token: Address
+  /** Number of charge operations (API requests) fulfilled in the current session. */
+  units: number
+}
+
+/**
+ * Internal store interface for channel state persistence.
+ *
+ * ## Atomicity contract
+ *
+ * The `updateChannel` method uses an atomic read-modify-write callback.
+ * The callback receives the current state (or `null` if none exists), and
+ * returns the next state (or `null` to delete). Implementations must
+ * guarantee that no concurrent mutation occurs between reading `current`
+ * and writing the return value.
+ *
+ * Backends implement this via their native mechanisms:
+ * - **In-memory / JS single-thread**: Synchronous callback execution
+ * - **Durable Objects**: Single-threaded execution model
+ * - **D1 / SQL**: Database transactions
+ */
+export type ChannelStore = {
+  getChannel(channelId: Hex): Promise<State | null>
+
+  /**
+   * Atomic read-modify-write for channel state.
+   * Return `null` from `fn` to delete the channel.
+   */
+  updateChannel(channelId: Hex, fn: (current: State | null) => State | null): Promise<State | null>
+
+  /**
+   * Wait for the next update to a channel.
+   *
+   * Returns a `Promise` that resolves once `updateChannel` is called for
+   * `channelId`. Implementations should resolve immediately if the channel
+   * was updated between the call to `waitForUpdate` and the `Promise`
+   * being awaited.
+   *
+   * When not implemented, callers fall back to polling.
+   */
+  waitForUpdate?(channelId: Hex): Promise<void>
+}
+
+export type DeductResult = { ok: true; channel: State } | { ok: false; channel: State }
+
+/**
+ * Atomically deduct `amount` from a channel's available balance.
+ *
+ * Returns `{ ok: true, channel }` if the deduction succeeded, or
+ * `{ ok: false, channel }` with the unchanged state if balance is
+ * insufficient. Throws if the channel does not exist.
+ */
+export async function deductFromChannel(
+  store: ChannelStore,
+  channelId: Hex,
+  amount: bigint,
+): Promise<DeductResult> {
+  let deducted = false
+  const channel = await store.updateChannel(channelId, (current) => {
+    deducted = false
+    if (!current) return null
+    if (current.highestVoucherAmount - current.spent >= amount) {
+      deducted = true
+      return { ...current, spent: current.spent + amount, units: current.units + 1 }
+    }
+    return current
+  })
+  if (!channel) throw new Error('channel not found')
+  return { ok: deducted, channel }
+}
+
+/**
+ * Wraps a generic {@link Store} into the internal {@link Store}
+ * interface used by server handlers and the SSE metering loop.
+ *
+ * Provides `waitForUpdate` notifications so the SSE `chargeOrWait` loop
+ * can wake up without polling.
+ *
+ * ## Atomicity
+ *
+ * Mutations use `get` → `fn` → `set` guarded by a per-key in-process
+ * mutex. This serializes concurrent `updateChannel` calls within a
+ * single JS runtime but does **not** protect against races across
+ * multiple processes or instances.
+ *
+ * Backends that need true atomicity (e.g., Durable Objects, D1)
+ * should implement {@link Store} directly.
+ */
+const storeCache = new WeakMap<Store.Store, ChannelStore>()
+
+export function fromStore(store: Store.Store): ChannelStore {
+  const cached = storeCache.get(store)
+  if (cached) return cached
+
+  const waiters = new Map<string, Set<() => void>>()
+  const locks = new Map<string, Promise<void>>()
+
+  function notify(channelId: string) {
+    const set = waiters.get(channelId)
+    if (!set) return
+    for (const resolve of set) resolve()
+    waiters.delete(channelId)
+  }
+
+  async function update(
+    channelId: Hex,
+    fn: (current: State | null) => State | null,
+  ): Promise<State | null> {
+    while (locks.has(channelId)) await locks.get(channelId)
+
+    let release!: () => void
+    locks.set(
+      channelId,
+      new Promise<void>((r) => {
+        release = r
+      }),
+    )
+
+    try {
+      const current = await store.get<State | null>(channelId)
+      const next = fn(current)
+      if (next) await store.put(channelId, next)
+      else await store.delete(channelId)
+      return next
+    } finally {
+      locks.delete(channelId)
+      release()
+    }
+  }
+
+  const cs: ChannelStore = {
+    async getChannel(channelId) {
+      return store.get<State | null>(channelId)
+    },
+    async updateChannel(channelId, fn) {
+      const result = await update(channelId, fn)
+      notify(channelId)
+      return result
+    },
+    waitForUpdate(channelId) {
+      return new Promise<void>((resolve) => {
+        let set = waiters.get(channelId)
+        if (!set) {
+          set = new Set()
+          waiters.set(channelId, set)
+        }
+        set.add(resolve)
+      })
+    },
+  }
+
+  storeCache.set(store, cs)
+  return cs
+}