mainnet-js 2.3.15 → 2.4.0

package/src/network/ElectrumNetworkProvider.ts

@@ -5,7 +5,13 @@ import {
   ConnectionStatus,
 } from "electrum-cash";
 import { default as NetworkProvider } from "./NetworkProvider.js";
-import { HeaderI, TxI, UtxoI, ElectrumBalanceI } from "../interface.js";
+import {
+  HexHeaderI,
+  TxI,
+  UtxoI,
+  ElectrumBalanceI,
+  HeaderI,
+} from "../interface.js";
 import { Network } from "../interface.js";
 import { delay } from "../util/delay.js";
 import { ElectrumRawTransaction, ElectrumUtxo } from "./interface.js";
@@ -13,6 +19,7 @@ import { ElectrumRawTransaction, ElectrumUtxo } from "./interface.js";
 import { CancelWatchFn } from "../wallet/interface.js";
 import { getTransactionHash } from "../util/transaction.js";
 import { Config } from "../config.js";
+import { decodeHeader } from "../util/header.js";
 
 export default class ElectrumNetworkProvider implements NetworkProvider {
   public electrum: ElectrumCluster | ElectrumClient;
@@ -105,6 +112,35 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
     return result.confirmed + result.unconfirmed;
   }
 
+  static rawHeaderCache = {};
+  async getHeader(
+    height: number,
+    verbose: boolean = false
+  ): Promise<HeaderI | HexHeaderI> {
+    const key = `header-${this.network}-${height}-${verbose}`;
+
+    if (Config.UseLocalStorageCache) {
+      const cached = localStorage.getItem(key);
+      if (cached) {
+        return verbose ? decodeHeader(JSON.parse(cached)) : JSON.parse(cached);
+      }
+    } else {
+      ElectrumNetworkProvider.rawTransactionCache[key];
+    }
+
+    const result = (await this.performRequest(
+      "blockchain.header.get",
+      height
+    )) as HexHeaderI;
+    if (Config.UseLocalStorageCache) {
+      localStorage.setItem(key, JSON.stringify(result));
+    } else {
+      ElectrumNetworkProvider.rawTransactionCache[key] = result;
+    }
+
+    return verbose ? decodeHeader(result) : result;
+  }
+
   async getBlockHeight(): Promise<number> {
     return ((await this.performRequest("blockchain.headers.get_tip")) as any)
       .height;
@@ -116,7 +152,7 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
     verbose: boolean = false,
     loadInputValues: boolean = false
   ): Promise<string> {
-    const key = `${this.network}-${txHash}-${verbose}-${loadInputValues}`;
+    const key = `tx-${this.network}-${txHash}-${verbose}-${loadInputValues}`;
 
     if (Config.UseLocalStorageCache) {
       const cached = localStorage.getItem(key);
@@ -219,10 +255,16 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
   }
 
   // Get transaction history of a given cashaddr
-  async getHistory(cashaddr: string): Promise<TxI[]> {
+  async getHistory(
+    cashaddr: string,
+    fromHeight: number = 0,
+    toHeight: number = -1
+  ): Promise<TxI[]> {
     const result = (await this.performRequest(
       "blockchain.address.get_history",
-      cashaddr
+      cashaddr,
+      fromHeight,
+      toHeight
     )) as TxI[];
 
     return result;
@@ -316,10 +358,13 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
     });
   }
 
