@zcash-app/sdk 0.0.0-stage → 0.1.0-alpha.0

package/dist/constants.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_TEST_MNEMONICS = void 0;
+/**
+ * Shared test fixture mnemonics (BIP-39 english).
+ * Publicly known seeds used exclusively for development and automated testing.
+ * Strictly prohibited on mainnet.
+ */
+exports.KNOWN_TEST_MNEMONICS = [
+    'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
+    'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong',
+    'legal winner thank year wave sausage worth useful legal winner thank yellow',
+    'coast same leader clip mail imitate place never place disease gold endless',
+    'believe ketchup guitar sustain cushion hat napkin enforce require skull paper mail',
+    'mind mix pipe average diary crisp slam purse cram fiction depth sport',
+    'flat skate furnace copper burst deposit opinion marine napkin canal truth sick',
+    'pet inmate guard tiny okay damage tornado load addict insect alone merry',
+    'inflict miracle moment wish adult cry author disagree flip large total bronze',
+    'suggest travel flower pigeon digital dirt sudden shrimp sort urban miracle photo',
+];

package/dist/dashboard-wallet.d.ts

@@ -0,0 +1,36 @@
+import { WalletHandle } from '@zcash-app/core';
+import { ZcashClient } from './client.js';
+import { SyncOptions } from './sync.js';
+/**
+ * SECURITY NOTICE:
+ * Memos and counterparties are stored in plaintext in the SQLite wallet database.
+ * To protect user privacy, directory permissions are strictly enforced to 0700
+ * and database files to 0600.
+ */
+export interface DashboardSyncStatus {
+    status: 'idle' | 'syncing' | 'synced' | 'error';
+    scanned: number;
+    target: number;
+    notesFound: number;
+    pendingFetches: number;
+    failedFetches: number;
+    error?: string;
+    lastSyncedAt?: number;
+}
+export declare function clearDashboardWalletCache(): void;
+export declare function getDashboardWalletDir(): string;
+export declare function getDashboardWalletPath(network: string, accountId: string): string;
+/**
+ * Opens or retrieves a cached WalletHandle for the given (network, account)
+ * persisted under ~/.zcash-app/dashboard/ with strict 0700 dir and 0600 file permissions.
+ */
+export declare function getDashboardWallet(network: string, accountId: string, ufvk: string, birthday?: number): WalletHandle;
+/**
+ * Returns the current background sync status immediately without blocking.
+ */
+export declare function getDashboardSyncStatus(network: string, accountId: string, wallet?: WalletHandle): DashboardSyncStatus;
+/**
+ * Initiates an asynchronous background synchronization job if one is not already running.
+ * Returns immediately without blocking (< 50ms) so no API endpoint blocks.
+ */
+export declare function startDashboardSync(client: ZcashClient, wallet: WalletHandle, options?: SyncOptions): DashboardSyncStatus;

