pivx-wallet 0.3.2 → 0.3.4

package/dist/transparent-wallet.d.ts

@@ -39,6 +39,7 @@ export declare class TransparentWallet {
     private utxos;
     private lastScanned;
     private lastScannedHash;
+    private scannedHashes;
     private pending;
     /** One sync at a time (mirrors the shield wallet's busy guard). */
     private busy;

package/dist/transparent-wallet.js

@@ -14,6 +14,14 @@ const isHex = (s) => /^(?:[0-9a-fA-F]{2})+$/.test(s);
 const dustThreshold = (scriptLen) => Math.floor((30_000 * (8 + 1 + scriptLen + 148)) / 1000);
 /** Coinbase/coinstake maturity in blocks (nCoinbaseMaturity): mainnet 100, testnet 15. */
 const coinbaseMaturity = (network) => (network === 'mainnet' ? 100 : 15);
+/**
+ * Depth of the rolling (height, hash) window kept for reorg recovery. On a
+ * detected same-height tip reorg, sync walks this window newest→oldest to find
+ * the true fork and resets there; a reorg deeper than the window cannot be
+ * located safely and fails loud instead of silently retaining orphaned UTXOs.
+ * Identical in the Rust SDK.
+ */
+const REORG_WINDOW = 100;
 /**
  * hash160 of a scriptPubKey we know how to spend, if it is one: a standard
  * 25-byte P2PKH (76a914<20>88ac) or the 26-byte exchange form with an
@@ -43,6 +51,7 @@ export class TransparentWallet {
     utxos = new Map(); // "txid:vout" → utxo
     lastScanned = 0; // height of the last block passed to scanBlock
     lastScannedHash = null; // hash of that block, for reorg detection
+    scannedHashes = []; // rolling window of recent (height, hash) for the reorg walk-back
     pending = new Set(); // "txid:vout" reserved by buildSend until markSpent/release
     /** One sync at a time (mirrors the shield wallet's busy guard). */
     busy = false;
@@ -175,6 +184,14 @@ export class TransparentWallet {
             }
         }
         this.lastScannedHash = typeof block.hash === 'string' ? block.hash : null;
+        // Record this block into the rolling reorg window (same usable-hash guard as
+        // lastScannedHash), keeping only the last REORG_WINDOW entries.
+        if (typeof block.hash === 'string') {
+            this.scannedHashes.push({ height, hash: block.hash });
+            if (this.scannedHashes.length > REORG_WINDOW) {
+                this.scannedHashes.splice(0, this.scannedHashes.length - REORG_WINDOW);
+            }
+        }
     }
     /** Height of the last block passed to {@link scanBlock} (0 if none). */
     lastScannedBlock() {
@@ -193,8 +210,13 @@ export class TransparentWallet {
                 this.pending.delete(k);
             }
         }
+        // Trim the reorg window to the retained span; if the reset height is itself a
+        // known window entry (a true fork), restore its hash so scan continuity is
+        // preserved — otherwise (a manual reset to an unknown height) leave it null.
+        this.scannedHashes = this.scannedHashes.filter((e) => e.height <= height);
+        const retained = this.scannedHashes.find((e) => e.height === height);
         this.lastScanned = height;