-  // Wait for the next block or a block at given blockchain height.
-  public watchBlocks(callback: (header: HeaderI) => void): CancelWatchFn {
-    let acknowledged = false;
-    const waitForBlockCallback = (_header: HeaderI | HeaderI[]) => {
+  // watch for block headers and block height, if `skipCurrentHeight` is set, the notification about current block will not arrive
+  public watchBlocks(
+    callback: (header: HexHeaderI) => void,
+    skipCurrentHeight: boolean = true
+  ): CancelWatchFn {
+    let acknowledged = !skipCurrentHeight;
+    const waitForBlockCallback = (_header: HexHeaderI | HexHeaderI[]) => {
       if (!acknowledged) {
         acknowledged = true;
         return;
@@ -336,7 +381,7 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
   }
 
   // Wait for the next block or a block at given blockchain height.
-  public async waitForBlock(height?: number): Promise<HeaderI> {
+  public async waitForBlock(height?: number): Promise<HexHeaderI> {
     return new Promise(async (resolve) => {
       const cancelWatch = this.watchBlocks(async (header) => {
         if (height === undefined || header.height >= height!) {
@@ -348,13 +393,15 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
   }
 
   // subscribe to notifications sent when new block is found, the block header is sent to callback
-  async subscribeToHeaders(callback: (header: HeaderI) => void): Promise<void> {
+  async subscribeToHeaders(
+    callback: (header: HexHeaderI) => void
+  ): Promise<void> {
     await this.subscribeRequest("blockchain.headers.subscribe", callback);
   }
 
   // unsubscribe to notifications sent when new block is found
   async unsubscribeFromHeaders(
-    callback: (header: HeaderI) => void
+    callback: (header: HexHeaderI) => void
   ): Promise<void> {
     await this.unsubscribeRequest("blockchain.headers.subscribe", callback);
   }

package/src/network/NetworkProvider.ts

@@ -1,4 +1,4 @@
-import { TxI, UtxoI, Network, HeaderI } from "../interface.js";
+import { TxI, UtxoI, Network, HexHeaderI, HeaderI } from "../interface.js";
 
 export default interface NetworkProvider {
   /**
@@ -20,6 +20,12 @@ export default interface NetworkProvider {
    */
   getBalance(cashaddr: string): Promise<number>;
 
+  /**
+   * @returns The block header fetched at blockheight @param height.
+   * @param verbose steers the response type. If true, a verbose response is returned.
+   */
+  getHeader(height: number, verbose: boolean): Promise<HeaderI | HexHeaderI>;
+
   /**
    * @returns The current block height.
    */
@@ -65,14 +71,18 @@ export default interface NetworkProvider {
    * @throws {Error} When failing to get history.
    * @returns Array of transactions.
    */
-  getHistory(cashaddr: string): Promise<TxI[]>;
+  getHistory(
+    cashaddr: string,
+    fromHeight?: number,
+    toHeight?: number
+  ): Promise<TxI[]>;
 
   /**
    * Wait for the next block or a block at given blockchain height.
    * @param height If specified, waits for blockchain to reach this height.
    * @returns Block header.
    */
-  waitForBlock(height?: number): Promise<HeaderI>;
+  waitForBlock(height?: number): Promise<HexHeaderI>;
 
   /**
    * Subscribe to the address change events

package/src/util/header.test.ts

@@ -0,0 +1,34 @@
+import { HeaderI, HexHeaderI } from "../interface";
+import { disconnectProviders, initProviders } from "../network";
+import { Wallet } from "../wallet/Wif";
+
+beforeAll(async () => {
+  await initProviders();
+});
+afterAll(async () => {
+  await disconnectProviders();
+});
+
+describe("header tests", () => {
+  it("decodeHeader", async () => {
+    const wallet = await Wallet.newRandom();
+    const hexHeader = (await wallet.provider!.getHeader(854724)) as HexHeaderI;
+    expect(hexHeader.height).toBe(854724);
+    expect(hexHeader.hex).toBe(
+      "0080c4339674a81d4e35a5b590b15a6b69f93b7b22bd14845b3517000000000000000000128a8b776c82fda87f60c6fdb0de26f021cdf39ffd835dc309eb1fc6bbfaac343e2f96662d5202184db2428f"
+    );
+
+    const header = (await wallet.provider!.getHeader(854724, true)) as HeaderI;
+    expect(header.version).toBe(868515840);
+    expect(header.previousBlockHash).toBe(
+      "00000000000000000017355b8414bd227b3bf9696b5ab190b5a5354e1da87496"
+    );
+    expect(header.merkleRoot).toBe(
+      "34acfabbc61feb09c35d83fd9ff3cd21f026deb0fdc6607fa8fd826c778b8a12"
+    );
+    expect(header.timestamp).toBe(1721118526);
+    expect(header.bits).toBe(402805293);
+    expect(header.nonce).toBe(2403512909);
+    expect(header.height).toBe(854724);
+  });
+});

package/src/util/header.ts

@@ -0,0 +1,16 @@
+import { HeaderI, HexHeaderI } from "../interface";
+
+export const decodeHeader = (hexHeader: HexHeaderI): HeaderI => {
+  const result = {} as HeaderI;
+
+  const header = Buffer.from(hexHeader.hex, "hex");
+  result.version = header.readUInt32LE(0);
+  result.previousBlockHash = header.subarray(4, 36).reverse().toString("hex");
+  result.merkleRoot = header.subarray(36, 68).reverse().toString("hex");
+  result.timestamp = header.readUInt32LE(68);
+  result.bits = header.readUInt32LE(72);
+  result.nonce = header.readUInt32LE(76);
+  result.height = hexHeader.height;
+
+  return result;
+};

package/src/util/index.ts

@@ -34,3 +34,4 @@ export {
   balanceResponseFromSatoshi,
 } from "./balanceObjectFromSatoshi.js";
 export * from "./sumUtxoValue.js";
+export { decodeHeader } from "./header.js";

package/src/wallet/Wif.ts

@@ -2,7 +2,6 @@
 // Stable
 import {
   decodeCashAddress,
-  decodeCashAddressVersionByte,
   encodeHdPublicKey,
   HdKeyNetwork,
   secp256k1,
@@ -25,7 +24,7 @@ import {
 import { mnemonicToSeedSync, generateMnemonic } from "@scure/bip39";
 import { NetworkType, prefixFromNetworkMap, UnitEnum } from "../enum.js";
 
-import { Network, HeaderI, TxI, NFTCapability } from "../interface.js";
+import { Network, HexHeaderI, TxI, NFTCapability } from "../interface.js";
 
 import { networkPrefixMap } from "../enum.js";
 import { PrivateKeyI, UtxoI } from "../interface.js";
@@ -104,14 +103,14 @@ import { amountInSatoshi } from "../util/amountInSatoshi.js";
 import { getXPubKey } from "../util/getXPubKey.js";
 import { DERIVATION_PATHS, DUST_UTXO_THRESHOLD } from "../constant.js";
 
-import { TransactionHistoryI } from "../history/interface.js";
 import { getAddressHistory } from "../history/electrumTransformer.js";
-import { IdentitySnapshot, Registry } from "./bcmr-v2.schema.js";
+import { IdentitySnapshot } from "./bcmr-v2.schema.js";
 import { BCMR } from "./Bcmr.js";
 import { qrAddress } from "../qr/Qr.js";
 import { ImageI } from "../qr/interface.js";
 import { Config } from "../config.js";
 import { checkUtxos } from "../util/checkUtxos.js";
+import { TransactionHistoryItem } from "../history/interface.js";
 
 //#endregion Imports
 
@@ -1282,25 +1281,53 @@ export class Wallet extends BaseWallet {
   }
 
   // gets transaction history of this wallet
-  public async getRawHistory(): Promise<TxI[]> {
-    return await this.provider!.getHistory(this.cashaddr!);
+  public async getRawHistory(
+    fromHeight: number = 0,
+    toHeight: number = -1
+  ): Promise<TxI[]> {
+    return await this.provider!.getHistory(
+      this.cashaddr!,
+      fromHeight,
+      toHeight
+    );
   }
 
-  // gets transaction history of this wallet
-  public async getHistory(
-    unit: UnitEnum,
-    start?: number,
-    count?: number,
-    collapseChange?: boolean
-  ): Promise<TransactionHistoryI> {
-    return getAddressHistory(
-      this.cashaddr!,
-      this.provider!,
+  /**
+   * getHistory gets transaction history of this wallet with most data decoded and ready to present to user
+   * @note balance calculations are valid only if querying to the blockchain tip (`toHeight` === -1, `count` === -1)
+   * @note this method is heavy on network calls, if invoked in browser use of cache is advised, @see `Config.UseLocalStorageCache`
+   * @note this method tries to recreate the history tab view of Electron Cash wallet, however, it may not be 100% accurate if the tnransaction value changes are the same in the same block (ordering)
+   *
+   * @param unit optional, BCH or currency unit to present balance and balance changes. If unit is currency like USD or EUR, balances will be subject to possible rounding errors. Default 0
+   * @param fromHeight optional, if set, history will be limited. Default 0
+   * @param toHeight optional, if set, history will be limited. Default -1, meaning that all history items will be returned, including mempool
+   * @param start optional, if set, the result set will be paginated with offset `start`
+   * @param count optional, if set, the result set will be paginated with `count`. Default -1, meaning that all history items will be returned
+   *
+   * @returns an array of transaction history items, with input values and addresses encoded in cashaddress format. @see `TransactionHistoryItem` type
+   */
+  public async getHistory({
+    unit = "sat",
+    fromHeight = 0,
+    toHeight = -1,
+    start = 0,
+    count = -1,
+  }: {
+    unit?: UnitEnum;
+    fromHeight?: number;
+    toHeight?: number;
+    start?: number;
+    count?: number;
+  }): Promise<TransactionHistoryItem[]> {
+    return getAddressHistory({
+      address: this.cashaddr!,
+      provider: this.provider!,
       unit,
+      fromHeight,
+      toHeight,
       start,
       count,
-      collapseChange
-    );
+    });
   }
 
   // gets last transaction of this wallet
@@ -1393,11 +1420,18 @@ export class Wallet extends BaseWallet {
    * watchBlocks Watch network blocks
    *
    * @param callback callback with a block header object
+   * @param skipCurrentHeight if set, the notification about current block will not arrive
    *
    * @returns a function which will cancel watching upon evaluation
    */
-  public watchBlocks(callback: (header: HeaderI) => void): CancelWatchFn {
-    return (this.provider! as ElectrumNetworkProvider).watchBlocks(callback);
+  public watchBlocks(
+    callback: (header: HexHeaderI) => void,
+    skipCurrentHeight: boolean = true
+  ): CancelWatchFn {
+    return (this.provider! as ElectrumNetworkProvider).watchBlocks(
+      callback,
+      skipCurrentHeight
+    );
   }
 
   /**
@@ -1406,7 +1440,7 @@ export class Wallet extends BaseWallet {
    * @param height if specified waits for this exact blockchain height, otherwise resolves with the next block
    *
    */
-  public async waitForBlock(height?: number): Promise<HeaderI> {
+  public async waitForBlock(height?: number): Promise<HexHeaderI> {
     return (this.provider! as ElectrumNetworkProvider).waitForBlock(height);
   }
   //#endregion Funds