mainnet-js 3.1.7 → 4.0.0-next.2

package/src/wallet/Watch.ts

@@ -6,6 +6,8 @@ import {
   encodeCashAddress,
   assertSuccess,
   hash160,
+  sha256,
+  utf8ToBin,
   decodeCashAddressFormatWithoutPrefix,
 } from "@bitauth/libauth";
 import {
@@ -19,12 +21,17 @@ import { WalletTypeEnum } from "./enum.js";
 import { DUST_UTXO_THRESHOLD } from "../constant.js";
 import { TxI, Utxo } from "../interface.js";
 import { derivePrefix } from "../util/derivePublicKeyHash.js";
-import { SignedMessage } from "../message/signed.js";
 import { VerifyMessageResponseI } from "../message/interface.js";
 import { TransactionHistoryItem } from "../history/interface.js";
 import { getHistory } from "../history/getHistory.js";
-import { WalletInfoI } from "./interface.js";
+import { CancelFn, WalletInfoI } from "./interface.js";
 import { toCashaddr, toTokenaddr } from "../util/deriveCashaddr.js";
+import { sumUtxoValue } from "../util/sumUtxoValue.js";
+import {
+  SingleAddressWalletCache,
+  WalletCacheEntry,
+  WalletCacheI,
+} from "../cache/walletCache.js";
 
 export interface WatchWalletOptions {
   name?: string;
@@ -38,6 +45,7 @@ export interface WatchWalletOptions {
  * Class to manage a mainnet watch wallet.
  */
 export class WatchWallet extends BaseWallet {
+  declare readonly walletCache: WalletCacheI;
   readonly publicKeyCompressed?: Uint8Array;
   readonly publicKey?: Uint8Array;
   readonly publicKeyHash!: Uint8Array;
@@ -47,6 +55,20 @@ export class WatchWallet extends BaseWallet {
   static networkPrefix = CashAddressNetworkPrefix.mainnet;
   static walletType = WalletTypeEnum.Watch;
 
+  // Subscription-first infrastructure: single subscription shared by all watchers
+  private watchCallbacks: Array<
+    (status: string | null, address: string) => void
+  > = [];
+  private baseCancelFn?: CancelFn;
+  watchPromise?: Promise<void>;
+  updatePromise?: Promise<void>;
+
+  // Live state — updated by subscription notifications
+  private status: string | null = null;
+  private utxos: Utxo[] = [];
+  private rawHistory: TxI[] = [];
+  private lastConfirmedHeight: number = 0;
+
   constructor(
     name = "",
     network = NetworkType.Mainnet,
@@ -141,9 +163,159 @@ export class WatchWallet extends BaseWallet {
 
     this.name = name;
 
+    // Initialize persistent cache and load saved state
+    await this.initWalletCache();
+    const cached = this.getCacheEntry();
+    this.status = cached.status;
+    this.utxos = cached.utxos;
+    this.rawHistory = cached.rawHistory;
+    this.lastConfirmedHeight = cached.lastConfirmedHeight;
+
+    // Start subscription immediately (subscription-first approach)
+    this.watchPromise = this.makeWatchPromise().catch(() => {});
+
     return this;
   }
 
+  protected deriveWalletId(): string {
+    return binToHex(sha256.hash(utf8ToBin(`${this.cashaddr}-${this.network}`)));
+  }
+
+  protected async initWalletCache(): Promise<void> {
+    const cache = new SingleAddressWalletCache(
+      this.deriveWalletId(),
+      this.cashaddr,
+      this.tokenaddr
+    );
+    await cache.init();
+    const wallet = this as any;
+    if (wallet.privateKey) {
+      cache.get(this.cashaddr)!.privateKey = wallet.privateKey;
+    }
+    // @ts-ignore
+    this.walletCache = cache;
+  }
+
+  protected getCacheEntry(): WalletCacheEntry {
+    return this.walletCache.get(this.cashaddr)!;
+  }
+
+  /// Subscribe to the single address for status change notifications
+  private async makeWatchPromise(): Promise<void> {
+    const addr = this.cashaddr;
+    let resolved = false;
+
+    return new Promise<void>(async (resolve) => {
+      this.baseCancelFn = await this.provider.subscribeToAddress(
+        addr,
+        async (args: [address: string, status: string | null]) => {
+          const [address, status] = args;
+          if (address !== addr) return;
+
+          if (status !== null && status !== this.status) {
+            this.updatePromise = this.fetchData(status);
+          }
+          this.status = status;
+          this.notifyWatchCallbacks(status, addr);
+
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        }
+      );
+    });
+  }
+
+  private async fetchData(status: string | null): Promise<void> {
+    const addr = this.cashaddr;
+    const fromHeight = this.lastConfirmedHeight;
+
+    const [utxos, newHistory] = await Promise.all([
+      this.provider.getUtxos(addr),
+      this.provider.getHistory(addr, fromHeight),
+    ]);
+
+    // Merge: keep confirmed items below fromHeight, add new items
+    const confirmedFromHistory = this.rawHistory.filter(
+      (tx) => tx.height > 0 && tx.height < fromHeight
+    );
+    const seen = new Set(confirmedFromHistory.map((tx) => tx.tx_hash));
+    const merged = [...confirmedFromHistory];
+    for (const tx of newHistory) {
+      if (!seen.has(tx.tx_hash)) {
+        seen.add(tx.tx_hash);
+        merged.push(tx);
+      }
+    }
+
+    this.lastConfirmedHeight = merged.reduce(
+      (max, tx) => (tx.height > 0 ? Math.max(max, tx.height) : max),
+      fromHeight
+    );
+
+    // Update live state
+    this.utxos = utxos;
+    this.rawHistory = merged;
+
+    // Persist to cache
+    this.walletCache.setStatusAndUtxos(
+      addr,
+      status,
+      utxos,
+      merged,
+      this.lastConfirmedHeight
+    );
+  }
+
+  private notifyWatchCallbacks(status: string | null, address: string) {
+    for (const callback of this.watchCallbacks) {
+      try {
+        callback(status, address);
+      } catch (_e) {
+        // Ignore callback errors to not break other watchers
+      }
+    }
+  }
+
+  public override async watchStatus(
+    callback: (status: string | null, address: string) => void
+  ): Promise<CancelFn> {
+    await this.watchPromise;
+
+    this.watchCallbacks.push(callback);
+
+    return async () => {
+      const index = this.watchCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.watchCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  public override async waitForUpdate(
+    options: { timeout?: number } = {}
+  ): Promise<void> {
+    const timeout = options.timeout ?? 100;
+
+    let cancel: CancelFn;
+    const statusChange = new Promise<void>(async (resolve) => {
+      cancel = await this.watchStatus(() => resolve());
+    });
+
+    const timer = new Promise<void>((resolve) => setTimeout(resolve, timeout));
+
+    await Promise.race([statusChange, timer]);
+    await cancel!();
+  }
+
+  public override async stop() {
+    await super.stop();
+    await this.baseCancelFn?.();
+    this.baseCancelFn = undefined;
+    this.watchCallbacks = [];
+  }
+
   /**
    * getDepositAddress - get a wallet deposit address
    *
@@ -227,16 +399,20 @@ export class WatchWallet extends BaseWallet {
    *
    */
   public async getUtxos(): Promise<Utxo[]> {
-    const bchUtxos: Utxo[] = await this.provider.getUtxos(this.cashaddr);
+    await this.watchPromise;
+    await this.updatePromise;
+
     return this._slpSemiAware
-      ? bchUtxos.filter((u) => u.satoshis > DUST_UTXO_THRESHOLD)
-      : bchUtxos;
+      ? this.utxos.filter((u) => u.satoshis > DUST_UTXO_THRESHOLD)
+      : this.utxos;
   }
 
   // Gets balance by summing value in all utxos in sats
   // Balance includes DUST utxos which could be slp tokens and also cashtokens with BCH amounts
   public async getBalance(): Promise<bigint> {
-    return this.provider.getBalance(this.cashaddr);
+    await this.watchPromise;
+    await this.updatePromise;
+    return sumUtxoValue(this.utxos);
   }
 
   // gets transaction history of this wallet
@@ -244,7 +420,23 @@ export class WatchWallet extends BaseWallet {
     fromHeight: number = 0,
     toHeight: number = -1
   ): Promise<TxI[]> {
-    return await this.provider.getHistory(this.cashaddr, fromHeight, toHeight);
+    await this.watchPromise;
+    await this.updatePromise;
+
+    let history = this.rawHistory;
+
+    if (fromHeight > 0 || toHeight !== -1) {
+      history = history.filter((tx) => {
+        if (tx.height <= 0) {
+          return toHeight === -1;
+        }
+        const aboveFrom = tx.height >= fromHeight;
+        const belowTo = toHeight === -1 || tx.height <= toHeight;
+        return aboveFrom && belowTo;
+      });
+    }
+
+    return history;
   }
 
   /**

package/src/wallet/Wif.test.ts

@@ -891,6 +891,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
       cashaddr: charlieWallet.cashaddr!,
       value: DUST,
     });
+    await charlieWallet.waitForUpdate();
     expect(await charlieWallet.getBalance()).toBe(DUST);
   });
 
@@ -911,6 +912,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
       cashaddr: charlieWallet.cashaddr!,
       value: DUST,
     });
+    await charlieWallet.waitForUpdate();
     expect(await charlieWallet.getBalance()).toBe(DUST);
   });
 
@@ -928,6 +930,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
     ]);
 
     await bobWallet.send([{ cashaddr: charlieWallet.cashaddr!, value: DUST }]);
+    await charlieWallet.waitForUpdate();
     expect(await charlieWallet.getBalance()).toBe(DUST);
   });
 
@@ -945,6 +948,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
     ]);
 
     await bobWallet.send([{ cashaddr: charlieWallet.cashaddr!, value: DUST }]);
+    await charlieWallet.waitForUpdate();
     expect(await charlieWallet.getBalance()).toBe(DUST);
   });
 
@@ -960,6 +964,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
     ]);
 
     await bobWallet.send([{ cashaddr: charlieWallet.cashaddr!, value: DUST }]);
+    await charlieWallet.waitForUpdate();
     expect(await charlieWallet.getBalance()).toBe(DUST);
   });
   test(`Should throw error with dust amounts (${
@@ -1033,6 +1038,7 @@ describe(`Wallet extrema behavior regression testing`, () => {
       { cashaddr: bob.getDepositAddress(), value: 546n },
       { cashaddr: bob.getDepositAddress(), value: 1000n },
     ]);
+    await bob.waitForUpdate();
     expect(sumUtxoValue(await bob.getUtxos())).toBe(1546n);
     bob.slpSemiAware();
     expect(sumUtxoValue(await bob.getUtxos())).toBe(1000n);

package/src/wallet/Wif.ts

@@ -65,7 +65,7 @@ export interface WalletOptions {
  * Class to manage a bitcoin cash wallet.
  */
 export class Wallet extends WatchWallet {
-  declare readonly provider: ElectrumNetworkProvider;
+  declare provider: ElectrumNetworkProvider;
 
   readonly derivationPath: string = Config.DefaultParentDerivationPath + "/0/0";
   readonly parentDerivationPath: string = Config.DefaultParentDerivationPath;
@@ -223,16 +223,9 @@ export class Wallet extends WatchWallet {
       address,
     });
 
-    if (this.privateKey) {
-      // @ts-ignore
-      this.walletCache = new Map<string, { privateKey: Uint8Array }>().set(
-        this.cashaddr,
-        { privateKey: this.privateKey }
-      );
-    }
-
     return this;
   }
+
   //#endregion Constructors and Statics
 
   //#region Accessors

package/tsconfig.browser.json

@@ -3,7 +3,16 @@
   "compilerOptions": {
     "baseUrl": "src",
     "paths": {
-      "pg": ["false*"]
+      "pg": ["false*"],
+      "@rpckit/core/electrum-cash": [
+        "../../../node_modules/@rpckit/core/dist/electrum-cash/index.d.ts"
+      ],
+      "@rpckit/websocket/electrum-cash": [
+        "../../../node_modules/@rpckit/websocket/dist/electrum-cash/index.d.ts"
+      ],
+      "@rpckit/fallback/electrum-cash": [
+        "../../../node_modules/@rpckit/fallback/dist/electrum-cash/index.d.ts"
+      ]
     }
   },
   "include": ["src/**/*.ts"],

package/tsconfig.json

@@ -25,7 +25,18 @@
     "sourceMap": true,
     "noEmit": false,
     "strictPropertyInitialization": false,
-    "useDefineForClassFields": false
+    "useDefineForClassFields": false,
+    "paths": {
+      "@rpckit/core/electrum-cash": [
+        "../../node_modules/@rpckit/core/dist/electrum-cash/index.d.ts"
+      ],
+      "@rpckit/websocket/electrum-cash": [
+        "../../node_modules/@rpckit/websocket/dist/electrum-cash/index.d.ts"
+      ],
+      "@rpckit/fallback/electrum-cash": [
+        "../../node_modules/@rpckit/fallback/dist/electrum-cash/index.d.ts"
+      ]
+    }
   },
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules/**", "src/**/*test.ts"],

package/webpack.config.cjs

@@ -15,6 +15,7 @@ const baseConfig = {
     extensionAlias: {
       ".js": [".ts", ".js"],
     },
+    symlinks: true,
   },
   optimization: {
     minimize: false,

package/dist/module/network/util.d.ts

@@ -1,3 +0,0 @@
-import { ElectrumHostParams } from "./interface.js";
-export declare function parseElectrumUrl(givenUrl: string): ElectrumHostParams;
-//# sourceMappingURL=util.d.ts.map

package/dist/module/network/util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/network/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAMrE"}

package/dist/module/network/util.js

@@ -1,27 +0,0 @@
-export function parseElectrumUrl(givenUrl) {
-    let url = new URL(givenUrl);
-    let port = parseInt(url.port || "443");
-    let scheme = getElectrumScheme(url.protocol);
-    return { host: url.hostname, port: port, scheme: scheme };
-}
-function getElectrumScheme(protocol) {
-    let transport;
-    switch (protocol) {
-        case "http:":
-            transport = "tcp";
-            break;
-        case "https:":
-            transport = "tcp_tls";
-            break;
-        case "ws:":
-            transport = "ws";
-            break;
-        case "wss:":
-            transport = "wss";
-            break;
-        default:
-            throw Error("Electrum transport protocol not understood.");
-    }
-    return transport;
-}
-//# sourceMappingURL=util.js.map

package/dist/module/network/util.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../../../src/network/util.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC;IACvC,IAAI,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE7C,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB;IACzC,IAAI,SAAiB,CAAC;IACtB,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO;YACV,SAAS,GAAG,KAAK,CAAC;YAClB,MAAM;QACR,KAAK,QAAQ;YACX,SAAS,GAAG,SAAS,CAAC;YACtB,MAAM;QACR,KAAK,KAAK;YACR,SAAS,GAAG,IAAI,CAAC;YACjB,MAAM;QACR,KAAK,MAAM;YACT,SAAS,GAAG,KAAK,CAAC;YAClB,MAAM;QACR;YACE,MAAM,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,SAA6C,CAAC;AACvD,CAAC"}

package/src/network/util.test.ts

@@ -1,24 +0,0 @@
-import { parseElectrumUrl } from "./util";
-
-test("Should parse various electrum urls", async () => {
-  expect(parseElectrumUrl("https://localhost:1")).toEqual({
-    host: "localhost",
-    port: 1,
-    scheme: "tcp_tls",
-  });
-  expect(parseElectrumUrl("http://127.0.0.1:1")).toEqual({
-    host: "127.0.0.1",
-    port: 1,
-    scheme: "tcp",
-  });
-  expect(parseElectrumUrl("ws://1.2.3.4:10001")).toEqual({
-    host: "1.2.3.4",
-    port: 10001,
-    scheme: "ws",
-  });
-  expect(parseElectrumUrl("wss://example.space:1")).toEqual({
-    host: "example.space",
-    port: 1,
-    scheme: "wss",
-  });
-});

package/src/network/util.ts

@@ -1,30 +0,0 @@
-import { ElectrumHostParams } from "./interface.js";
-
-export function parseElectrumUrl(givenUrl: string): ElectrumHostParams {
-  let url = new URL(givenUrl);
-  let port = parseInt(url.port || "443");
-  let scheme = getElectrumScheme(url.protocol);
-
-  return { host: url.hostname, port: port, scheme: scheme };
-}
-
-function getElectrumScheme(protocol: string) {
-  let transport: string;
-  switch (protocol) {
-    case "http:":
-      transport = "tcp";
-      break;
-    case "https:":
-      transport = "tcp_tls";
-      break;
-    case "ws:":
-      transport = "ws";
-      break;
-    case "wss:":
-      transport = "wss";
-      break;
-    default:
-      throw Error("Electrum transport protocol not understood.");
-  }
-  return transport as "tcp" | "tcp_tls" | "ws" | "wss";
-}