mppx 0.8.17 → 0.8.18

package/src/tempo/server/Relay.ts

@@ -1,297 +0,0 @@
-import { Bytes, Hash, Hex, Json } from 'ox'
-
-import { PaymentExpiredError, VerificationFailedError } from '../../Errors.js'
-import type * as Method from '../../Method.js'
-import * as Receipt from '../../Receipt.js'
-
-const defaultApiBaseUrl = 'https://api.tempo.xyz'
-
-const relayErrorCode = [
-  'already_used',
-  'broadcast_failed',
-  'expired',
-  'invalid_payment',
-  'insufficient_funds',
-  'policy_denied',
-  'screen_rejected',
-  'simulation_failed',
-  'temporarily_unavailable',
-  'unsupported',
-  'unknown',
-] as const
-
-type RelayErrorCode = (typeof relayErrorCode)[number]
-
-/** Error body returned by Tempo API's MPP relay. */
-type RelayError = {
-  /** Stable machine-readable reason the relay rejected the credential. */
-  code: RelayErrorCode
-  /** Human-readable explanation of the relay result. */
-  message?: string | undefined
-}
-
-/** Credential fields accepted by Tempo API's MPP relay. */
-type RelayInput = {
-  /** Challenge from the submitted credential. */
-  challenge: Record<string, unknown>
-  /** Method-specific credential payload. */
-  payload: unknown
-  /** Optional payer identity. */
-  source?: string | undefined
-}
-
-/** Response returned by the MPP relay validation endpoint. */
-type ValidateResponse = { success: true } | { error: RelayError; success: false }
-
-/** Receipt returned by the MPP relay after broadcast. */
-type RelayReceipt = {
-  /** Optional caller-provided payment reference. */
-  externalId?: string | undefined
-  /** Payment method that settled the credential. */
-  method: string
-  /** On-chain or payment-system settlement reference. */
-  reference: string
-  /** RFC 3339 settlement timestamp. */
-  timestamp: string
-}
-
-/** Response returned by the MPP relay broadcast endpoint. */
-type BroadcastResponse =
-  | { receipt: RelayReceipt; success: true }
-  | { error: RelayError; success: false }
-
-/**
- * Configures a Tempo payment method to use Tempo API's MPP relay.
- *
- * The adapter preserves the supplied method's challenge configuration while
- * delegating validation and finalization to `/v1/mpp/validate` and
- * `/v1/mpp/broadcast`. The relay receives every submitted credential: it
- * broadcasts pull transactions and finalizes push transaction hashes without
- * sending them again.
- *
- * @internal
- */
-export function configure<const intent extends Method.Method>(
-  method: Method.Server<intent>,
-  options: configure.Options,
-): configure.Adapter<intent> {
-  const request = createRequest(options)
-
-  const validate: Method.ValidateFn<intent> = async (parameters) => {
-    const input = toRelayInput(parameters.credential)
-    await request.validate(input)
-
-    return {
-      challenge: parameters.credential.challenge,
-      credential: parameters.credential,
-      details: {},
-      intent: method.intent,
-      method: method.name,
-      request: parameters.credential.challenge.request,
-      ...(parameters.credential.source ? { source: parameters.credential.source } : {}),
-    } as Method.Validation<intent>
-  }
-
-  const broadcast: Method.BroadcastFn<intent> = async (parameters) => {
-    const input = toRelayInput(parameters.credential)
-    const receipt = await request.broadcast(input, {
-      idempotencyKey: idempotencyKey(input),
-    })
-    if (receipt.method !== method.name) throw failure()
-    try {
-      return Receipt.from({ ...receipt, status: 'success' })
-    } catch {
-      throw failure()
-    }
-  }
-
-  // Preserve the legacy combined hook for direct method consumers.
-  const verify: Method.VerifyFn<intent> = async (parameters) => {
-    await validate(parameters)
-    return broadcast(parameters)
-  }
-
-  return {
-    ...method,
-    broadcast,
-    verify,
-    validate,
-  } as configure.Adapter<intent>
-}
-
-export declare namespace configure {
-  /**
-   * Server method augmented with Tempo API validation and broadcast hooks.
-   *
-   * The legacy `verify` method validates and broadcasts in one call.
-   */
-  type Adapter<intent extends Method.Method> = Omit<
-    Method.Server<intent>,
-    'broadcast' | 'validate'
-  > & {
-    /** Delegates payment finalization to Tempo API's relay. */
-    broadcast: Method.BroadcastFn<intent>
-    /** Validates the credential through Tempo API. */
-    validate: Method.ValidateFn<intent>
-  }
-
-  /**
-   * Tempo API relay configuration for server-side Tempo charges.
-   *
-   * The adapter sends every credential to the relay for finalization. The
-   * relay broadcasts pull credentials, while it recognizes a push credential
-   * as an already-broadcast transaction and returns its receipt without
-   * sending it again.
-   */
-  type Options = {
-    /** Tempo API key with the `mpp:write` scope. */
-    apiKey: string
-    /** Fetch implementation used to call Tempo API. */
-    fetch?: typeof globalThis.fetch | undefined
-    /** Tempo API base URL, including an optional path prefix. @default 'https://api.tempo.xyz' */
-    apiBaseUrl?: string | undefined
-  }
-
-  /** Stable failure codes returned by Tempo API's MPP relay. */
-  type ErrorCode = RelayErrorCode
-
-  /** Safe relay error details exposed in Payment Auth problem details. */
-  type ErrorDetails =
-    | { code: 'already_used' | 'broadcast_failed' | 'insufficient_funds' | 'invalid_payment' }
-    | { code: 'simulation_failed' | 'unsupported' }
-    | { code: 'temporarily_unavailable'; retry: 'same_credential' }
-}
-
-function createRequest(options: configure.Options) {
-  const fetch = options.fetch ?? globalThis.fetch
-  const apiBaseUrl = new URL(options.apiBaseUrl ?? defaultApiBaseUrl)
-  if (!apiBaseUrl.pathname.endsWith('/')) apiBaseUrl.pathname += '/'
-
-  async function post(
-    path: 'v1/mpp/broadcast' | 'v1/mpp/validate',
-    input: RelayInput,
-    headers?: Record<string, string>,
-  ): Promise<unknown> {
-    let response: Response
-    try {
-      response = await fetch(new URL(path, apiBaseUrl), {
-        body: JSON.stringify(input),
-        headers: {
-          Accept: 'application/json',
-          'content-type': 'application/json',
-          'tempo-api-key': options.apiKey,
-          ...headers,
-        },
-        method: 'POST',
-      })
-    } catch {
-      throw failure()
-    }
-
-    if (!response.ok) throw failure()
-    return response.json().catch(() => undefined)
-  }
-
-  const validate = async (input: RelayInput) => {
-    const response = await post('v1/mpp/validate', input)
-    if (!isValidateSuccess(response)) throw failure(response)
-  }
-
-  const broadcast = async (input: RelayInput, broadcastOptions: { idempotencyKey: string }) => {
-    const response = await post('v1/mpp/broadcast', input, {
-      'idempotency-key': broadcastOptions.idempotencyKey,
-    })
-    if (!isBroadcastSuccess(response)) throw failure(response)
-    return response.receipt
-  }
-
-  return {
-    broadcast,
-    validate,
-  }
-}
-
-function toRelayInput(credential: {
-  challenge: Record<string, unknown>
-  payload: unknown
-  source?: string | undefined
-}): RelayInput {
-  return {
-    challenge: credential.challenge,
-    payload: credential.payload,
-    ...(credential.source ? { source: credential.source } : {}),
-  }
-}
-
-function idempotencyKey(input: RelayInput): string {
-  const payload = input.payload
-  if (
-    isRecord(payload) &&
-    payload.type === 'transaction' &&
-    typeof payload.signature === 'string' &&
-    Hex.validate(payload.signature)
-  ) {
-    const transactionHash = Hash.keccak256(Hex.toBytes(payload.signature), { as: 'Hex' })
-    return `mpp_${transactionHash}`
-  }
-
-  const hash = Hash.sha256(Bytes.fromString(Json.canonicalize(input)), { as: 'Hex' })
-  return `mpp_${hash}`
-}
-
-function failure(value?: unknown) {
-  const code = relayErrorCodeFrom(value)
-  if (code === 'expired') return new PaymentExpiredError()
-
-  const details = code && safeDetails(code)
-  return new VerificationFailedError(details ? { details } : undefined)
-}
-
-function isValidateSuccess(value: unknown): value is Extract<ValidateResponse, { success: true }> {
-  return isRecord(value) && value.success === true
-}
-
-function isBroadcastSuccess(
-  value: unknown,
-): value is Extract<BroadcastResponse, { success: true }> {
-  return isRecord(value) && value.success === true && isRelayReceipt(value.receipt)
-}
-
-function relayErrorCodeFrom(value: unknown): RelayErrorCode | undefined {
-  if (!isRecord(value) || !isRecord(value.error) || !isRelayErrorCode(value.error.code)) return
-  return value.error.code
-}
-
-function isRelayErrorCode(value: unknown): value is RelayErrorCode {
-  return typeof value === 'string' && (relayErrorCode as readonly string[]).includes(value)
-}
-
-function safeDetails(code: RelayErrorCode): configure.ErrorDetails | undefined {
-  switch (code) {
-    case 'already_used':
-    case 'broadcast_failed':
-    case 'insufficient_funds':
-    case 'invalid_payment':
-    case 'simulation_failed':
-    case 'unsupported':
-      return { code }
-    case 'temporarily_unavailable':
-      return { code, retry: 'same_credential' }
-    default:
-      return
-  }
-}
-
-function isRelayReceipt(value: unknown): value is RelayReceipt {
-  return (
-    isRecord(value) &&
-    typeof value.method === 'string' &&
-    typeof value.reference === 'string' &&
-    typeof value.timestamp === 'string' &&
-    (value.externalId === undefined || typeof value.externalId === 'string')
-  )
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}

