Merge pull request #6 from bitcoinerlab/feature/fetchBlockStatus

feat: Implement fetchBlockStatus and fix block height comparison bug

Author: landabaso

package-lock.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/explorer",
   "description": "Bitcoin Blockchain Explorer: Client Interface featuring Esplora and Electrum Implementations.",
   "homepage": "https://github.com/bitcoinerlab/explorer",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "prettier": "@bitcoinerlab/configs/prettierConfig.json",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "bitcoinjs-lib": "^6.1.3",
-    "electrum-client": "github:BlueWallet/rn-electrum-client#76c0ea35e1a50c47f3a7f818d529ebd100161496",
+    "electrum-client": "github:BlueWallet/rn-electrum-client#47acb51149e97fab249c3f8a314f708dbee4fb6e",
     "net": "^1.0.2",
     "tls": "^0.0.1"
   }

package.json

@@ -39,5 +39,7 @@ declare module 'electrum-client' {
     blockchainEstimatefee(target: number): Promise<number>;
 
     blockchainTransaction_broadcast(txHex: string): Promise<string>;
+
+    blockchainBlock_header(height: number): Promise<string>;
   }
 }

src/electrum-client.d.ts

@@ -4,7 +4,7 @@ import ElectrumClient from 'electrum-client';
 import { checkFeeEstimates } from './checkFeeEstimates';
 //API: https://electrumx.readthedocs.io/en/latest/protocol-methods.html
 
