pivx-wallet 0.3.3 → 0.3.5

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)).
@@ -274,6 +326,13 @@ export class TransparentWallet {
      * (broadcast definitively rejected) resolves them.
      */
     buildSend(to, amount, feePerByte = 100) {
+        // A sync running in the event-loop gap (suspended on an RPC await) may be
+        // mid-reorg reset; selecting/reserving a UTXO now risks spending an output
+        // resetScan is about to drop. Refuse until the sync releases the guard.
+        // (markSpent/release stay unguarded: removal-only finalization must always
+        // complete, or a reservation leaks.)
+        if (this.busy)
+            throw new Error('wallet is busy: a sync is in progress');
         if (!Number.isSafeInteger(amount) || amount <= 0)
             throw new Error('amount must be a positive integer (satoshis)');
         if (!Number.isInteger(feePerByte) || feePerByte <= 0)
@@ -364,6 +423,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 +485,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 +528,22 @@ 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 });
+        }
+        // Honest save() output is ascending, unique, ≤ REORG_WINDOW entries, all
+        // heights ≤ lastScanned. The reorg walk-back trusts array order and entry
+        // heights, so reject anything else rather than let a hostile or corrupt
+        // state mislead it (this also keeps duplicates out of resetScan).
+        if (w.scannedHashes.length > REORG_WINDOW ||
+            w.scannedHashes.some((e, i) => e.height > w.lastScanned || (i > 0 && e.height <= w.scannedHashes[i - 1].height))) {
+            throw new Error('wallet state contains an invalid scanned-hash window');
+        }
         return w;
     }
 }

package/dist/wallet.d.ts

@@ -104,6 +104,15 @@ export declare class PivxWallet {
      * SECURITY.md.
      */
     sync(client: PivxClient, opts?: SyncOptions): Promise<void>;
+    /**
+     * The node's finalsaplingroot at height h, or null below the SAPLING_ACTIVATION
+     * threshold — below real V5_0 the node reports a zero root our non-zero empty
+     * tree can't match, so returning null signals "skip the check". At/above the
+     * threshold the node must report one; treating an omitted root as "no root"
+     * would let a node suppress the check or force an all-the-way rewind by simply
+     * withholding the field.
+     */
+    private nodeSaplingRoot;
     /**
      * Confirm the starting commitment tree against the node before scanning
      * forward. A fresh wallet begins at a bundled checkpoint; if that

package/dist/wallet.js

@@ -2,9 +2,12 @@ import { RpcError } from 'pivx-rpc';
 import { loadShield } from './shield-bindings.js';
 /** PIVX BIP44 coin types. */
 const COIN_TYPE = { mainnet: 119, testnet: 1 };
-/** Heights at/after which a block must carry a sapling root. Below these,
- * the node legitimately has none. */
-const SAPLING_ACTIVATION = { mainnet: 2_700_000, testnet: 43_200 };
+/** Threshold at/above which the sapling root check runs; below it we skip. These
+ * are the exact UPGRADE_V5_0 activation heights (inclusive) from PIVX consensus,
+ * so at/above them an honest node always reports a real, matchable
+ * finalsaplingroot, and below them (no shielded txs yet) there is nothing to
+ * verify. Mainnet V5_0 is 2_700_500; testnet is 201. */
+const SAPLING_ACTIVATION = { mainnet: 2_700_500, testnet: 201 };
 /** A note worth no more than its own input fee (sapling input 384 bytes ×
  * 1000 sats/byte) never helps cover amount+fee, so it is never spent. */
 const DUST_NOTE_SATS = 384_000;
@@ -332,6 +335,32 @@ 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).
+            // Runs even at an exact checkpoint height: a fresh wallet still on its
+            // bundled checkpoint matches the node's finalsaplingroot there (that is
+            // what a checkpoint is, and ensureValidCheckpoint already confirmed it),
+            // so it is a clean no-op — while a wallet that scanned up to a checkpoint
+            // height and was then same-height reorged finally gets the check it was
+            // missing. Route the fetch through nodeSaplingRoot so it is skipped below
+            // the SAPLING_ACTIVATION threshold: below real V5_0 the node reports a
+            // zero root our non-zero empty tree can't match, so an honest wallet would
+            // false-diverge — the same activation exception ensureValidCheckpoint
+            // relies on. nodeSaplingRoot's verbosity-1 getblock returns
+            // finalsaplingroot without the full tx list the batch fetchBlock needs.
+            if (this.lastProcessedBlock === tip) {
+                const nodeRoot = await this.nodeSaplingRoot(client, tip);
+                if (nodeRoot !== null) {
+                    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;
@@ -356,15 +385,25 @@ export class PivxWallet {
                         height: h,
                         txs: blocks[i].tx.map(({ hex, txid }) => ({ hex, txid })),
                     })));
