@did-btcr2/api 0.2.2 → 0.3.0

package/src/bitcoin.ts

@@ -0,0 +1,129 @@
+import {
+  BitcoinConnection,
+  BitcoinCoreRpcClient,
+  BitcoinRestClient,
+  type RawTransactionRest
+} from '@did-btcr2/bitcoin';
+import { assertString } from './helpers.js';
+import type { BitcoinApiConfig } from './types.js';
+
+/**
+ * Bitcoin network operations sub-facade.
+ * Always backed by a {@link BitcoinConnection} so it can be passed to
+ * resolve/update without extra configuration.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} to avoid connection overhead
+ * when Bitcoin features are not used.
+ * @public
+ */
+export class BitcoinApi {
+  /** The underlying BitcoinConnection used for all operations. */
+  readonly connection: BitcoinConnection;
+
+  /** REST client for the active network. */
+  get rest(): BitcoinRestClient {
+    return this.connection.rest;
+  }
+
+  /**
+   * RPC client for the active network, or `undefined` if not configured.
+   * Use {@link requireRpc} when RPC is expected to be available.
+   */
+  get rpc(): BitcoinCoreRpcClient | undefined {
+    return this.connection.rpc;
+  }
+
+  /** Whether an RPC client is available for this network. */
+  get hasRpc(): boolean {
+    return this.connection.rpc !== undefined;
+  }
+
+  /**
+   * RPC client for the active network.
+   * @throws {Error} If RPC was not configured for this network.
+   */
+  requireRpc(): BitcoinCoreRpcClient {
+    const client = this.connection.rpc;
+    if (!client) {
+      throw new Error(
+        'RPC client not configured. Pass an rpc config when creating the BitcoinApi, e.g.: '
+        + '{ network: \'regtest\', rpc: { host: \'http://localhost:18443\', username: \'u\', password: \'p\' } }'
+      );
+    }
+    return client;
+  }
+
+  /**
+   * Create a BitcoinApi for a specific network with optional endpoint overrides.
+   * Uses BitcoinConnection.forNetwork() — no env vars consulted.
+   * @param cfg The network and optional REST/RPC overrides.
+   */
+  constructor(cfg: BitcoinApiConfig) {
+    let executor = cfg.executor;
+    // Wrap the default fetch with a timeout if configured and no custom
+    // executor was provided.
+    if (!executor && cfg.timeoutMs !== undefined) {
+      const ms = cfg.timeoutMs;
+      executor = (req) => fetch(req.url, {
+        method  : req.method,
+        headers : req.headers,
+        body    : req.body,
+        signal  : AbortSignal.timeout(ms),
+      });
+    }
+    this.connection = BitcoinConnection.forNetwork(cfg.network, {
+      rest : cfg.rest,
+      rpc  : cfg.rpc,
+      executor,
+    });
+  }
+
+  /**
+   * Fetch a transaction by txid via REST.
+   * @param txid The transaction ID (64-character hex string).
+   * @returns The fetched transaction.
+   */
+  async getTransaction(txid: string): Promise<RawTransactionRest> {
+    assertString(txid, 'txid');
+    return await this.rest.transaction.get(txid);
+  }
+
+  /**
+   * Broadcast a raw tx (hex) via REST.
+   * @param rawTxHex The raw transaction hex string.
+   */
+  async send(rawTxHex: string) {
+    assertString(rawTxHex, 'rawTxHex');
+    return await this.rest.transaction.send(rawTxHex);
+  }
+
+  /**
+   * Get UTXOs for an address via REST.
+   * @param address The Bitcoin address.
+   */
+  async getUtxos(address: string) {
+    assertString(address, 'address');
+    return await this.rest.address.getUtxos(address);
+  }
+
+  /**
+   * Get a block by hash or height via REST.
+   * @param params Block identifier — at least one of `hash` or `height` is required.
+   */
+  async getBlock(params: { hash?: string; height?: number }) {
+    if (!params.hash && params.height === undefined) {
+      throw new Error('getBlock requires at least one of hash or height.');
+    }
+    return await this.rest.block.get({ blockhash: params.hash, height: params.height });
+  }
+
+  /** Convert BTC to satoshis (integer-safe string-split arithmetic). */
+  static btcToSats(btc: number): number {
+    return BitcoinConnection.btcToSats(btc);
+  }
+
+  /** Convert satoshis to BTC (integer-safe string-split arithmetic). */
+  static satsToBtc(sats: number): number {
+    return BitcoinConnection.satsToBtc(sats);
+  }
+}

package/src/cas.ts

