@did-btcr2/bitcoin 0.3.4 → 0.5.0

package/src/client/rpc/interface.ts

@@ -3,63 +3,98 @@ import {
   ChainInfo,
   CreateRawTxInputs,
   CreateRawTxOutputs,
-  FeeEstimateMode,
+  DerivedAddresses,
   GetBlockParams,
-  RawTransactionResponse
+  ListTransactionsParams,
+  ListTransactionsResult,
+  RawTransactionV2,
+  SignedRawTx,
+  UnspentTxInfo
 } from '../../types.js';
 
 /**
- * General interface for a Bitcoin Core RPC client.\
- * @name BitcoinRpcClient
- * @type {BitcoinRpcClient}
+ * General interface for a Bitcoin Core RPC client.
  */
 export interface BitcoinRpcClient {
-    /** Creates a raw transaction spending specified inputs to specified outputs. */
-    createRawTransaction(inputs: CreateRawTxInputs[], outputs: CreateRawTxOutputs[], locktime?: number, replacable?: boolean): Promise<string>;
-
-    /** Returns the number of blocks in the longest blockchain. */
-    getBlockCount(): Promise<number>;
-
-    /** Gets the hash of a block at a given height. */
-    getBlockHash(height: number): Promise<string>;
-
-    /** Gets detailed information about a specific block. */
-    getBlock({ blockhash, height, verbosity }: GetBlockParams): Promise<BlockResponse | undefined>
-
-    /** Retrieves general blockchain state info. */
-    getBlockchainInfo(): Promise<ChainInfo>;
-
-    /** Gets a new Bitcoin address for receiving payments. */
-    getNewAddress(account?: string): Promise<string>;
-
-    /** Sends raw transaction hex to the Bitcoin network. */
-    sendRawTransaction(
-      hexstring: string,
-      maxfeerate?: number | string,
-      maxBurnAmount?: number | string
-    ): Promise<string>;
-
-    /** Sends bitcoins to a specified address. */
-    sendToAddress(
-        address: string,
-        amount: number,
-        comment?: string,
-        comment_to?: string,
-        subtreactfeefromamount?: boolean,
-        replaceable?: boolean,
-        conf_target?: number,
-        estimate_mode?: FeeEstimateMode,
-    ): Promise<RawTransactionResponse>;
-
-    /** Verifies a signed message. */
-    verifyMessage(address: string, signature: string, message: string): Promise<boolean>;
-
-    signMessage(address: string, message: string): Promise<string>;
-}
+  /** Gets detailed information about a specific block. */
+  getBlock({ blockhash, height, verbosity }: GetBlockParams): Promise<BlockResponse | undefined>;
+
+  /** Returns the number of blocks in the longest blockchain. */
+  getBlockCount(): Promise<number>;
+
+  /** Gets the hash of a block at a given height. */
+  getBlockHash(height: number): Promise<string>;
+
+  /** Retrieves general blockchain state info. */
+  getBlockchainInfo(): Promise<ChainInfo>;
+
+  /** Signs a raw transaction with the wallet's private keys. */
+  signRawTransaction(hexstring: string): Promise<SignedRawTx>;
+
+  /** Sends a raw transaction hex to the Bitcoin network. */
+  sendRawTransaction(hexstring: string, maxfeerate?: number | string, maxBurnAmount?: number | string): Promise<string>;
+
+  /** Signs and sends a raw transaction in one step. */
+  signAndSendRawTransaction(hexstring: string): Promise<string>
+
+  /** Creates, signs, and sends a raw transaction in one step. */
+  createSignSendRawTransaction(inputs: CreateRawTxInputs[], outputs: CreateRawTxOutputs[]): Promise<string>;
+
+  /** Lists transactions in the wallet. */
+  listTransactions(params: ListTransactionsParams): Promise<ListTransactionsResult>;
+
+  /** Creates a raw transaction spending specified inputs to specified outputs. */
+  createRawTransaction(inputs: CreateRawTxInputs[], outputs: CreateRawTxOutputs[], locktime?: number, replacable?: boolean): Promise<string>;
+
+  /** Derives addresses from a descriptor. */
+  deriveAddresses(descriptor: string, range?: Array<number>): Promise<Array<DerivedAddresses>>;
+
+  /** Mines a specified number of blocks to a given address. */
+  generateToAddress(nblocks: number, address: string): Promise<string[]>;
+
+  /** Gets the wallet's balance. */
+  getBalance(): Promise<number>;
 
