@did-btcr2/bitcoin 0.3.4 → 0.4.0

package/src/client/rpc/interface.ts

@@ -9,57 +9,48 @@ import {
 } 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>;
+  /** 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>;
 }
-
-export function isBitcoinRpcClient(obj: any): obj is BitcoinRpcClient {
-  return obj &&
-    typeof obj.getBlockCount === 'function' &&
-    typeof obj.getBlockHash === 'function' &&
-    typeof obj.getBlockchainInfo === 'function';
-}

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/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;

package/src/index.ts

@@ -1,13 +1,81 @@
-export * from './bitcoin.js';
-export * from './client/rest/address.js';
-export * from './client/rest/block.js';
-export * from './client/rest/index.js';
-export * from './client/rest/transaction.js';
-export * from './client/rpc/index.js';
-export * from './client/rpc/interface.js';
-export * from './client/rpc/json-rpc.js';
-export * from './client/utils.js';
-export * from './constants.js';
-export * from './errors.js';
-export * from './network.js';
-export * from './types.js';
+// Core
+export { BitcoinConnection, type BitcoinConnectionOptions } from './bitcoin.js';
+
+// Sans-I/O protocol layer
+export type { HttpRequest, HttpExecutor } from './client/http.js';
+export { defaultHttpExecutor } from './client/http.js';
+export { EsploraProtocol } from './client/rest/protocol.js';
+export { JsonRpcProtocol } from './client/rpc/protocol.js';
+
+// Clients (convenience wrappers around the protocol layer)
+export { BitcoinRestClient } from './client/rest/index.js';
+export { BitcoinCoreRpcClient } from './client/rpc/index.js';
+export type { RpcMethodMap, TypedRpcMethod } from './client/rpc/index.js';
+export type { BitcoinRpcClient } from './client/rpc/interface.js';
+
+// Sub-clients (for direct construction in tests or advanced use)
+export { BitcoinAddress } from './client/rest/address.js';
+export { BitcoinBlock } from './client/rest/block.js';
+export { BitcoinTransaction } from './client/rest/transaction.js';
+export { JsonRpcTransport } from './client/rpc/json-rpc.js';
+
+// Errors
+export { BitcoinRpcError, BitcoinRestError } from './errors.js';
+export type { RpcErrorType } from './errors.js';
+
+// Helpers
+export { getNetwork } from './network.js';
+export { toBase64, safeText } from './client/utils.js';
+
+// Constants
+export {
+  DEFAULT_BITCOIN_NETWORK_CONFIG,
+  INITIAL_BLOCK_REWARD,
+  HALVING_INTERVAL,
+  COINBASE_MATURITY_DELAY,
+  DEFAULT_BLOCK_CONFIRMATIONS,
+  TXIN_WITNESS_COINBASE,
+  GENESIS_TX_ID,
+} from './constants.js';
+
+// Types
+export type {
+  // Network
+  NetworkName,
+  // REST
+  RestConfig,
+  EsploraBlock,
+  TransactionStatus,
+  Vin,
+  Vout,
+  ChainStats,
+  MempoolStats,
+  AddressInfo,
+  RawTransactionRest,
+  AddressUtxo,
+  // RPC
+  RpcConfig,
+  ChainInfo,
+  GetBlockParams,
+  BlockResponse,
+  BlockV0,
+  BlockV1,
+  BlockV2,
+  BlockV3,
+  RawTransactionResponse,
+  RawTransactionV0,
+  RawTransactionV1,
+  RawTransactionV2,
+  CreateRawTxInputs,
+  CreateRawTxOutputs,
+  SignedRawTx,
+  UnspentTxInfo,
+  WalletTransaction,
+  DerivedAddresses,
+  ListTransactionsParams,
+  ListTransactionsResult,
+  MethodNameInLowerCase,
+  FeeEstimateMode,
+} from './types.js';
+
+export { VerbosityLevel } from './types.js';