pivx-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 The PIVX developers
+Wallet crypto core: Copyright (c) PIVX Labs (pivx-shield)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# pivx-wallet
+
+Standalone [PIVX](https://pivx.org) wallet SDK: the application owns the keys.
+ZIP32 derivation, shielded (SHIELD/Sapling) block scanning with note
+decryption, checkpointed sync verified against `finalsaplingroot`, and
+locally-proved shielded transactions — plus a transparent (BIP44 HD, UTXO)
+wallet. The node is only a chain-data source; point it at one you trust.
+Amounts are integer satoshis.
+
+## Install
+
+```
+npm install pivx-wallet pivx-rpc
+```
+
+Node >= 20.19. ESM only.
+
+## Usage
+
+```js
+import { PivxClient } from 'pivx-rpc';
+import { PivxWallet } from 'pivx-wallet';
+
+// exchange deposit detection: keys never on this host
+const wallet = await PivxWallet.create({ viewingKey, birthHeight: 4_800_000 });
+await wallet.sync(new PivxClient({ user, pass }));
+console.log(wallet.getBalance()); // sats
+
+// standalone send (with a spending key + prover loaded)
+const txid = await wallet.send(client, { to: 'ps1…', amount: 150_000_000, memo: 'hi' });
+```
+
+A wallet is built from a seed, spending key, or viewing key — watch-only is a
+capability level, upgradeable in place.
+
+Full docs, security model, and examples: https://github.com/Liquid369/pivx-js-sdk

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { PivxWallet, NoSpendAuthorityError, ScanDivergedError } from './wallet.js';
+export { deriveKey, p2pkhAddress, encodeAddress, decodeAddress, isValidAddress, hash160, type AddressKind, type DecodedAddress, type TransparentKey, } from './transparent.js';
+export { buildTransparentTx, scriptPubKeyForAddress, type TxInput, type TxOutput, } from './transparent-tx.js';
+export { TransparentWallet, type OwnedUtxo, type ScannedOutput, type ScannedInput, } from './transparent-wallet.js';
+export type { ProvingOptions } from './shield-bindings.js';
+export type { SpendableNote, WalletBlock, TransparentInput, CreateWalletOptions, CreateTransactionOptions, BuiltTransaction, SyncOptions, WalletState, } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PivxWallet, NoSpendAuthorityError, ScanDivergedError } from './wallet.js';
+export { deriveKey, p2pkhAddress, encodeAddress, decodeAddress, isValidAddress, hash160, } from './transparent.js';
+export { buildTransparentTx, scriptPubKeyForAddress, } from './transparent-tx.js';
+export { TransparentWallet, } from './transparent-wallet.js';

package/dist/shield-bindings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Loads the pivx-shield WASM module once per process.
+ *
+ * Two builds exist. The single-core build (`pivx-shield-rust`) runs anywhere
+ * but proves transactions on one thread, which is slow. The multicore build
+ * (`pivx-shield-rust-multicore`) proves in parallel across Web Workers and is
+ * much faster, but it needs a browser with SharedArrayBuffer available under
+ * cross-origin isolation. Multicore is opt-in through {@link ProvingOptions}.
+ *
+ * For server-side proving throughput, use the native Rust SDK rather than the
+ * WASM build — native proving does not have this constraint.
+ */
+import * as singleCore from 'pivx-shield-rust';
+export type Shield = typeof singleCore;
+export interface ProvingOptions {
+    /**
+     * Use the multicore WASM build and spin up a worker thread pool. Requires a
+     * browser with SharedArrayBuffer (cross-origin isolated). Ignored with a
+     * warning where that is unavailable, falling back to single-core.
+     */
+    multicore?: boolean;
+    /** Worker threads for the multicore pool. Defaults to the hardware core count. */
+    threads?: number;
+}
+/**
+ * Load and memoize the WASM module. The first call decides single- vs
+ * multicore for the process; later calls return the same instance.
+ */
+export declare function loadShield(opts?: ProvingOptions): Promise<Shield>;

package/dist/shield-bindings.js

