pivx-wallet 0.1.0

package/dist/transparent.d.ts

@@ -0,0 +1,31 @@
+export type Network = 'mainnet' | 'testnet';
+export type AddressKind = 'p2pkh' | 'p2sh' | 'staking' | 'exchange';
+/** hash160 = RIPEMD160(SHA256(data)). */
+export declare function hash160(data: Uint8Array): Uint8Array;
+/** Encode a 20-byte hash as a PIVX base58check address of the given kind. */
+export declare function encodeAddress(hash: Uint8Array, network: Network, kind: AddressKind): string;
+/** P2PKH address for a compressed public key. */
+export declare function p2pkhAddress(pubkey: Uint8Array, network: Network): string;
+export interface DecodedAddress {
+    hash: Uint8Array;
+    kind: AddressKind;
+    network: Network;
+}
+/** Decode and validate a PIVX transparent address, identifying kind + network. */
+export declare function decodeAddress(address: string): DecodedAddress;
+/** True if `address` is a well-formed PIVX transparent address. */
+export declare function isValidAddress(address: string): boolean;
+/** A derived transparent key. */
+export interface TransparentKey {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+    network: Network;
+    address: string;
+    /** WIF (compressed) encoding, for import into other tools. */
+    wif: string;
+}
+/**
+ * Derive the BIP44 transparent key at m/44'/coin'/account'/change/index.
+ * `change` is 0 for external (receive) addresses, 1 for internal (change).
+ */
+export declare function deriveKey(seed: Uint8Array, network: Network, account: number, change: number, index: number): TransparentKey;

package/dist/transparent.js