package/src/tempo/server/SponsorBudget.test.ts

@@ -1,154 +0,0 @@
-import type { Hex } from 'viem'
-import { describe, expect, test } from 'vp/test'
-
-import * as Store from '../../Store.js'
-import * as SponsorBudget from './SponsorBudget.js'
-
-const sponsor = '0x0000000000000000000000000000000000000001'
-const hash1 = `0x${'01'.repeat(32)}` as Hex
-const hash2 = `0x${'02'.repeat(32)}` as Hex
-const storeKey = `mppx:charge:sponsor-budget:42431:${sponsor}` as const
-
-function memoryStore() {
-  return Store.memory() as Parameters<typeof SponsorBudget.reserve>[0]
-}
-
-function parameters(overrides: Partial<Parameters<typeof SponsorBudget.reserve>[1]> = {}) {
-  return {
-    chainId: 42431,
-    expiresAt: Date.now() + 10_000,
-    fee: 1n,
-    getReceipt: async () => {
-      throw new Error('not found')
-    },
-    id: hash1,
-    maxReservations: 10,
-    maxTotalFee: 1n,
-    owner: 'worker-1',
-    sponsor,
-    transactionHash: hash1,
-    waitUntil: Date.now() + 10_000,
-    ...overrides,
-  } satisfies Parameters<typeof SponsorBudget.reserve>[1]
-}
-
-describe('SponsorBudget', () => {
-  test('rejects a transaction larger than the aggregate budget', async () => {
-    const store = memoryStore()
-    await expect(
-      SponsorBudget.reserve(store, parameters({ fee: 2n, maxTotalFee: 1n })),
-    ).rejects.toThrow('fee exceeds the aggregate sponsor budget')
-    expect(await store.get(storeKey)).toBeNull()
-  })
-
-  test('retains pending exposure until a receipt is observed', async () => {
-    const store = memoryStore()
-    let confirmed = false
-    const getReceipt = async (hash: Hex) => {
-      if (hash === hash1 && confirmed) return {}
-      throw new Error('not found')
-    }
-    const first = await SponsorBudget.reserve(store, parameters({ getReceipt }))
-    expect(await SponsorBudget.transition(store, first, 'broadcasting')).toBe(true)
-    expect(await SponsorBudget.transition(store, first, 'pending')).toBe(true)
-
-    const second = SponsorBudget.reserve(
-      store,
-      parameters({
-        getReceipt,
-        id: hash2,
-        owner: 'worker-2',
-        transactionHash: hash2,
-      }),
-    )
-    expect(
-      await Promise.race([
-        second.then(() => 'reserved' as const),
-        new Promise<'waiting'>((resolve) => setTimeout(() => resolve('waiting'), 40)),
-      ]),
-    ).toBe('waiting')
-
-    confirmed = true
-    await expect(second).resolves.toMatchObject({ id: hash2, owner: 'worker-2' })
-    const state = await store.get(storeKey)
-    expect(Object.keys(state!.reservations)).toEqual([hash2])
-  })
-
-  test('does not reconcile a broadcasting reservation before its owner publishes pending', async () => {
-    const store = memoryStore()
-    const getReceipt = async (hash: Hex) => {
-      if (hash === hash1) return {}
-      throw new Error('not found')
-    }
-    const first = await SponsorBudget.reserve(store, parameters({ getReceipt }))
-    expect(await SponsorBudget.transition(store, first, 'broadcasting')).toBe(true)
-
-    const second = SponsorBudget.reserve(
-      store,
-      parameters({
-        getReceipt,
-        id: hash2,
-        owner: 'worker-2',
-        transactionHash: hash2,
-      }),
-    )
-    expect(
-      await Promise.race([
-        second.then(() => 'reserved' as const),
-        new Promise<'waiting'>((resolve) => setTimeout(() => resolve('waiting'), 40)),
-      ]),
-    ).toBe('waiting')
-
-    expect(await SponsorBudget.transition(store, first, 'pending')).toBe(true)
-    await expect(second).resolves.toMatchObject({ id: hash2, owner: 'worker-2' })
-  })
-
-  test('fences release and transition by reservation owner', async () => {
-    const store = memoryStore()
-    const handle = await SponsorBudget.reserve(store, parameters())
-    const staleHandle = { ...handle, owner: 'stale-worker' }
-
-    expect(await SponsorBudget.transition(store, staleHandle, 'broadcasting')).toBe(false)
-    expect(await SponsorBudget.release(store, staleHandle)).toBe(false)
-    expect(await store.get(storeKey)).toMatchObject({
-      reservations: {
-        [hash1]: {
-          owner: 'worker-1',
-          phase: 'prepared',
-          transactionHash: hash1,
-        },
-      },
-    })
-
-    expect(await SponsorBudget.release(store, handle)).toBe(true)
-    expect(await store.get(storeKey)).toBeNull()
-  })
-
-  test('caps reservation count independently of fee exposure', async () => {
-    const store = memoryStore()
-    const first = await SponsorBudget.reserve(
-      store,
-      parameters({ fee: 0n, maxReservations: 1, maxTotalFee: 100n }),
-    )
-    const second = SponsorBudget.reserve(
-      store,
-      parameters({
-        fee: 0n,
-        id: hash2,
-        maxReservations: 1,
-        maxTotalFee: 100n,
-        owner: 'worker-2',
-        transactionHash: hash2,
-      }),
-    )
-
-    expect(
-      await Promise.race([
-        second.then(() => 'reserved' as const),
-        new Promise<'waiting'>((resolve) => setTimeout(() => resolve('waiting'), 40)),
-      ]),
-    ).toBe('waiting')
-    await SponsorBudget.release(store, first)
-    await expect(second).resolves.toMatchObject({ id: hash2 })
-  })
-})