@@ -0,0 +1,65 @@
+/**
+ * Loads the pivx-shield WASM module once per process.
+ *
+ * Two builds exist. The single-core build (`pivx-shield-rust`) runs anywhere
+ * but proves transactions on one thread, which is slow. The multicore build
+ * (`pivx-shield-rust-multicore`) proves in parallel across Web Workers and is
+ * much faster, but it needs a browser with SharedArrayBuffer available under
+ * cross-origin isolation. Multicore is opt-in through {@link ProvingOptions}.
+ *
+ * For server-side proving throughput, use the native Rust SDK rather than the
+ * WASM build — native proving does not have this constraint.
+ */
+import * as singleCore from 'pivx-shield-rust';
+let ready;
+async function initSingleCore() {
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const wasmUrl = import.meta.resolve('pivx-shield-rust/pivx_shield_rust_bg.wasm');
+        await singleCore.default({ module_or_path: await readFile(fileURLToPath(wasmUrl)) });
+    }
+    else {
+        await singleCore.default();
+    }
+    return singleCore;
+}
+function multicoreUsable() {
+    // The rayon thread pool is built on Web Workers + SharedArrayBuffer, so it
+    // only runs in a browser that is cross-origin isolated.
+    return (typeof SharedArrayBuffer !== 'undefined' &&
+        typeof Worker !== 'undefined' &&
+        (typeof process === 'undefined' || !process.versions?.node));
+}
+async function initMulticore(threads) {
+    // Loaded dynamically so single-core users need not install the package.
+    const mc = await import('pivx-shield-rust-multicore');
+    await mc.default();
+    const n = threads ?? (globalThis.navigator?.hardwareConcurrency ?? 4);
+    await mc.initThreadPool(n);
+    return mc;
+}
+/**
+ * Load and memoize the WASM module. The first call decides single- vs
+ * multicore for the process; later calls return the same instance.
+ */
+export function loadShield(opts = {}) {
+    ready ??= (async () => {
+        if (opts.multicore) {
+            if (multicoreUsable()) {
+                try {
+                    return await initMulticore(opts.threads);
+                }
+                catch (err) {
+                    console.warn(`multicore proving unavailable (${err.message}); using single-core`);
+                }
+            }
+            else {
+                console.warn('multicore proving needs a cross-origin-isolated browser; using single-core. ' +
+                    'For server-side proving use the native Rust SDK.');
+            }
+        }
+        return initSingleCore();
+    })();
+    return ready;
+}

package/dist/transparent-tx.d.ts

@@ -0,0 +1,27 @@
+export interface TxInput {
+    txid: string;
+    vout: number;
+    amount: number;
+    /** scriptPubKey of the output being spent (bytes, as from listunspent hex). */
+    scriptPubKey: Uint8Array;
+    /** 32-byte private key controlling the input. */
+    privateKey: Uint8Array;
+}
+export interface TxOutput {
+    address: string;
+    amount: number;
+}
+/**
+ * scriptPubKey for a destination address (P2PKH, P2SH, or exchange).
+ *
+ * An exchange address is NOT a plain P2PKH: PIVX prefixes the P2PKH script
+ * with OP_EXCHANGEADDR (0xe0) — see GetScriptForDestination in
+ * src/script/standard.cpp. Emitting a plain P2PKH would send to the wrong script.
+ */
+export declare function scriptPubKeyForAddress(address: string): Uint8Array;
+/**
+ * Build and sign a transparent transaction; returns raw tx hex for
+ * `sendrawtransaction`. Caller selects inputs and includes change as an
+ * explicit output; no coin selection or fee computation is done here.
+ */
+export declare function buildTransparentTx(inputs: TxInput[], outputs: TxOutput[], locktime?: number): string;

package/dist/transparent-tx.js

