@did-btcr2/bitcoin 0.3.4 → 0.4.0

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

@@ -0,0 +1,129 @@
+import { StringUtils } from '@did-btcr2/common';
+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 {
+    baseUrl;
+    defaultHeaders;
+    constructor(config) {
+        this.baseUrl = StringUtils.replaceEnd(config.host, '/');
+        this.defaultHeaders = {
+            'Content-Type': 'application/json',
+            ...config.headers,
+        };
+    }
+    // ── validation ─────────────────────────────────────────────────────
+    static assertHex64(value, label) {
+        if (!HEX64_RE.test(value)) {
+            throw new Error(`Invalid ${label}: expected 64-char hex string`);
+        }
+    }
+    static assertAddress(value) {
+        if (!value || /[/\\.?#]/.test(value)) {
+            throw new Error('Invalid address: contains illegal characters');
+        }
+    }
+    // ── helpers ──────────────────────────────────────────────────────────
+    get(path) {
+        return {
+            url: `${this.baseUrl}${path}`,
+            method: 'GET',
+            headers: { ...this.defaultHeaders },
+        };
+    }
+    post(path, body, headers) {
+        return {
+            url: `${this.baseUrl}${path}`,
+            method: 'POST',
+            headers: headers ?? { ...this.defaultHeaders },
+            body,
+        };
+    }
+    // ── Transaction ──────────────────────────────────────────────────────
+    /** GET /tx/:txid */
+    getTx(txid) {
+        EsploraProtocol.assertHex64(txid, 'txid');
+        return this.get(`/tx/${txid}`);
+    }
+    /** GET /tx/:txid/hex */
+    getTxHex(txid) {
+        EsploraProtocol.assertHex64(txid, 'txid');
+        return this.get(`/tx/${txid}/hex`);
+    }
+    /** GET /tx/:txid/raw */
+    getTxRaw(txid) {
+        EsploraProtocol.assertHex64(txid, 'txid');
+        return this.get(`/tx/${txid}/raw`);
+    }
+    /** POST /tx */
+    postTx(hex) {
+        return this.post('/tx', hex, { 'Content-Type': 'text/plain' });
+    }
+    // ── Block ────────────────────────────────────────────────────────────
+    /** GET /blocks/tip/height */
+    getBlockTipHeight() {
+        return this.get('/blocks/tip/height');
+    }
+    /** GET /block/:blockhash */
+    getBlock(blockhash) {
+        EsploraProtocol.assertHex64(blockhash, 'blockhash');
+        return this.get(`/block/${blockhash}`);
+    }
+    /** GET /block-height/:height */
+    getBlockHeight(height) {
+        return this.get(`/block-height/${height}`);
+    }
+    // ── Address ──────────────────────────────────────────────────────────
+    /** GET /address/:address/txs */
+    getAddressTxs(address) {
+        EsploraProtocol.assertAddress(address);
+        return this.get(`/address/${address}/txs`);
+    }
+    /** GET /address/:address/txs/mempool */
+    getAddressTxsMempool(address) {
+        EsploraProtocol.assertAddress(address);
+        return this.get(`/address/${address}/txs/mempool`);
+    }
+    /** GET /address/:address/txs/chain[/:last_seen_txid] */
+    getAddressTxsChain(address, lastSeenTxId) {
+        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) {
+        EsploraProtocol.assertAddress(address);
+        return this.get(`/address/${address}`);
+    }
+    /** GET /address/:address/utxo */
+    getAddressUtxos(address) {
+        EsploraProtocol.assertAddress(address);
+        return this.get(`/address/${address}/utxo`);
+    }
+}
+//# sourceMappingURL=protocol.js.map

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

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

package/dist/esm/client/rest/transaction.js

@@ -1,56 +1,54 @@
 export class BitcoinTransaction {
-    api;
-    constructor(api) {
-        this.api = api;
+    protocol;
+    exec;
+    constructor(protocol, exec) {
+        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.
      */
     async get(txid) {
-        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.
      */
     async isConfirmed(txid) {
         const tx = await this.get(txid);
         return tx.status.confirmed;
     }
     /**
-     * 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.
      */
     async getHex(txid) {
-        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.
      */
     async getRaw(txid) {
-        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.
      */
     async send(tx) {
-        return await this.api({ path: '/tx', method: 'POST', body: tx, headers: { 'Content-Type': 'text/plain' } });
+        return await this.exec(this.protocol.postTx(tx));
     }
 }
 //# sourceMappingURL=transaction.js.map

package/dist/esm/client/rest/transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../../src/client/rest/transaction.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,kBAAkB;IACrB,GAAG,CAA8C;IAEzD,YAAY,GAAgD;QAC1D,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,GAAG,CAAC,IAAY;QAC3B,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,WAAW,CAAC,IAAY;QACnC,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,IAAY;QAC9B,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,IAAY;QAC9B,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,IAAI,CAAC,EAAU;QAC1B,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;IAC9G,CAAC;CACF"}
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../../src/client/rest/transaction.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,kBAAkB;IACZ,QAAQ,CAAkB;IAC1B,IAAI,CAAqC;IAE1D,YAAY,QAAyB,EAAE,IAAwC;QAC7E,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,GAAG,CAAC,IAAY;QAC3B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,WAAW,CAAC,IAAY;QACnC,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,MAAM,CAAC,IAAY;QAC9B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,MAAM,CAAC,IAAY;QAC9B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,IAAI,CAAC,EAAU;QAC1B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,CAAC;CACF"}