@@ -0,0 +1,121 @@
+import { canonicalize, decode as decodeHash } from '@did-btcr2/common';
+import type { Helia } from 'helia';
+import { CID } from 'multiformats/cid';
+import * as raw from 'multiformats/codecs/raw';
+import { create as createDigest } from 'multiformats/hashes/digest';
+import { sha256 } from 'multiformats/hashes/sha2';
+import { assertString } from './helpers.js';
+
+/**
+ * Executor interface for content-addressed storage.
+ *
+ * Implementations handle the actual I/O (IPFS, HTTP gateway, local store, etc.).
+ * All hashes are base64url-encoded SHA-256 digests (no padding).
+ * @public
+ */
+export interface CasExecutor {
+  /** Retrieve raw bytes by base64url SHA-256 hash. Returns null if not found. */
+  retrieve(hash: string): Promise<Uint8Array | null>;
+  /** Publish raw bytes and return the base64url SHA-256 hash. */
+  publish(data: Uint8Array): Promise<string>;
+}
+
+/**
+ * Default {@link CasExecutor} backed by IPFS via Helia.
+ *
+ * Stores/retrieves data as raw blocks (`0x55` codec) with SHA-256 hashing.
+ * The CID is deterministically derived from the content hash, so lookups
+ * by base64url SHA-256 hash translate directly to CID lookups.
+ * @public
+ */
+export class IpfsCasExecutor implements CasExecutor {
+  readonly #helia: Helia;
+
+  constructor(helia: Helia) {
+    this.#helia = helia;
+  }
+
+  async retrieve(hash: string): Promise<Uint8Array | null> {
+    const hashBytes = decodeHash(hash, 'base64url');
+    const cid = CID.create(1, raw.code, createDigest(sha256.code, hashBytes));
+    try {
+      return await this.#helia.blockstore.get(cid);
+    } catch {
+      return null;
+    }
+  }
+
+  async publish(data: Uint8Array): Promise<string> {
+    const digest = await sha256.digest(data);
+    const cid = CID.createV1(raw.code, digest);
+    await this.#helia.blockstore.put(cid, data);
+    // Return base64url-encoded hash (no padding)
+    return btoa(String.fromCharCode(...digest.bytes.slice(2)))
+      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  }
+}
+
+/**
+ * Configuration for the CAS (Content-Addressed Storage) driver.
+ * @public
+ */
+export type CasConfig = {
+  /** Custom executor implementation (overrides the default IPFS executor). */
+  executor?: CasExecutor;
+  /** Pre-existing Helia instance for the default IPFS executor. */
+  helia?: Helia;
+};
+
+/**
+ * Content-Addressed Storage API sub-facade.
+ *
+ * Provides `publish` and `retrieve` for JSON objects using their
+ * JCS-canonicalized SHA-256 hash as the content address.
+ *
+ * By default uses IPFS (via Helia). Inject a custom {@link CasExecutor}
+ * to use a different CAS backend.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} to avoid startup overhead
+ * when CAS features are not used.
+ * @public
+ */
+export class CasApi {
+  readonly #executor: CasExecutor;
+
+  constructor(config: CasConfig) {
+    if (config.executor) {
+      this.#executor = config.executor;
+    } else if (config.helia) {
+      this.#executor = new IpfsCasExecutor(config.helia);
+    } else {
+      throw new Error(
+        'CAS configuration requires either an executor or a Helia instance. '
+        + 'Example: createApi({ cas: { helia: await createHelia() } })'
+      );
+    }
+  }
+
+  /**
+   * Retrieve a JSON object from the CAS by its base64url SHA-256 hash.
+   * @param hash Base64url-encoded SHA-256 hash of the JCS-canonicalized object.
+   * @returns The parsed JSON object, or `null` if not found.
+   */
+  async retrieve(hash: string): Promise<object | null> {
+    assertString(hash, 'hash');
+    const bytes = await this.#executor.retrieve(hash);
+    if (!bytes) return null;
+    return JSON.parse(new TextDecoder().decode(bytes)) as object;
+  }
+
+  /**
+   * Publish a JSON object to the CAS.
+   * The object is JCS-canonicalized before storage; the returned hash
+   * matches what {@link canonicalHash} would produce.
+   * @param object The JSON object to publish.
+   * @returns The base64url-encoded SHA-256 hash (content address).
+   */
+  async publish(object: object): Promise<string> {
+    const bytes = new TextEncoder().encode(canonicalize(object as Record<string, any>));
+    return await this.#executor.publish(bytes);
+  }
+}