@did-btcr2/bitcoin 0.3.4 → 0.4.0

package/src/client/rest/index.ts

@@ -1,129 +1,73 @@
-import { JSONUtils, MethodError, StringUtils } from '@did-btcr2/common';
-import { DEFAULT_BITCOIN_NETWORK_CONFIG } from '../../constants.js';
+import { MethodError } from '@did-btcr2/common';
 import { BitcoinAddress } from './address.js';
 import { BitcoinBlock } from './block.js';
 import { BitcoinTransaction } from './transaction.js';
-import { RestClientConfig, RestApiCallParams, RestResponse } from '../../types.js';
-
+import { EsploraProtocol } from './protocol.js';
+import { RestConfig } from '../../types.js';
+import { HttpExecutor, HttpRequest, defaultHttpExecutor } from '../http.js';
 
 /**
- * Implements a strongly-typed BitcoinRestClient to connect to remote bitcoin node via REST API.
- * @class BitcoinRestClient
- * @type {BitcoinRestClient}
+ * Esplora REST API client for Bitcoin.
+ *
+ * Wraps the sans-I/O {@link EsploraProtocol} with an {@link HttpExecutor}
+ * for convenience.  Users who want full control over I/O can access the
+ * protocol layer directly via the {@link protocol} property.
  */
 export class BitcoinRestClient {
-  /**
-   * The encapsulated {@link RestClientConfig} object.
-   * @private
-   * @type {RestClientConfig}
-   */
-  private _config: RestClientConfig;
+  private _config: RestConfig;
 
   /**
-   * The api calls related to bitcoin transactions.
-   * @type {BitcoinTransaction}
+   * The sans-I/O protocol layer.  Use this to build {@link HttpRequest}
+   * descriptors without performing any I/O.
    */
+  readonly protocol: EsploraProtocol;
+
+  private readonly executor: HttpExecutor;
+
+  /** Transaction-related API calls. */
   public transaction: BitcoinTransaction;
 
-  /**
-   * The api calls related to bitcoin blocks.
-   * @type {BitcoinBlock}
-   */
+  /** Block-related API calls. */
   public block: BitcoinBlock;
 
-  /**
-   * The api calls related to bitcoin addresses.
-   * @type {BitcoinAddress}
-   */
+  /** Address-related API calls. */
   public address: BitcoinAddress;
 
-  /**
-   * The API call method that can be used to make requests to the REST API.
-   * @returns {Promise<any>} A promise resolving to the response data.
-   */
-  public api: (params: RestApiCallParams) => Promise<any> = this.call;
-
-  constructor(config: RestClientConfig){
-    this._config = new RestClientConfig(config);
-    this.api = this.call.bind(this);
-    this.transaction = new BitcoinTransaction(this.api);
-    this.block = new BitcoinBlock(this.api);
-    this.address = new BitcoinAddress(this.api);
-  }
+  constructor(config: RestConfig, executor?: HttpExecutor) {
+    this._config = config;
+    this.protocol = new EsploraProtocol(config);
+    this.executor = executor ?? defaultHttpExecutor;
 
-  /**
-   * Get the configuration object.
-   * @private
-   */
-  get config(): RestClientConfig {
-    const config = this._config;
-    return config;
+    const exec = this.executeRequest.bind(this);
+    this.transaction = new BitcoinTransaction(this.protocol, exec);
+    this.block = new BitcoinBlock(this.protocol, exec);
+    this.address = new BitcoinAddress(this.protocol, exec);
   }
 
-  /**
-   * Static method connects to a bitcoin node running a esplora REST API.
-   *
-   * @param {RestClientConfig} config The configuration object for the client (optional).
-   * @returns {BitcoinRestClient} A new {@link BitcoinRestClient} instance.
-   * @example
-   * ```
-   * const rest = BitcoinRestClient.connect();
-   * ```
-   */
-  public static connect(config?: RestClientConfig): BitcoinRestClient {
-    return new BitcoinRestClient(config ?? DEFAULT_BITCOIN_NETWORK_CONFIG.regtest.rest);
+  get config(): RestConfig {
+    return this._config;
   }
 
   /**
-   * Make a REST API call to the configured Bitcoin node.
-   * @private
-   * @param {RestApiCallParams} params The parameters for the API call. See {@link RestApiCallParams} for details.
-   * @param {string} [params.path] The path to the API endpoint (required).
-   * @param {string} [params.url] The full URL to the API endpoint (optional).
-   * @param {string} [params.method] The HTTP method to use (default is 'GET').
-   * @param {any} [params.body] The body of the request (optional).
-   * @param {any} [params.headers] Additional headers to include in the request (optional).
-   * @returns {Promise<any>} A promise resolving to the response data.
+   * Execute an {@link HttpRequest} built by the protocol layer,
+   * parse the response, and throw on HTTP errors.
    */
-  private async call({ path, url, method, body, headers }: RestApiCallParams): Promise<any> {
-    // Construct the URL if not provided
-    url ??= `${StringUtils.replaceEnd(this.config.host, '/')}${path}`;
-
-    // Set the method to GET if not provided
-    method ??= 'GET';
-
-    // Construct the request options
-    const requestInit = {
-      method,
-      headers : headers ?? {
-        'Content-Type' : 'application/json',
-        ...this.config.headers,
-      }
-    } as any;
-
-    // If the method is POST or PUT, add the body to the request
-    if(body) {
-      requestInit.body = JSONUtils.isObject(body) ? JSON.stringify(body) : body;
-      requestInit.method = 'POST';
-    }
-
-    // Make the request
-    const response = await fetch(url, requestInit) as RestResponse;
+  private async executeRequest(request: HttpRequest): Promise<any> {
+    const response = await this.executor(request);
 
-    // Check if the response is a text/plain response
-    const data = (response.headers.get('Content-Type') ?? 'json') === 'text/plain'
+    const contentType = response.headers.get('Content-Type') ?? '';
+    const data = contentType.includes('text/plain')
       ? await response.text()
       : await response.json();
 
-    // Check if the response is ok (status in the range 200-299)
     if (!response.ok) {
       throw new MethodError(
-        `Request to ${url} failed: ${response.status} - ${response.statusText}`,
+        `Request to ${request.url} failed: ${response.status} - ${response.statusText}`,
         'FAILED_HTTP_REQUEST',
-        { data, response }
+        { data }
       );
     }
 
     return data;
   }
-}
+}

package/src/client/rest/protocol.ts

@@ -0,0 +1,153 @@
+import { StringUtils } from '@did-btcr2/common';
+import { RestConfig } from '../../types.js';
+import { HttpRequest } from '../http.js';
+
+const HEX64_RE = /^[0-9a-f]{64}$/i;
+
+/**
+ * Sans-I/O Esplora REST API protocol.
+ *
+ * Every method returns an {@link HttpRequest} descriptor — a plain object
+ * describing *what* to request — without performing any I/O.  The caller
+ * is responsible for executing the request with an HTTP client of their
+ * choice and deserializing the response.
+ *
+ * This mirrors the pattern used by the Rust `esploda` crate where
+ * `Esplora` methods return `http::Request<()>` objects.
+ *
+ * @example
+ * ```ts
+ * const protocol = new EsploraProtocol({ host: 'https://mempool.space/api' });
+ *
+ * // Build a request descriptor (no I/O)
+ * const req = protocol.getTx('abc123...');
+ *
+ * // Execute with any HTTP client
+ * const res = await fetch(req.url, req);
+ * const tx: RawTransactionRest = await res.json();
+ * ```
+ */
+export class EsploraProtocol {
+  private readonly baseUrl: string;
+  private readonly defaultHeaders: Record<string, string>;
+
+  constructor(config: RestConfig) {
+    this.baseUrl = StringUtils.replaceEnd(config.host, '/');
+    this.defaultHeaders = {
+      'Content-Type' : 'application/json',
+      ...config.headers,
+    };
+  }
+
+  // ── validation ─────────────────────────────────────────────────────
+
+  private static assertHex64(value: string, label: string): void {
+    if (!HEX64_RE.test(value)) {
+      throw new Error(`Invalid ${label}: expected 64-char hex string`);
+    }
+  }
+
+  private static assertAddress(value: string): void {
+    if (!value || /[/\\.?#]/.test(value)) {
+      throw new Error('Invalid address: contains illegal characters');
+    }
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────────
+
+  private get(path: string): HttpRequest {
+    return {
+      url     : `${this.baseUrl}${path}`,
+      method  : 'GET',
+      headers : { ...this.defaultHeaders },
+    };
+  }
+
+  private post(path: string, body: string, headers?: Record<string, string>): HttpRequest {
+    return {
+      url     : `${this.baseUrl}${path}`,
+      method  : 'POST',
+      headers : headers ?? { ...this.defaultHeaders },
+      body,
+    };
+  }
+
+  // ── Transaction ──────────────────────────────────────────────────────
+
+  /** GET /tx/:txid */
+  getTx(txid: string): HttpRequest {
+    EsploraProtocol.assertHex64(txid, 'txid');
+    return this.get(`/tx/${txid}`);
+  }
+
+  /** GET /tx/:txid/hex */
+  getTxHex(txid: string): HttpRequest {
+    EsploraProtocol.assertHex64(txid, 'txid');
+    return this.get(`/tx/${txid}/hex`);
+  }
+
+  /** GET /tx/:txid/raw */
+  getTxRaw(txid: string): HttpRequest {
+    EsploraProtocol.assertHex64(txid, 'txid');
+    return this.get(`/tx/${txid}/raw`);
+  }
+
+  /** POST /tx */
+  postTx(hex: string): HttpRequest {
+    return this.post('/tx', hex, { 'Content-Type': 'text/plain' });
+  }
+
+  // ── Block ────────────────────────────────────────────────────────────
+
+  /** GET /blocks/tip/height */
+  getBlockTipHeight(): HttpRequest {
+    return this.get('/blocks/tip/height');
+  }
+
+  /** GET /block/:blockhash */
+  getBlock(blockhash: string): HttpRequest {
+    EsploraProtocol.assertHex64(blockhash, 'blockhash');
+    return this.get(`/block/${blockhash}`);
+  }
+
+  /** GET /block-height/:height */
+  getBlockHeight(height: number): HttpRequest {
+    return this.get(`/block-height/${height}`);
+  }
+
+  // ── Address ──────────────────────────────────────────────────────────
+
+  /** GET /address/:address/txs */
+  getAddressTxs(address: string): HttpRequest {
+    EsploraProtocol.assertAddress(address);
+    return this.get(`/address/${address}/txs`);
+  }
+
+  /** GET /address/:address/txs/mempool */
+  getAddressTxsMempool(address: string): HttpRequest {
+    EsploraProtocol.assertAddress(address);
+    return this.get(`/address/${address}/txs/mempool`);
+  }
+
+  /** GET /address/:address/txs/chain[/:last_seen_txid] */
+  getAddressTxsChain(address: string, lastSeenTxId?: string): HttpRequest {
+    EsploraProtocol.assertAddress(address);
+    if (lastSeenTxId) EsploraProtocol.assertHex64(lastSeenTxId, 'lastSeenTxId');
+    const path = lastSeenTxId
+      ? `/address/${address}/txs/chain/${lastSeenTxId}`
+      : `/address/${address}/txs/chain`;
+    return this.get(path);
+  }
+
+  /** GET /address/:address */
+  getAddressInfo(address: string): HttpRequest {
+    EsploraProtocol.assertAddress(address);
+    return this.get(`/address/${address}`);
+  }
+
+  /** GET /address/:address/utxo */
+  getAddressUtxos(address: string): HttpRequest {
+    EsploraProtocol.assertAddress(address);
+    return this.get(`/address/${address}/utxo`);
+  }
+}

package/src/client/rest/transaction.ts

@@ -1,28 +1,31 @@
 import { Bytes } from '@did-btcr2/common';
-import { RawTransactionRest, RestApiCallParams } from '../../types.js';
+import { RawTransactionRest } from '../../types.js';
+import { HttpRequest } from '../http.js';
+import { EsploraProtocol } from './protocol.js';
 
 export class BitcoinTransaction {
-  private api: (params: RestApiCallParams) => Promise<any>;
+  private readonly protocol: EsploraProtocol;
+  private readonly exec: (req: HttpRequest) => Promise<any>;
 
-  constructor(api: (params: RestApiCallParams) => Promise<any>) {
-    this.api = api;
+  constructor(protocol: EsploraProtocol, exec: (req: HttpRequest) => Promise<any>) {
+    this.protocol = protocol;
+    this.exec = exec;
   }
 
   /**
    * Returns the transaction in JSON format.
    * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxid | Esplora GET /tx/:txid } for details.
    * @param {string} txid The transaction id (required).
-   * @returns {GetRawTransaction} A promise resolving to data about a transaction in the form specified by verbosity.
+   * @returns {Promise<RawTransactionRest>} A promise resolving to data about a transaction.
    */
   public async get(txid: string): Promise<RawTransactionRest> {
-    return await this.api({ path: `/tx/${txid}` });
+    return await this.exec(this.protocol.getTx(txid));
   }
 
   /**
-   * Returns the transaction in JSON format.
-   * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxid | Esplora GET /tx/:txid } for details.
+   * Checks if a transaction is confirmed.
    * @param {string} txid The transaction id (required).
-   * @returns {GetRawTransaction} A promise resolving to data about a transaction in the form specified by verbosity.
+   * @returns {Promise<boolean>} True if the transaction is confirmed.
    */
   public async isConfirmed(txid: string): Promise<boolean> {
     const tx = await this.get(txid);
@@ -30,35 +33,32 @@ export class BitcoinTransaction {
   }
 
   /**
-   * Returns the raw transaction in hex or as binary data.
-   * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidhex | Esplora GET /tx/:txid/hex } and
-   * {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidraw | Esplora GET /tx/:txid/raw } for details.
+   * Returns the raw transaction as a hex string.
+   * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidhex | Esplora GET /tx/:txid/hex } for details.
    * @param {string} txid The transaction id (required).
-   * @returns {Promise<RawTransactionRest | string>} A promise resolving to the raw transaction in the specified format.
+   * @returns {Promise<string>} A promise resolving to the raw transaction hex.
    */
   public async getHex(txid: string): Promise<string> {
-    return await this.api({ path: `/tx/${txid}/hex` });
+    return await this.exec(this.protocol.getTxHex(txid));
   }
 
   /**
-   * Returns the raw transaction in hex or as binary data.
-   * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidhex | Esplora GET /tx/:txid/hex } and
-   * {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidraw | Esplora GET /tx/:txid/raw } for details.
+   * Returns the raw transaction as binary data.
+   * See {@link https://github.com/blockstream/esplora/blob/master/API.md#get-txtxidraw | Esplora GET /tx/:txid/raw } for details.
    * @param {string} txid The transaction id (required).
-   * @returns {Promise<RawTransactionRest | string>} A promise resolving to the raw transaction in the specified format.
+   * @returns {Promise<Bytes>} A promise resolving to the raw transaction bytes.
    */
   public async getRaw(txid: string): Promise<Bytes> {
-    return await this.api({ path: `/tx/${txid}/raw` });
+    return await this.exec(this.protocol.getTxRaw(txid));
   }
 
   /**
-   * Broadcast a raw transaction to the network. The transaction should be provided as hex in the request body. The txid
-   * will be returned on success.
+   * Broadcast a raw transaction to the network.
    * See {@link https://github.com/blockstream/esplora/blob/master/API.md#post-tx | Esplora POST /tx } for details.
    * @param {string} tx The raw transaction in hex format (required).
    * @returns {Promise<string>} The transaction id of the broadcasted transaction.
    */
   public async send(tx: string): Promise<string> {
-    return await this.api({ path: '/tx', method: 'POST', body: tx, headers: { 'Content-Type': 'text/plain' } });
+    return await this.exec(this.protocol.postTx(tx));
   }
-}
+}