mppx 0.6.31 → 0.7.0

package/src/tempo/session/ChannelStore.ts

@@ -1,308 +0,0 @@
-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
-  /** On-chain timestamp when a force-close was requested (0n if not requested). */
-  closeRequestedAt: bigint
-  /** 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.
- *
- * Callbacks should be synchronous and deterministic. When a `ChannelStore`
- * is backed by `Store.update()`, adapters may retry them internally.
- *
- * 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>
-
-  /**
-   * Atomic read-modify-write that returns the callback's `result` directly.
-   *
-   * Used by {@link deductFromChannel} to atomically compute the deduction
-   * outcome. When backed by `Store.update()`, this delegates to the store's
-   * native atomic primitive.
-   */
-  updateChannelResult?<result>(
-    channelId: Hex,
-    fn: (current: State | null) => Store.Change<State, result>,
-  ): Promise<result>
-}
-
-export type DeductResult = { ok: true; channel: State } | { ok: false; channel: State }
-
-export function normalizeChannelId(channelId: Hex): Hex {
-  return channelId.toLowerCase() as Hex
-}
-
-function normalizeState(channelId: Hex, state: State): State {
-  return state.channelId === channelId ? state : { ...state, channelId }
-}
-
-function normalizeMaybeState(channelId: Hex, state: State | null): State | null {
-  return state ? normalizeState(channelId, state) : null
-}
-
-/**
- * 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> {
-  if (store.updateChannelResult) {
-    const result = await store.updateChannelResult<DeductResult | null>(
-      channelId,
-      (current): Store.Change<State, DeductResult | null> => {
-        if (!current) return { op: 'noop', result: null }
-        if (current.finalized)
-          return { op: 'noop', result: { ok: false, channel: current } as const }
-        if (current.closeRequestedAt !== 0n)
-          return { op: 'noop', result: { ok: false, channel: current } as const }
-        if (current.highestVoucherAmount - current.spent >= amount) {
-          const next = { ...current, spent: current.spent + amount, units: current.units + 1 }
-          return { op: 'set', value: next, result: { ok: true, channel: next } as const }
-        }
-        return { op: 'noop', result: { ok: false, channel: current } as const }
-      },
-    )
-    if (!result) throw new Error('channel not found')
-    return result
-  }
-
-  let result: DeductResult | null = null
-  const channel = await store.updateChannel(channelId, (current) => {
-    if (!current) return null
-    if (current.finalized) {
-      result = { ok: false, channel: current }
-      return current
-    }
-    if (current.closeRequestedAt !== 0n) {
-      result = { ok: false, channel: current }
-      return current
-    }
-    if (current.highestVoucherAmount - current.spent >= amount) {
-      const next = { ...current, spent: current.spent + amount, units: current.units + 1 }
-      result = { ok: true, channel: next }
-      return next
-    }
-    result = { ok: false, channel: current }
-    return current
-  })
-  if (!channel) throw new Error('channel not found')
-  return result ?? { ok: false, 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 | Store.AtomicStore): ChannelStore {
-  const cached = storeCache.get(store)
-  if (cached) return cached
-
-  const atomicUpdate = 'update' in store ? (store as Store.AtomicStore).update : undefined
-
-  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> {
-    return updateResult(channelId, (current) => {
-      const next = fn(current)
-      if (next) return { op: 'set', value: next, result: next }
-      return { op: 'delete', result: null }
-    })
-  }
-
-  async function updateResult<result>(
-    channelId: Hex,
-    fn: (current: State | null) => Store.Change<State, result>,
-  ): Promise<result> {
-    const normalizedChannelId = normalizeChannelId(channelId)
-    let change: Store.Change<State, result> | undefined
-
-    if (atomicUpdate) {
-      const result = await atomicUpdate(normalizedChannelId, (current) => {
-        change = fn(normalizeMaybeState(normalizedChannelId, (current as State | null) ?? null))
-        if (change.op === 'set') {
-          change = {
-            ...change,
-            value: normalizeState(normalizedChannelId, change.value),
-          }
-        }
-        if (change.op !== 'set') return change
-        return { ...change, value: change.value as never }
-      })
-      if (change?.op !== 'noop') notify(normalizedChannelId)
-      return result
-    }
-
-    while (locks.has(normalizedChannelId)) await locks.get(normalizedChannelId)
-
-    let release!: () => void
-    locks.set(
-      normalizedChannelId,
-      new Promise<void>((r) => {
-        release = r
-      }),
-    )
-
-    try {
-      const current = normalizeMaybeState(
-        normalizedChannelId,
-        (await store.get(normalizedChannelId)) as State | null,
-      )
-      change = fn(current)
-      if (change.op === 'set') {
-        change = {
-          ...change,
-          value: normalizeState(normalizedChannelId, change.value),
-        }
-        await store.put(normalizedChannelId, change.value as never)
-      }
-      if (change.op === 'delete') await store.delete(normalizedChannelId)
-      if (change.op !== 'noop') notify(normalizedChannelId)
-      return change.result
-    } finally {
-      locks.delete(normalizedChannelId)
-      release()
-    }
-  }
-
-  const cs: ChannelStore = {
-    async getChannel(channelId) {
-      const normalizedChannelId = normalizeChannelId(channelId)
-      return normalizeMaybeState(
-        normalizedChannelId,
-        (await store.get(normalizedChannelId)) as State | null,
-      )
-    },
-    async updateChannel(channelId, fn) {
-      return update(channelId, fn)
-    },
-    waitForUpdate(channelId) {
-      return new Promise<void>((resolve) => {
-        const normalizedChannelId = normalizeChannelId(channelId)
-        let set = waiters.get(normalizedChannelId)
-        if (!set) {
-          set = new Set()
-          waiters.set(normalizedChannelId, set)
-        }
-        set.add(resolve)
-      })
-    },
-  }
-
-  cs.updateChannelResult = updateResult
-
-  storeCache.set(store, cs)
-  return cs
-}

package/src/tempo/session/Receipt.test.ts

@@ -1,89 +0,0 @@
-import type { Hex } from 'viem'
-import { describe, expect, test } from 'vp/test'
-
-import {
-  createSessionReceipt,
-  deserializeSessionReceipt,
-  serializeSessionReceipt,
-} from './Receipt.js'
-
-const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
-
-describe('Receipt', () => {
-  test('createSessionReceipt', () => {
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      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(channelId)
-    expect(receipt.challengeId).toBe('test-challenge-id')
-    expect(receipt.channelId).toBe(channelId)
-    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,
-      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,
-      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,
-      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,
-      acceptedCumulative: 1n,
-      spent: 0n,
-    })
-
-    const encoded = serializeSessionReceipt(receipt)
-    // base64url uses - and _ instead of + and /, no = padding
-    expect(encoded).not.toMatch(/[+/=]/)
-  })
-})

package/src/tempo/session/Receipt.ts

@@ -1,46 +0,0 @@
-import { Base64 } from 'ox'
-import type { Hex } from 'viem'
-
-import type { SessionReceipt } from './Types.js'
-
-/**
- * Create a session receipt.
- */
-export function createSessionReceipt(params: {
-  challengeId: string
-  channelId: Hex
-  acceptedCumulative: bigint
-  spent: bigint
-  units?: number | undefined
-  txHash?: Hex | undefined
-}): SessionReceipt {
-  return {
-    method: 'tempo',
-    intent: 'session',
-    status: 'success',
-    timestamp: new Date().toISOString(),
-    reference: params.channelId,
-    challengeId: params.challengeId,
-    channelId: params.channelId,
-    acceptedCumulative: params.acceptedCumulative.toString(),
-    spent: params.spent.toString(),
-    ...(params.units !== undefined && { units: params.units }),
-    ...(params.txHash !== undefined && { txHash: params.txHash }),
-  }
-}
-
-/**
- * Serialize a session receipt to the Payment-Receipt header format.
- */
-export function serializeSessionReceipt(receipt: SessionReceipt): string {
-  const json = JSON.stringify(receipt)
-  return Base64.fromString(json, { pad: false, url: true })
-}
-
-/**
- * Deserialize a Payment-Receipt header value to a session receipt.
- */
-export function deserializeSessionReceipt(encoded: string): SessionReceipt {
-  const json = Base64.toString(encoded)
-  return JSON.parse(json) as SessionReceipt
-}