@obbyx/x402-obyte 0.0.0-stage → 0.1.0

package/src/exact/requirements.ts

@@ -0,0 +1,109 @@
+import type { PaymentPayload, PaymentRequirements } from '@x402/core/types';
+import {
+  type ObyteNetwork,
+  type Verdict,
+  accept,
+  getNetwork,
+  isAddress,
+  isAssetId,
+  isObyteNetwork,
+  parseAmount,
+  reject,
+} from '@obbyx/obyte';
+import { z } from 'zod';
+
+export const EXACT_SCHEME = 'exact';
+
+/**
+ * Scheme-specific `extra` of x402 PaymentRequirements for `exact` on Obyte.
+ *
+ * `binding` is computed by the seller per request (an HMAC over the quote and
+ * the request fingerprint, see `@obbyx/sdk`) and must be signed by the client
+ * inside the unit's data message. `quoteId`/`validUntil` bound the offer.
+ */
+export const exactExtraSchema = z
+  .object({
+    binding: z.string().regex(/^[0-9a-f]{64}$/, 'binding must be 64 lowercase hex chars'),
+    quoteId: z
+      .string()
+      .min(8)
+      .max(64)
+      .regex(/^[A-Za-z0-9_-]+$/),
+    validUntil: z.number().int().positive(),
+    // x402 §6.1: Obyte supports the `upfront` flow (settle, then serve) and the
+    // default `authorization` flow; `escrow` and any asset transfer method
+    // (there is none on Obyte: the payer signs the transfer itself) are refused.
+    paymentFlow: z.enum(['authorization', 'upfront']).optional(),
+  })
+  .strict();
+
+export type ExactExtra = z.infer<typeof exactExtraSchema>;
+
+export interface ParsedExactRequirements {
+  readonly network: ObyteNetwork;
+  readonly asset: string;
+  readonly amount: bigint;
+  readonly payTo: string;
+  readonly maxTimeoutSeconds: number;
+  readonly extra: ExactExtra;
+}
+
+export function parseExactRequirements(req: PaymentRequirements): Verdict<ParsedExactRequirements> {
+  if (req.scheme !== EXACT_SCHEME) return reject('unsupported_scheme', 'Scheme is not exact');
+  if (!isObyteNetwork(req.network)) return reject('invalid_network', 'Not an Obyte network');
+  if (!isAssetId(req.asset)) return reject('invalid_payment_requirements', 'Invalid asset');
+  if (!isAddress(req.payTo)) return reject('invalid_payment_requirements', 'Invalid payTo');
+  if (!Number.isSafeInteger(req.maxTimeoutSeconds) || req.maxTimeoutSeconds <= 0) {
+    return reject('invalid_payment_requirements', 'Invalid maxTimeoutSeconds');
+  }
+  let amount: bigint;
+  try {
+    amount = parseAmount(req.amount);
+  } catch {
+    return reject('invalid_payment_requirements', 'Invalid amount');
+  }
+  if (amount <= 0n) return reject('invalid_payment_requirements', 'Amount must be positive');
+  const extra = exactExtraSchema.safeParse(req.extra);
+  if (!extra.success) {
+    return reject(
+      'invalid_payment_requirements',
+      `Invalid extra: ${extra.error.issues[0]?.message}`,
+    );
+  }
+  return accept({
+    network: getNetwork(req.network),
+    asset: req.asset,
+    amount,
+    payTo: req.payTo,
+    maxTimeoutSeconds: req.maxTimeoutSeconds,
+    extra: extra.data,
+  });
+}
+
+/**
+ * x402 core does not compare the client's `accepted` requirements with the
+ * server's; a mismatch could let a client pay under different terms.
+ */
+export function acceptedMatches(payload: PaymentPayload, req: PaymentRequirements): boolean {
+  const a = payload.accepted;
+  return (
+    a !== undefined &&
+    a.scheme === req.scheme &&
+    a.network === req.network &&
+    a.asset === req.asset &&
+    a.amount === req.amount &&
+    a.payTo === req.payTo &&
+    a.maxTimeoutSeconds === req.maxTimeoutSeconds &&
+    canonical(a.extra) === canonical(req.extra)
+  );
+}
+
+export function canonical(value: unknown): string {
+  return JSON.stringify(value, (_k, v: unknown) =>
+    v && typeof v === 'object' && !Array.isArray(v)
+      ? Object.fromEntries(
+          Object.entries(v as Record<string, unknown>).sort(([x], [y]) => x.localeCompare(y)),
+        )
+      : v,
+  );
+}