-        this.lastScannedHash = null;
+        this.lastScannedHash = retained ? retained.hash : null;
     }
     /**
      * Sync from the node into the wallet, from `max(fromHeight, lastScanned+1)`
@@ -218,6 +240,36 @@ export class TransparentWallet {
             };
             const concurrency = 8;
             const tip = await client.getBlockCount();
+            // Stale-tip reorg detection: the forward scan only checks parent-hash
+            // continuity for blocks above lastScanned, so a same-height reorg (block N
+            // replaced while the tip stays N) leaves lastScanned == tip and is missed.
+            // Any reorg at/below lastScanned changes that block's hash, so re-verify
+            // the node's current hash for it. On a mismatch, walk the recorded window
+            // newest→oldest to find the true fork (the highest stored height whose
+            // hash the node still confirms) and reset there; the UTXO model self-heals
+            // (resetScan drops UTXOs above the fork and the re-scan re-credits the
+            // survivors). If the reorg is deeper than the window we cannot locate the
+            // fork safely, so fail loud rather than silently retain orphaned UTXOs.
+            // Honest chain = 1 getBlockHash (tip matches → skip the walk).
+            if (this.lastScanned > 0 && this.lastScannedHash !== null) {
+                const nodeTip = await client.getBlockHash(this.lastScanned);
+                if (nodeTip !== this.lastScannedHash) {
+                    let fork;
+                    for (let i = this.scannedHashes.length - 1; i >= 0; i--) {
+                        const entry = this.scannedHashes[i];
+                        if ((await client.getBlockHash(entry.height)) === entry.hash) {
+                            fork = entry.height;
+                            break;
+                        }
+                    }
+                    if (fork !== undefined) {
+                        this.resetScan(fork);
+                    }
+                    else {
+                        throw new ScanDivergedError(this.lastScanned, this.lastScannedHash, nodeTip);
+                    }
+                }
+            }
             const fetchBlock = async (h) => client.getBlock(await client.getBlockHash(h), 2);
             // NaN/0/fractional → sane integer: 0 would loop forever and fractional
             // heights would skip blocks (matches Rust batch.max(1)).
@@ -364,6 +416,9 @@ export class TransparentWallet {
             nextChange: this.nextChange,
             lastScanned: this.lastScanned,
             lastScannedHash: this.lastScannedHash,
+            // Rolling reorg window (ascending by height, newest last). Emitted here —
+            // after lastScannedHash, before utxos — for byte parity with the Rust SDK.
+            scannedHashes: this.scannedHashes.map((e) => ({ height: e.height, hash: e.hash })),
             // Sorted by (txid, vout) so save() output is deterministic and
             // byte-comparable with the Rust SDK's.
             utxos: [...this.utxos.values()]
@@ -423,6 +478,10 @@ export class TransparentWallet {
         if (!Array.isArray(s.utxos) || !Array.isArray(s.pending)) {
             throw new Error('wallet state has invalid utxo or pending lists');
         }
+        // Backward-compatible: older states have no window → treat as empty.
+        if (s.scannedHashes !== undefined && !Array.isArray(s.scannedHashes)) {
+            throw new Error('wallet state has an invalid scanned-hash window');
+        }
         const w = TransparentWallet.create(seed, s.network, s.account, s.gap);
         w.nextExternal = s.nextExternal;
         w.nextChange = s.nextChange;
@@ -462,6 +521,14 @@ export class TransparentWallet {
             }
             w.pending.add(`${p.txid}:${p.vout}`);
         }
+        for (const e of s.scannedHashes ?? []) {
+            // hash is string-checked (not hex-validated), matching lastScannedHash
+            // and the Rust SDK so a state loads in both or neither.
+            if (!isCount(e?.height) || typeof e.hash !== 'string') {
+                throw new Error('wallet state contains a malformed scanned-hash entry');
+            }
+            w.scannedHashes.push({ height: e.height, hash: e.hash });
+        }
         return w;
     }
 }

package/dist/wallet.js

@@ -332,6 +332,26 @@ export class PivxWallet {
                 }
                 return block;
             };
+            // Stale-tip reorg detection: when lastProcessedBlock === tip the batch
+            // loop below never runs, so its per-batch root check never fires. A
+            // same-height reorg (block N replaced while the tip stays N) changes the
+            // shielded set's root but not the height. The tree can't be cheaply
+            // rewound, so re-verify the tip's finalsaplingroot against our local
+            // commitment root — the same localRoot-vs-nodeRoot check the batch loop
+            // does — and diverge on mismatch (caller recovers via reloadFromCheckpoint).
+            // Skip when nothing has been scanned past the checkpoint (a fresh wallet
+            // still on its bundled checkpoint has no tree of its own to check).
+            if (this.lastProcessedBlock === tip) {
+                const [checkpoint] = this.shield.get_closest_checkpoint(this.lastProcessedBlock, this.isTestnet);
+                if (this.lastProcessedBlock > checkpoint) {
+                    const nodeRoot = (await fetchBlock(tip)).finalsaplingroot;
+                    if (!nodeRoot)
+                        throw new Error(`node omitted finalsaplingroot at height ${tip}`);
+                    const localRoot = reverseHex(this.shield.get_sapling_root(this.commitmentTree));
+                    if (localRoot !== nodeRoot)
+                        throw new ScanDivergedError(tip, localRoot, nodeRoot);
+                }
+            }
             while (this.lastProcessedBlock < tip) {
                 throwIfAborted(); // batch boundary: nothing applied yet, state consistent
                 const from = this.lastProcessedBlock + 1;
@@ -511,31 +531,35 @@ export class PivxWallet {
                 }
             }
         }
-        // Spendable notes, minus pending spends and dust. Dust notes (worth no
-        // more than their own input fee) can never help cover amount+fee and only
-        // let an attacker inflate the fee, so they are excluded from spending.
-        const pending = new Set([...this.pendingSpends.values()].flat());
-        const spendable = this.notes.filter((n) => !pending.has(n.nullifier) && n.note.value > DUST_NOTE_SATS);
-        // Refuse a send the inputs can't cover including the fee, unless the
-        // caller opts into sweep. Both branches mirror the Rust selection so the
-        // WASM can't silently pay the fee out of the recipient's amount — the
-        // WASM shares the same fee model but has no such guard.
-        const sufficient = useShield
-            ? estimateShieldSelection(spendable, opts.amount, this.isShieldAddress(opts.to)).sufficient
-            : estimateTransparentSelection(opts.inputs, opts.amount, this.isShieldAddress(opts.to)).sufficient;
-        if (!sufficient && !opts.sweep) {
-            throw new Error('insufficient input value to cover amount + fee; lower the amount, ' +
-                'add inputs, or pass sweep:true to deduct the fee from the recipient');
-        }
-        // Prover is only needed to build; check it after the cheap validations
-        // so callers get input errors without loading ~50MB of parameters.
-        if (!(await this.shield.prover_is_loaded())) {
-            throw new Error('sapling prover not loaded: call loadProver() first');
-        }
+        // Acquire the single-writer guard BEFORE snapshotting spendable notes or
+        // awaiting anything. Otherwise two concurrent createTransaction calls could
+        // each snapshot the same notes before either set `busy`, then serialize on
+        // the guard and both build with the same inputs — a double-spend.
         if (this.busy)
             throw new Error('wallet is busy: another sync or spend is in progress');
         this.busy = true;
         try {
+            // Spendable notes, minus pending spends and dust. Dust notes (worth no
+            // more than their own input fee) can never help cover amount+fee and only
+            // let an attacker inflate the fee, so they are excluded from spending.
+            const pending = new Set([...this.pendingSpends.values()].flat());
+            const spendable = this.notes.filter((n) => !pending.has(n.nullifier) && n.note.value > DUST_NOTE_SATS);
+            // Refuse a send the inputs can't cover including the fee, unless the
+            // caller opts into sweep. Both branches mirror the Rust selection so the
+            // WASM can't silently pay the fee out of the recipient's amount — the
+            // WASM shares the same fee model but has no such guard.
+            const sufficient = useShield
+                ? estimateShieldSelection(spendable, opts.amount, this.isShieldAddress(opts.to)).sufficient
+                : estimateTransparentSelection(opts.inputs, opts.amount, this.isShieldAddress(opts.to)).sufficient;
+            if (!sufficient && !opts.sweep) {
+                throw new Error('insufficient input value to cover amount + fee; lower the amount, ' +
+                    'add inputs, or pass sweep:true to deduct the fee from the recipient');
+            }
+            // Prover is only needed to build; check it after the cheap validations
+            // so callers get input errors without loading ~50MB of parameters.
+            if (!(await this.shield.prover_is_loaded())) {
+                throw new Error('sapling prover not loaded: call loadProver() first');
+            }
             const changeAddress = useShield ? this.getNewAddress() : opts.transparentChangeAddress;
             const result = (await this.shield.create_transaction({
                 notes: useShield ? spendable : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pivx-wallet",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Standalone PIVX wallet SDK: local key management, shielded (SHIELD/Sapling) scanning, balances, and transaction building. The node is only a chain-data source.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "@noble/hashes": "^2.2.0",
     "@scure/base": "^2.2.0",
     "@scure/bip32": "^2.2.0",
-    "pivx-rpc": "^0.4.0",
+    "pivx-rpc": "^0.5.0",
     "pivx-shield-rust": "^1.4.0"
   },
   "optionalDependencies": {