brk-client 0.3.0-beta.9 → 0.3.0

package/index.js

@@ -281,6 +281,54 @@ Matches mempool.space/bitcoin-cli behavior.
  * @property {(Height|null)=} height - Block height (only if in best chain)
  * @property {(BlockHash|null)=} nextBest - Hash of the next block in the best chain (null if tip)
  */
+/**
+ * Projected next-block contents from Bitcoin Core's `getblocktemplate`
+ * (block 0 of the snapshot). Returned by
+ * `GET /api/v1/mempool/block-template`.
+ *
+ * @typedef {Object} BlockTemplate
+ * @property {NextBlockHash} hash - Pass back as `<hash>` on
+`/api/v1/mempool/block-template/diff/{hash}` to fetch deltas.
+ * @property {MempoolBlock} stats - Aggregate stats for this block (size, vsize, fee range, ...).
+ * @property {Transaction[]} transactions - Full transaction bodies in `getblocktemplate` order.
+ */
+/**
+ * Delta between the current `getblocktemplate` projection and a prior
+ * one identified by `since`. Returned by
+ * `GET /api/v1/mempool/block-template/diff/{hash}`.
+ *
+ * `order` carries the full new template in template order: each entry
+ * is either a `Retained(idx)` pointing into the prior template (which
+ * the client cached at `since`) or a `New(tx)` inline body. Walk it
+ * once to rebuild the new template; no separate `added` array to
+ * cross-reference.
+ *
+ * `removed` is redundant (computable from `order` by collecting prior
+ * indices that don't appear) but shipped for cache-eviction ergonomics.
+ *
+ * @typedef {Object} BlockTemplateDiff
+ * @property {NextBlockHash} hash - Current next-block hash. Use as `since` on the next diff call.
+ * @property {NextBlockHash} since - Echoed prior hash the diff was computed against.
+ * @property {BlockTemplateDiffEntry[]} order - New template in order. Each entry is either an index into the
+prior template's transactions or a full transaction body.
+ * @property {Txid[]} removed - Txids that left the projected next block since `since`
+(confirmed, evicted, replaced, or pushed past block 0).
+ */
+/**
+ * One slot of the new template in a `BlockTemplateDiff`.
+ *
+ * Untagged on the wire so JSON type disambiguates the variants:
+ * - `Retained(idx)` serializes as a bare integer - index into the
+ *   transactions of the prior template (which the client cached at
+ *   `since`).
+ * - `New(tx)` serializes as a transaction object - a body that was
+ *   not in the prior template and must be added at this position.
+ *
+ * Reconstruction is a single pass: for each entry, either copy
+ * `prior[idx]` or append the inline body.
+ *
+ * @typedef {(number|Transaction)} BlockTemplateDiffEntry
+ */
 /**
  * Block information returned for timestamp queries
  *
@@ -711,6 +759,20 @@ ancestors and no descendants (matches mempool.space).
 /** @typedef {number} Month1 */
 /** @typedef {number} Month3 */
 /** @typedef {number} Month6 */
