@obbyx/x402-obyte 0.0.0-stage → 0.2.0

package/src/coins/reservations.ts

@@ -0,0 +1,139 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ObbyxError } from '@obbyx/obyte';
+import { type Utxo, inputKey } from './selection.js';
+
+/** Durable (SQLite) reservations of the wallet's coins, bound to the unit that spends them. */
+export interface ReservationRow {
+  input_key: string;
+  network: string;
+  payment_unit: string | null;
+  reserved_at: number;
+}
+
+export class CoinReservations {
+  private readonly db: DatabaseSync;
+
+  constructor(
+    path: string,
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {
+    this.db = new DatabaseSync(path);
+    this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = FULL;
+      PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS coin_reservations (
+        input_key TEXT PRIMARY KEY,
+        network TEXT NOT NULL,
+        address TEXT NOT NULL,
+        payment_unit TEXT,
+        reserved_at INTEGER NOT NULL,
+        hold_until INTEGER
+      ) STRICT;
+    `);
+    // Databases created before hold_until existed.
+    const columns = this.db.prepare('PRAGMA table_info(coin_reservations)').all() as {
+      name: string;
+    }[];
+    if (!columns.some((c) => c.name === 'hold_until')) {
+      this.db.exec('ALTER TABLE coin_reservations ADD COLUMN hold_until INTEGER');
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  reservedKeys(network: string): Set<string> {
+    const rows = this.db
+      .prepare('SELECT input_key FROM coin_reservations WHERE network = ?')
+      .all(network) as unknown as {
+      input_key: string;
+    }[];
+    return new Set(rows.map((r) => r.input_key));
+  }
+
+  /** Reserves all inputs atomically; fails if any is already reserved. */
+  reserve(network: string, address: string, inputs: readonly Utxo[]): void {
+    const ts = this.now();
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const insert = this.db.prepare(
+        'INSERT INTO coin_reservations (input_key, network, address, payment_unit, reserved_at) VALUES (?, ?, ?, NULL, ?)',
+      );
+      for (const u of inputs) insert.run(inputKey(network, u), network, address, ts);
+      this.db.exec('COMMIT');
+    } catch (err) {
+      this.db.exec('ROLLBACK');
+      throw new ObbyxError('coins_reserved', 'An input is already reserved by another payment', {
+        cause: err,
+      });
+    }
+  }
+
+  /**
+   * Binds the inputs reserved for a compose to the resulting unit hash.
+   * `holdUntil`: the unit may still be published until then (offer validity +
+   * the facilitator's publication window), so its inputs are never released earlier.
+   */
+  bind(network: string, inputs: readonly Utxo[], unit: string, holdUntil?: number): void {
+    const update = this.db.prepare(
+      'UPDATE coin_reservations SET payment_unit = ?, hold_until = ? WHERE input_key = ? AND payment_unit IS NULL',
+    );
+    for (const u of inputs) update.run(unit, holdUntil ?? null, inputKey(network, u));
+  }
+
+  /** Releases inputs whose compose failed (no unit was produced). */
+  releaseUnbound(network: string, inputs: readonly Utxo[]): void {
+    const del = this.db.prepare(
+      'DELETE FROM coin_reservations WHERE input_key = ? AND payment_unit IS NULL',
+    );
+    for (const u of inputs) del.run(inputKey(network, u));
+  }
+
+  /** Units with live reservations, oldest first. */
+  boundUnits(network: string): { unit: string; reservedAt: number; holdUntil: number | null }[] {
+    const rows = this.db
+      .prepare(
+        `SELECT payment_unit, MIN(reserved_at) AS reserved_at, MAX(hold_until) AS hold_until
+           FROM coin_reservations
+          WHERE network = ? AND payment_unit IS NOT NULL GROUP BY payment_unit ORDER BY reserved_at`,
+      )
+      .all(network) as unknown as {
+      payment_unit: string;
+      reserved_at: number;
+      hold_until: number | null;
+    }[];
+    return rows.map((r) => ({
+      unit: r.payment_unit,
+      reservedAt: r.reserved_at,
+      holdUntil: r.hold_until,
+    }));
+  }
+
+  /** Ends all reservations of a unit (seen on the ledger, or provably never published). */
+  endUnit(network: string, unit: string): number {
+    return Number(
+      this.db
+        .prepare('DELETE FROM coin_reservations WHERE network = ? AND payment_unit = ?')
+        .run(network, unit).changes,
+    );
+  }
+
+  /** Drops reservations of composes that crashed before producing a unit. */
+  dropStaleUnbound(network: string, olderThan: number): number {
+    return Number(
+      this.db
+        .prepare(
+          'DELETE FROM coin_reservations WHERE network = ? AND payment_unit IS NULL AND reserved_at < ?',
+        )
+        .run(network, olderThan).changes,
+    );
+  }
+
+  rows(): ReservationRow[] {
+    return this.db
+      .prepare('SELECT input_key, network, payment_unit, reserved_at FROM coin_reservations')
+      .all() as unknown as ReservationRow[];
+  }
+}

package/src/coins/selection.ts

@@ -0,0 +1,93 @@
+/** Coin selection from a light history (pure functions). */
+export interface Utxo {
+  readonly unit: string;
+  readonly messageIndex: number;
+  readonly outputIndex: number;
+  readonly asset: string;
+  readonly amount: bigint;
+}
+
+export function inputKey(
+  network: string,
+  u: Pick<Utxo, 'unit' | 'messageIndex' | 'outputIndex'>,
+): string {
+  return `${network}:${u.unit}:${u.messageIndex}:${u.outputIndex}`;
+}
+
+export interface HistoryJoint {
+  unit: {
+    unit: string;
+    main_chain_index?: number | null;
+    authors?: { address: string }[];
+    messages?: {
+      app: string;
+      payload?: {
+        asset?: string;
+        inputs?: { unit?: string; message_index?: number; output_index?: number }[];
+        outputs?: { address: string; amount: number }[];
+      };
+    }[];
+  };
+  ball?: string;
+}
+
+/**
+ * Unspent outputs of `address` from a `light/get_history` response.
+ * Others' outputs count only if stable and at or before `lastBallMci`.
+ */
+export function unspentOutputs(
+  joints: readonly HistoryJoint[],
+  address: string,
+  lastBallMci: number,
+): Utxo[] {
+  const spent = new Set<string>();
+  for (const j of joints) {
+    for (const m of j.unit.messages ?? []) {
+      if (m.app !== 'payment') continue;
+      for (const i of m.payload?.inputs ?? []) {
+        if (i.unit !== undefined) spent.add(`${i.unit}:${i.message_index}:${i.output_index}`);
+      }
+    }
+  }
+  const utxos: Utxo[] = [];
+  for (const j of joints) {
+    const own = j.unit.authors?.some((a) => a.address === address) === true;
+    const stable = j.ball !== undefined;
+    const mci = j.unit.main_chain_index;
+    if (!own && !(stable && typeof mci === 'number' && mci <= lastBallMci)) continue;
+    (j.unit.messages ?? []).forEach((m, messageIndex) => {
+      if (m.app !== 'payment') return;
+      (m.payload?.outputs ?? []).forEach((o, outputIndex) => {
+        if (o.address !== address || spent.has(`${j.unit.unit}:${messageIndex}:${outputIndex}`))
+          return;
+        utxos.push({
+          unit: j.unit.unit,
+          messageIndex,
+          outputIndex,
+          asset: m.payload?.asset ?? 'base',
+          amount: BigInt(o.amount),
+        });
+      });
+    });
+  }
+  return utxos;
+}
+
+/** Largest-first selection until the target is covered. */
+export function selectCoins(
+  utxos: readonly Utxo[],
+  asset: string,
+  target: bigint,
+): Utxo[] | undefined {
+  const candidates = utxos
+    .filter((u) => u.asset === asset)
+    .sort((a, b) => (a.amount > b.amount ? -1 : a.amount < b.amount ? 1 : 0));
+  const picked: Utxo[] = [];
+  let total = 0n;
+  for (const u of candidates) {
+    if (total >= target) break;
+    picked.push(u);
+    total += u.amount;
+  }
+  return total >= target ? picked : undefined;
+}

package/src/exact/client.ts

@@ -0,0 +1,144 @@
+import type {
+  PaymentPayloadContext,
+  PaymentPayloadResult,
+  PaymentRequirements,
+  SchemeNetworkClient,
+} from '@x402/core/types';
+import { ObbyxError, toSafeNumber } from '@obbyx/obyte';
+import { type Logger, moduleLogger } from '@obbyx/obyte/logger';
+import type obyte from 'obyte';
+import type { ReservingComposer } from '../coins/index.js';
+import { type PaymentRequirementsV1, requirementsV1ToV2 } from './facilitator-v1.js';
+import { EXACT_SCHEME, parseExactRequirements } from './requirements.js';
+
+/**
+ * Client side of `exact` on Obyte: composes and signs (but does NOT
+ * broadcast) a unit paying `payTo` with the seller's binding in a data
+ * message — obyte.js `client.compose.message` used directly.
+ *
+ * With a `composer` (ReservingComposer) inputs are reserved per payment and
+ * composes are serialized, so concurrent payments never pick the same coins.
+ */
+export interface ExactObyteClientOptions {
+  /** obyte.js client connected to a hub of `network`. */
+  readonly client: obyte.Client;
+  readonly network: string;
+  readonly privateKey: Uint8Array;
+  readonly logger: Logger;
+  /** Refuse requirements above this amount (atomic units) per asset. */
+  readonly maxAmount?: ReadonlyMap<string, bigint>;
+  /** Reserves inputs and serializes composes (strongly recommended; see coins.ts). */
+  readonly composer?: ReservingComposer;
+  /** Refuse units whose network fees (headers + payload + tps) exceed this (bytes). */
+  readonly maxFee?: bigint;
+}
+
+/**
+ * Inputs of a signed unit stay reserved at least until the offer expires plus
+ * this margin (covers the facilitator's default publication window). An Obyte
+ * unit never expires, so any release is a heuristic; releasing too early can
+ * only make a LATER payment of ours fail (one of two units spending the same
+ * input becomes final-bad), it cannot pay twice.
+ */
+const PUBLICATION_MARGIN_SECONDS = 900;
+
+export class ExactObyteClient implements SchemeNetworkClient {
+  readonly scheme = EXACT_SCHEME;
+  private readonly log: Logger;
+
+  constructor(private readonly options: ExactObyteClientOptions) {
+    this.log = moduleLogger(options.logger, 'x402.exact.client');
+  }
+
+  async createPaymentPayload(
+    x402Version: number,
+    requirements: PaymentRequirements,
+    context?: PaymentPayloadContext,
+  ): Promise<PaymentPayloadResult> {
+    if (x402Version !== 1 && x402Version !== 2) {
+      throw new ObbyxError('invalid_x402_version', 'Only x402 v1 and v2 are supported');
+    }
+    // v1 requirements (maxAmountRequired, plain network name) → v2 shape.
+    const v2 =
+      x402Version === 1
+        ? requirementsV1ToV2(requirements as unknown as PaymentRequirementsV1)
+        : requirements;
+    const parsed = parseExactRequirements(v2);
+    if (!parsed.ok) throw new ObbyxError(parsed.reason, parsed.message);
+    const req = parsed.value;
+    if (req.network.caip2 !== this.options.network) {
+      throw new ObbyxError('invalid_network', `This client pays on ${this.options.network}`);
+    }
+    const cap = this.options.maxAmount?.get(req.asset);
+    if (cap !== undefined && req.amount > cap) {
+      throw new ObbyxError(
+        'amount_over_limit',
+        `Price ${req.amount} exceeds the limit ${cap} for ${req.asset}`,
+      );
+    }
+    if (
+      context?.maxAmountPerPayment !== undefined &&
+      req.amount > BigInt(context.maxAmountPerPayment)
+    ) {
+      throw new ObbyxError('amount_over_limit', 'Price exceeds maxAmountPerPayment');
+    }
+    if (req.extra.validUntil < Math.floor(Date.now() / 1000)) {
+      throw new ObbyxError('quote_expired', 'The payment offer has expired');
+    }
+
+    const output = { address: req.payTo, amount: toSafeNumber(req.amount) };
+    const payment =
+      req.asset === 'base'
+        ? { app: 'payment', payload: { outputs: [output] } }
+        : { app: 'payment', payload: { asset: req.asset, outputs: [output] } };
+    const data = {
+      app: 'data',
+      payload: { x402: { binding: req.extra.binding, quoteId: req.extra.quoteId } },
+    };
+
+    const compose = () =>
+      this.options.client.compose.message('multi', [payment, data] as never, {
+        privateKey: this.options.privateKey,
+        testnet: req.network.testnet,
+      }) as unknown as Promise<Record<string, unknown>>;
+    // The signed unit stays publishable until the offer expires plus the
+    // facilitator's publication window: keep its inputs reserved that long.
+    const holdUntil = req.extra.validUntil + PUBLICATION_MARGIN_SECONDS;
+    const unit = await (this.options.composer
+      ? this.options.composer.compose(compose, { holdUntil })
+      : compose());
+    const fee =
+      BigInt(Number(unit['headers_commission'] ?? 0)) +
+      BigInt(Number(unit['payload_commission'] ?? 0)) +
+      BigInt(Number(unit['tps_fee'] ?? 0)) +
+      BigInt(Number(unit['burn_fee'] ?? 0)); // same total the facilitator checks
+    if (this.options.maxFee !== undefined && fee > this.options.maxFee) {
+      // The unit was never sent anywhere: its inputs can be released at once.
+      this.options.composer?.discard(String(unit['unit']));
+      throw new ObbyxError(
+        'fee_over_limit',
+        `Network fee ${fee} exceeds the limit ${this.options.maxFee} bytes`,
+      );
+    }
+    this.log.info(
+      {
+        proofId: unit['unit'],
+        payTo: req.payTo,
+        asset: req.asset,
+        amount: req.amount.toString(),
+        binding: req.extra.binding,
+      },
+      'payment unit signed (not broadcast)',
+    );
+    // v1: the mechanism returns the complete payload (core passes it through as-is).
+    if (x402Version === 1) {
+      return {
+        x402Version: 1,
+        scheme: EXACT_SCHEME,
+        network: requirements.network,
+        payload: { unit },
+      } as unknown as PaymentPayloadResult;
+    }
+    return { x402Version, payload: { unit } };
+  }
+}

package/src/exact/facilitator-v1.ts

@@ -0,0 +1,137 @@
+import type {
+  Network,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkFacilitator,
+  SettleResponse,
+  VerifyResponse,
+} from '@x402/core/types';
+import { getNetwork, isObyteNetwork } from '@obbyx/obyte';
+import type { ExactObyteFacilitator } from './facilitator.js';
+import { EXACT_SCHEME } from './requirements.js';
+
+/**
+ * x402 **v1** for the Obyte `exact` scheme.
+ *
+ * v1 differs in shape only: plain network names (`obyte-testnet`),
+ * `maxAmountRequired`, `resource`/`mimeType` inside the requirements, and a
+ * payload without `accepted`. This adapter converts to the v2 shapes and runs
+ * the SAME v2 mechanism with the SAME store: settlement keys use the CAIP-2 id,
+ * so a proof spent through v1 can never be spent again through v2 (and vice versa).
+ */
+export interface PaymentRequirementsV1 {
+  readonly scheme: string;
+  readonly network: string;
+  readonly maxAmountRequired: string;
+  readonly resource: string;
+  readonly description: string;
+  readonly mimeType: string;
+  readonly outputSchema?: Record<string, unknown>;
+  readonly payTo: string;
+  readonly maxTimeoutSeconds: number;
+  readonly asset: string;
+  readonly extra: Record<string, unknown>;
+}
+
+export interface PaymentPayloadV1 {
+  readonly x402Version: 1;
+  readonly scheme: string;
+  readonly network: string;
+  readonly payload: Record<string, unknown>;
+}
+
+export function requirementsV1ToV2(req: PaymentRequirementsV1): PaymentRequirements {
+  return {
+    scheme: req.scheme,
+    network: getNetwork(req.network).caip2,
+    asset: req.asset,
+    amount: req.maxAmountRequired,
+    payTo: req.payTo,
+    maxTimeoutSeconds: req.maxTimeoutSeconds,
+    extra: req.extra ?? {},
+  };
+}
+
+export function requirementsV2ToV1(
+  req: PaymentRequirements,
+  resource: { url: string; description?: string; mimeType?: string },
+): PaymentRequirementsV1 {
+  return {
+    scheme: req.scheme,
+    network: getNetwork(req.network).v1Name,
+    maxAmountRequired: req.amount,
+    resource: resource.url,
+    description: resource.description ?? '',
+    mimeType: resource.mimeType ?? '',
+    outputSchema: {},
+    payTo: req.payTo,
+    maxTimeoutSeconds: req.maxTimeoutSeconds,
+    asset: req.asset,
+    extra: req.extra,
+  };
+}
+
+export class ExactObyteFacilitatorV1 implements SchemeNetworkFacilitator {
+  readonly scheme = EXACT_SCHEME;
+  readonly caipFamily = 'obyte-*';
+
+  constructor(private readonly v2: ExactObyteFacilitator) {}
+
+  getExtra(network: Network): Record<string, unknown> | undefined {
+    return this.v2.getExtra(getNetwork(network).caip2);
+  }
+
+  getSigners(): string[] {
+    return [];
+  }
+
+  async verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<VerifyResponse> {
+    const converted = this.convert(payload, requirements);
+    if (!converted.ok) return { isValid: false, invalidReason: converted.reason };
+    return this.v2.verify(converted.payload, converted.requirements);
+  }
+
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<SettleResponse> {
+    const converted = this.convert(payload, requirements);
+    const v1Network = (requirements as unknown as PaymentRequirementsV1).network as Network;
+    if (!converted.ok)
+      return { success: false, errorReason: converted.reason, transaction: '', network: v1Network };
+    const res = await this.v2.settle(converted.payload, converted.requirements);
+    return { ...res, network: v1Network };
+  }
+
+  private convert(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ):
+    | { ok: true; payload: PaymentPayload; requirements: PaymentRequirements }
+    | { ok: false; reason: string } {
+    const p = payload as unknown as PaymentPayloadV1;
+    const r = requirements as unknown as PaymentRequirementsV1;
+    if (p.x402Version !== 1) return { ok: false, reason: 'invalid_x402_version' };
+    if (p.scheme !== EXACT_SCHEME || r.scheme !== EXACT_SCHEME)
+      return { ok: false, reason: 'unsupported_scheme' };
+    if (!isObyteNetwork(r.network) || p.network !== r.network)
+      return { ok: false, reason: 'invalid_network' };
+    if (typeof r.maxAmountRequired !== 'string')
+      return { ok: false, reason: 'invalid_payment_requirements' };
+    const v2req = requirementsV1ToV2(r);
+    // v1 has no `accepted`: the client paid the requirements the server sent.
+    return {
+      ok: true,
+      requirements: v2req,
+      payload: {
+        x402Version: 2,
+        resource: { url: r.resource, description: r.description, mimeType: r.mimeType },
+        accepted: v2req,
+        payload: p.payload,
+      },
+    };
+  }
+}