@@ -0,0 +1,82 @@
+/**
+ * Transparent (non-shielded) HD wallet: BIP32/44 key derivation and PIVX
+ * address encoding/decoding for P2PKH, cold-staking, and exchange addresses.
+ *
+ * Keys derive under BIP44 m/44'/119'/account'/change/index (coin type 119
+ * mainnet, 1 testnet). Addresses are base58check with network-specific
+ * version prefixes (from chainparams).
+ */
+import { HDKey } from '@scure/bip32';
+import { base58check } from '@scure/base';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { ripemd160 } from '@noble/hashes/legacy.js';
+const b58c = base58check(sha256);
+/** base58 version prefix bytes per network + kind (from chainparams.cpp). */
+const PREFIX = {
+    mainnet: { p2pkh: [30], p2sh: [13], staking: [63], exchange: [0x01, 0xb9, 0xa2] },
+    testnet: { p2pkh: [139], p2sh: [19], staking: [73], exchange: [0x01, 0xb9, 0xb1] },
+};
+const COIN_TYPE = { mainnet: 119, testnet: 1 };
+const WIF_PREFIX = { mainnet: 212, testnet: 239 };
+/** hash160 = RIPEMD160(SHA256(data)). */
+export function hash160(data) {
+    return ripemd160(sha256(data));
+}
+/** Encode a 20-byte hash as a PIVX base58check address of the given kind. */
+export function encodeAddress(hash, network, kind) {
+    if (hash.length !== 20)
+        throw new Error('hash must be 20 bytes');
+    const prefix = PREFIX[network][kind];
+    return b58c.encode(Uint8Array.from([...prefix, ...hash]));
+}
+/** P2PKH address for a compressed public key. */
+export function p2pkhAddress(pubkey, network) {
+    return encodeAddress(hash160(pubkey), network, 'p2pkh');
+}
+/** Decode and validate a PIVX transparent address, identifying kind + network. */
+export function decodeAddress(address) {
+    let data;
+    try {
+        data = b58c.decode(address);
+    }
+    catch {
+        throw new Error(`invalid address: ${address}`);
+    }
+    for (const network of ['mainnet', 'testnet']) {
+        for (const kind of ['p2pkh', 'p2sh', 'staking', 'exchange']) {
+            const prefix = PREFIX[network][kind];
+            if (data.length === prefix.length + 20 && prefix.every((b, i) => data[i] === b)) {
+                return { hash: data.slice(prefix.length), kind, network };
+            }
+        }
+    }
+    throw new Error(`invalid address: ${address}`);
+}
+/** True if `address` is a well-formed PIVX transparent address. */
+export function isValidAddress(address) {
+    try {
+        decodeAddress(address);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Derive the BIP44 transparent key at m/44'/coin'/account'/change/index.
+ * `change` is 0 for external (receive) addresses, 1 for internal (change).
+ */
+export function deriveKey(seed, network, account, change, index) {
+    const master = HDKey.fromMasterSeed(seed);
+    const child = master.derive(`m/44'/${COIN_TYPE[network]}'/${account}'/${change}/${index}`);
+    if (!child.privateKey || !child.publicKey)
+        throw new Error('key derivation failed');
+    const wif = b58c.encode(Uint8Array.from([WIF_PREFIX[network], ...child.privateKey, 0x01]));
+    return {
+        privateKey: child.privateKey,
+        publicKey: child.publicKey, // compressed
+        network,
+        address: p2pkhAddress(child.publicKey, network),
+        wif,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/** Amounts in this package are integer satoshis (1 PIV = 1e8), the unit of
+ * the underlying shield library — unlike the `pivx-rpc` layer, which uses
+ * PIV floats as the node emits them. */
+/** A decrypted shielded note the wallet can track (and spend, with a spending key). */
+export interface SpendableNote {
+    /** Opaque note object from the shield library (JSON-serializable). */
+    note: {
+        value: number;
+        recipient: number[];
+        rseed: unknown;
+    };
+    /** Hex-serialized incremental merkle witness. */
+    witness: string;
+    /** Hex nullifier — how spends of this note are recognized on-chain. */
+    nullifier: string;
+    /** Decoded text memo, when the note carried one. */
+    memo?: string | null;
+}
+/** A block to scan: raw tx hexes plus the block height. */
+export interface WalletBlock {
+    height: number;
+    txs: {
+        hex: string;
+        txid: string;
+    }[];
+}
+/** Transparent UTXO used as input when shielding funds. */
+export interface TransparentInput {
+    txid: string;
+    vout: number;
+    amount: number;
+    /** 32-byte private key controlling the UTXO. */
+    private_key: Uint8Array;
+    /** scriptPubKey bytes of the UTXO. */
+    script: Uint8Array;
+}
+export interface CreateWalletOptions {
+    /** 32 bytes of seed entropy (derives the spending key; full capability). */
+    seed?: Uint8Array;
+    /** Bech32 extended spending key (`p-secret-spending-key-…`; full capability). */
+    spendingKey?: string;
+    /** Bech32 extended full viewing key (watch-only: scan/receive, no spending). */
+    viewingKey?: string;
+    network?: 'mainnet' | 'testnet';
+    /** Wallet birth height: scanning starts at the nearest checkpoint at or below it. */
+    birthHeight: number;
+    /** ZIP32 account index under the seed. Default 0. */
+    accountIndex?: number;
+    /**
+     * Proving backend. Defaults to single-core WASM. Set `multicore: true` to
+     * use the parallel WASM build (browser only, needs cross-origin isolation).
+     * For server-side proving, use the native Rust SDK instead.
+     */
+    proving?: import('./shield-bindings.js').ProvingOptions;
+}
+export interface CreateTransactionOptions {
+    /** Recipient: shield (ps1…) or transparent address. */
+    to: string;
+    /** Amount in satoshis. */
+    amount: number;
+    /** UTF-8 memo (shield recipients only, max 512 bytes). */
+    memo?: string;
+    /**
+     * Inputs: 'shield' (default) spends the wallet's notes; pass transparent
+     * UTXOs instead to shield transparent funds.
+     */
+    inputs?: 'shield' | TransparentInput[];
+    /** Required when spending transparent inputs (change must stay transparent). */
+    transparentChangeAddress?: string;
+    /**
+     * Opt in to sweep semantics: allow the amount to consume the entire
+     * spendable balance, paying the fee out of the recipient's amount.
+     * Without this, an amount that leaves no room for the fee is rejected.
+     */
+    sweep?: boolean;
+}
+export interface BuiltTransaction {
+    txid: string;
+    /** Fully-proved raw transaction hex, ready for `sendrawtransaction`. */
+    hex: string;
+    /** Nullifiers this tx spends (tracked as pending until finalize/discard). */
+    nullifiers: string[];
+}
+export interface SyncOptions {
+    /** Blocks per root-check batch. Default 100. */
+    batchSize?: number;
+    /**
+     * Max concurrent block fetches. Default 8. Keep well under the node's
+     * rpcworkqueue (default 16) — a full batch fired at once returns 500s.
+     */
+    rpcConcurrency?: number;
+    onProgress?: (height: number, tip: number) => void;
+}
+/** Serialized wallet state (spending key deliberately excluded). */
+export interface WalletState {
+    version: 1;
+    network: 'mainnet' | 'testnet';
+    extfvk: string;
+    lastProcessedBlock: number;
+    commitmentTree: string;
+    diversifierIndex: number[];
+    notes: SpendableNote[];
+    nullifierMap: Record<string, {
+        recipient: string;
+        value: number;
+    }>;
+    /** txid → nullifiers for broadcast-but-unconfirmed spends. */
+    pendingSpends?: Record<string, string[]>;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/** Amounts in this package are integer satoshis (1 PIV = 1e8), the unit of
+ * the underlying shield library — unlike the `pivx-rpc` layer, which uses
+ * PIV floats as the node emits them. */
+export {};

package/dist/wallet.d.ts

@@ -0,0 +1,161 @@
+import { type PivxClient } from 'pivx-rpc';
+import { type ProvingOptions } from './shield-bindings.js';
+import type { BuiltTransaction, CreateTransactionOptions, CreateWalletOptions, SpendableNote, SyncOptions, WalletBlock } from './types.js';
+/** Thrown when a watch-only wallet is asked to spend. */
+export declare class NoSpendAuthorityError extends Error {
+    constructor();
+}
+/** Thrown when the local commitment tree diverges from the node's sapling root. */
+export declare class ScanDivergedError extends Error {
+    readonly height: number;
+    readonly localRoot: string;
+    readonly nodeRoot: string;
+    constructor(height: number, localRoot: string, nodeRoot: string);
+}
+/**
+ * Standalone PIVX wallet: owns keys, scans blocks, tracks shielded notes,
+ * and builds fully-proved transactions locally. A node (via `pivx-rpc`) is
+ * only used as a chain-data source and broadcast endpoint.
+ *
+ * Capabilities follow the key material: constructed from a seed or spending
+ * key the wallet can spend; from a viewing key it can scan, derive receive
+ * addresses, and track balance (watch-only) — and can be upgraded in place
+ * with {@link loadSpendingKey}.
+ */
+export declare class PivxWallet {
+    private readonly shield;
+    readonly network: 'mainnet' | 'testnet';
+    private readonly extfvk;
+    private commitmentTree;
+    private lastProcessedBlock;
+    private extsk?;
+    private notes;
+    private nullifierMap;
+    /** txid → nullifiers awaiting broadcast confirmation. Persisted, so a
+     * crash between broadcast and finalize can't resurrect spent notes. */
+    private pendingSpends;
+    private diversifierIndex;
+    /** One writer at a time: block state-mutating operations from racing. */
+    private busy;
+    /** Whether the starting checkpoint has been confirmed against the node. */
+    private startValidated;
+    private constructor();
+    private get isTestnet();
+    /** True when the wallet holds spend authority. */
+    get canSpend(): boolean;
+    static create(opts: CreateWalletOptions): Promise<PivxWallet>;
+    /** Upgrade a watch-only wallet. The key must match the stored viewing key. */
+    loadSpendingKey(spendingKey: string): void;
+    /** Next diversified shield receive address. */
+    getNewAddress(): string;
+    /** Confirmed shielded balance in satoshis (scanned notes, minus pending spends). */
+    getBalance(): number;
+    /** Whether `address` is a shield (Sapling) address on this wallet's network. */
+    private isShieldAddress;
+    /** Currently tracked unspent notes. */
+    getNotes(): readonly SpendableNote[];
+    getLastSyncedBlock(): number;
+    /** Look up a note by its on-chain nullifier (payment attribution for spends). */
+    getNoteFromNullifier(nullifier: string): {
+        recipient: string;
+        value: number;
+    } | undefined;
+    /**
+     * Scan blocks (strictly ascending heights, all above the last synced
+     * block). Returns the raw hexes of transactions relevant to this wallet.
+     * Use this directly when you have your own block feed; otherwise see
+     * {@link sync}.
+     */
+    handleBlocks(blocks: WalletBlock[]): string[];
+    /** handleBlocks without the busy guard, for internal use by sync (which
+     * already holds the guard). */
+    private applyBlocks;
+    /**
+     * Decrypt a single transaction's outputs for this wallet without touching
+     * wallet state — a hint for 0-conf payment detection from the mempool.
+     *
+     * This only trial-decrypts; it does NOT validate the transaction (proof,
+     * double-spend, or whether it will ever confirm). Do not credit funds
+     * from a preview: dedupe on the caller's own txid and credit only from
+     * confirmed notes returned by {@link getNotes} after {@link sync}.
+     */
+    previewTransaction(hex: string): {
+        recipient: string;
+        value: number;
+        memo?: string | null;
+    }[];
+    /**
+     * Sync from the node up to its current tip.
+     *
+     * Each batch checks the locally-built tree against the node's own
+     * `finalsaplingroot`. That catches malformed or mis-ordered data from the
+     * node, but it is a self-consistency check, not chain authentication: the
+     * SDK does not validate proof-of-stake, so a dishonest node can still serve
+     * a self-consistent fabricated chain. Point this at a node you trust. See
+     * SECURITY.md.
+     */
+    sync(client: PivxClient, opts?: SyncOptions): Promise<void>;
+    /**
+     * Confirm the starting commitment tree against the node before scanning
+     * forward. A fresh wallet begins at a bundled checkpoint; if that
+     * checkpoint's tree does not match the node's sapling root at that height
+     * (some near-tip checkpoints in the shield library are captured on stale
+     * blocks), walk back to the newest checkpoint the node does confirm. A
+     * wallet that already holds scanned notes and no longer matches is treated
+     * as diverged rather than silently rewound.
+     */
+    private ensureValidCheckpoint;
+    /**
+     * Reset scan state to the checkpoint at or below `height` and drop all
+     * tracked notes. This is the recovery path after a divergence error: call
+     * it, then sync again. It needs no keys.
+     */
+    reloadFromCheckpoint(height: number): void;
+    /** Load sapling proving parameters (required once before building transactions). */
+    loadProver(source: {
+        path: string;
+    } | {
+        url: string;
+    } | {
+        spend: Uint8Array;
+        output: Uint8Array;
+    }): Promise<void>;
+    /**
+     * Build and prove a transaction locally. Nothing is broadcast; the spent
+     * notes are held as pending until {@link finalizeTransaction} or
+     * {@link discardTransaction}.
+     */
+    createTransaction(opts: CreateTransactionOptions): Promise<BuiltTransaction>;
+    /** Build, broadcast, and finalize in one step. */
+    send(client: PivxClient, opts: CreateTransactionOptions): Promise<string>;
+    /** Mark a broadcast transaction's notes as spent. */
+    finalizeTransaction(txid: string): void;
+    /** Release a failed transaction's notes back to the spendable set. */
+    discardTransaction(txid: string): void;
+    /**
+     * Transactions built and broadcast but not yet finalized or discarded
+     * (txid → the nullifiers they spend). After a broadcast error left a spend
+     * ambiguous, use this to find the txid, confirm it on-chain, then
+     * {@link finalizeTransaction} or {@link discardTransaction}.
+     */
+    pendingTransactions(): Record<string, string[]>;
+    /**
+     * Serialize wallet state to JSON. The spending key is deliberately
+     * excluded — persist it separately (encrypted) and restore with
+     * {@link loadSpendingKey}.
+     */
+    save(): string;
+    /**
+     * Restore a wallet from {@link save} output.
+     *
+     * For a watch-only deposit scanner, pass `opts.expectedViewingKey` (the key
+     * you know this wallet should have): a tampered state file that swapped in
+     * an attacker's viewing key would otherwise silently repoint deposit
+     * addresses to the attacker. Saved-state integrity is theft-critical here.
+     */
+    static load(json: string, opts?: {
+        proving?: ProvingOptions;
+        expectedViewingKey?: string;
+    }): Promise<PivxWallet>;
+    private encodeRecipient;
+}