+/**
+ * Content hash of the projected next block (block 0 of the mempool
+ * snapshot). Same value as the mempool ETag. Opaque token: pass back
+ * as `since` on `/api/v1/mempool/block-template/diff/{hash}` to fetch
+ * deltas.
+ *
+ * @typedef {number} NextBlockHash
+ */
+/**
+ * `since` hash for `/api/v1/mempool/block-template/diff/{hash}`.
+ *
+ * @typedef {Object} NextBlockHashParam
+ * @property {NextBlockHash} hash
+ */
 /**
  * OHLC (Open, High, Low, Close) data in cents
  *
@@ -7499,7 +7561,7 @@ function createTransferPattern(client, acc) {
  * @extends BrkClientBase
  */
 class BrkClient extends BrkClientBase {
-  VERSION = "v0.3.0-beta.9";
+  VERSION = "v0.3.0";
 
   INDEXES = /** @type {const} */ ([
     "minute10",
@@ -10473,7 +10535,7 @@ class BrkClient extends BrkClientBase {
   /**
    * Health check
    *
-   * Returns the health status of the API server, including uptime information.
+   * Liveness probe. Returns server identity, uptime, and indexed/computed heights from local state only (no bitcoind round-trip). For real chain-tip catch-up, see `/api/server/sync`.
    *
    * Endpoint: `GET /health`
    * @param {{ signal?: AbortSignal, onValue?: (value: Health) => void }} [options]
@@ -10912,7 +10974,7 @@ class BrkClient extends BrkClientBase {
   /**
    * Address transactions
    *
-   * Get transaction history for an address, sorted with newest first. Returns up to 50 entries: mempool transactions first, then confirmed transactions filling the remainder. To paginate further confirmed transactions, use `/address/{address}/txs/chain/{last_seen_txid}`.
+   * Get transaction history for an address, newest first. Returns up to 50 mempool transactions plus a confirmed page sized to fill the response to 50 total (chain floor of 25, so 25-50 confirmed depending on mempool weight). To paginate further confirmed history, use `/address/{address}/txs/chain/{last_seen_txid}`.
    *
    * *[Mempool.space docs](https://mempool.space/docs/api/rest#get-address-transactions)*
    *
@@ -11620,7 +11682,7 @@ class BrkClient extends BrkClientBase {
   /**
    * Projected mempool blocks
    *
-   * Get projected blocks from the mempool for fee estimation.
+   * Projected blocks for fee estimation. Block 0 reflects Bitcoin Core's actual next-block selection; blocks 1+ are a fee-tier approximation.
    *
    * *[Mempool.space docs](https://mempool.space/docs/api/rest#get-mempool-blocks-fees)*
    *
@@ -11636,7 +11698,7 @@ class BrkClient extends BrkClientBase {
   /**
    * Recommended fees
    *
-   * Get recommended fee rates for different confirmation targets.
+   * Recommended fee rates by confirmation target.
    *
    * *[Mempool.space docs](https://mempool.space/docs/api/rest#get-recommended-fees)*
    *
@@ -11652,7 +11714,7 @@ class BrkClient extends BrkClientBase {
   /**
    * Precise recommended fees
    *
-   * Get recommended fee rates with up to 3 decimal places.
+   * Recommended fee rates with sub-integer precision.
    *
    * *[Mempool.space docs](https://mempool.space/docs/api/rest#get-recommended-fees-precise)*
    *
@@ -11684,11 +11746,11 @@ class BrkClient extends BrkClientBase {
   /**
    * Mempool content hash
    *
-   * Returns an opaque `u64` that changes whenever the projected next block changes. Same value as the mempool ETag. Useful as a freshness/liveness signal: if it stays constant for tens of seconds on a live network, the mempool sync loop has stalled.
+   * Returns an opaque hash that changes whenever the projected next block changes. Same value as the mempool ETag. Useful as a freshness/liveness signal: if it stays constant for tens of seconds on a live network, the mempool sync loop has stalled.
    *
    * Endpoint: `GET /api/mempool/hash`
-   * @param {{ signal?: AbortSignal, onValue?: (value: number) => void }} [options]
-   * @returns {Promise<number>}
+   * @param {{ signal?: AbortSignal, onValue?: (value: NextBlockHash) => void }} [options]
+   * @returns {Promise<NextBlockHash>}
    */
   async getMempoolHash({ signal, onValue } = {}) {
     const path = `/api/mempool/hash`;
@@ -11759,6 +11821,36 @@ class BrkClient extends BrkClientBase {
     return this.getJson(path, { signal, onValue });
   }
 
+  /**
+   * Projected next block template
+   *
+   * Bitcoin Core's `getblocktemplate` selection: full transaction bodies in GBT order with aggregate stats. The returned `hash` is an opaque content token; pass it as `<hash>` on `/api/v1/mempool/block-template/diff/{hash}` to fetch deltas instead of refetching the whole template.
+   *
+   * Endpoint: `GET /api/v1/mempool/block-template`
+   * @param {{ signal?: AbortSignal, onValue?: (value: BlockTemplate) => void }} [options]
+   * @returns {Promise<BlockTemplate>}
+   */
+  async getBlockTemplate({ signal, onValue } = {}) {
+    const path = `/api/v1/mempool/block-template`;
+    return this.getJson(path, { signal, onValue });
+  }
+
+  /**
+   * Block template diff since hash
+   *
+   * Delta of the projected next block since `<hash>`. `order` is the full new template in order: each entry is either a number (index into the prior template the client cached at `<hash>`) or a transaction object (new body to insert at this position). Walk `order` once to rebuild; `removed` is a convenience list of txids that left so clients can evict cached bodies. After applying, use the response `hash` as `<hash>` on the next call to keep iterating. Returns `404` when `<hash>` has aged out of server history; clients should fall back to `/api/v1/mempool/block-template`.
+   *
+   * Endpoint: `GET /api/v1/mempool/block-template/diff/{hash}`
+   *
+   * @param {NextBlockHash} hash
+   * @param {{ signal?: AbortSignal, onValue?: (value: BlockTemplateDiff) => void }} [options]
+   * @returns {Promise<BlockTemplateDiff>}
+   */
+  async getBlockTemplateDiff(hash, { signal, onValue } = {}) {
+    const path = `/api/v1/mempool/block-template/diff/${hash}`;
+    return this.getJson(path, { signal, onValue });
+  }
+
   /**
    * Live BTC/USD price
    *

package/package.json

@@ -40,5 +40,5 @@
     "url": "git+https://github.com/bitcoinresearchkit/brk.git"
   },
   "type": "module",
-  "version": "0.3.0-beta.9"
+  "version": "0.3.0"
 }