@did-btcr2/bitcoin 0.3.4 → 0.4.0

package/dist/esm/client/rpc/json-rpc.js

@@ -1,77 +1,54 @@
-import { safeText, toBase64 } from '../utils.js';
+import { BitcoinRpcError } from '../../errors.js';
+import { defaultHttpExecutor } from '../http.js';
+import { safeText } from '../utils.js';
+import { JsonRpcProtocol } from './protocol.js';
 export class JsonRpcTransport {
-    url;
-    authHeader;
-    id = 0;
-    constructor(cfg) {
-        this.url = (cfg.host || 'http://127.0.0.1:8332').replace(/\/+$/, '');
-        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) {
-                console.error(`Invalid URL in Bitcoin RPC config: ${this.url}`, error);
-            }
-        }
-    }
     /**
-     * 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
+     * The sans-I/O protocol layer.  Use this to build {@link HttpRequest}
+     * descriptors without performing any I/O.
      */
-    async command(batch) {
-        if (Array.isArray(batch)) {
-            const out = [];
-            for (const item of batch) {
-                out.push(await this.call(item.method, item.parameters ?? []));
-            }
-            return out;
-        }
-        else {
-            return this.call(batch.method, batch.parameters ?? []);
-        }
+    protocol;
+    execute;
+    constructor(cfg, executor) {
+        this.protocol = new JsonRpcProtocol(cfg);
+        this.execute = executor ?? defaultHttpExecutor;
+    }
+    /** @internal Expose URL for tests that inspect transport state. */
+    get url() {
+        return this.protocol.url;
     }
     /**
-     * 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 single JSON-RPC call.
      */
-    async call(method, params) {
-        const body = { jsonrpc: '2.0', id: ++this.id, method, params };
-        const res = await fetch(this.url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...(this.authHeader ? { Authorization: this.authHeader } : {})
-            },
-            body: JSON.stringify(body)
-        });
+    async call(method, params = []) {
+        const request = this.protocol.buildRequest(method, params);
+        const res = await this.execute(request);
         if (!res.ok) {
             const text = await safeText(res);
-            const err = new Error(text || `${res.status} ${res.statusText}`);
-            err.code = res.status;
-            err.rpc = true;
-            throw err;
+            throw new BitcoinRpcError('HTTP_ERROR', res.status, text || `${res.status} ${res.statusText}`, { method });
         }
         const payload = await res.json();
-        if (payload.error) {
-            const err = new Error(payload.error.message);
-            err.code = payload.error.code;
-            err.rpc = true;
-            throw err;
+        return this.protocol.parseResponse(payload, method);
+    }
+    /**
+     * Execute a JSON-RPC batch in a single HTTP request.
+     * Returns results in the same order as the input calls.
+     */
+    async batch(calls) {
+        if (calls.length === 0)
+            return [];
+        if (calls.length === 1) {
+            const result = await this.call(calls[0].method, calls[0].params);
+            return [result];
+        }
+        const request = this.protocol.buildBatchRequest(calls);
+        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}`, { methods: calls.map(c => c.method) });
         }
-        return payload.result;
+        const payloads = await res.json();
+        return this.protocol.parseBatchResponse(payloads, calls);
     }
 }
 //# sourceMappingURL=json-rpc.js.map

package/dist/esm/client/rpc/json-rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-rpc.js","sourceRoot":"","sources":["../../../../src/client/rpc/json-rpc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json-rpc.js","sourceRoot":"","sources":["../../../../src/client/rpc/json-rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAgB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,OAAO,gBAAgB;IAC3B;;;OAGG;IACM,QAAQ,CAAkB;IAElB,OAAO,CAAe;IAEvC,YAAY,GAAc,EAAE,QAAuB;QACjD,IAAI,CAAC,QAAQ,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,QAAQ,IAAI,mBAAmB,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,SAAoB,EAAE;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAExC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,IAAI,eAAe,CACvB,YAAY,EACZ,GAAG,CAAC,MAAM,EACV,IAAI,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,EACzC,EAAE,MAAM,EAAE,CACX,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,EAAqE,CAAC;QACpG,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,KAAmD;QAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACvD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAExC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,IAAI,eAAe,CACvB,YAAY,EACZ,GAAG,CAAC,MAAM,EACV,IAAI,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,EACzC,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CACtC,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAwF,CAAC;QACxH,OAAO,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/esm/client/rpc/protocol.js

@@ -0,0 +1,134 @@
+import { BitcoinRpcError } from '../../errors.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 {
+    url;
+    /** Whether this protocol instance has credentials configured. */
+    hasAuth;
+    _headers;
+    _id = 0;
+    constructor(cfg) {
+        let url = (cfg.host || 'http://127.0.0.1:8332').replace(/\/+$/, '');
+        let authHeader;
+        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) {
+                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, params) {
+        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) {
+        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, method) {
+        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, calls) {
+        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() {
+        const copy = { ...this._headers };
+        if (copy.Authorization) {
+            copy.Authorization = 'Basic [REDACTED]';
+        }
+        return copy;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/esm/client/rpc/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../../src/client/rpc/protocol.ts"],"names":[],"mappings":"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"}

package/dist/esm/constants.js

@@ -4,6 +4,22 @@ 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 +43,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/dist/esm/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,kEAAkE,CAAC;AACxG,MAAM,CAAC,MAAM,aAAa,GAAG,kEAAkE,CAAC;AAChG,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,OAAO,EAAG;QACR,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,2BAA2B,EAAE;KAC7C;IACD,QAAQ,EAAG;QACT,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,mCAAmC,EAAE;KACrD;IACD,QAAQ,EAAG;QACT,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,oCAAoC,EAAE;KACtD;IACD,MAAM,EAAI;QACR,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,kCAAkC,EAAE;KACpD;IACD,SAAS,EAAG;QACV,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,2BAA2B,EAAE;KAC7C;IACD,OAAO,EAAG;QACR,GAAG,EAAI;YACL,OAAO,EAAc,SAAS;YAC9B,IAAI,EAAiB,wBAAwB;YAC7C,IAAI,EAAiB,KAAK;YAC1B,QAAQ,EAAa,WAAW;YAChC,QAAQ,EAAa,WAAW;YAChC,kBAAkB,EAAG,IAAI;YACzB,OAAO,EAAc,QAAQ;SAC9B;QACD,IAAI,EAAG,EAAE,IAAI,EAAE,uBAAuB,EAAE;KACzC;CACO,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,kEAAkE,CAAC;AACxG,MAAM,CAAC,MAAM,aAAa,GAAG,kEAAkE,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,OAAO,EAAG;QACR,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,2BAA2B,EAAE;KAC7C;IACD,QAAQ,EAAG;QACT,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,mCAAmC,EAAE;KACrD;IACD,QAAQ,EAAG;QACT,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,oCAAoC,EAAE;KACtD;IACD,MAAM,EAAI;QACR,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,kCAAkC,EAAE;KACpD;IACD,SAAS,EAAG;QACV,GAAG,EAAI,SAAS;QAChB,IAAI,EAAG,EAAE,IAAI,EAAE,2BAA2B,EAAE;KAC7C;IACD,OAAO,EAAG;QACR,GAAG,EAAI;YACL,IAAI,EAAiB,wBAAwB;YAC7C,kBAAkB,EAAG,IAAI;SAC1B;QACD,IAAI,EAAG,EAAE,IAAI,EAAE,uBAAuB,EAAE;KACzC;CACO,CAAC"}

package/dist/esm/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,IAAI,CAAS;IACb,IAAI,CAAO;IAC3B,YAAY,IAAY,EAAE,IAAY,EAAE,OAAe,EAAE,IAAU;QACjE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzB,IAAI,CAAO;IAC3B,YAAY,OAAe,EAAE,IAAU;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxB,IAAI,CAAe;IACnB,IAAI,CAAS;IACb,IAAI,CAAW;IAC/B,YAAY,IAAkB,EAAE,IAAY,EAAE,OAAe,EAAE,IAAc;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzB,IAAI,CAAO;IAC3B,YAAY,OAAe,EAAE,IAAU;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/esm/index.js

@@ -1,14 +1,22 @@
-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 } from './bitcoin.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';
+// 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';
+// 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';
+export { VerbosityLevel } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","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.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO;AACP,OAAO,EAAE,iBAAiB,EAAiC,MAAM,cAAc,CAAC;AAIhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D,2DAA2D;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAI7D,iEAAiE;AACjE,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;AAE5D,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGhE,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEvD,YAAY;AACZ,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,qBAAqB,EACrB,aAAa,GACd,MAAM,gBAAgB,CAAC;AA0CxB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/types.js

@@ -1,69 +1,19 @@
 ;
-export class RestClientConfig {
-    host;
-    headers;
-    constructor({ host, headers }) {
-        this.host = host;
-        this.headers = headers;
-    }
-}
-;
-export class BitcoinRpcClientConfig {
-    network;
-    headers;
-    host;
-    logger;
-    password;
-    timeout;
-    username;
-    version;
-    wallet;
-    allowDefaultWallet;
-    constructor(options = {
-        headers: {},
-        host: 'http://localhost',
-        logger: console,
-        password: '',
-        timeout: 30000,
-        username: '',
-        version: '0.21.1',
-        wallet: '',
-        allowDefaultWallet: false,
-    }) {
-        this.headers = options.headers;
-        this.host = options.host;
-        this.logger = options.logger;
-        this.password = options.password;
-        this.timeout = options.timeout;
-        this.username = options.username;
-        this.version = options.version;
-        this.wallet = options.wallet;
-        this.allowDefaultWallet = options.allowDefaultWallet;
-    }
-}
 ;
 ;
 /**
  * Defines verbosity levels for block and transaction outputs.
- * Used to specify the format of returned block or transaction data.
- * @enum {number} VerbosityLevel for block and transaction outputs.
+ * @enum {number}
  */
 export var VerbosityLevel;
 (function (VerbosityLevel) {
-    /** Return block or transaction data in raw hex-encoded format */
+    /** Return data in raw hex-encoded format */
     VerbosityLevel[VerbosityLevel["hex"] = 0] = "hex";
-    /** Return block or transaction data in JSON object format */
+    /** Return data in JSON object format */
     VerbosityLevel[VerbosityLevel["json"] = 1] = "json";
-    /**
-     * Return block or transaction data in JSON object format with additional information.
-     * Returns block data with information about each transaction.
-     * Returns transaction data with information about the transaction including fee and prevout information.
-     */
+    /** Return data in JSON format with additional information */
     VerbosityLevel[VerbosityLevel["jsonext"] = 2] = "jsonext";
-    /**
-     * Return block data in JSON object format with additional information.
-     * Returns block data with information about each transaction, including prevout information for inputs.
-     */
+    /** Return block data in JSON format with prevout information for inputs */
     VerbosityLevel[VerbosityLevel["jsonextprev"] = 3] = "jsonextprev";
 })(VerbosityLevel || (VerbosityLevel = {}));
 //# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAkBC,CAAC;AAoDF,MAAM,OAAO,gBAAgB;IAC3B,IAAI,CAAS;IACb,OAAO,CAA6B;IACpC,YAAY,EAAE,IAAI,EAAE,OAAO,EAA0B;QACnD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAQA,CAAC;AAiDF,MAAM,OAAO,sBAAsB;IACjC,OAAO,CAAU;IACjB,OAAO,CAA0B;IACjC,IAAI,CAAU;IACd,MAAM,CAAO;IACb,QAAQ,CAAU;IAClB,OAAO,CAAU;IACjB,QAAQ,CAAU;IAClB,OAAO,CAAU;IACjB,MAAM,CAAU;IAChB,kBAAkB,CAAW;IAE7B,YAAY,UAA2B;QACrC,OAAO,EAAc,EAAE;QACvB,IAAI,EAAiB,kBAAkB;QACvC,MAAM,EAAe,OAAO;QAC5B,QAAQ,EAAa,EAAE;QACvB,OAAO,EAAc,KAAK;QAC1B,QAAQ,EAAa,EAAE;QACvB,OAAO,EAAc,QAAQ;QAC7B,MAAM,EAAe,EAAE;QACvB,kBAAkB,EAAG,KAAK;KAC3B;QACC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IACvD,CAAC;CACF;AAkZA,CAAC;AAKD,CAAC;AAygBF;;;;GAIG;AACH,MAAM,CAAN,IAAY,cAgBX;AAhBD,WAAY,cAAc;IACtB,iEAAiE;IACjE,iDAAO,CAAA;IACP,6DAA6D;IAC7D,mDAAQ,CAAA;IACR;;;;OAIG;IACH,yDAAW,CAAA;IACX;;;OAGG;IACH,iEAAe,CAAA;AACnB,CAAC,EAhBW,cAAc,KAAd,cAAc,QAgBzB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AA6BC,CAAC;AA+ND,CAAC;AAKD,CAAC;AA4FF;;;GAGG;AACH,MAAM,CAAN,IAAY,cASX;AATD,WAAY,cAAc;IACxB,4CAA4C;IAC5C,iDAAO,CAAA;IACP,wCAAwC;IACxC,mDAAQ,CAAA;IACR,6DAA6D;IAC7D,yDAAW,CAAA;IACX,2EAA2E;IAC3E,iEAAe,CAAA;AACjB,CAAC,EATW,cAAc,KAAd,cAAc,QASzB"}

package/dist/types/bitcoin.d.ts

@@ -1,60 +1,81 @@
 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 { AvailableNetworks, BitcoinClientConfig } from './types.js';
-export type BitcoinNetworkConfig = {
-    name: keyof AvailableNetworks;
-    rpc?: BitcoinCoreRpcClient;
-    rest: BitcoinRestClient;
-    config: BitcoinClientConfig;
-    data: networks.Network;
-};
-export type BitcoinNetworkConfigMap = {
-    [key in keyof AvailableNetworks]?: BitcoinNetworkConfig;
+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;
 };
 /**
- * The BitcoinNetworkConnection class contains relevant data and methods for interacting with different Bitcoin network.
- * @name BitcoinNetworkConnection
- * @type {BitcoinNetworkConnection}
+ * 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 BitcoinNetworkConnection {
-    network: BitcoinNetworkConfig;
-    bitcoin?: BitcoinNetworkConfig;
-    testnet3?: BitcoinNetworkConfig;
-    testnet4?: BitcoinNetworkConfig;
-    signet?: BitcoinNetworkConfig;
-    mutinynet?: BitcoinNetworkConfig;
-    regtest?: BitcoinNetworkConfig;
-    /**
-     * Creates an instance of the Bitcoin class.
-     * @param {BitcoinNetworkConfigMap} configs Optional configuration object for the Bitcoin client. If not provided, it will
-     * be loaded from the BITCOIN_CLIENT_CONFIG environment variables.
-     * @throws {MethodError} If no configs is passed and BITCOIN_NETWORK_CONFIG is missing or invalid.
-     */
-    constructor(configs?: BitcoinNetworkConfigMap);
-    /**
-     * Get the Bitcoin network configuration for a specific network.
-     * @param {keyof AvailableNetworks} network - The Bitcoin network (e.g., 'bitcoin', 'testnet3', 'signet', 'regtest').
-     * @returns {Bitcoin} The Bitcoin object.
-     */
-    getNetworkConnection(network: string): BitcoinNetworkConnection;
+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);
     /**
-     * Sets the active Bitcoin network.
-     * @param {keyof AvailableNetworks} active - The Bitcoin network to set as active (e.g., 'bitcoin', 'testnet3', 'signet', 'regtest').
-     * @throws {MethodError} If no configuration is found for the specified 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.
      */
-    setActiveNetwork(active: string): void;
+    static forNetwork(network: NetworkName, overrides?: {
+        rest?: Partial<RestConfig>;
+        rpc?: RpcConfig;
+        executor?: HttpExecutor;
+    }): BitcoinConnection;
     /**
-     * Converts Bitcoin (BTC) to satoshis (SAT).
-     * @param {number} btc - The amount in BTC.
-     * @returns {number} The amount in SAT.
+     * 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 (SAT) to Bitcoin (BTC).
-     * @param {number} sats - The amount in SAT.
-     * @returns {number} The amount in BTC.
+     * 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;
 }
-export declare const bitcoin: BitcoinNetworkConnection;

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

@@ -1 +1 @@
-{"version":3,"file":"bitcoin.d.ts","sourceRoot":"","sources":["../../src/bitcoin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGpE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,iBAAiB,CAAC;IAC9B,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;KACnC,GAAG,IAAI,MAAM,iBAAiB,CAAC,CAAC,EAAE,oBAAoB;CACxD,CAAC;AAEF;;;;GAIG;AACH,qBAAa,wBAAwB;IAC5B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAEtC;;;;;OAKG;gBACS,OAAO,CAAC,EAAE,uBAAuB;IAyD7C;;;;OAIG;IACI,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB;IAWtE;;;;OAIG;IACI,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAW7C;;;;OAIG;WACW,SAAS,CAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAI7C;;;;OAIG;WACW,SAAS,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM;CAG/C;AAED,eAAO,MAAM,OAAO,0BAAiC,CAAC"}
+{"version":3,"file":"bitcoin.d.ts","sourceRoot":"","sources":["../../src/bitcoin.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/client/http.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HTTP request descriptor. Represents a request that can be executed
+ * by any HTTP client — the library never performs I/O itself at the
+ * protocol layer.
+ */
+export interface HttpRequest {
+    url: string;
+    method: 'GET' | 'POST';
+    headers: Record<string, string>;
+    body?: string;
+}
+/**
+ * A function that executes an {@link HttpRequest} and returns a standard
+ * {@link Response}.  Users can supply their own implementation to use
+ * any HTTP client (e.g. `undici`, `axios`, a caching proxy, etc.).
+ */
+export type HttpExecutor = (request: HttpRequest) => Promise<Response>;
+/**
+ * Default executor backed by the global `fetch` function.
+ */
+export declare const defaultHttpExecutor: HttpExecutor;

package/dist/types/client/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAK9B,CAAC"}