pivx-wallet 0.2.0 → 0.3.0

package/dist/transparent-wallet.d.ts

@@ -105,10 +105,18 @@ export declare class TransparentWallet {
      * Like the shield wallet's sync this is a chain-data pull, not chain
      * authentication: point it at a node you trust. See SECURITY.md.
      */
-    sync(client: PivxClient, { fromHeight, batchSize, onProgress }?: {
+    sync(client: PivxClient, { fromHeight, batchSize, onProgress, signal }?: {
         fromHeight?: number;
         batchSize?: number;
         onProgress?: (height: number, tip: number) => void;
+        /**
+         * Abort the sync. Checked at every batch and concurrency-chunk
+         * boundary, before the next round of RPCs is issued; when set, sync
+         * throws `signal.reason` (an `AbortError` DOMException by default).
+         * Fully scanned blocks are kept and the busy guard is released, so a
+         * follow-up sync resumes where this one stopped.
+         */
+        signal?: AbortSignal;
     }): Promise<void>;
     /**
      * Total spendable transparent balance in satoshis. Outputs reserved by

package/dist/transparent-wallet.js

@@ -207,11 +207,15 @@ export class TransparentWallet {
      * Like the shield wallet's sync this is a chain-data pull, not chain
      * authentication: point it at a node you trust. See SECURITY.md.
      */
-    async sync(client, { fromHeight = 0, batchSize = 100, onProgress } = {}) {
+    async sync(client, { fromHeight = 0, batchSize = 100, onProgress, signal } = {}) {
         if (this.busy)
             throw new Error('wallet is busy: another sync is in progress');
         this.busy = true;
         try {
+            const throwIfAborted = () => {
+                if (signal?.aborted)
+                    throw signal.reason ?? new DOMException('sync aborted', 'AbortError');
+            };
             const concurrency = 8;
             const tip = await client.getBlockCount();
             const fetchBlock = async (h) => client.getBlock(await client.getBlockHash(h), 2);
@@ -220,9 +224,11 @@ export class TransparentWallet {
             const batch = Math.max(1, Math.floor(batchSize) || 1);
             let from = Math.max(fromHeight, this.lastScanned + 1);
             while (from <= tip) {
+                throwIfAborted(); // batch boundary: before issuing the next round of RPCs
                 const to = Math.min(from + batch - 1, tip);
                 const heights = Array.from({ length: to - from + 1 }, (_, i) => from + i);
                 for (let i = 0; i < heights.length; i += concurrency) {
+                    throwIfAborted(); // chunk boundary: previous chunk fully scanned
                     const blocks = await Promise.all(heights.slice(i, i + concurrency).map(fetchBlock));
                     for (const b of blocks) {
                         // getblock verbosity 2 always carries these; a block without them

package/dist/types.d.ts

@@ -90,6 +90,14 @@ export interface SyncOptions {
      */
     rpcConcurrency?: number;
     onProgress?: (height: number, tip: number) => void;
+    /**
+     * Abort the sync. Checked at every batch and concurrency-chunk boundary,
+     * before the next round of RPCs is issued; when set, sync throws
+     * `signal.reason` (an `AbortError` DOMException by default). State stays
+     * consistent: only fully applied, root-verified batches are kept, and the
+     * busy guard is released so a follow-up sync can resume where it stopped.
+     */
+    signal?: AbortSignal;
 }
 /** Serialized wallet state (spending key deliberately excluded). */
 export interface WalletState {

package/dist/wallet.d.ts

@@ -60,6 +60,15 @@ export declare class PivxWallet {
         recipient: string;
         value: number;
     } | undefined;
+    /**
+     * Remove every nullifier-map entry that is no longer referenced by a
+     * currently tracked unspent note or by a pending spend, and return the
+     * number removed. Explicit and opt-in: the map is what powers
+     * {@link getNoteFromNullifier}, so callers using nullifier → note
+     * attribution should call this only after reconciling the spends they
+     * care about. Deterministic; the save/load format is unchanged.
+     */
+    pruneNullifiers(): number;
     /**
      * Scan blocks (strictly ascending heights, all above the last synced
      * block). Returns the raw hexes of transactions relevant to this wallet.

package/dist/wallet.js

@@ -202,6 +202,28 @@ export class PivxWallet {
     getNoteFromNullifier(nullifier) {
         return this.nullifierMap.get(nullifier);
     }
+    /**
+     * Remove every nullifier-map entry that is no longer referenced by a
+     * currently tracked unspent note or by a pending spend, and return the
+     * number removed. Explicit and opt-in: the map is what powers
+     * {@link getNoteFromNullifier}, so callers using nullifier → note
+     * attribution should call this only after reconciling the spends they
+     * care about. Deterministic; the save/load format is unchanged.
+     */
+    pruneNullifiers() {
+        const live = new Set(this.notes.map((n) => n.nullifier));
+        for (const nulls of this.pendingSpends.values())
+            for (const n of nulls)
+                live.add(n);
+        let removed = 0;
+        for (const nullifier of this.nullifierMap.keys()) {
+            if (!live.has(nullifier)) {
+                this.nullifierMap.delete(nullifier);
+                removed++;
+            }
+        }
+        return removed;
+    }
     // ── Scanning ──────────────────────────────────────────────────────────────
     /**
      * Scan blocks (strictly ascending heights, all above the last synced
@@ -286,6 +308,11 @@ export class PivxWallet {
             throw new Error('wallet is busy: another sync or spend is in progress');
         this.busy = true;
         try {
+            const throwIfAborted = () => {
+                if (opts.signal?.aborted) {
+                    throw opts.signal.reason ?? new DOMException('sync aborted', 'AbortError');
+                }
+            };
             // NaN/0/fractional → sane integer; 0 would loop forever.
             const batchSize = Math.max(1, Math.floor(opts.batchSize ?? 100) || 1);
             // getblock verbosity 2 is heavy. A default node has 4 RPC threads and a
@@ -306,11 +333,13 @@ export class PivxWallet {
                 return block;
             };
             while (this.lastProcessedBlock < tip) {
+                throwIfAborted(); // batch boundary: nothing applied yet, state consistent
                 const from = this.lastProcessedBlock + 1;
                 const to = Math.min(from + batchSize - 1, tip);
                 const heights = Array.from({ length: to - from + 1 }, (_, i) => from + i);
                 const blocks = [];
                 for (let i = 0; i < heights.length; i += concurrency) {
+                    throwIfAborted(); // chunk boundary: before issuing the next RPCs
                     blocks.push(...(await Promise.all(heights.slice(i, i + concurrency).map(fetchBlock))));
                 }
                 // Snapshot so a failed root check can't leave partial state behind.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pivx-wallet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.1.0",
+    "pivx-rpc": "^0.2.0",
     "pivx-shield-rust": "^1.4.0"
   },
   "optionalDependencies": {