-import { networks, Network } from 'bitcoinjs-lib';
+import { networks, Network, Block } from 'bitcoinjs-lib';
 import {
   ELECTRUM_BLOCKSTREAM_HOST,
   ELECTRUM_BLOCKSTREAM_PORT,
@@ -18,6 +18,7 @@ import {
 } from './constants';
 import {
   Explorer,
+  BlockStatus,
   IRREV_CONF_THRESH,
   MAX_TX_PER_SCRIPTPUBKEY
 } from './interface';
@@ -71,10 +72,11 @@ function defaultElectrumServer(network: Network = networks.bitcoin): {
 
 export class ElectrumExplorer implements Explorer {
   #irrevConfThresh: number;
-  #blockTipHeight!: number;
+  #tipBlockHeight!: number;
   #maxTxPerScriptPubKey: number;
   #pingInterval!: ReturnType<typeof setTimeout> | undefined;
   #client!: ElectrumClient | undefined;
+  #blockStatusMap: Map<number, BlockStatus> = new Map();
 
   #host: string;
   #port: number;
@@ -155,7 +157,7 @@ export class ElectrumExplorer implements Explorer {
       });
       this.#client.subscribe.on(
         'blockchain.headers.subscribe',
-        (headers: Array<{ height: number }>) => {
+        (headers: Array<{ height: number; hex: string }>) => {
           if (Array.isArray(headers)) {
             for (const header of headers) {
               this.#updateBlockTipHeight(header);
@@ -190,6 +192,24 @@ export class ElectrumExplorer implements Explorer {
     }, 60 * 1000); // 60 * 1000 ms = 1 minute
   }
 
+  /**
+   * Implements {@link Explorer#fetchBlockStatus}.
+   */
+  async fetchBlockStatus(
+    blockHeight: number
+  ): Promise<BlockStatus | undefined> {
+    let blockStatus = this.#blockStatusMap.get(blockHeight);
+    if (blockStatus && blockStatus.irreversible) return blockStatus;
+    if (blockHeight > this.#tipBlockHeight) return;
+
+    const client = await this.#getClient();
+    const headerHex = await client.blockchainBlock_header(blockHeight);
+    //cache header info to skip queries in fetchBlockStatus
+    blockStatus = this.#updateBlockStatusMap(blockHeight, headerHex);
+
+    return blockStatus;
+  }
+
   /**
    * Implements {@link Explorer#close}.
    */
@@ -213,21 +233,42 @@ export class ElectrumExplorer implements Explorer {
     }
   }
 
-  #updateBlockTipHeight(header: { height: number }) {
+  #updateBlockStatusMap(blockHeight: number, headerHex: string): BlockStatus {
+    let blockStatus = this.#blockStatusMap.get(blockHeight);
+    if (blockStatus && blockStatus.irreversible) return blockStatus;
+
+    const headerBuffer = Buffer.from(headerHex, 'hex');
+    const header = Block.fromBuffer(headerBuffer);
+
+    const blockHash = header.getId();
+    const blockTime = header.timestamp;
+    const numConfirmations = this.#tipBlockHeight - blockHeight + 1;
+    const irreversible = numConfirmations >= this.#irrevConfThresh;
+
+    blockStatus = { blockHeight, blockHash, blockTime, irreversible };
+    this.#blockStatusMap.set(blockHeight, blockStatus);
+
+    return blockStatus;
+  }
+
+  #updateBlockTipHeight(header: { height: number; hex: string }) {
     if (
       header &&
+      header.hex &&
       header.height &&
-      (typeof this.#blockTipHeight === 'undefined' ||
-        header.height > this.#blockTipHeight)
+      (typeof this.#tipBlockHeight === 'undefined' ||
+        header.height > this.#tipBlockHeight)
     ) {
-      this.#blockTipHeight = header.height;
-      //this.#blockTime = Math.floor(+new Date() / 1000);
+      this.#tipBlockHeight = header.height;
+
+      //cache header info to skip queries in fetchBlockStatus
+      this.#updateBlockStatusMap(header.height, header.hex);
     }
   }
 
-  async getBlockHeight() {
-    return this.#blockTipHeight;
-  }
+  //async #getBlockHeight() {
+  //  return this.#tipBlockHeight;
+  //}
 
   /**
    * Implements {@link Explorer#fetchAddress}.
@@ -309,13 +350,13 @@ export class ElectrumExplorer implements Explorer {
    */
   async fetchBlockHeight(): Promise<number> {
     //Get's the client even if we don't need to use it. We call this so that it
-    //throws if it's not connected (and this.#blockTipHeight is erroneous)
+    //throws if it's not connected (and this.#tipBlockHeight is erroneous)
     await this.#getClient();
-    if (this.#blockTipHeight === undefined)
+    if (this.#tipBlockHeight === undefined)
       throw new Error(
         `Error: block tip height has not been retrieved yet. Probably not connected`
       );
-    return this.#blockTipHeight;
+    return this.#tipBlockHeight;
   }
 
   /**
@@ -354,14 +395,14 @@ export class ElectrumExplorer implements Explorer {
     const transactionHistory = history.map(({ tx_hash, height }) => {
       const txId = tx_hash;
       const blockHeight: number = height || 0;
-      if (blockHeight > this.#blockTipHeight) {
+      if (blockHeight > this.#tipBlockHeight) {
         console.warn(
-          `tx ${tx_hash} block height ${blockHeight} larger than the tip ${this.#blockTipHeight}`
+          `tx ${tx_hash} block height ${blockHeight} larger than the tip ${this.#tipBlockHeight}`
         );
-        this.#blockTipHeight = blockHeight;
+        this.#tipBlockHeight = blockHeight;
       }
       const numConfirmations = blockHeight
-        ? this.#blockTipHeight - blockHeight + 1
+        ? this.#tipBlockHeight - blockHeight + 1
         : 0;
       const irreversible = numConfirmations >= this.#irrevConfThresh;
       return { txId, blockHeight, irreversible };

src/electrum.ts

@@ -4,6 +4,7 @@ import { ESPLORA_BLOCKSTREAM_URL } from './constants';
 import { reverseScriptHash } from './address';
 
 import {
+  BlockStatus,
   Explorer,
   IRREV_CONF_THRESH,
   MAX_TX_PER_SCRIPTPUBKEY
@@ -60,10 +61,11 @@ function isValidHttpUrl(string: string): boolean {
 export class EsploraExplorer implements Explorer {
   #irrevConfThresh: number;
   #BLOCK_HEIGHT_CACHE_TIME: number = 3; //cache for 3 seconds at most
-  #cachedBlockTipHeight: number = 0;
-  #blockTipHeightCacheTime: number = 0;
+  #cachedTipBlockHeight: number = 0;
+  #tipBlockHeightCacheTime: number = 0;
   #url: string;
   #maxTxPerScriptPubKey: number;
+  #blockStatusMap: Map<number, BlockStatus> = new Map();
 
   /**
    * @param {object} params
@@ -95,6 +97,37 @@ export class EsploraExplorer implements Explorer {
     return;
   }
 
+  /**
+   * Implements {@link Explorer#fetchBlockStatus}.
+   */
+  async fetchBlockStatus(
+    blockHeight: number
+  ): Promise<BlockStatus | undefined> {
+    let blockStatus = this.#blockStatusMap.get(blockHeight);
+    if (blockStatus && blockStatus.irreversible) return blockStatus;
+    if (blockHeight > (await this.#getTipBlockHeight())) return;
+
+    const blockHash = await esploraFetchText(
+      `${this.#url}/block-height/${blockHeight}`
+    );
+    const fetchedBlock = (await esploraFetchJson(
+      `${this.#url}/block/${blockHash}`
+    )) as { timestamp: number };
+    const tipBlockHeight = await this.#getTipBlockHeight(blockHeight);
+    const numConfirmations = tipBlockHeight - blockHeight + 1;
+    const irreversible = numConfirmations >= this.#irrevConfThresh;
+    blockStatus = {
+      blockHeight,
+      blockHash,
+      blockTime: fetchedBlock.timestamp,
+      irreversible
+    };
+    //cache this info to skip queries in fetchBlockStatus
+    this.#blockStatusMap.set(blockHeight, blockStatus);
+
+    return blockStatus;
+  }
+
   async fetchAddressOrScriptHash({
     address,
     scriptHash
@@ -193,28 +226,28 @@ export class EsploraExplorer implements Explorer {
    * @returns A number representing the current height.
    */
   async fetchBlockHeight(): Promise<number> {
-    const blockTipHeight = parseInt(
+    const tipBlockHeight = parseInt(
       await esploraFetchText(`${this.#url}/blocks/tip/height`)
     );
-    this.#cachedBlockTipHeight = blockTipHeight;
-    this.#blockTipHeightCacheTime = Math.floor(+new Date() / 1000);
-    return blockTipHeight;
+    this.#cachedTipBlockHeight = tipBlockHeight;
+    this.#tipBlockHeightCacheTime = Math.floor(+new Date() / 1000);
+    return tipBlockHeight;
   }
 
   /** Returns the height of the last block.
    * It does not fetch it, unless either:
    *    fetched before more than #BLOCK_HEIGHT_CACHE_TIME ago
-   *    the #cachedBlockTipHeight is behind the blockHeight passed as a param
+   *    the #cachedTipBlockHeight is behind the blockHeight passed as a param
    */
 
-  async #getBlockHeight(blockHeight?: number): Promise<number> {
+  async #getTipBlockHeight(blockHeight?: number): Promise<number> {
     const now: number = +new Date() / 1000;
     if (
-      now - this.#blockTipHeightCacheTime > this.#BLOCK_HEIGHT_CACHE_TIME ||
-      (blockHeight && blockHeight > this.#blockTipHeightCacheTime)
+      now - this.#tipBlockHeightCacheTime > this.#BLOCK_HEIGHT_CACHE_TIME ||
+      (blockHeight && blockHeight > this.#cachedTipBlockHeight)
     )
       await this.fetchBlockHeight();
-    return this.#cachedBlockTipHeight;
+    return this.#cachedTipBlockHeight;
   }
 
   /**
@@ -242,7 +275,14 @@ export class EsploraExplorer implements Explorer {
 
     const txHistory = [];
 
-    type FetchedTxs = Array<{ txid: string; status: { block_height: number } }>;
+    type FetchedTxs = Array<{
+      txid: string;
+      status: {
+        block_height: number | null;
+        block_hash: string | null;
+        block_time: number | null;
+      };
+    }>;
 
     let fetchedTxs: FetchedTxs;
     let lastTxid: string | undefined;
@@ -258,15 +298,23 @@ export class EsploraExplorer implements Explorer {
       if (lastTx) {
         if (lastTx.status.block_height !== 0) lastTxid = lastTx.txid;
         for (const fetchedTx of fetchedTxs) {
+          let irreversible = false;
+          let blockHeight = 0;
           const txId = fetchedTx.txid;
           const status = fetchedTx.status;
-          const blockHeight = status.block_height || 0;
-          const blockTipHeight = await this.#getBlockHeight(blockHeight);
-          const numConfirmations =
-            blockHeight === 0 ? 0 : blockTipHeight - blockHeight + 1;
-          const irreversible =
-            blockHeight !== 0 && numConfirmations >= this.#irrevConfThresh;
-
+          if (status.block_hash && status.block_time && status.block_height) {
+            const tipBlockHeight = await this.#getTipBlockHeight(blockHeight);
+            blockHeight = status.block_height;
+            const numConfirmations = tipBlockHeight - blockHeight + 1;
+            irreversible = numConfirmations >= this.#irrevConfThresh;
+            //cache this info to skip queries in fetchBlockStatus
+            this.#blockStatusMap.set(status.block_height, {
+              blockHeight,
+              blockTime: status.block_time,
+              blockHash: status.block_hash,
+              irreversible
+            });
+          }
           txHistory.push({ txId, blockHeight, irreversible });
           if (txHistory.length > this.#maxTxPerScriptPubKey)
             throw new Error(`Too many transactions per address`);

src/esplora.ts

@@ -99,7 +99,17 @@ export interface Explorer {
   fetchFeeEstimates(): Promise<Record<string, number>>;
 
   /**
-   * Get's current block height.
+   * Get's the `BlockStatus: { blockHeight: number; blockHash: string; blockTime: number; }`)
+   * of a certain `blockHeight`.
+   *
+   * Returns `undefined` if this block height has not been mined yet.
+   * @async
+   * @returns `BlockStatus | undefined`;
+   */
+  fetchBlockStatus(blockHeight: number): Promise<BlockStatus | undefined>;
+
+  /**
+   * Get's current block height (blockchain tip).
    * @async
    * @returns A number representing the current height.
    */
@@ -114,3 +124,10 @@ export interface Explorer {
    */
   push(txHex: string): Promise<string>;
 }
+
+export type BlockStatus = {
+  blockHeight: number;
+  blockHash: string;
+  blockTime: number;
+  irreversible: boolean;
+};