mppx 0.8.13 → 0.8.14

package/src/tempo/server/Relay.ts

@@ -0,0 +1,288 @@
+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 credential validation and terminal broadcast to
+ * `/v1/mpp/validate` and `/v1/mpp/broadcast` respectively.
+ *
+ * @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'
+  > & {
+    /** Broadcasts the credential through Tempo API. */
+    broadcast: Method.BroadcastFn<intent>
+    /** Validates the credential through Tempo API. */
+    validate: Method.ValidateFn<intent>
+  }
+
+  /** Tempo API relay configuration for server-side Tempo charges. */
+  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 `mppx_${transactionHash}`
+  }
+
+  const hash = Hash.sha256(Bytes.fromString(Json.canonicalize(input)), { as: 'Hex' })
+  return `mppx_${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

@@ -0,0 +1,125 @@
+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('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

@@ -0,0 +1,213 @@
+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
+      }
+      if (reservation.phase === 'prepared') 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)
+}