-export function isBitcoinRpcClient(obj: any): obj is BitcoinRpcClient {
-  return obj &&
-    typeof obj.getBlockCount === 'function' &&
-    typeof obj.getBlockHash === 'function' &&
-    typeof obj.getBlockchainInfo === 'function';
-}
+  /** Gets a new Bitcoin address for receiving payments. */
+  getNewAddress(addressType: string, label?: string): Promise<string>;
+
+  /** Lists unspent transaction outputs in the wallet. */
+  listUnspent(params: { minconf?: number; maxconf?: number; address?: string[]; include_unsafe?: boolean; }): Promise<UnspentTxInfo[]>
+
+  /** Creates a raw transaction spending specified inputs to specified outputs. */
+  createRawTransaction(inputs: CreateRawTxInputs[], outputs: CreateRawTxOutputs[], locktime?: number, replacable?: boolean): Promise<string>;
+
+  /** Returns the number of blocks in the longest blockchain. */
+  getBlockCount(): Promise<number>;
+
+  /** Gets the hash of a block at a given height. */
+  getBlockHash(height: number): Promise<string>;
+
+  /** Gets detailed information about a specific block. */
+  getBlock({ blockhash, height, verbosity }: GetBlockParams): Promise<BlockResponse | undefined>
+
+  /** Retrieves general blockchain state info. */
+  getBlockchainInfo(): Promise<ChainInfo>;
+
+  /** Gets a new Bitcoin address for receiving payments. */
+  getNewAddress(account?: string): Promise<string>;
+
+  /** Sends raw transaction hex to the Bitcoin network. */
+  sendRawTransaction(
+    hexstring: string,
+    maxfeerate?: number | string,
+    maxBurnAmount?: number | string
+  ): Promise<string>;
+
+  /** Sends bitcoins to a specified address. */
+  sendToAddress(address: string, amount: number): Promise<RawTransactionV2>;
+
+  /** Verifies a signed message. */
+  verifyMessage(address: string, signature: string, message: string): Promise<boolean>;
+
+  /** Sign a message with the private key of an address. */
+  signMessage(address: string, message: string): Promise<string>;
+
+  /** Mines a specified number of blocks to a given address. */
+  generateToAddress(nblocks: number, address: string): Promise<string[]>;
+}

package/src/client/rpc/json-rpc.ts