package/dist/dashboard-wallet.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearDashboardWalletCache = clearDashboardWalletCache;
+exports.getDashboardWalletDir = getDashboardWalletDir;
+exports.getDashboardWalletPath = getDashboardWalletPath;
+exports.getDashboardWallet = getDashboardWallet;
+exports.getDashboardSyncStatus = getDashboardSyncStatus;
+exports.startDashboardSync = startDashboardSync;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const core_1 = require("@zcash-app/core");
+const sync_js_1 = require("./sync.js");
+const walletCache = new Map();
+const syncStatusMap = new Map();
+const syncPromiseMap = new Map();
+function clearDashboardWalletCache() {
+    walletCache.clear();
+    syncStatusMap.clear();
+    syncPromiseMap.clear();
+}
+function getDashboardWalletDir() {
+    const baseHome = process.env.ZCASH_APP_HOME || os_1.default.homedir();
+    const dir = path_1.default.join(baseHome, '.zcash-app', 'dashboard');
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch (_) { }
+    return dir;
+}
+function getDashboardWalletPath(network, accountId) {
+    const dir = getDashboardWalletDir();
+    const safeNetwork = network.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+    const safeAccount = accountId.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+    return path_1.default.join(dir, `${safeNetwork}_${safeAccount}.db`);
+}
+/**
+ * Opens or retrieves a cached WalletHandle for the given (network, account)
+ * persisted under ~/.zcash-app/dashboard/ with strict 0700 dir and 0600 file permissions.
+ */
+function getDashboardWallet(network, accountId, ufvk, birthday) {
+    const cacheKey = `${network.toLowerCase()}:${accountId.toLowerCase()}`;
+    const existing = walletCache.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const dbPath = getDashboardWalletPath(network, accountId);
+    const wallet = core_1.WalletHandle.open(dbPath, network, ufvk, accountId, birthday);
+    // Enforce 0600 on the database file
+    if (fs_1.default.existsSync(dbPath)) {
+        try {
+            fs_1.default.chmodSync(dbPath, 0o600);
+        }
+        catch (_) { }
+    }
+    walletCache.set(cacheKey, wallet);
+    return wallet;
+}
+/**
+ * Returns the current background sync status immediately without blocking.
+ */
+function getDashboardSyncStatus(network, accountId, wallet) {
+    const key = `${network.toLowerCase()}:${accountId.toLowerCase()}`;
+    let status = syncStatusMap.get(key);
+    if (!status) {
+        let scanned = 0;
+        let notesFound = 0;
+        let pendingFetches = 0;
+        let failedFetches = 0;
+        if (wallet) {
+            try {
+                const summary = wallet.getWalletSummary();
+                scanned = summary.lastScannedHeight;
+                notesFound = summary.unspentNotesCount;
+                const fetchCounts = wallet.getTxFetchCounts();
+                pendingFetches = fetchCounts.pendingCount;
+                failedFetches = fetchCounts.failedCount;
+            }
+            catch (_) { }
+        }
+        status = {
+            status: 'idle',
+            scanned,
+            target: scanned,
+            notesFound,
+            pendingFetches,
+            failedFetches,
+        };
+        syncStatusMap.set(key, status);
+    }
+    else if (wallet && status.status !== 'syncing') {
+        // Refresh counts from wallet if idle/synced/error
+        try {
+            const summary = wallet.getWalletSummary();
+            status.scanned = summary.lastScannedHeight;
+            status.notesFound = summary.unspentNotesCount;
+            const fetchCounts = wallet.getTxFetchCounts();
+            status.pendingFetches = fetchCounts.pendingCount;
+            status.failedFetches = fetchCounts.failedCount;
+        }
+        catch (_) { }
+    }
+    return { ...status };
+}
+/**
+ * Initiates an asynchronous background synchronization job if one is not already running.
+ * Returns immediately without blocking (< 50ms) so no API endpoint blocks.
+ */
+function startDashboardSync(client, wallet, options = {}) {
+    const network = options.network ?? wallet.network ?? client.config?.network ?? 'testnet';
+    const accountId = options.accountId ?? wallet.accountId ?? 'account0';
+    const key = `${network.toLowerCase()}:${accountId.toLowerCase()}`;
+    // If already syncing, return current status immediately
+    if (syncPromiseMap.has(key)) {
+        return getDashboardSyncStatus(network, accountId, wallet);
+    }
+    const currentSummary = wallet.getWalletSummary();
+    const currentFetchCounts = wallet.getTxFetchCounts();
+    const statusObj = {
+        status: 'syncing',
+        scanned: currentSummary.lastScannedHeight,
+        target: options.targetHeight ?? options.endHeight ?? currentSummary.lastScannedHeight,
+        notesFound: currentSummary.unspentNotesCount,
+        pendingFetches: currentFetchCounts.pendingCount,
+        failedFetches: currentFetchCounts.failedCount,
+    };
+    syncStatusMap.set(key, statusObj);
+    const syncPromise = (async () => {
+        try {
+            const result = await (0, sync_js_1.syncWallet)(client, wallet, {
+                ...options,
+                onProgress: (scanned, target, notes) => {
+                    statusObj.scanned = scanned;
+                    statusObj.target = target;
+                    statusObj.notesFound = notes;
+                    try {
+                        const counts = wallet.getTxFetchCounts();
+                        statusObj.pendingFetches = counts.pendingCount;
+                        statusObj.failedFetches = counts.failedCount;
+                    }
+                    catch (_) { }
+                    if (options.onProgress) {
+                        options.onProgress(scanned, target, notes);
+                    }
+                },
+            });
+            statusObj.status = 'synced';
+            statusObj.scanned = result.summary.lastScannedHeight;
+            statusObj.target = result.tipHeight;
+            statusObj.notesFound = result.summary.unspentNotesCount;
+            statusObj.pendingFetches = result.pendingFetches;
+            statusObj.failedFetches = result.failedFetches;
+            statusObj.lastSyncedAt = Date.now();
+            statusObj.error = undefined;
+        }
+        catch (err) {
+            statusObj.status = 'error';
+            statusObj.error = err?.message ?? String(err);
+            try {
+                const counts = wallet.getTxFetchCounts();
+                statusObj.pendingFetches = counts.pendingCount;
+                statusObj.failedFetches = counts.failedCount;
+            }
+            catch (_) { }
+        }
+        finally {
+            syncPromiseMap.delete(key);
+        }
+    })();
+    syncPromiseMap.set(key, syncPromise);
+    return { ...statusObj };
+}