package/src/tempo/server/SponsorBudget.ts

@@ -1,219 +0,0 @@
-import type { Hex } from 'viem'
-
-import { VerificationFailedError } from '../../Errors.js'
-import type * as Store from '../../Store.js'
-
-export type Phase = 'prepared' | 'broadcasting' | 'pending'
-
-export type Reservation = {
-  expiresAt: number
-  fee: string
-  leaseUntil: number
-  owner: string
-  phase: Phase
-  transactionHash: Hex
-}
-
-export type State = {
-  reservations: Record<string, Reservation>
-  version: 1
-}
-
-export type Handle = {
-  chainId: number
-  id: string
-  owner: string
-  sponsor: Hex
-}
-
-type ItemMap = {
-  [key: `mppx:charge:sponsor-budget:${string}`]: State
-}
-
-type ReserveParameters = Handle & {
-  expiresAt: number
-  fee: bigint
-  getReceipt: (hash: Hex) => Promise<unknown>
-  maxReservations: number
-  maxTotalFee: bigint
-  transactionHash: Hex
-  waitUntil: number
-}
-
-const initialPollIntervalMs = 10
-const maxPollIntervalMs = 250
-const preparedLeaseMs = 30_000
-
-function key(parameters: Pick<Handle, 'chainId' | 'sponsor'>) {
-  return `mppx:charge:sponsor-budget:${parameters.chainId}:${parameters.sponsor.toLowerCase()}` as const
-}
-
-function isState(value: State | null): value is State {
-  return value?.version === 1 && typeof value.reservations === 'object'
-}
-
-async function mutateOwned(
-  store: Store.AtomicStore<ItemMap>,
-  handle: Handle,
-  mutate: (reservation: Reservation) => Reservation | null,
-) {
-  return store.update(key(handle), (current) => {
-    if (!isState(current)) return { op: 'noop', result: false }
-    const reservation = current.reservations[handle.id]
-    if (!reservation || reservation.owner !== handle.owner) return { op: 'noop', result: false }
-
-    const reservations = { ...current.reservations }
-    const next = mutate(reservation)
-    if (next) reservations[handle.id] = next
-    else delete reservations[handle.id]
-
-    if (Object.keys(reservations).length === 0) return { op: 'delete', result: true }
-    return {
-      op: 'set',
-      value: { reservations, version: 1 },
-      result: true,
-    }
-  })
-}
-
-async function reconcile(
-  store: Store.AtomicStore<ItemMap>,
-  parameters: Pick<ReserveParameters, 'chainId' | 'getReceipt' | 'sponsor'>,
-) {
-  const state = await store.get(key(parameters))
-  if (!isState(state)) return
-
-  const now = Date.now()
-  await Promise.all(
-    Object.entries(state.reservations).map(async ([id, reservation]) => {
-      const handle = {
-        chainId: parameters.chainId,
-        id,
-        owner: reservation.owner,
-        sponsor: parameters.sponsor,
-      }
-      if (
-        reservation.expiresAt <= now ||
-        (reservation.phase === 'prepared' && reservation.leaseUntil <= now)
-      ) {
-        await release(store, handle)
-        return
-      }
-      // The broadcasting owner has submitted (or is about to submit) the
-      // transaction but has not yet published that outcome to this store.
-      // Releasing its reservation here races the owner's transition to
-      // `pending`: the transaction can settle while the owner observes a lost
-      // reservation and reports a retryable payment failure. Only reconcile
-      // receipts after the owner has completed that hand-off.
-      if (reservation.phase !== 'pending') return
-
-      try {
-        await parameters.getReceipt(reservation.transactionHash)
-      } catch {
-        return
-      }
-      await release(store, handle)
-    }),
-  )
-}
-
-/**
- * Reserves aggregate sponsor fee capacity across processes.
- *
- * Pending broadcasts remain charged to the budget until a receipt is observed
- * or their expiring nonce becomes invalid. Capacity waiters do not rewrite the
- * shared state while waiting.
- *
- * @internal
- */
-export async function reserve(
-  store: Store.AtomicStore<ItemMap>,
-  parameters: ReserveParameters,
-): Promise<Handle> {
-  if (parameters.fee > parameters.maxTotalFee)
-    throw new VerificationFailedError({
-      reason: 'Sponsored transaction fee exceeds the aggregate sponsor budget',
-    })
-
-  let pollIntervalMs = initialPollIntervalMs
-  for (;;) {
-    const now = Date.now()
-    if (now >= parameters.waitUntil)
-      throw new VerificationFailedError({
-        reason: 'Sponsored transaction expired while waiting for sponsor budget',
-      })
-
-    await reconcile(store, parameters)
-    const result = await store.update(key(parameters), (current) => {
-      if (current !== null && !isState(current)) return { op: 'noop', result: 'invalid' as const }
-
-      const reservations = { ...(current?.reservations ?? {}) }
-      const existing = reservations[parameters.id]
-      if (existing) return { op: 'noop', result: 'duplicate' as const }
-
-      const values = Object.values(reservations)
-      const totalFee = values.reduce((total, reservation) => total + BigInt(reservation.fee), 0n)
-      if (
-        values.length >= parameters.maxReservations ||
-        totalFee + parameters.fee > parameters.maxTotalFee
-      )
-        return { op: 'noop', result: 'wait' as const }
-
-      reservations[parameters.id] = {
-        expiresAt: parameters.expiresAt,
-        fee: parameters.fee.toString(),
-        leaseUntil: Math.min(parameters.expiresAt, now + preparedLeaseMs),
-        owner: parameters.owner,
-        phase: 'prepared',
-        transactionHash: parameters.transactionHash,
-      }
-      return {
-        op: 'set',
-        value: { reservations, version: 1 },
-        result: 'reserved' as const,
-      }
-    })
-
-    if (result === 'reserved') return parameters
-    if (result === 'invalid')
-      throw new VerificationFailedError({
-        reason: 'Sponsor budget store contains incompatible state',
-      })
-    if (result === 'duplicate')
-      throw new VerificationFailedError({
-        reason: 'Sponsored transaction already has a budget reservation',
-      })
-
-    await new Promise((resolve) =>
-      setTimeout(resolve, Math.min(pollIntervalMs, parameters.waitUntil - now)),
-    )
-    pollIntervalMs = Math.min(pollIntervalMs * 2, maxPollIntervalMs)
-  }
-}
-
-/**
- * Advances a reservation before and after the broadcast call.
- *
- * The owner token fences stale workers from mutating a replacement reservation.
- *
- * @internal
- */
-export async function transition(
-  store: Store.AtomicStore<ItemMap>,
-  handle: Handle,
-  phase: Exclude<Phase, 'prepared'>,
-): Promise<boolean> {
-  return mutateOwned(store, handle, (reservation) => ({
-    ...reservation,
-    phase,
-  }))
-}
-
-/**
- * Releases a reservation only when the caller still owns it.
- *
- * @internal
- */
-export async function release(store: Store.AtomicStore<ItemMap>, handle: Handle): Promise<boolean> {
-  return mutateOwned(store, handle, () => null)
-}