@obbyx/x402-obyte 0.0.0-stage → 0.2.0

package/src/batch/store.ts

@@ -0,0 +1,359 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { ObbyxError } from '@obbyx/obyte';
+
+/**
+ * Facilitator-side storage for `batch-settlement` (ADR-0003), sharing the
+ * facilitator's SQLite connection (one process per database file).
+ *
+ * - `batch_channels`: per (network, aa) the committed cumulative amount for the
+ *   current period and at most ONE pending commitment (serialization, MVP).
+ * - `batch_commitments`: the journal. `seq` is global and monotonic; the seller's
+ *   watcher reads it by cursor. An entry is `pending` until the watcher has
+ *   durably stored it (ack), then `committed`.
+ *
+ * Amounts are decimal strings (BigInt in code).
+ */
+export interface ChannelRow {
+  readonly key: string;
+  readonly network: string;
+  readonly aa: string;
+  readonly payTo: string;
+  readonly payer: string;
+  readonly asset: string;
+  readonly period: number;
+  readonly committed: bigint;
+  readonly pendingSeq: number | null;
+}
+
+export type CommitmentState = 'pending' | 'committed';
+
+export interface CommitmentRow {
+  readonly seq: number;
+  readonly channelKey: string;
+  readonly network: string;
+  readonly aa: string;
+  readonly payTo: string;
+  readonly period: number;
+  readonly amountSpent: bigint;
+  readonly paymentAmount: bigint;
+  readonly binding: string;
+  readonly packageHash: string;
+  readonly packageJson: string;
+  readonly state: CommitmentState;
+}
+
+export type AppendResult =
+  | { ok: true; commitment: CommitmentRow }
+  | {
+      ok: false;
+      reason: 'channel_busy' | 'cumulative_amount_mismatch' | 'period_mismatch';
+      committed: bigint;
+    };
+
+export interface AppendInput {
+  channelKey: string;
+  network: string;
+  aa: string;
+  payTo: string;
+  payer: string;
+  asset: string;
+  period: number;
+  amountSpent: bigint;
+  paymentAmount: bigint;
+  binding: string;
+  packageHash: string;
+  packageJson: string;
+}
+
+/** Port for batch-settlement storage (node:sqlite here, Prisma in apps/facilitator). */
+export interface BatchStore {
+  channel(key: string): Promise<ChannelRow | undefined>;
+  commitmentByHash(packageHash: string): Promise<CommitmentRow | undefined>;
+  commitment(seq: number): Promise<CommitmentRow | undefined>;
+  journal(payTo: string, cursor: number, limit?: number): Promise<CommitmentRow[]>;
+  /**
+   * Every still-pending entry of a seller, whatever its seq: on reconnect they
+   * are re-delivered even if the watcher's cursor is past them (stored but the
+   * ack was lost, or stored out of order) — otherwise they would stay pending
+   * forever and block their channels.
+   */
+  pending(payTo: string): Promise<CommitmentRow[]>;
+  /** Atomically: check the channel is free and the cumulative rule, append a pending entry. */
+  appendPending(input: AppendInput): Promise<AppendResult>;
+  /**
+   * pending → committed (idempotent); releases the channel. Only commits a
+   * voucher of `owner` (seller + network): a watcher can never ack — and thus
+   * commit — another seller's voucher. Returns undefined if not owned.
+   */
+  commit(
+    seq: number,
+    owner: { payTo: string; network: string },
+  ): Promise<CommitmentRow | undefined>;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS batch_channels (
+  key TEXT PRIMARY KEY,
+  network TEXT NOT NULL,
+  aa TEXT NOT NULL,
+  pay_to TEXT NOT NULL,
+  payer TEXT NOT NULL,
+  asset TEXT NOT NULL,
+  period INTEGER NOT NULL,
+  committed TEXT NOT NULL,
+  pending_seq INTEGER,
+  updated_at INTEGER NOT NULL
+) STRICT;
+CREATE TABLE IF NOT EXISTS batch_commitments (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  channel_key TEXT NOT NULL,
+  network TEXT NOT NULL,
+  aa TEXT NOT NULL,
+  pay_to TEXT NOT NULL,
+  period INTEGER NOT NULL,
+  amount_spent TEXT NOT NULL,
+  payment_amount TEXT NOT NULL,
+  binding TEXT NOT NULL,
+  package_hash TEXT NOT NULL UNIQUE,
+  package_json TEXT NOT NULL,
+  state TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  committed_at INTEGER
+) STRICT;
+CREATE INDEX IF NOT EXISTS batch_commitments_seller ON batch_commitments(pay_to, seq);
+`;
+
+interface ChannelDbRow {
+  key: string;
+  network: string;
+  aa: string;
+  pay_to: string;
+  payer: string;
+  asset: string;
+  period: number;
+  committed: string;
+  pending_seq: number | null;
+}
+
+interface CommitmentDbRow {
+  seq: number;
+  channel_key: string;
+  network: string;
+  aa: string;
+  pay_to: string;
+  period: number;
+  amount_spent: string;
+  payment_amount: string;
+  binding: string;
+  package_hash: string;
+  package_json: string;
+  state: CommitmentState;
+}
+
+export class SqliteBatchStore implements BatchStore {
+  constructor(
+    private readonly db: DatabaseSync,
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {
+    db.exec(SCHEMA);
+  }
+
+  async channel(key: string): Promise<ChannelRow | undefined> {
+    return this.channelSync(key);
+  }
+
+  private channelSync(key: string): ChannelRow | undefined {
+    const row = this.db.prepare('SELECT * FROM batch_channels WHERE key = ?').get(key) as
+      ChannelDbRow | undefined;
+    return row === undefined ? undefined : toChannel(row);
+  }
+
+  async commitmentByHash(packageHash: string): Promise<CommitmentRow | undefined> {
+    const row = this.db
+      .prepare('SELECT * FROM batch_commitments WHERE package_hash = ?')
+      .get(packageHash) as CommitmentDbRow | undefined;
+    return row === undefined ? undefined : toCommitment(row);
+  }
+
+  async commitment(seq: number): Promise<CommitmentRow | undefined> {
+    return this.commitmentSync(seq);
+  }
+
+  private commitmentSync(seq: number): CommitmentRow | undefined {
+    const row = this.db.prepare('SELECT * FROM batch_commitments WHERE seq = ?').get(seq) as
+      CommitmentDbRow | undefined;
+    return row === undefined ? undefined : toCommitment(row);
+  }
+
+  /** Journal for one seller after `cursor` (both pending and committed). */
+  async pending(payTo: string): Promise<CommitmentRow[]> {
+    const rows = this.db
+      .prepare(
+        "SELECT * FROM batch_commitments WHERE pay_to = ? AND state = 'pending' ORDER BY seq",
+      )
+      .all(payTo) as unknown as CommitmentDbRow[];
+    return rows.map(toCommitment);
+  }
+
+  async journal(payTo: string, cursor: number, limit = 500): Promise<CommitmentRow[]> {
+    const rows = this.db
+      .prepare('SELECT * FROM batch_commitments WHERE pay_to = ? AND seq > ? ORDER BY seq LIMIT ?')
+      .all(payTo, cursor, limit) as unknown as CommitmentDbRow[];
+    return rows.map(toCommitment);
+  }
+
+  /**
+   * Appends a pending commitment if the channel is free and the cumulative
+   * rule holds against the stored state; all in one IMMEDIATE transaction.
+   * A new period (the channel was closed and reopened) resets `committed`.
+   */
+  async appendPending(input: AppendInput): Promise<AppendResult> {
+    return this.tx(() => {
+      let channel = this.channelSync(input.channelKey);
+      const ts = this.now();
+      if (channel === undefined || channel.period < input.period) {
+        if (channel?.pendingSeq != null) {
+          return {
+            ok: false as const,
+            reason: 'channel_busy' as const,
+            committed: channel.committed,
+          };
+        }
+        this.db
+          .prepare(
+            `INSERT INTO batch_channels (key, network, aa, pay_to, payer, asset, period, committed, pending_seq, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, '0', NULL, ?)
+             ON CONFLICT(key) DO UPDATE SET period = excluded.period, committed = '0', updated_at = excluded.updated_at`,
+          )
+          .run(
+            input.channelKey,
+            input.network,
+            input.aa,
+            input.payTo,
+            input.payer,
+            input.asset,
+            input.period,
+            ts,
+          );
+        channel = this.channelSync(input.channelKey);
+      }
+      if (channel === undefined) throw new ObbyxError('store_inconsistent', 'channel row missing');
+      if (channel.period !== input.period) {
+        return {
+          ok: false as const,
+          reason: 'period_mismatch' as const,
+          committed: channel.committed,
+        };
+      }
+      if (channel.pendingSeq !== null) {
+        return {
+          ok: false as const,
+          reason: 'channel_busy' as const,
+          committed: channel.committed,
+        };
+      }
+      if (input.amountSpent !== channel.committed + input.paymentAmount) {
+        return {
+          ok: false as const,
+          reason: 'cumulative_amount_mismatch' as const,
+          committed: channel.committed,
+        };
+      }
+      const res = this.db
+        .prepare(
+          `INSERT INTO batch_commitments
+            (channel_key, network, aa, pay_to, period, amount_spent, payment_amount, binding, package_hash,
+             package_json, state, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`,
+        )
+        .run(
+          input.channelKey,
+          input.network,
+          input.aa,
+          input.payTo,
+          input.period,
+          input.amountSpent.toString(),
+          input.paymentAmount.toString(),
+          input.binding,
+          input.packageHash,
+          input.packageJson,
+          ts,
+        );
+      const seq = Number(res.lastInsertRowid);
+      this.db
+        .prepare('UPDATE batch_channels SET pending_seq = ?, updated_at = ? WHERE key = ?')
+        .run(seq, ts, input.channelKey);
+      const commitment = this.commitmentSync(seq);
+      if (commitment === undefined)
+        throw new ObbyxError('store_inconsistent', 'commitment missing');
+      return { ok: true as const, commitment };
+    });
+  }
+
+  /** Watcher acked `seq` (durably stored): pending → committed. Idempotent. */
+  async commit(
+    seq: number,
+    owner: { payTo: string; network: string },
+  ): Promise<CommitmentRow | undefined> {
+    return this.tx(() => {
+      const c = this.commitmentSync(seq);
+      if (c === undefined || c.payTo !== owner.payTo || c.network !== owner.network)
+        return undefined;
+      if (c.state === 'committed') return c;
+      const ts = this.now();
+      this.db
+        .prepare("UPDATE batch_commitments SET state = 'committed', committed_at = ? WHERE seq = ?")
+        .run(ts, seq);
+      this.db
+        .prepare(
+          `UPDATE batch_channels SET committed = ?, pending_seq = NULL, updated_at = ?
+            WHERE key = ? AND pending_seq = ? AND period = ?`,
+        )
+        .run(c.amountSpent.toString(), ts, c.channelKey, seq, c.period);
+      return this.commitmentSync(seq);
+    });
+  }
+
+  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 toChannel(r: ChannelDbRow): ChannelRow {
+  return {
+    key: r.key,
+    network: r.network,
+    aa: r.aa,
+    payTo: r.pay_to,
+    payer: r.payer,
+    asset: r.asset,
+    period: r.period,
+    committed: BigInt(r.committed),
+    pendingSeq: r.pending_seq,
+  };
+}
+
+function toCommitment(r: CommitmentDbRow): CommitmentRow {
+  return {
+    seq: r.seq,
+    channelKey: r.channel_key,
+    network: r.network,
+    aa: r.aa,
+    payTo: r.pay_to,
+    period: r.period,
+    amountSpent: BigInt(r.amount_spent),
+    paymentAmount: BigInt(r.payment_amount),
+    binding: r.binding,
+    packageHash: r.package_hash,
+    packageJson: r.package_json,
+    state: r.state,
+  };
+}

package/src/batch/watcher-protocol.ts

@@ -0,0 +1,89 @@
+import { type ObyteNetwork, type Verdict, accept, reject, verifySignedPackage } from '@obbyx/obyte';
+import { z } from 'zod';
+
+/**
+ * Facilitator ↔ seller-watcher protocol (ADR-0003), JSON over WebSocket at
+ * `/watcher`.
+ *
+ *   F → W  challenge   {challenge}
+ *   W → F  hello       {network, login: signed {purpose, challenge, network, expires}, cursor, bytesBalance}
+ *   F → W  welcome     {seller}               then replays the journal after `cursor`
+ *   F → W  commitment  {seq, ...voucher}      (pending or committed)
+ *   W → F  ack         {seq}                  ONLY after the voucher is durably stored
+ *   W → F  heartbeat   {cursor, bytesBalance, closing?}   closing: channels the seller is closing (no new vouchers)
+ *   F → W  error       {message}              then close
+ *
+ * The login is an Obyte signed message by the seller's address (payTo), so
+ * only the seller's watcher receives that seller's vouchers. Vouchers are
+ * bearer-sensitive (ADR-0001): never log `signedPackage`.
+ */
+export const WATCHER_LOGIN_PURPOSE = 'obbyx-watcher-login';
+
+export const commitmentMessageSchema = z.object({
+  type: z.literal('commitment'),
+  seq: z.number().int().positive(),
+  network: z.string(),
+  aa: z.string(),
+  period: z.number().int().positive(),
+  amountSpent: z.string().regex(/^\d+$/),
+  paymentAmount: z.string().regex(/^\d+$/),
+  binding: z.string(),
+  signedPackage: z.record(z.string(), z.unknown()),
+  state: z.enum(['pending', 'committed']),
+});
+export type CommitmentMessage = z.infer<typeof commitmentMessageSchema>;
+
+export const serverMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('challenge'), challenge: z.string() }),
+  z.object({ type: z.literal('welcome'), seller: z.string(), network: z.string() }),
+  commitmentMessageSchema,
+  z.object({ type: z.literal('error'), message: z.string() }),
+]);
+export type ServerMessage = z.infer<typeof serverMessageSchema>;
+
+export const clientMessageSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('hello'),
+    network: z.string(),
+    login: z.record(z.string(), z.unknown()),
+    cursor: z.number().int().nonnegative(),
+    bytesBalance: z.string().regex(/^\d+$/),
+    closing: z.array(z.string()).max(10_000).optional(),
+  }),
+  z.object({ type: z.literal('ack'), seq: z.number().int().positive() }),
+  z.object({
+    type: z.literal('heartbeat'),
+    cursor: z.number().int().nonnegative(),
+    bytesBalance: z.string().regex(/^\d+$/),
+    closing: z.array(z.string()).max(10_000).optional(),
+  }),
+]);
+export type ClientMessage = z.infer<typeof clientMessageSchema>;
+
+const loginSchema = z
+  .object({
+    purpose: z.literal(WATCHER_LOGIN_PURPOSE),
+    challenge: z.string(),
+    network: z.string(),
+    expires: z.number().int(),
+  })
+  .strict();
+
+export function loginMessage(challenge: string, network: string, now: number) {
+  return { purpose: WATCHER_LOGIN_PURPOSE, challenge, network, expires: now + 60 };
+}
+
+/** Verifies a watcher login; returns the seller address that signed it. */
+export function verifyWatcherLogin(
+  login: unknown,
+  expected: { challenge: string; network: ObyteNetwork; now: number },
+): Verdict<string> {
+  const verified = verifySignedPackage<unknown>(login, { network: expected.network });
+  if (!verified.ok) return reject('watcher_login', verified.message);
+  const body = loginSchema.safeParse(verified.value.message);
+  if (!body.success) return reject('watcher_login', 'Malformed login message');
+  if (body.data.challenge !== expected.challenge) return reject('watcher_login', 'Wrong challenge');
+  if (body.data.network !== expected.network.caip2) return reject('watcher_login', 'Wrong network');
+  if (body.data.expires < expected.now) return reject('watcher_login', 'Login expired');
+  return accept(verified.value.signer);
+}

package/src/binding/binding.ts

@@ -0,0 +1,50 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { canonical } from '../exact/requirements.js';
+
+/**
+ * Binding of a payment to ONE operation (invariant I1/I2).
+ *
+ * binding = HMAC-SHA256(sellerSecret, canonical{v, sellerId, scheme, quoteId,
+ *           validUntil, method, url, bodyHash, network, asset, amount, payTo})
+ *
+ * - The client signs the binding into its payment (unit data message), so a
+ *   payment cannot be moved to another operation.
+ * - The HMAC makes quotes unforgeable without storing them: on the paid
+ *   request the seller recomputes it from the request and the quote fields.
+ */
+export interface BindingInput {
+  readonly sellerId: string;
+  /** x402 scheme of the offer (a payment of one scheme never counts for another). */
+  readonly scheme: string;
+  readonly quoteId: string;
+  readonly validUntil: number;
+  readonly method: string;
+  /** Path + query string, as requested. */
+  readonly url: string;
+  /** sha256 hex of the request body ('' for none), or a custom fingerprint. */
+  readonly bodyHash: string;
+  readonly network: string;
+  readonly asset: string;
+  readonly amount: string;
+  readonly payTo: string;
+}
+
+export function computeBinding(secret: Uint8Array | string, input: BindingInput): string {
+  return createHmac('sha256', secret)
+    .update(canonical({ v: 1, ...input, method: input.method.toUpperCase() }))
+    .digest('hex');
+}
+
+export function bindingsEqual(a: string, b: string): boolean {
+  const x = Buffer.from(a, 'utf8');
+  const y = Buffer.from(b, 'utf8');
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+export function newQuoteId(): string {
+  return randomBytes(16).toString('base64url');
+}
+
+export function sha256Hex(data: string | Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}

package/src/coins/composer.ts

@@ -0,0 +1,159 @@
+import type obyte from 'obyte';
+import { ObbyxError } from '@obbyx/obyte';
+import { type Logger, moduleLogger } from '@obbyx/obyte/logger';
+import { hubCall } from '../hub/hub-call.js';
+import { parseHistory } from '../hub/schemas.js';
+import type { CoinReservations } from './reservations.js';
+import { type Utxo, inputKey, selectCoins, unspentOutputs } from './selection.js';
+
+/**
+ * Input reservation for client-composed units (ADR-0002 "publication").
+ *
+ * Problem: an `exact` unit is signed by the client but broadcast later by the
+ * facilitator. Until the hub knows it, the hub would pick the SAME coins for
+ * the next unit → double spend, one unit becomes bad.
+ *
+ * Solution: our own coin picker, installed on obyte.js's extension point
+ * `client.api.pickDivisibleCoinsForAmount`. It computes the wallet's unspent
+ * outputs from `light/get_history`, skips reserved ones, reserves what it
+ * picks (SQLite, durable) and binds the reservation to the unit hash. Composes
+ * per wallet are serialized. A reservation ends when the unit is seen on the
+ * ledger (its inputs are then spent for the hub) or, if it never appears, only
+ * after `releaseAfterSeconds` (≥ quote validity + the facilitator's publication
+ * window) — never earlier, because a signed unit can still be published.
+ *
+ * Coin rules mirror an ocore light wallet with `spend_unconfirmed: 'own'`:
+ * outputs of OTHER authors must be stable and at or before `last_ball_mci`;
+ * own unstable outputs (change) may be spent.
+ */
+export interface ReservingComposerOptions {
+  readonly client: obyte.Client;
+  readonly network: string;
+  readonly address: string;
+  readonly reservations: CoinReservations;
+  readonly logger: Logger;
+  /** Minimum age before an unpublished unit's inputs are released (s). */
+  readonly releaseAfterSeconds?: number;
+  readonly hubTimeoutMs?: number;
+  readonly now?: () => number;
+}
+
+/**
+ * Installs the reserving coin picker on an obyte.js client and serializes
+ * composes for the wallet. Use `compose(fn)` around every `client.compose.*`.
+ */
+export class ReservingComposer {
+  private queue: Promise<unknown> = Promise.resolve();
+  private lastPick: Utxo[] = [];
+  private readonly log: Logger;
+  private readonly now: () => number;
+
+  constructor(private readonly options: ReservingComposerOptions) {
+    this.log = moduleLogger(options.logger, 'x402.coins', { address: options.address });
+    this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const api = options.client.api as unknown as Record<string, unknown>;
+    api['pickDivisibleCoinsForAmount'] = (params: {
+      addresses: string[];
+      last_ball_mci: number;
+      amount: number;
+      asset?: string | null;
+    }) => this.pick(params);
+  }
+
+  /** Runs `fn` (which composes exactly one unit) with reservations; returns its unit. */
+  compose<T extends { unit?: unknown }>(
+    fn: () => Promise<T>,
+    opts: { holdUntil?: number } = {},
+  ): Promise<T> {
+    const run = this.queue.then(async () => {
+      await this.sweep();
+      this.lastPick = [];
+      try {
+        const unit = await fn();
+        const hash = typeof unit.unit === 'string' ? unit.unit : undefined;
+        if (hash === undefined) throw new ObbyxError('compose_failed', 'Composed unit has no hash');
+        this.options.reservations.bind(this.options.network, this.lastPick, hash, opts.holdUntil);
+        this.log.debug({ unit: hash, inputs: this.lastPick.length }, 'inputs reserved for unit');
+        return unit;
+      } catch (err) {
+        this.options.reservations.releaseUnbound(this.options.network, this.lastPick);
+        throw err;
+      } finally {
+        this.lastPick = [];
+      }
+    });
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** Releases the inputs of a unit that was composed but provably never sent anywhere. */
+  discard(unit: string): void {
+    this.options.reservations.endUnit(this.options.network, unit);
+  }
+
+  /** Ends reservations of units now known to the hub, or provably expired. */
+  async sweep(): Promise<void> {
+    const { reservations, network, client } = this.options;
+    const releaseAfter = this.options.releaseAfterSeconds ?? 1200;
+    reservations.dropStaleUnbound(network, this.now() - 600);
+    for (const { unit, reservedAt, holdUntil } of reservations.boundUnits(network)) {
+      const res = await hubCall(
+        () => client.api.getJoint(unit),
+        this.options.hubTimeoutMs ?? 15_000,
+      );
+      if (res.kind !== 'ok') return; // unknown: keep everything reserved (fail-safe)
+      if (res.value.joint !== undefined) {
+        reservations.endUnit(network, unit); // the hub knows the spend now
+      } else if (this.now() - reservedAt > releaseAfter && this.now() > (holdUntil ?? 0)) {
+        reservations.endUnit(network, unit);
+        this.log.info({ unit }, 'unit was never published; inputs released');
+      }
+    }
+  }
+
+  private async pick(params: {
+    addresses: string[];
+    last_ball_mci: number;
+    amount: number;
+    asset?: string | null;
+  }) {
+    const { client, network, address, reservations } = this.options;
+    if (params.addresses.length !== 1 || params.addresses[0] !== address) {
+      throw new ObbyxError('coins_wrong_address', 'The reserving picker serves a single address');
+    }
+    const asset = params.asset ?? 'base';
+    const t = this.options.hubTimeoutMs ?? 15_000;
+    const history = await hubCall(
+      () =>
+        client.api
+          .getWitnesses()
+          .then((witnesses) => client.api.getHistory({ witnesses, addresses: [address] } as never)),
+      t,
+    );
+    if (history.kind !== 'ok')
+      throw new ObbyxError('ledger_unavailable', `history: ${history.error}`);
+    const parsedHistory = parseHistory(history.value);
+    if (parsedHistory === undefined)
+      throw new ObbyxError('ledger_unavailable', 'history: malformed hub answer');
+    const joints = parsedHistory.joints;
+    const reserved = reservations.reservedKeys(network);
+    const free = unspentOutputs(joints, address, params.last_ball_mci).filter(
+      (u) => !reserved.has(inputKey(network, u)),
+    );
+    const picked = selectCoins(free, asset, BigInt(params.amount));
+    if (picked === undefined) {
+      throw new ObbyxError(
+        'insufficient_funds',
+        `Not enough unreserved ${asset} (some coins may be reserved by pending payments)`,
+      );
+    }
+    reservations.reserve(network, address, picked);
+    this.lastPick.push(...picked);
+    return {
+      inputs_with_proofs: picked.map((u) => ({
+        input: { unit: u.unit, message_index: u.messageIndex, output_index: u.outputIndex },
+      })),
+      total_amount: Number(picked.reduce((s, u) => s + u.amount, 0n)),
+    };
+  }
+}

package/src/coins/index.ts

@@ -0,0 +1,9 @@
+export { type ReservationRow, CoinReservations } from './reservations.js';
+export {
+  type HistoryJoint,
+  type Utxo,
+  inputKey,
+  selectCoins,
+  unspentOutputs,
+} from './selection.js';
+export { ReservingComposer, type ReservingComposerOptions } from './composer.js';