package/dist/decrypted-tx.d.ts

@@ -0,0 +1,26 @@
+import type { DecryptedTransaction, DecodedTransaction } from './types.js';
+/**
+ * Decrypts an Ironwood transaction wire serialization using a Unified Full Viewing Key.
+ *
+ * Recovers incoming actions (external and internal scope, marked with isChange/isInternal)
+ * and outgoing actions (via OVK recovery). Also returns txid, net fee (valueBalance),
+ * expiry height, and consensus branch ID.
+ *
+ * @param ufvk The Unified Full Viewing Key encoded string.
+ * @param network Network name ('regtest', 'testnet', 'mainnet', 'regtest-nu7').
+ * @param rawTxBytes Raw transaction serialized bytes.
+ * @param height Block height of the transaction (or target height).
+ * @returns Fully decrypted transaction details with typed values and decoded memos.
+ */
+export declare function decryptTransaction(ufvk: string, network: string, rawTxBytes: Uint8Array | Buffer, height: number): DecryptedTransaction;
+/**
+ * Parses and decodes raw transaction bytes locally using core crypto parsers.
+ * Does not trust or rely on remote node's decoded JSON representation.
+ *
+ * @param rawTxBytes Serialized transaction bytes as Buffer or Uint8Array.
+ * @param network Network name (optional, defaults to 'testnet').
+ * @param height Confirmed block height if known (optional).
+ * @returns Fully decoded transaction structure with upgrade name, pool action counts,
+ *          anchors, nullifiers, commitments, and ZIP 317 fee calculation.
+ */
+export declare function decodeTransaction(rawTxBytes: Uint8Array | Buffer, network?: string, height?: number): DecodedTransaction;