@@ -0,0 +1,132 @@
+/**
+ * Build and sign transparent (LEGACY, v1) PIVX transactions.
+ *
+ * PIVX serializes int16 nVersion, int16 nType, vin, vout, nLockTime, then
+ * (sapling versions only) sapData — see src/primitives/transaction.h. For a
+ * legacy transparent tx (nVersion=1, nType=0) the leading four bytes are
+ * `01 00 00 00` with no sapData, i.e. a standard Bitcoin v1 transaction.
+ * Signing is legacy P2PKH SIGHASH_ALL.
+ */
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { decodeAddress } from './transparent.js';
+const SIGHASH_ALL = 1;
+const hexToBytes = (h) => Uint8Array.from(h.match(/../g).map((b) => parseInt(b, 16)));
+const bytesToHex = (b) => [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+const doubleSha256 = (d) => sha256(sha256(d));
+class Writer {
+    parts = [];
+    u16le(n) { this.parts.push(n & 0xff, (n >> 8) & 0xff); }
+    u32le(n) { for (let i = 0; i < 4; i++)
+        this.parts.push((n >>> (8 * i)) & 0xff); }
+    u64le(n) {
+        let v = BigInt(n);
+        for (let i = 0; i < 8; i++) {
+            this.parts.push(Number(v & 0xffn));
+            v >>= 8n;
+        }
+    }
+    varint(n) {
+        if (n < 0xfd)
+            this.parts.push(n);
+        else if (n <= 0xffff) {
+            this.parts.push(0xfd);
+            this.u16le(n);
+        }
+        else {
+            this.parts.push(0xfe);
+            this.u32le(n);
+        }
+    }
+    bytes(b) { for (const x of b)
+        this.parts.push(x); }
+    script(s) { this.varint(s.length); this.bytes(s); }
+    done() { return Uint8Array.from(this.parts); }
+}
+/**
+ * scriptPubKey for a destination address (P2PKH, P2SH, or exchange).
+ *
+ * An exchange address is NOT a plain P2PKH: PIVX prefixes the P2PKH script
+ * with OP_EXCHANGEADDR (0xe0) — see GetScriptForDestination in
+ * src/script/standard.cpp. Emitting a plain P2PKH would send to the wrong script.
+ */
+export function scriptPubKeyForAddress(address) {
+    const d = decodeAddress(address);
+    if (d.kind === 'p2pkh') {
+        return Uint8Array.from([0x76, 0xa9, 0x14, ...d.hash, 0x88, 0xac]);
+    }
+    if (d.kind === 'exchange') {
+        return Uint8Array.from([0xe0, 0x76, 0xa9, 0x14, ...d.hash, 0x88, 0xac]);
+    }
+    if (d.kind === 'p2sh') {
+        return Uint8Array.from([0xa9, 0x14, ...d.hash, 0x87]);
+    }
+    throw new Error('sending to a cold-staking address is not supported');
+}
+function serialize(inputs, scriptSigs, outputs, locktime) {
+    const w = new Writer();
+    w.u16le(1); // nVersion = 1 (LEGACY)
+    w.u16le(0); // nType = 0 (NORMAL)
+    w.varint(inputs.length);
+    inputs.forEach((input, i) => {
+        const txid = hexToBytes(input.txid);
+        if (txid.length !== 32)
+            throw new Error('txid must be 32 bytes');
+        w.bytes(txid.reverse()); // little-endian prevout hash
+        w.u32le(input.vout);
+        w.script(scriptSigs[i]);
+        w.u32le(0xffffffff); // nSequence
+    });
+    w.varint(outputs.length);
+    for (const [script, value] of outputs) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error('output amount must be a non-negative integer (satoshis)');
+        w.u64le(value);
+        w.script(script);
+    }
+    w.u32le(locktime);
+    return w.done();
+}
+/**
+ * Build and sign a transparent transaction; returns raw tx hex for
+ * `sendrawtransaction`. Caller selects inputs and includes change as an
+ * explicit output; no coin selection or fee computation is done here.
+ */
+export function buildTransparentTx(inputs, outputs, locktime = 0) {
+    if (inputs.length === 0)
+        throw new Error('transaction has no inputs');
+    for (const input of inputs) {
+        if (input.privateKey.length !== 32)
+            throw new Error('private key must be 32 bytes');
+        if (!Number.isSafeInteger(input.amount) || input.amount < 0) {
+            throw new Error('input amount must be a non-negative integer (satoshis)');
+        }
+    }
+    const outScripts = outputs.map((o) => [scriptPubKeyForAddress(o.address), o.amount]);
+    const empty = inputs.map(() => new Uint8Array(0));
+    const scriptSigs = inputs.map(() => new Uint8Array(0));
+    inputs.forEach((input, i) => {
+        // Legacy SIGHASH_ALL preimage: this input's scriptSig = its prevout
+        // scriptPubKey, all others empty; append the 4-byte sighash type.
+        const preimageSigs = empty.slice();
+        preimageSigs[i] = input.scriptPubKey;
+        const preimage = serialize(inputs, preimageSigs, outScripts, locktime);
+        const w = new Writer();
+        w.bytes(preimage);
+        w.u32le(SIGHASH_ALL);
+        const digest = doubleSha256(w.done());
+        // prehash: false — sign the double-SHA256 sighash directly. Without it,
+        // @noble applies its own SHA-256 to the input, producing a signature over
+        // the wrong (triple-hashed) value that the node rejects.
+        const der = secp256k1.sign(digest, input.privateKey, { lowS: true, format: 'der', prehash: false });
+        const pubkey = secp256k1.getPublicKey(input.privateKey, true); // compressed
+        const ss = new Writer();
+        ss.varint(der.length + 1);
+        ss.bytes(der);
+        ss.bytes(Uint8Array.from([SIGHASH_ALL]));
+        ss.varint(pubkey.length);
+        ss.bytes(pubkey);
+        scriptSigs[i] = ss.done();
+    });
+    return bytesToHex(serialize(inputs, scriptSigs, outScripts, locktime));
+}