@@ -1,81 +1,74 @@
-import { BatchOption, RpcClientConfig } from '../../types.js';
-import { safeText, toBase64 } from '../utils.js';
+import { BitcoinRpcError } from '../../errors.js';
+import { RpcConfig } from '../../types.js';
+import { HttpExecutor, defaultHttpExecutor } from '../http.js';
+import { safeText } from '../utils.js';
+import { JsonRpcProtocol } from './protocol.js';
 
 export class JsonRpcTransport {
-  private url: string;
-  private authHeader?: string;
-  private id = 0;
+  /**
+   * The sans-I/O protocol layer.  Use this to build {@link HttpRequest}
+   * descriptors without performing any I/O.
+   */
+  readonly protocol: JsonRpcProtocol;
 
-  constructor(cfg: RpcClientConfig) {
-    this.url = (cfg.host || 'http://127.0.0.1:8332').replace(/\/+$/, '');
+  private readonly execute: HttpExecutor;
 
-    if (cfg.username && cfg.password) {
-      this.authHeader = `Basic ${toBase64(`${cfg.username}:${cfg.password}`)}`;
-    } else {
-      try {
-        const u = new URL(this.url);
-        if (u.username || u.password) {
-          this.authHeader = `Basic ${toBase64(`${decodeURIComponent(u.username)}:${decodeURIComponent(u.password)}`)}`;
-          u.username = ''; u.password = '';
-          this.url = u.toString().replace(/\/+$/, '');
-        }
-      } catch(error: any) {
-        console.error(`Invalid URL in Bitcoin RPC config: ${this.url}`, error);
-      }
-    }
+  constructor(cfg: RpcConfig, executor?: HttpExecutor) {
+    this.protocol = new JsonRpcProtocol(cfg);
+    this.execute = executor ?? defaultHttpExecutor;
+  }
+
+  /** @internal Expose URL for tests that inspect transport state. */
+  get url(): string {
+    return this.protocol.url;
   }
 
   /**
-   * Make a JSON-RPC call or batch of calls to the Bitcoin node.
-   * @param {BatchOption[] | { method: string; parameters?: any[] }} batch A single RPC call or an array of calls to be made.
-   * @returns {Promise<any[] | any>} The result of the RPC call(s).
-   * @example
+   * Execute a single JSON-RPC call.
    */
-  async command(batch: BatchOption[] | { method: string; parameters?: any[] }): Promise<any[] | any> {
-    if (Array.isArray(batch)) {
-      const out: any[] = [];
-      for (const item of batch) {
-        out.push(await this.call(item.method, item.parameters ?? []));
-      }
-      return out;
-    } else {
-      return this.call(batch.method, batch.parameters ?? []);
+  async call(method: string, params: unknown[] = []): Promise<unknown> {
+    const request = this.protocol.buildRequest(method, params);
+    const res = await this.execute(request);
+
+    if (!res.ok) {
+      const text = await safeText(res);
+      throw new BitcoinRpcError(
+        'HTTP_ERROR',
+        res.status,
+        text || `${res.status} ${res.statusText}`,
+        { method }
+      );
     }
+
+    const payload = await res.json() as { result?: unknown; error?: { code: number; message: string } };
+    return this.protocol.parseResponse(payload, method);
   }
 
   /**
-   * Internal method to perform the actual JSON-RPC call.
-   * @param {string} method The RPC method to call.
-   * @param {any[]} params The parameters for the RPC method.
-   * @returns {Promise<any>} The result of the RPC call.
+   * Execute a JSON-RPC batch in a single HTTP request.
+   * Returns results in the same order as the input calls.
    */
-  private async call(method: string, params: any[]): Promise<any> {
-    const body = { jsonrpc: '2.0', id: ++this.id, method, params };
+  async batch(calls: Array<{ method: string; params: unknown[] }>): Promise<unknown[]> {
+    if (calls.length === 0) return [];
+    if (calls.length === 1) {
+      const result = await this.call(calls[0].method, calls[0].params);
+      return [result];
+    }
 
-    const res = await fetch(this.url, {
-      method  : 'POST',
-      headers : {
-        'Content-Type' : 'application/json',
-        ...(this.authHeader ? { Authorization: this.authHeader } : {})
-      },
-      body : JSON.stringify(body)
-    });
+    const request = this.protocol.buildBatchRequest(calls);
+    const res = await this.execute(request);
 
     if (!res.ok) {
       const text = await safeText(res);
-      const err = new Error(text || `${res.status} ${res.statusText}`);
-      (err as any).code = res.status;
-      (err as any).rpc = true;
-      throw err;
+      throw new BitcoinRpcError(
+        'HTTP_ERROR',
+        res.status,
+        text || `${res.status} ${res.statusText}`,
+        { methods: calls.map(c => c.method) }
+      );
     }
 
-    const payload = await res.json() as { result?: any; error?: { code: number; message: string } };
-    if (payload.error) {
-      const err = new Error(payload.error.message);
-      (err as any).code = payload.error.code;
-      (err as any).rpc = true;
-      throw err;
-    }
-    return payload.result;
+    const payloads = await res.json() as Array<{ id: number; result?: unknown; error?: { code: number; message: string } }>;
+    return this.protocol.parseBatchResponse(payloads, calls);
   }
 }

package/src/client/rpc/protocol.ts

@@ -0,0 +1,160 @@
+import { BitcoinRpcError } from '../../errors.js';
+import { RpcConfig } from '../../types.js';
+import { HttpRequest } from '../http.js';
+import { toBase64 } from '../utils.js';
+
+/**
+ * Sans-I/O JSON-RPC protocol for Bitcoin Core.
+ *
+ * Builds {@link HttpRequest} descriptors for JSON-RPC method calls and
+ * provides response parsing — without performing any I/O.
+ *
+ * **Security note:** Built requests include an `Authorization` header when
+ * credentials are configured.  Do not log or persist {@link HttpRequest}
+ * objects without redacting the `Authorization` header.
+ *
+ * @example
+ * ```ts
+ * const protocol = new JsonRpcProtocol({
+ *   host: 'http://localhost:18443',
+ *   username: 'user',
+ *   password: 'pass',
+ * });
+ *
+ * // Build a request descriptor (no I/O)
+ * const req = protocol.buildRequest('getblockcount', []);
+ *
+ * // Execute with any HTTP client
+ * const res = await fetch(req.url, req);
+ * const json = await res.json();
+ *
+ * // Parse the JSON-RPC response (throws on errors)
+ * const blockCount = protocol.parseResponse(json, 'getblockcount', []);
+ * ```
+ */
+export class JsonRpcProtocol {
+  readonly url: string;
+
+  /** Whether this protocol instance has credentials configured. */
+  readonly hasAuth: boolean;
+
+  private readonly _headers: Record<string, string>;
+  private _id = 0;
+
+  constructor(cfg: RpcConfig) {
+    let url = (cfg.host || 'http://127.0.0.1:8332').replace(/\/+$/, '');
+    let authHeader: string | undefined;
+
+    if (cfg.username && cfg.password) {
+      authHeader = `Basic ${toBase64(`${cfg.username}:${cfg.password}`)}`;
+    } else {
+      try {
+        const u = new URL(url);
+        if (u.username || u.password) {
+          authHeader = `Basic ${toBase64(`${decodeURIComponent(u.username)}:${decodeURIComponent(u.password)}`)}`;
+          u.username = ''; u.password = '';
+          url = u.toString().replace(/\/+$/, '');
+        }
+      } catch (error: unknown) {
+        console.error(`Invalid URL in Bitcoin RPC config: ${url}`, error);
+      }
+    }
+
+    this.url = url;
+    this.hasAuth = authHeader !== undefined;
+    this._headers = {
+      'Content-Type' : 'application/json',
+      ...(authHeader ? { Authorization: authHeader } : {}),
+    };
+  }
+
+  /**
+   * Build an {@link HttpRequest} for a JSON-RPC method call.
+   */
+  buildRequest(method: string, params: unknown[]): HttpRequest {
+    const body = { jsonrpc: '2.0', id: ++this._id, method, params };
+    return {
+      url     : this.url,
+      method  : 'POST',
+      headers : { ...this._headers },
+      body    : JSON.stringify(body),
+    };
+  }
+
+  /**
+   * Build an {@link HttpRequest} for a JSON-RPC batch call.
+   * Sends all calls in a single HTTP request per the JSON-RPC 2.0 spec.
+   */
+  buildBatchRequest(calls: Array<{ method: string; params: unknown[] }>): HttpRequest {
+    const body = calls.map(c => ({
+      jsonrpc : '2.0',
+      id      : ++this._id,
+      method  : c.method,
+      params  : c.params,
+    }));
+    return {
+      url     : this.url,
+      method  : 'POST',
+      headers : { ...this._headers },
+      body    : JSON.stringify(body),
+    };
+  }
+
+  /**
+   * Parse a JSON-RPC response payload, throwing {@link BitcoinRpcError}
+   * if the response contains an error.
+   */
+  parseResponse(
+    payload: { result?: unknown; error?: { code: number; message: string } },
+    method: string,
+  ): unknown {
+    if (payload.error) {
+      throw new BitcoinRpcError(
+        'RPC_ERROR',
+        payload.error.code,
+        payload.error.message,
+        { method }
+      );
+    }
+    return payload.result;
+  }
+
+  /**
+   * Parse a JSON-RPC batch response payload.
+   * Returns results in the same order as the original calls.
+   */
+  parseBatchResponse(
+    payloads: Array<{ id: number; result?: unknown; error?: { code: number; message: string } }>,
+    calls: Array<{ method: string; params: unknown[] }>,
+  ): unknown[] {
+    const byId = new Map(payloads.map(p => [p.id, p]));
+    // Batch responses may arrive out of order; re-sort by sequential id.
+    // IDs were assigned as (_id - calls.length + 1) .. _id
+    const startId = this._id - calls.length + 1;
+
+    return calls.map((call, i) => {
+      const payload = byId.get(startId + i);
+      if (!payload) {
+        throw new BitcoinRpcError(
+          'RPC_ERROR',
+          -1,
+          `Missing response for batch call ${call.method} (id ${startId + i})`,
+          { method: call.method }
+        );
+      }
+      return this.parseResponse(payload, call.method);
+    });
+  }
+
+  /**
+   * Return a copy of the headers with the Authorization value redacted.
+   * Use this for logging or debugging.
+   */
+  redactedHeaders(): Record<string, string> {
+    const copy = { ...this._headers };
+    if (copy.Authorization) {
+      copy.Authorization = 'Basic [REDACTED]';
+    }
+    return copy;
+  }
+}

package/src/connection.ts

@@ -0,0 +1,136 @@
+import { MethodError } from '@did-btcr2/common';
+import { networks } from 'bitcoinjs-lib';
+import { HttpExecutor } from './client/http.js';
+import { BitcoinRestClient } from './client/rest/index.js';
+import { BitcoinCoreRpcClient } from './client/rpc/index.js';
+import { getNetwork } from './network.js';
+import { NetworkName, RestConfig, RpcConfig } from './types.js';
+import { DEFAULT_BITCOIN_NETWORK_CONFIG } from './constants.js';
+
+/**
+ * Options for creating a BitcoinConnection.
+ */
+export type BitcoinConnectionOptions = {
+  network: NetworkName;
+  rest: RestConfig;
+  rpc?: RpcConfig;
+  /** Optional HTTP executor for sans-I/O usage. Defaults to global `fetch`. */
+  executor?: HttpExecutor;
+};
+
+/**
+ * Represents a connection to a single Bitcoin network.
+ * Holds the REST and optional RPC clients for that network.
+ *
+ * The underlying clients use a sans-I/O protocol layer that separates
+ * request construction from HTTP execution.  By default, requests are
+ * executed via the global `fetch` function.  Supply a custom
+ * {@link HttpExecutor} to use any HTTP client.
+ *
+ * @example
+ * ```ts
+ * // Quick setup with defaults (uses fetch)
+ * const btc = BitcoinConnection.forNetwork('regtest');
+ *
+ * // With a custom HTTP executor
+ * const btc = BitcoinConnection.forNetwork('testnet4', {
+ *   rest: { host: 'https://my-mempool/api' },
+ *   executor: myCustomExecutor,
+ * });
+ *
+ * // Direct usage
+ * const tx = await btc.rest.transaction.get(txid);
+ * const block = await btc.rpc?.getBlock({ height: 100 });
+ *
+ * // Sans-I/O: build requests without performing I/O
+ * const req = btc.rest.protocol.getTx(txid);
+ * const res = await myHttpClient.execute(req);
+ * ```
+ */
+export class BitcoinConnection {
+  /** The network this connection targets. */
+  readonly name: NetworkName;
+
+  /** REST client (Esplora API). */
+  readonly rest: BitcoinRestClient;
+
+  /** RPC client (Bitcoin Core). May be undefined if not configured. */
+  readonly rpc?: BitcoinCoreRpcClient;
+
+  /** bitcoinjs-lib network data (for address derivation, PSBT signing, etc.). */
+  readonly data: networks.Network;
+
+  constructor(options: BitcoinConnectionOptions) {
+    this.name = options.network;
+    this.rest = new BitcoinRestClient(options.rest, options.executor);
+    this.rpc  = options.rpc ? new BitcoinCoreRpcClient(options.rpc, options.executor) : undefined;
+    this.data = getNetwork(options.network);
+  }
+
+  /**
+   * Create a connection for a single network with optional REST/RPC endpoint overrides.
+   * Merges overrides on top of defaults from DEFAULT_BITCOIN_NETWORK_CONFIG.
+   * Does not read environment variables.
+   *
+   * @param network The network name (e.g., 'regtest', 'testnet4', 'bitcoin').
+   * @param overrides Optional endpoint and executor overrides.
+   * @returns A BitcoinConnection for the requested network.
+   */
+  static forNetwork(
+    network: NetworkName,
+    overrides?: { rest?: Partial<RestConfig>; rpc?: RpcConfig; executor?: HttpExecutor }
+  ): BitcoinConnection {
+    const defaults = DEFAULT_BITCOIN_NETWORK_CONFIG[network];
+
+    if (!defaults) {
+      throw new MethodError(
+        `Unknown network '${network}'. Available: bitcoin, testnet3, testnet4, signet, mutinynet, regtest`,
+        'UNKNOWN_NETWORK',
+        { network }
+      );
+    }
+
+    const restCfg: RestConfig = { ...defaults.rest, ...overrides?.rest };
+
+    const hasRpc = defaults.rpc !== undefined || overrides?.rpc !== undefined;
+    const rpcCfg = hasRpc
+      ? { ...defaults.rpc, ...overrides?.rpc } as RpcConfig
+      : undefined;
+
+    return new BitcoinConnection({
+      network,
+      rest     : restCfg,
+      rpc      : rpcCfg,
+      executor : overrides?.executor,
+    });
+  }
+
+  /**
+   * Converts Bitcoin (BTC) to satoshis.
+   * Uses string-based arithmetic to avoid floating-point precision errors.
+   * @throws {RangeError} If the value has more than 8 decimal places.
+   */
+  static btcToSats(btc: number): number {
+    const str = btc.toFixed(8);
+    const [whole, frac] = str.split('.');
+    // Verify no precision beyond 8 decimals was lost
+    if (Math.abs(btc - Number(str)) > Number.EPSILON) {
+      throw new RangeError(`BTC value ${btc} exceeds 8 decimal places of precision`);
+    }
+    return Number(whole) * 1e8 + Number(frac);
+  }
+
+  /**
+   * Converts satoshis to Bitcoin (BTC).
+   * Uses string-based arithmetic to avoid floating-point precision errors.
+   * @param sats Must be a non-negative integer.
+   */
+  static satsToBtc(sats: number): number {
+    const negative = sats < 0;
+    const abs = Math.abs(sats);
+    const whole = Math.floor(abs / 1e8);
+    const frac = abs % 1e8;
+    const result = Number(`${whole}.${frac.toString().padStart(8, '0')}`);
+    return negative ? -result : result;
+  }
+}

package/src/constants.ts

@@ -4,6 +4,23 @@ export const COINBASE_MATURITY_DELAY = 100;
 export const DEFAULT_BLOCK_CONFIRMATIONS = 7;
 export const TXIN_WITNESS_COINBASE = '0000000000000000000000000000000000000000000000000000000000000000';
 export const GENESIS_TX_ID = '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b';
+
+/**
+ * Default endpoint configuration per Bitcoin network.
+ *
+ * **Regtest RPC:** Credentials are intentionally omitted — callers must
+ * provide `username` and `password` via overrides or explicit config.
+ * This prevents accidentally using hardcoded credentials in non-local
+ * environments.
+ *
+ * @example
+ * ```ts
+ * // Provide credentials explicitly
+ * BitcoinConnection.forNetwork('regtest', {
+ *   rpc: { username: 'polaruser', password: 'polarpass' },
+ * });
+ * ```
+ */
 export const DEFAULT_BITCOIN_NETWORK_CONFIG = {
   bitcoin : {
     rpc  : undefined,
@@ -27,13 +44,8 @@ export const DEFAULT_BITCOIN_NETWORK_CONFIG = {
   },
   regtest : {
     rpc  : {
-      network            : 'regtest',
       host               : 'http://localhost:18443',
-      port               : 18443,
-      username           : 'polaruser',
-      password           : 'polarpass',
       allowDefaultWallet : true,
-      version            : '28.1.0',
     },
     rest : { host: 'http://localhost:3000' }
   },

package/src/errors.ts

@@ -1,11 +1,18 @@
+export type RpcErrorType =
+  | 'HTTP_ERROR'
+  | 'RPC_ERROR'
+  | 'INVALID_PARAMS_GET_BLOCK'
+  | 'SIGNING_INCOMPLETE'
+  | 'UNKNOWN_ERROR';
+
 /**
  * Custom Error class for handling Bitcoin RPC errors.
  */
 export class BitcoinRpcError extends Error {
-  public readonly type: string;
+  public readonly type: RpcErrorType;
   public readonly code: number;
-  public readonly data?: any;
-  constructor(type: string, code: number, message: string, data?: any) {
+  public readonly data?: unknown;
+  constructor(type: RpcErrorType, code: number, message: string, data?: unknown) {
     super(message);
     this.type = type;
     this.code = code;