package/dist/decrypted-tx.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decryptTransaction = decryptTransaction;
+exports.decodeTransaction = decodeTransaction;
+const core_1 = require("@zcash-app/core");
+const consensus_js_1 = require("./consensus.js");
+/**
+ * Decrypts an Ironwood transaction wire serialization using a Unified Full Viewing Key.
+ *
+ * Recovers incoming actions (external and internal scope, marked with isChange/isInternal)
+ * and outgoing actions (via OVK recovery). Also returns txid, net fee (valueBalance),
+ * expiry height, and consensus branch ID.
+ *
+ * @param ufvk The Unified Full Viewing Key encoded string.
+ * @param network Network name ('regtest', 'testnet', 'mainnet', 'regtest-nu7').
+ * @param rawTxBytes Raw transaction serialized bytes.
+ * @param height Block height of the transaction (or target height).
+ * @returns Fully decrypted transaction details with typed values and decoded memos.
+ */
+function decryptTransaction(ufvk, network, rawTxBytes, height) {
+    const buf = Buffer.isBuffer(rawTxBytes) ? rawTxBytes : Buffer.from(rawTxBytes);
+    const res = (0, core_1.decryptTransaction)(ufvk, network, buf, height);
+    return {
+        txid: res.txid,
+        fee: res.fee !== null && res.fee !== undefined ? BigInt(res.fee) : null,
+        expiryHeight: res.expiryHeight,
+        consensusBranchId: res.consensusBranchId,
+        incoming: res.incoming.map((inc) => ({
+            actionIndex: inc.actionIndex,
+            value: BigInt(inc.value),
+            memo: {
+                text: inc.memo.text,
+                hex: inc.memo.hex,
+            },
+            recipient: inc.recipient,
+            isChange: inc.isChange,
+            isInternal: inc.isInternal,
+        })),
+        outgoing: res.outgoing.map((out) => ({
+            actionIndex: out.actionIndex,
+            value: BigInt(out.value),
+            memo: {
+                text: out.memo.text,
+                hex: out.memo.hex,
+            },
+            recipient: out.recipient,
+        })),
+    };
+}
+/**
+ * Parses and decodes raw transaction bytes locally using core crypto parsers.
+ * Does not trust or rely on remote node's decoded JSON representation.
+ *
+ * @param rawTxBytes Serialized transaction bytes as Buffer or Uint8Array.
+ * @param network Network name (optional, defaults to 'testnet').
+ * @param height Confirmed block height if known (optional).
+ * @returns Fully decoded transaction structure with upgrade name, pool action counts,
+ *          anchors, nullifiers, commitments, and ZIP 317 fee calculation.
+ */
+function decodeTransaction(rawTxBytes, network, height) {
+    const buf = Buffer.isBuffer(rawTxBytes) ? rawTxBytes : Buffer.from(rawTxBytes);
+    const res = (0, core_1.decodeTransaction)(buf, network, height);
+    const upgradeName = (0, consensus_js_1.getUpgradeName)(res.consensusBranchId);
+    return {
+        txid: res.txid,
+        version: res.version,
+        consensusBranchId: res.consensusBranchId,
+        upgradeName,
+        expiryHeight: res.expiryHeight,
+        fee: res.fee !== null && res.fee !== undefined ? BigInt(res.fee) : null,
+        feeUnknown: res.fee === null || res.fee === undefined,
+        pools: res.pools,
+        actionCounts: {
+            transparentInputs: res.actionCounts.transparentInputs,
+            transparentOutputs: res.actionCounts.transparentOutputs,
+            saplingSpends: res.actionCounts.saplingSpends,
+            saplingOutputs: res.actionCounts.saplingOutputs,
+            orchardActions: res.actionCounts.orchardActions,
+            ironwoodActions: res.actionCounts.ironwoodActions,
+        },
+        anchors: {
+            sapling: res.anchors.sapling
+                ? {
+                    walletOrchardOrder: res.anchors.sapling.walletOrchardOrder,
+                    zebraRpcOrder: res.anchors.sapling.zebraRpcOrder,
+                }
+                : undefined,
+            orchard: res.anchors.orchard
+                ? {
+                    walletOrchardOrder: res.anchors.orchard.walletOrchardOrder,
+                    zebraRpcOrder: res.anchors.orchard.zebraRpcOrder,
+                }
+                : undefined,
+            ironwood: res.anchors.ironwood
+                ? {
+                    walletOrchardOrder: res.anchors.ironwood.walletOrchardOrder,
+                    zebraRpcOrder: res.anchors.ironwood.zebraRpcOrder,
+                }
+                : undefined,
+        },
+        nullifiers: res.nullifiers,
+        noteCommitments: res.noteCommitments,
+        size: res.size,
+    };
+}

package/dist/detection.d.ts

@@ -0,0 +1,20 @@
+import { ZcashClient } from './client.js';
+import { Account, AccountBalance, IncomingNote, SyncResult, Ufvk, WatchOnlyAccount } from './types.js';
+export declare function detectIncoming(client: ZcashClient, key: Ufvk | WatchOnlyAccount | Account, opts?: {
+    sinceHeight?: number;
+    endHeight?: number;
+}): Promise<{
+    notes: IncomingNote[];
+    spentNullifiers: Set<string>;
+}>;
+export declare function getBalance(client: ZcashClient, key: Ufvk | WatchOnlyAccount | Account, opts?: {
+    minConf?: number;
+    sinceHeight?: number;
+    endHeight?: number;
+}): Promise<AccountBalance>;
+export declare function sync(client: ZcashClient, key: Ufvk | WatchOnlyAccount | Account, opts?: {
+    sinceHeight?: number;
+}): Promise<SyncResult>;
+export declare function watch(client: ZcashClient, key: Ufvk | WatchOnlyAccount | Account, onNote: (note: IncomingNote) => void, opts?: {
+    pollMs?: number;
+}): () => void;

package/dist/detection.js