package/dist/transparent-wallet.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Transparent wallet: HD address management, UTXO tracking (from a block scan
+ * or caller-supplied), coin selection, and sending. Complements the shielded
+ * PivxWallet; both derive from the seed.
+ *
+ * PIVX has no address index, so UTXOs are discovered either by scanning blocks
+ * ({@link scan}) or supplied by the caller ({@link addUtxo}).
+ */
+import type { PivxClient } from 'pivx-rpc';
+import { type Network } from './transparent.js';
+import { scriptPubKeyForAddress } from './transparent-tx.js';
+/** A tracked unspent transparent output we can spend. */
+export interface OwnedUtxo {
+    txid: string;
+    vout: number;
+    amount: number;
+    scriptPubKey: Uint8Array;
+    keyHash: string;
+    coinbase: boolean;
+    height: number;
+}
+export interface ScannedOutput {
+    txid: string;
+    vout: number;
+    amount: number;
+    scriptPubKey: Uint8Array;
+}
+export interface ScannedInput {
+    txid: string;
+    vout: number;
+}
+export declare class TransparentWallet {
+    private readonly network;
+    private keys;
+    private external;
+    private change;
+    private nextExternal;
+    private nextChange;
+    private utxos;
+    private lastScanned;
+    private constructor();
+    /**
+     * Derive `gap` external and `gap` change addresses from `seed` under
+     * `account`. Only outputs to these addresses are recognized.
+     */
+    static create(seed: Uint8Array, network: Network, account?: number, gap?: number): TransparentWallet;
+    /** Next unused external receive address. */
+    newAddress(): string;
+    private nextChangeHash;
+    /**
+     * Add a caller-supplied UTXO if it pays one of our addresses. Returns true if
+     * ours. Assumed a normal (non-coinbase) spendable output; use {@link scanBlock}
+     * for chain data where coinbase maturity is tracked.
+     */
+    addUtxo(txid: string, vout: number, amount: number, scriptPubKey: Uint8Array): boolean;
+    private insertUtxo;
+    /** Apply a scanned block's transparent outputs (added if ours) and spent inputs (removed). */
+    scan(outputs: ScannedOutput[], spent: ScannedInput[]): void;
+    /**
+     * Scan one decoded block (`getblock <hash> 2`): credit every output that
+     * pays us and remove every tracked UTXO the block spends. Coinbase vins (no
+     * prevout `txid`) are skipped. Records the block's height as last scanned.
+     */
+    scanBlock(block: any): void;
+    /** Height of the last block passed to {@link scanBlock} (0 if none). */
+    lastScannedBlock(): number;
+    /**
+     * Sync from the node into the wallet, from `max(fromHeight, lastScanned+1)`
+     * up to the current tip, fetching each block with getBlockHash +
+     * getBlock(hash, 2) and feeding it to {@link scanBlock}. Blocks are fetched
+     * with bounded concurrency but scanned in ascending order.
+     *
+     * 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 }?: {
+        fromHeight?: number;
+        batchSize?: number;
+        onProgress?: (height: number, tip: number) => void;
+    }): Promise<void>;
+    /** Total tracked transparent balance in satoshis. */
+    balance(): number;
+    getUtxos(): readonly OwnedUtxo[];
+    private static estSize;
+    /**
+     * Build and sign a transparent send of `amount` sats to `to`, selecting
+     * UTXOs largest-first with change to a fresh change address. `feePerByte`
+     * defaults to 100 sats/byte. Returns the raw tx hex and the spent inputs.
+     */
+    buildSend(to: string, amount: number, feePerByte?: number): {
+        hex: string;
+        spent: {
+            txid: string;
+            vout: number;
+        }[];
+    };
+    /** Mark inputs spent after a successful broadcast. */
+    markSpent(spent: {
+        txid: string;
+        vout: number;
+    }[]): void;
+}
+export { scriptPubKeyForAddress };