package/src/exact/store.ts

@@ -0,0 +1,391 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ObbyxError } from '@obbyx/obyte';
+
+/**
+ * Settlement state machine storage for the `exact` scheme (ADR-0002, ADR-0005).
+ *
+ *   claimed → broadcasting → accepted → stable_good
+ *                  │             └────→ final_bad
+ *                  ├──→ rejected
+ *                  └──→ expired
+ *
+ * - One row per (network, unit). The row is created (claimed) BEFORE the unit
+ *   is broadcast (outbox), so a crash between broadcast and the next write is
+ *   recovered by re-reading non-terminal rows on startup.
+ * - Transitions are compare-and-set on the current state inside one
+ *   SQLite transaction; a lost race returns `false` instead of overwriting.
+ * - One facilitator process per database file: the connection takes an
+ *   exclusive lock at open, so a second process fails fast.
+ */
+export type SettlementState =
+  'claimed' | 'broadcasting' | 'accepted' | 'stable_good' | 'final_bad' | 'rejected' | 'expired';
+
+export const TERMINAL_STATES: ReadonlySet<SettlementState> = new Set([
+  'stable_good',
+  'final_bad',
+  'rejected',
+  'expired',
+]);
+
+export interface SettlementRecord {
+  readonly key: string;
+  readonly network: string;
+  readonly unitHash: string;
+  readonly binding: string;
+  readonly payer: string;
+  readonly payTo: string;
+  readonly asset: string;
+  readonly amount: string;
+  readonly state: SettlementState;
+  /** Signed unit JSON; deleted (null) after a terminal state and retention. */
+  readonly unitJson: string | null;
+  /** After this time (unix s) an unpublished unit is never broadcast. */
+  readonly publishDeadline: number;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export interface NewSettlement {
+  readonly key: string;
+  readonly network: string;
+  readonly unitHash: string;
+  readonly binding: string;
+  readonly payer: string;
+  readonly payTo: string;
+  readonly asset: string;
+  readonly amount: string;
+  readonly unitJson: string;
+  readonly publishDeadline: number;
+}
+
+export interface SettlementEvent {
+  readonly key: string;
+  readonly kind: string;
+  readonly from?: SettlementState | null;
+  readonly to?: SettlementState | null;
+  readonly data?: Record<string, unknown>;
+}
+
+/**
+ * Port for the `exact` settlement state machine (implemented with node:sqlite
+ * here, and with Prisma in apps/facilitator). All implementations must pass
+ * the shared contract tests: unique claim, compare-and-set transitions,
+ * single process per database.
+ */
+export interface SettlementStore {
+  get(key: string): Promise<SettlementRecord | undefined>;
+  claim(input: NewSettlement): Promise<{ created: boolean; record: SettlementRecord }>;
+  transition(
+    key: string,
+    from: readonly SettlementState[],
+    to: SettlementState,
+    patch?: TransitionPatch,
+  ): Promise<SettlementRecord | undefined>;
+  event(event: SettlementEvent): Promise<void>;
+  listActive(limit?: number): Promise<SettlementRecord[]>;
+  events(
+    key: string,
+  ): Promise<{ kind: string; from: string | null; to: string | null; data: unknown }[]>;
+  pruneUnitBodies(olderThan: number): Promise<number>;
+  close(): Promise<void>;
+}
+
+export interface TransitionPatch {
+  readonly lastError?: string | null;
+  readonly incrementAttempts?: boolean;
+  readonly data?: Record<string, unknown>;
+}
+
+export class StoreLockedError extends ObbyxError {
+  constructor(path: string, cause: unknown) {
+    super(
+      'store_locked',
+      `Database ${path} is in use by another facilitator process (one instance per database file)`,
+      { cause, details: { path } },
+    );
+  }
+}
+
+interface Row {
+  key: string;
+  network: string;
+  unit_hash: string;
+  binding: string;
+  payer: string;
+  pay_to: string;
+  asset: string;
+  amount: string;
+  state: SettlementState;
+  unit_json: string | null;
+  publish_deadline: number;
+  attempts: number;
+  last_error: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS exact_settlements (
+  key TEXT PRIMARY KEY,
+  network TEXT NOT NULL,
+  unit_hash TEXT NOT NULL,
+  binding TEXT NOT NULL,
+  payer TEXT NOT NULL,
+  pay_to TEXT NOT NULL,
+  asset TEXT NOT NULL,
+  amount TEXT NOT NULL,
+  state TEXT NOT NULL,
+  unit_json TEXT,
+  publish_deadline INTEGER NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+) STRICT;
+CREATE INDEX IF NOT EXISTS exact_settlements_active ON exact_settlements(state)
+  WHERE state IN ('claimed', 'broadcasting', 'accepted');
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  key TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  from_state TEXT,
+  to_state TEXT,
+  data TEXT
+) STRICT;
+CREATE INDEX IF NOT EXISTS events_key ON events(key);
+`;
+
+export class SqliteSettlementStore implements SettlementStore {
+  private readonly db: DatabaseSync;
+  private readonly now: () => number;
+
+  /**
+   * @param path SQLite file, or `:memory:` for tests.
+   * @param now  Clock in unix seconds (injectable for tests).
+   */
+  constructor(path: string, now: () => number = () => Math.floor(Date.now() / 1000)) {
+    this.now = now;
+    this.db = new DatabaseSync(path);
+    try {
+      this.db.exec('PRAGMA busy_timeout = 0');
+      this.db.exec('PRAGMA journal_mode = WAL');
+      this.db.exec('PRAGMA synchronous = FULL');
+      // Exclusive lock for the lifetime of the connection: a second process
+      // fails on its first write instead of racing us.
+      this.db.exec('PRAGMA locking_mode = EXCLUSIVE');
+      this.db.exec('BEGIN IMMEDIATE');
+      this.db.exec(SCHEMA);
+      this.db.exec('COMMIT');
+    } catch (err) {
+      this.db.close();
+      if (isBusy(err)) throw new StoreLockedError(path, err);
+      throw err;
+    }
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+
+  /** The exclusive connection, shared with other facilitator stores (e.g. BatchStore). */
+  get database(): DatabaseSync {
+    return this.db;
+  }
+
+  async get(key: string): Promise<SettlementRecord | undefined> {
+    return this.getSync(key);
+  }
+
+  private getSync(key: string): SettlementRecord | undefined {
+    const row = this.db.prepare('SELECT * FROM exact_settlements WHERE key = ?').get(key) as
+      Row | undefined;
+    return row === undefined ? undefined : toRecord(row);
+  }
+
+  /**
+   * Inserts a new settlement in state `claimed` unless the key exists.
+   * Returns the stored record and whether this call created it.
+   */
+  async claim(input: NewSettlement): Promise<{ created: boolean; record: SettlementRecord }> {
+    return this.tx(() => {
+      const existing = this.getSync(input.key);
+      if (existing !== undefined) return { created: false, record: existing };
+      const ts = this.now();
+      this.db
+        .prepare(
+          `INSERT INTO exact_settlements
+            (key, network, unit_hash, binding, payer, pay_to, asset, amount, state, unit_json,
+             publish_deadline, attempts, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'claimed', ?, ?, 0, ?, ?)`,
+        )
+        .run(
+          input.key,
+          input.network,
+          input.unitHash,
+          input.binding,
+          input.payer,
+          input.payTo,
+          input.asset,
+          input.amount,
+          input.unitJson,
+          input.publishDeadline,
+          ts,
+          ts,
+        );
+      this.insertEvent({ key: input.key, kind: 'claimed', from: null, to: 'claimed' }, ts);
+      return { created: true, record: this.mustGet(input.key) };
+    });
+  }
+
+  /**
+   * Compare-and-set transition. Returns the new record, or `undefined` if the
+   * current state is not one of `from` (someone else moved it first).
+   */
+  async transition(
+    key: string,
+    from: readonly SettlementState[],
+    to: SettlementState,
+    patch: TransitionPatch = {},
+  ): Promise<SettlementRecord | undefined> {
+    return this.tx(() => {
+      const current = this.getSync(key);
+      if (current === undefined || !from.includes(current.state)) return undefined;
+      const ts = this.now();
+      this.db
+        .prepare(
+          `UPDATE exact_settlements
+             SET state = ?, last_error = ?, attempts = attempts + ?, updated_at = ?
+           WHERE key = ? AND state = ?`,
+        )
+        .run(
+          to,
+          patch.lastError === undefined ? current.lastError : patch.lastError,
+          patch.incrementAttempts === true ? 1 : 0,
+          ts,
+          key,
+          current.state,
+        );
+      this.insertEvent(
+        {
+          key,
+          kind: 'transition',
+          from: current.state,
+          to,
+          ...(patch.data ? { data: patch.data } : {}),
+        },
+        ts,
+      );
+      return this.mustGet(key);
+    });
+  }
+
+  /** Records a non-transition event (e.g. a retry) in the payment journal. */
+  async event(event: SettlementEvent): Promise<void> {
+    this.insertEvent(event, this.now());
+  }
+
+  /** Non-terminal settlements, oldest first — resumed by the recovery worker. */
+  async listActive(limit = 100): Promise<SettlementRecord[]> {
+    const rows = this.db
+      .prepare(
+        `SELECT * FROM exact_settlements
+          WHERE state IN ('claimed', 'broadcasting', 'accepted')
+          ORDER BY updated_at ASC LIMIT ?`,
+      )
+      .all(limit) as unknown as Row[];
+    return rows.map(toRecord);
+  }
+
+  async events(
+    key: string,
+  ): Promise<{ kind: string; from: string | null; to: string | null; data: unknown }[]> {
+    const rows = this.db
+      .prepare('SELECT kind, from_state, to_state, data FROM events WHERE key = ? ORDER BY id')
+      .all(key) as unknown as {
+      kind: string;
+      from_state: string | null;
+      to_state: string | null;
+      data: string | null;
+    }[];
+    return rows.map((r) => ({
+      kind: r.kind,
+      from: r.from_state,
+      to: r.to_state,
+      data: r.data === null ? null : (JSON.parse(r.data) as unknown),
+    }));
+  }
+
+  /** Drops signed unit bodies of terminal settlements older than `olderThan` (unix s). */
+  async pruneUnitBodies(olderThan: number): Promise<number> {
+    const res = this.db
+      .prepare(
+        `UPDATE exact_settlements SET unit_json = NULL
+          WHERE unit_json IS NOT NULL AND updated_at < ?
+            AND state IN ('stable_good', 'final_bad', 'rejected', 'expired')`,
+      )
+      .run(olderThan);
+    return Number(res.changes);
+  }
+
+  private insertEvent(event: SettlementEvent, ts: number): void {
+    this.db
+      .prepare(
+        'INSERT INTO events (ts, key, kind, from_state, to_state, data) VALUES (?, ?, ?, ?, ?, ?)',
+      )
+      .run(
+        ts,
+        event.key,
+        event.kind,
+        event.from ?? null,
+        event.to ?? null,
+        event.data === undefined ? null : JSON.stringify(event.data),
+      );
+  }
+
+  private mustGet(key: string): SettlementRecord {
+    const record = this.getSync(key);
+    if (record === undefined)
+      throw new ObbyxError('store_inconsistent', `Missing settlement ${key}`);
+    return record;
+  }
+
+  private tx<T>(fn: () => T): T {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const result = fn();
+      this.db.exec('COMMIT');
+      return result;
+    } catch (err) {
+      this.db.exec('ROLLBACK');
+      throw err;
+    }
+  }
+}
+
+function toRecord(row: Row): SettlementRecord {
+  return {
+    key: row.key,
+    network: row.network,
+    unitHash: row.unit_hash,
+    binding: row.binding,
+    payer: row.payer,
+    payTo: row.pay_to,
+    asset: row.asset,
+    amount: row.amount,
+    state: row.state,
+    unitJson: row.unit_json,
+    publishDeadline: row.publish_deadline,
+    attempts: row.attempts,
+    lastError: row.last_error,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function isBusy(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return /database is locked|SQLITE_BUSY/i.test(message);
+}

package/src/hub/heartbeat.ts

@@ -0,0 +1,18 @@
+import type obyte from 'obyte';
+
+/**
+ * Keeps an obyte.js hub connection alive. obyte.js does not schedule
+ * heartbeats itself: the application must call `client.api.heartbeat()`
+ * periodically (its WSClient then skips the call if traffic was recent,
+ * and closes a connection whose heartbeat goes unanswered, letting
+ * `reconnect: true` re-establish it). Hubs drop idle peers without this.
+ *
+ * Returns a function that stops the timer.
+ */
+export function startHeartbeat(client: obyte.Client, intervalMs = 10_000): () => void {
+  const timer = setInterval(() => {
+    client.api.heartbeat().catch(() => undefined); // closed/reconnecting: the next tick retries
+  }, intervalMs);
+  timer.unref();
+  return () => clearInterval(timer);
+}

package/src/hub/hub-call.ts

@@ -0,0 +1,46 @@
+/**
+ * Outcome of one obyte.js hub request (ADR-0006, invariant I7).
+ *
+ * obyte.js requests have no timeout. It rejects with the hub's error value
+ * (usually a string) for definite hub errors, and with an `Error` for transport
+ * failures. A timeout or transport failure is an UNKNOWN outcome — for
+ * `postJoint` the unit may have been accepted.
+ */
+export type HubOutcome<T> =
+  | { readonly kind: 'ok'; readonly value: T }
+  | { readonly kind: 'hub_error'; readonly error: string }
+  | { readonly kind: 'unknown'; readonly error: string };
+
+export async function hubCall<T>(
+  request: () => Promise<T>,
+  timeoutMs: number,
+): Promise<HubOutcome<T>> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const value = await Promise.race([
+      request(),
+      new Promise<never>((_, rejectTimeout) => {
+        timer = setTimeout(
+          () => rejectTimeout(new Error(`hub request timed out after ${timeoutMs} ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+    return { kind: 'ok', value };
+  } catch (err) {
+    if (err instanceof Error || err === null || err === undefined) {
+      return { kind: 'unknown', error: err instanceof Error ? err.message : 'no error value' };
+    }
+    return { kind: 'hub_error', error: typeof err === 'string' ? err : safeJson(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/hub/schemas.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { HistoryJoint } from '../coins/index.js';
+
+/**
+ * Shapes of the hub (light vendor) answers we rely on. The hub is trusted for
+ * ledger reads (ADR-0001), but a malformed or unexpected answer must fail
+ * closed ("ledger unavailable"), never crash or be half-read.
+ */
+const safeAmount = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+
+export const paymentPayloadSchema = z
+  .object({
+    asset: z.string().optional(),
+    inputs: z
+      .array(
+        z
+          .object({
+            unit: z.string().optional(),
+            message_index: z.number().int().optional(),
+            output_index: z.number().int().optional(),
+          })
+          .loose(),
+      )
+      .optional(),
+    outputs: z.array(z.object({ address: z.string(), amount: safeAmount }).loose()).optional(),
+  })
+  .loose();
+
+/** A message; payment payloads are validated (positions of messages/outputs are kept). */
+const messageSchema = z
+  .object({ app: z.string(), payload: z.unknown().optional() })
+  .loose()
+  .superRefine((m, ctx) => {
+    if (m.app === 'payment' && !paymentPayloadSchema.safeParse(m.payload).success) {
+      ctx.addIssue({ code: 'custom', message: 'malformed payment payload' });
+    }
+  });
+
+export const ledgerUnitSchema = z
+  .object({
+    unit: z.string(),
+    timestamp: z.number().optional(),
+    main_chain_index: z.number().nullable().optional(),
+    authors: z.array(z.object({ address: z.string() }).loose()).optional(),
+    messages: z.array(messageSchema).default([]),
+  })
+  .loose();
+
+export type LedgerUnit = HistoryJoint['unit'];
+
+const historySchema = z
+  .object({
+    joints: z
+      .array(z.object({ unit: ledgerUnitSchema, ball: z.string().optional() }).loose())
+      .default([]),
+    proofchain_balls: z
+      .array(z.object({ unit: z.string(), is_nonserial: z.boolean().optional() }).loose())
+      .default([]),
+  })
+  .loose();
+
+/** A unit from `get_joint` (undefined when malformed). */
+export function parseLedgerUnit(raw: unknown): LedgerUnit | undefined {
+  const parsed = ledgerUnitSchema.safeParse(raw);
+  return parsed.success ? (parsed.data as unknown as LedgerUnit) : undefined;
+}
+
+export interface ProofchainBall {
+  readonly unit: string;
+  readonly is_nonserial?: boolean | undefined;
+}
+
+/** `light/get_history` (undefined when malformed). */
+export function parseHistory(
+  raw: unknown,
+): { joints: HistoryJoint[]; proofchainBalls: ProofchainBall[] } | undefined {
+  const parsed = historySchema.safeParse(raw);
+  if (!parsed.success) return undefined;
+  return {
+    joints: parsed.data.joints as unknown as HistoryJoint[],
+    proofchainBalls: parsed.data.proofchain_balls,
+  };
+}
+
+/** `light/get_aa_state_vars`: a plain record (undefined when malformed). */
+export function parseStateVars(raw: unknown): Record<string, unknown> | undefined {
+  const parsed = z.record(z.string(), z.unknown()).safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+}