-                    const nodeRoot = blocks[blocks.length - 1].finalsaplingroot;
-                    // A shielded chain always has a sapling root; a missing one means
-                    // the node is pre-activation or lying. Either way, refuse to
-                    // advance unverified.
-                    if (!nodeRoot)
-                        throw new Error(`node omitted finalsaplingroot at height ${to}`);
-                    const localRoot = reverseHex(this.shield.get_sapling_root(this.commitmentTree));
-                    if (localRoot !== nodeRoot)
-                        throw new ScanDivergedError(to, localRoot, nodeRoot);
+                    // Verify the locally-built tree against the node's finalsaplingroot,
+                    // except below the SAPLING_ACTIVATION threshold, where we skip: below
+                    // real V5_0 the node reports a zero root our non-zero empty tree can't
+                    // match, and no shielded txs exist below activation anyway, so there
+                    // is nothing to verify. Both networks can scan into the skip window: a
+                    // testnet wallet with a below-activation birth height resumes from the
+                    // height-0 empty-tree checkpoint, and a mainnet wallet resumes from
+                    // checkpoint 2_700_000 and scans the empty [2_700_001, 2_700_500) gap
+                    // below its real activation. Same exception nodeSaplingRoot encodes.
+                    if (to >= SAPLING_ACTIVATION[this.network]) {
+                        const nodeRoot = blocks[blocks.length - 1].finalsaplingroot;
+                        // A shielded chain always has a sapling root; a missing one past
+                        // activation means the node is lying. Refuse to advance unverified.
+                        if (!nodeRoot)
+                            throw new Error(`node omitted finalsaplingroot at height ${to}`);
+                        const localRoot = reverseHex(this.shield.get_sapling_root(this.commitmentTree));
+                        if (localRoot !== nodeRoot)
+                            throw new ScanDivergedError(to, localRoot, nodeRoot);
+                    }
                 }
                 catch (err) {
                     this.commitmentTree = snapshot.tree;
@@ -381,6 +420,23 @@ export class PivxWallet {
             this.busy = false;
         }
     }
+    /**
+     * The node's finalsaplingroot at height h, or null below the SAPLING_ACTIVATION
+     * threshold — below real V5_0 the node reports a zero root our non-zero empty
+     * tree can't match, so returning null signals "skip the check". At/above the
+     * threshold the node must report one; treating an omitted root as "no root"
+     * would let a node suppress the check or force an all-the-way rewind by simply
+     * withholding the field.
+     */
+    async nodeSaplingRoot(client, h) {
+        if (h < SAPLING_ACTIVATION[this.network])
+            return null;
+        const block = (await client.getBlock(await client.getBlockHash(h), 1));
+        if (!block.finalsaplingroot) {
+            throw new Error(`node omitted finalsaplingroot at height ${h} (past sapling activation)`);
+        }
+        return block.finalsaplingroot;
+    }
     /**
      * Confirm the starting commitment tree against the node before scanning
      * forward. A fresh wallet begins at a bundled checkpoint; if that
@@ -393,21 +449,8 @@ export class PivxWallet {
     async ensureValidCheckpoint(client) {
         if (this.startValidated)
             return;
-        const activation = SAPLING_ACTIVATION[this.network];
-        // Sapling root at height h. Above activation the node must report one;
-        // treating an omitted root as "no root" would let a node suppress this
-        // check or force an all-the-way rewind by simply withholding the field.
-        const rootAt = async (h) => {
-            if (h < activation)
-                return null;
-            const block = (await client.getBlock(await client.getBlockHash(h), 1));
-            if (!block.finalsaplingroot) {
-                throw new Error(`node omitted finalsaplingroot at height ${h} (past sapling activation)`);
-            }
-            return block.finalsaplingroot;
-        };
         const localRoot = () => reverseHex(this.shield.get_sapling_root(this.commitmentTree));
-        const node = await rootAt(this.lastProcessedBlock);
+        const node = await this.nodeSaplingRoot(client, this.lastProcessedBlock);
         if (node === null || localRoot() === node) {
             this.startValidated = true;
             return;
@@ -429,7 +472,7 @@ export class PivxWallet {
             if (cpHeight >= lastCp)
                 break; // no older checkpoint available
             lastCp = cpHeight;
-            const nodeRoot = await rootAt(cpHeight);
+            const nodeRoot = await this.nodeSaplingRoot(client, cpHeight);
             const cpRoot = reverseHex(this.shield.get_sapling_root(cpTree));
             if (nodeRoot === null || cpRoot === nodeRoot) {
                 this.commitmentTree = cpTree;
@@ -511,31 +554,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.3",
+  "version": "0.3.5",
   "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": {