package/dist/transparent-wallet.js

@@ -0,0 +1,233 @@
+import { decodeAddress, deriveKey, encodeAddress, hash160 } from './transparent.js';
+import { buildTransparentTx, scriptPubKeyForAddress } from './transparent-tx.js';
+const hex = (b) => [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+/**
+ * PIVX dust threshold (sats) for an output whose scriptPubKey is `scriptLen`
+ * bytes. Matches `GetDustThreshold` in src/policy/policy.cpp: the output plus
+ * the 148-byte input to spend it, priced at dustRelayFee = 30000 sat/kB. For
+ * our scripts (< 253 bytes) the length prefix is one byte, so the serialized
+ * output is `8 + 1 + scriptLen`; a 25-byte P2PKH gives 5460.
+ */
+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);
+/** hash160 of a standard P2PKH scriptPubKey (76a914<20>88ac), if it is one. */
+function p2pkhHash(script) {
+    if (script.length === 25 &&
+        script[0] === 0x76 && script[1] === 0xa9 && script[2] === 0x14 &&
+        script[23] === 0x88 && script[24] === 0xac) {
+        return hex(script.slice(3, 23));
+    }
+    return undefined;
+}
+export class TransparentWallet {
+    network;
+    keys = new Map(); // hex hash160 → privkey
+    external = [];
+    change = [];
+    nextExternal = 0;
+    nextChange = 0;
+    utxos = new Map(); // "txid:vout" → utxo
+    lastScanned = 0; // height of the last block passed to scanBlock
+    constructor(network) {
+        this.network = network;
+    }
+    /**
+     * Derive `gap` external and `gap` change addresses from `seed` under
+     * `account`. Only outputs to these addresses are recognized.
+     */
+    static create(seed, network, account = 0, gap = 100) {
+        const w = new TransparentWallet(network);
+        for (let i = 0; i < gap; i++) {
+            const ext = deriveKey(seed, network, account, 0, i);
+            const eh = hex(hash160(ext.publicKey));
+            w.external.push({ hash: eh, address: ext.address });
+            w.keys.set(eh, ext.privateKey);
+            const ch = deriveKey(seed, network, account, 1, i);
+            const chh = hex(hash160(ch.publicKey));
+            w.change.push(chh);
+            w.keys.set(chh, ch.privateKey);
+        }
+        return w;
+    }
+    /** Next unused external receive address. */
+    newAddress() {
+        const e = this.external[this.nextExternal];
+        if (!e)
+            throw new Error('address gap limit reached; increase gap');
+        this.nextExternal++;
+        return e.address;
+    }
+    nextChangeHash() {
+        const h = this.change[this.nextChange];
+        if (!h)
+            throw new Error('change gap limit reached; increase gap');
+        this.nextChange++;
+        return h;
+    }
+    /**
+     * Add a caller-supplied UTXO if it pays one of our addresses. Returns true if
+     * ours. Assumed a normal (non-coinbase) spendable output; use {@link scanBlock}
+     * for chain data where coinbase maturity is tracked.
+     */
+    addUtxo(txid, vout, amount, scriptPubKey) {
+        return this.insertUtxo(txid, vout, amount, scriptPubKey, false, 0);
+    }
+    insertUtxo(txid, vout, amount, scriptPubKey, coinbase, height) {
+        const h = p2pkhHash(scriptPubKey);
+        if (h && this.keys.has(h)) {
+            this.utxos.set(`${txid}:${vout}`, { txid, vout, amount, scriptPubKey, keyHash: h, coinbase, height });
+            return true;
+        }
+        return false;
+    }
+    /** Apply a scanned block's transparent outputs (added if ours) and spent inputs (removed). */
+    scan(outputs, spent) {
+        for (const o of outputs)
+            this.addUtxo(o.txid, o.vout, o.amount, o.scriptPubKey);
+        for (const s of spent)
+            this.utxos.delete(`${s.txid}:${s.vout}`);
+    }
+    /**
+     * Scan one decoded block (`getblock <hash> 2`): credit every output that
+     * pays us and remove every tracked UTXO the block spends. Coinbase vins (no
+     * prevout `txid`) are skipped. Records the block's height as last scanned.
+     */
+    scanBlock(block) {
+        if (typeof block.height === 'number')
+            this.lastScanned = block.height;
+        const height = this.lastScanned;
+        for (const tx of block.tx ?? []) {
+            if (typeof tx.txid !== 'string')
+                continue;
+            // Coinbase: first vin carries `coinbase` and no prevout. Coinstake (PoS):
+            // a spending vin plus an empty vout[0] (zero value). Both are maturity-
+            // gated for spending (src/txmempool.cpp).
+            const firstVin = tx.vin?.[0];
+            const isCoinbase = firstVin?.coinbase !== undefined;
+            const isCoinstake = firstVin?.txid !== undefined && tx.vout?.[0]?.value === 0;
+            const coinbase = isCoinbase || isCoinstake;
+            for (const o of tx.vout ?? []) {
+                const hexStr = o?.scriptPubKey?.hex;
+                // Skip malformed vouts rather than poisoning balance with NaN or
+                // throwing mid-sync (matches the Rust scanner).
+                if (typeof o?.n !== 'number' || typeof o?.value !== 'number' || typeof hexStr !== 'string')
+                    continue;
+                const script = Uint8Array.from((hexStr.match(/../g) ?? []).map((b) => parseInt(b, 16)));
+                this.insertUtxo(tx.txid, o.n, Math.round(o.value * 1e8), script, coinbase, height);
+            }
+            for (const i of tx.vin ?? []) {
+                if (i.txid !== undefined)
+                    this.utxos.delete(`${i.txid}:${i.vout}`);
+            }
+        }
+    }
+    /** Height of the last block passed to {@link scanBlock} (0 if none). */
+    lastScannedBlock() {
+        return this.lastScanned;
+    }
+    /**
+     * Sync from the node into the wallet, from `max(fromHeight, lastScanned+1)`
+     * up to the current tip, fetching each block with getBlockHash +
+     * getBlock(hash, 2) and feeding it to {@link scanBlock}. Blocks are fetched
+     * with bounded concurrency but scanned in ascending order.
+     *
+     * 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 } = {}) {
+        const concurrency = 8;
+        const tip = await client.getBlockCount();
+        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)).
+        const batch = Math.max(1, Math.floor(batchSize) || 1);
+        let from = Math.max(fromHeight, this.lastScanned + 1);
+        while (from <= tip) {
+            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) {
+                const blocks = await Promise.all(heights.slice(i, i + concurrency).map(fetchBlock));
+                for (const block of blocks)
+                    this.scanBlock(block);
+            }
+            onProgress?.(to, tip);
+            from = to + 1;
+        }
+    }
+    /** Total tracked transparent balance in satoshis. */
+    balance() {
+        return [...this.utxos.values()].reduce((s, u) => s + u.amount, 0);
+    }
+    getUtxos() {
+        return [...this.utxos.values()];
+    }
+    static estSize(nIn, nOut) {
+        return nIn * 148 + nOut * 34 + 10;
+    }
+    /**
+     * Build and sign a transparent send of `amount` sats to `to`, selecting
+     * UTXOs largest-first with change to a fresh change address. `feePerByte`
+     * defaults to 100 sats/byte. Returns the raw tx hex and the spent inputs.
+     */
+    buildSend(to, amount, feePerByte = 100) {
+        if (!Number.isSafeInteger(amount) || amount <= 0)
+            throw new Error('amount must be a positive integer (satoshis)');
+        if (!Number.isInteger(feePerByte) || feePerByte <= 0)
+            throw new Error('feePerByte must be a positive integer (satoshis/byte)');
+        const dest = decodeAddress(to); // throws on an invalid address
+        // A mainnet wallet must not send to a testnet-encoded address (or vice
+        // versa): the hash would be spent to this network's equivalent — a silent
+        // loss. Reject the mismatch up front.
+        if (dest.network !== this.network)
+            throw new Error('destination address is for a different network');
+        if (dest.kind === 'staking')
+            throw new Error('sending to a cold-staking address is not supported');
+        // Reject a recipient amount the node would drop as dust.
+        const toScript = scriptPubKeyForAddress(to);
+        if (amount < dustThreshold(toScript.length))
+            throw new Error('amount is below the dust threshold');
+        const feerate = feePerByte;
+        // Exclude immature coinbase/coinstake outputs: the node rejects a spend of
+        // one before nCoinbaseMaturity confirmations (depth vs. last scanned block).
+        const maturity = coinbaseMaturity(this.network);
+        const avail = [...this.utxos.values()]
+            .filter((u) => !(u.coinbase && this.lastScanned - u.height + 1 < maturity))
+            .sort((a, b) => b.amount - a.amount);
+        const selected = [];
+        let total = 0;
+        for (const u of avail) {
+            selected.push(u);
+            total += u.amount;
+            if (total >= amount + feerate * TransparentWallet.estSize(selected.length, 2))
+                break;
+        }
+        const fee = feerate * TransparentWallet.estSize(selected.length, 2);
+        if (total < amount + fee)
+            throw new Error('insufficient transparent balance to cover amount + fee');
+        const changeVal = total - amount - fee;
+        const outputs = [{ address: to, amount }];
+        // Emit change only above both floors: the node's fixed dust threshold (else
+        // the tx is rejected as dust) and the fee to later spend the change input.
+        // Change is always P2PKH (25-byte script).
+        if (changeVal > Math.max(feerate * 148, dustThreshold(25))) {
+            const chAddr = encodeAddress(Uint8Array.from(this.nextChangeHash().match(/../g).map((b) => parseInt(b, 16))), this.network, 'p2pkh');
+            outputs.push({ address: chAddr, amount: changeVal });
+        }
+        const inputs = selected.map((u) => ({
+            txid: u.txid,
+            vout: u.vout,
+            amount: u.amount,
+            scriptPubKey: u.scriptPubKey,
+            privateKey: this.keys.get(u.keyHash),
+        }));
+        const spent = selected.map((u) => ({ txid: u.txid, vout: u.vout }));
+        return { hex: buildTransparentTx(inputs, outputs, 0), spent };
+    }
+    /** Mark inputs spent after a successful broadcast. */
+    markSpent(spent) {
+        for (const s of spent)
+            this.utxos.delete(`${s.txid}:${s.vout}`);
+    }
+}
+export { scriptPubKeyForAddress };