@@ -0,0 +1,252 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectIncoming = detectIncoming;
+exports.getBalance = getBalance;
+exports.sync = sync;
+exports.watch = watch;
+const core = __importStar(require("@zcash-app/core"));
+async function detectIncoming(client, key, opts) {
+    const ufvk = typeof key === 'string' ? key : key.getUnifiedFullViewingKey();
+    const network = client.config.network;
+    const info = await client.getInfo();
+    const currentHeight = parseInt(info.blockHeight, 10);
+    const targetEndHeight = opts?.endHeight ?? currentHeight;
+    let startHeight = opts?.sinceHeight;
+    if (startHeight === undefined) {
+        const acctBirthday = typeof key !== 'string' ? key.birthdayHeight : undefined;
+        startHeight = acctBirthday ?? 1;
+    }
+    if (startHeight > targetEndHeight) {
+        return { notes: [], spentNullifiers: new Set() };
+    }
+    const detected = [];
+    const spentNullifiers = new Set();
+    const blockStream = client.getBlockRange(startHeight, targetEndHeight);
+    let orchardTreePosition = 0;
+    let ironwoodTreePosition = 0;
+    for await (const block of blockStream) {
+        const blockHeight = typeof block.height === 'string' ? parseInt(block.height, 10) : Number(block.height);
+        if (!block.vtx)
+            continue;
+        for (const tx of block.vtx) {
+            const rawTxid = tx.txid ?? tx.hash;
+            const txid = Buffer.isBuffer(rawTxid)
+                ? Buffer.from(rawTxid).reverse().toString('hex')
+                : String(rawTxid ?? '');
+            // Record any spent nullifiers in actions
+            if (tx.actions && tx.actions.length > 0) {
+                for (let i = 0; i < tx.actions.length; i++) {
+                    const action = tx.actions[i];
+                    const hasCmx = action.cmx && action.cmx.length === 32;
+                    const currentPos = hasCmx ? orchardTreePosition++ : undefined;
+                    if (action.nullifier && action.nullifier.length === 32) {
+                        const nfHex = Buffer.from(action.nullifier).toString('hex');
+                        spentNullifiers.add(nfHex);
+                    }
+                    // In protobuf keepCase: true, field is ciphertext
+                    const encCiphertext = action.ciphertext || action.cipherText;
+                    if (!encCiphertext)
+                        continue;
+                    const result = core.tryDecryptAction(ufvk, network, action.ephemeralKey, action.cmx, encCiphertext, false, i, action.nullifier);
+                    if (result) {
+                        detected.push({
+                            pool: 'orchard',
+                            value: BigInt(result.valueZatoshis),
+                            txid,
+                            height: blockHeight,
+                            recipient: result.recipient,
+                            nullifier: result.nullifier,
+                            rho: result.rho,
+                            rseed: result.rseed,
+                            cmx: hasCmx ? Buffer.from(action.cmx).toString('hex') : undefined,
+                            treePosition: currentPos,
+                        });
+                    }
+                }
+            }
+            // Record any spent nullifiers in ironwoodActions
+            if (tx.ironwoodActions && tx.ironwoodActions.length > 0) {
+                for (let i = 0; i < tx.ironwoodActions.length; i++) {
+                    const action = tx.ironwoodActions[i];
+                    const hasCmx = action.cmx && action.cmx.length === 32;
+                    const currentPos = hasCmx ? ironwoodTreePosition++ : undefined;
+                    if (action.nullifier && action.nullifier.length === 32) {
+                        const nfHex = Buffer.from(action.nullifier).toString('hex');
+                        spentNullifiers.add(nfHex);
+                    }
+                    const encCiphertext = action.ciphertext || action.cipherText;
+                    if (!encCiphertext)
+                        continue;
+                    const result = core.tryDecryptAction(ufvk, network, action.ephemeralKey, action.cmx, encCiphertext, true, i, action.nullifier);
+                    if (result) {
+                        detected.push({
+                            pool: 'ironwood',
+                            value: BigInt(result.valueZatoshis),
+                            txid,
+                            height: blockHeight,
+                            recipient: result.recipient,
+                            nullifier: result.nullifier,
+                            rho: result.rho,
+                            rseed: result.rseed,
+                            cmx: hasCmx ? Buffer.from(action.cmx).toString('hex') : undefined,
+                            treePosition: currentPos,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return { notes: detected, spentNullifiers };
+}
+async function getBalance(client, key, opts) {
+    const minConf = opts?.minConf ?? 1;
+    const info = await client.getInfo();
+    const currentHeight = parseInt(info.blockHeight, 10);
+    const { notes, spentNullifiers } = await detectIncoming(client, key, opts);
+    const confirmed = {
+        orchard: 0n,
+        ironwood: 0n,
+        sapling: 0n,
+        transparent: 0n,
+        total: 0n,
+    };
+    const pending = {
+        orchard: 0n,
+        ironwood: 0n,
+        sapling: 0n,
+        transparent: 0n,
+        total: 0n,
+    };
+    for (const n of notes) {
+        if (n.nullifier && spentNullifiers.has(n.nullifier)) {
+            continue;
+        }
+        const confs = currentHeight >= n.height ? currentHeight - n.height + 1 : 0;
+        const target = confs >= minConf ? confirmed : pending;
+        if (n.pool === 'orchard') {
+            target.orchard += n.value;
+        }
+        else if (n.pool === 'ironwood') {
+            target.ironwood += n.value;
+        }
+    }
+    let transparentConfirmed = 0n;
+    let transparentPending = 0n;
+    const tAddr = typeof key !== 'string' && key.getTransparentAddress ? key.getTransparentAddress() : undefined;
+    if (tAddr) {
+        try {
+            const utxos = await client.getAddressUtxos([tAddr]);
+            for (const u of utxos) {
+                if (u.valueZat) {
+                    const uHeight = u.height ? Number(u.height) : 0;
+                    const confs = uHeight > 0 && currentHeight >= uHeight ? currentHeight - uHeight + 1 : 0;
+                    if (confs >= minConf) {
+                        transparentConfirmed += BigInt(u.valueZat);
+                    }
+                    else {
+                        transparentPending += BigInt(u.valueZat);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            // transparent index not available or empty
+        }
+    }
+    confirmed.transparent = transparentConfirmed;
+    pending.transparent = transparentPending;
+    confirmed.total = confirmed.orchard + confirmed.ironwood + confirmed.sapling + confirmed.transparent;
+    pending.total = pending.orchard + pending.ironwood + pending.sapling + pending.transparent;
+    return {
+        orchard: confirmed.orchard,
+        ironwood: confirmed.ironwood,
+        sapling: confirmed.sapling,
+        transparent: confirmed.transparent,
+        total: confirmed.total,
+        confirmed,
+        pending,
+    };
+}
+async function sync(client, key, opts) {
+    const info = await client.getInfo();
+    const currentHeight = parseInt(info.blockHeight, 10);
+    const { notes } = await detectIncoming(client, key, opts);
+    const balances = await getBalance(client, key);
+    return {
+        syncedHeight: currentHeight,
+        newNotes: notes,
+        balances,
+    };
+}
+function watch(client, key, onNote, opts) {
+    const pollInterval = opts?.pollMs ?? 15000;
+    let active = true;
+    let lastScannedHeight = 0;
+    const poll = async () => {
+        if (!active)
+            return;
+        try {
+            const info = await client.getInfo();
+            const currentHeight = parseInt(info.blockHeight, 10);
+            if (lastScannedHeight === 0) {
+                // First run: establish tip without re-emitting history unless birthdayHeight is set
+                const birthday = typeof key !== 'string' ? key.birthdayHeight : undefined;
+                lastScannedHeight = birthday ? birthday - 1 : currentHeight;
+            }
+            if (currentHeight > lastScannedHeight) {
+                const nextStart = lastScannedHeight + 1;
+                const { notes } = await detectIncoming(client, key, {
+                    sinceHeight: nextStart,
+                    endHeight: currentHeight,
+                });
+                for (const note of notes) {
+                    onNote(note);
+                }
+                lastScannedHeight = currentHeight;
+            }
+        }
+        catch (err) {
+            // transient network poll error
+        }
+        if (active) {
+            setTimeout(poll, pollInterval);
+        }
+    };
+    poll();
+    return () => {
+        active = false;
+    };
+}

package/dist/dev.d.ts

@@ -0,0 +1,28 @@
+import { Account, TxResult } from './types.js';
+import { ZcashClient } from './client.js';
+export declare namespace dev {
+    const fixtures: {
+        mnemonics: readonly string[];
+        account(index: number, network?: "regtest" | "testnet" | "mainnet"): Account;
+    };
+    function mine(client: ZcashClient, blocks: number): Promise<void>;
+    function fund(client: ZcashClient, to: string, value: bigint): Promise<TxResult>;
+    function reset(client: ZcashClient): Promise<void>;
+    function faucet(address: string, opts?: {
+        ztapUrl?: string;
+    }): Promise<{
+        status: 'sent' | 'open-url';
+        txid?: string;
+        url?: string;
+    }>;
+}
+export declare const testkit: {
+    fixtures: {
+        mnemonics: readonly string[];
+        account(index: number, network?: "regtest" | "testnet" | "mainnet"): Account;
+    };
+    withRegtest(fn: (ctx: {
+        client: ZcashClient;
+        fund: typeof dev.fund;
+    }) => Promise<void>): Promise<void>;
+};