@did-btcr2/bitcoin 0.3.4 → 0.5.0

package/dist/types/client/utils.d.ts

@@ -10,3 +10,4 @@ export declare function toBase64(s: string): string;
  * @returns {Promise<string>} The text content or empty string on failure
  */
 export declare function safeText(res: Response): Promise<string>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/types/connection.d.ts

@@ -0,0 +1,82 @@
+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 { NetworkName, RestConfig, RpcConfig } from './types.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 declare 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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/types/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGhE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAiB;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAEjC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAEpC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC;gBAEpB,OAAO,EAAE,wBAAwB;IAO7C;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CACf,OAAO,EAAE,WAAW,EACpB,SAAS,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;KAAE,GACnF,iBAAiB;IA0BpB;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAUrC;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAQvC"}

package/dist/types/constants.d.ts

@@ -4,6 +4,22 @@ export declare const COINBASE_MATURITY_DELAY = 100;
 export declare const DEFAULT_BLOCK_CONFIRMATIONS = 7;
 export declare const TXIN_WITNESS_COINBASE = "0000000000000000000000000000000000000000000000000000000000000000";
 export declare 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 declare const DEFAULT_BITCOIN_NETWORK_CONFIG: {
     readonly bitcoin: {
         readonly rpc: undefined;
@@ -37,16 +53,12 @@ export declare const DEFAULT_BITCOIN_NETWORK_CONFIG: {
     };
     readonly regtest: {
         readonly rpc: {
-            readonly network: "regtest";
             readonly host: "http://localhost:18443";
-            readonly port: 18443;
-            readonly username: "polaruser";
-            readonly password: "polarpass";
             readonly allowDefaultWallet: true;
-            readonly version: "28.1.0";
         };
         readonly rest: {
             readonly host: "http://localhost:3000";
         };
     };
 };
+//# sourceMappingURL=constants.d.ts.map

package/dist/types/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,qBAAqB,qEAAqE,CAAC;AACxG,eAAO,MAAM,aAAa,qEAAqE,CAAC;AAChG,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCjC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,qBAAqB,qEAAqE,CAAC;AACxG,eAAO,MAAM,aAAa,qEAAqE,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BjC,CAAC"}

package/dist/types/errors.d.ts

@@ -1,13 +1,15 @@
+export type RpcErrorType = 'HTTP_ERROR' | 'RPC_ERROR' | 'INVALID_PARAMS_GET_BLOCK' | 'SIGNING_INCOMPLETE' | 'UNKNOWN_ERROR';
 /**
  * Custom Error class for handling Bitcoin RPC errors.
  */
 export declare class BitcoinRpcError extends Error {
-    readonly type: string;
+    readonly type: RpcErrorType;
     readonly code: number;
-    readonly data?: any;
-    constructor(type: string, code: number, message: string, data?: any);
+    readonly data?: unknown;
+    constructor(type: RpcErrorType, code: number, message: string, data?: unknown);
 }
 export declare class BitcoinRestError extends Error {
     readonly data?: any;
     constructor(message: string, data?: any);
 }
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,CAAC,EAAE,GAAG,CAAC;gBACf,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;CAOpE;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,CAAC,EAAE,GAAG,CAAC;gBACf,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;CAKxC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,WAAW,GACX,0BAA0B,GAC1B,oBAAoB,GACpB,eAAe,CAAC;AAEpB;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,YAAY,CAAC;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;gBACnB,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAO9E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,CAAC,EAAE,GAAG,CAAC;gBACf,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;CAKxC"}

package/dist/types/index.d.ts

@@ -1,13 +1,21 @@
-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';
+export { BitcoinConnection, type BitcoinConnectionOptions } from './connection.js';
+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';
+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';
+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';
+export { BitcoinRpcError, BitcoinRestError } from './errors.js';
+export type { RpcErrorType } from './errors.js';
+export { getNetwork } from './network.js';
+export { toBase64, safeText } from './client/utils.js';
+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';
+export type { NetworkName, RestConfig, EsploraBlock, TransactionStatus, Vin, Vout, ChainStats, MempoolStats, AddressInfo, RawTransactionRest, AddressUtxo, 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAGnF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,qBAAqB,EACrB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAEV,WAAW,EAEX,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,GAAG,EACH,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,WAAW,EAEX,SAAS,EACT,SAAS,EACT,cAAc,EACd,aAAa,EACb,OAAO,EACP,OAAO,EACP,OAAO,EACP,OAAO,EACP,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/network.d.ts

@@ -1,2 +1,3 @@
 import { networks } from 'bitcoinjs-lib';
 export declare function getNetwork(network: string): networks.Network;
+//# sourceMappingURL=network.d.ts.map