zcash-dev 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/cli.d.ts

@@ -1,7 +1,58 @@
 #!/usr/bin/env node
+import { Command } from 'commander';
+import { send, syncWallet, WalletHandle } from '@zcash-app/sdk';
 import { readZebraCookie, buildTestnetLightwalletdArgs, redactLightwalletdArgs, TestnetLightwalletdOptions } from './testnet-lightwalletd';
 export { readZebraCookie, buildTestnetLightwalletdArgs, redactLightwalletdArgs, TestnetLightwalletdOptions, };
 /** Reads this package's own version so `zcash-dev --version` cannot drift from package.json. */
 export declare function readOwnVersion(): string;
 export declare function getRegtestAccount0MinerAddress(network?: string): string;
+declare const program: Command;
+export interface SendActionOptions {
+    to: string;
+    amount: string;
+    memo?: string;
+    yes?: boolean;
+    mainnet?: boolean;
+    endpoint?: string;
+}
+export interface SendDependencies {
+    client?: any;
+    sendFn?: typeof send;
+    syncWalletFn?: typeof syncWallet;
+    openWalletFn?: typeof WalletHandle.open;
+}
+export interface SendResult {
+    isDryRun: boolean;
+    network: string;
+    recipient: string;
+    amountZatoshis: bigint;
+    feeZatoshis: bigint;
+    endpoint: string;
+    memo?: string;
+    txid?: string;
+}
+export declare function executeSend(options: SendActionOptions, config?: Record<string, string>, deps?: SendDependencies): Promise<SendResult>;
+export interface FundActionOptions {
+    address: string;
+    amount: string;
+    endpoint?: string;
+    stack?: string;
+}
+export interface FundDependencies {
+    client?: any;
+    sendFn?: typeof send;
+    syncWalletFn?: typeof syncWallet;
+    openWalletFn?: typeof WalletHandle.open;
+    fetchFn?: typeof fetch;
+}
+export interface FundResult {
+    txid: string;
+    stack: 'nu7' | 'z3';
+    recipient: string;
+    amountZec: string;
+    zatoshis: bigint;
+    endpoint: string;
+}
+export declare function executeFund(options: FundActionOptions, config?: Record<string, string>, deps?: FundDependencies): Promise<FundResult>;
 export declare function resolveRegtestDir(explicitPath?: string, stack?: string): string;
+export { program };

package/dist/cli.js

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.redactLightwalletdArgs = exports.buildTestnetLightwalletdArgs = exports.readZebraCookie = void 0;
+exports.program = exports.redactLightwalletdArgs = exports.buildTestnetLightwalletdArgs = exports.readZebraCookie = void 0;
 exports.readOwnVersion = readOwnVersion;
 exports.getRegtestAccount0MinerAddress = getRegtestAccount0MinerAddress;
+exports.executeSend = executeSend;
+exports.executeFund = executeFund;
 exports.resolveRegtestDir = resolveRegtestDir;
 const commander_1 = require("commander");
 const prompts_1 = __importDefault(require("prompts"));
@@ -15,6 +17,8 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const sdk_1 = require("@zcash-app/sdk");
+const env_1 = require("./env");
+const redact_1 = require("./redact");
 const testnet_lightwalletd_1 = require("./testnet-lightwalletd");
 Object.defineProperty(exports, "readZebraCookie", { enumerable: true, get: function () { return testnet_lightwalletd_1.readZebraCookie; } });
 Object.defineProperty(exports, "buildTestnetLightwalletdArgs", { enumerable: true, get: function () { return testnet_lightwalletd_1.buildTestnetLightwalletdArgs; } });
@@ -41,6 +45,7 @@ const REMOTE_ENDPOINTS = {
     mainnet: 'zec.rocks:443',
 };
 const program = new commander_1.Command();
+exports.program = program;
 program
     .name('zcash-dev')
     .description('Developer harness & regtest helper CLI for shielded Zcash apps')
@@ -75,54 +80,492 @@ program
         await client.close();
     }
 });
+async function executeSend(options, config, deps) {
+    const env = config ?? (0, env_1.loadProjectEnv)();
+    const network = (env.ZCASH_NETWORK ?? 'regtest').trim().toLowerCase();
+    const regtestStack = (env.ZCASH_REGTEST_STACK ?? '').trim().toLowerCase();
+    const endpoint = options.endpoint || env.ZCASH_ENDPOINT || REMOTE_ENDPOINTS[network] || '127.0.0.1:39067';
+    const isNu7 = network === 'regtest' && (regtestStack === 'nu7' || endpoint.includes('39067') || (!regtestStack && !endpoint.includes('28137')));
+    const effectiveNetwork = isNu7 ? 'regtest-nu7' : network;
+    const mnemonic = (env.ZCASH_MNEMONIC ?? '').trim();
+    const ufvk = (env.ZCASH_UFVK ?? '').trim();
+    const accountIndex = parseInt(env.ZCASH_ACCOUNT_INDEX ?? '0', 10) || 0;
+    const birthdayRaw = (env.ZCASH_BIRTHDAY ?? '').trim();
+    const birthday = /^\d+$/.test(birthdayRaw) ? parseInt(birthdayRaw, 10) : undefined;
+    // Reject UFVK-only configs
+    if (ufvk && !mnemonic) {
+        throw new Error('Cannot send from a watch-only account (UFVK). A spending key (mnemonic) is required.');
+    }
+    if (!mnemonic && network !== 'regtest') {
+        throw new Error(`No spending key (ZCASH_MNEMONIC) configured for ${network}. Cannot send without a spending key.`);
+    }
+    const amountZatoshis = (0, env_1.parseZecToZatoshis)(options.amount);
+    const feeZatoshis = (0, sdk_1.quoteFee)(2);
+    // Dry run mode (default when --yes is not set)
+    if (!options.yes) {
+        return {
+            isDryRun: true,
+            network,
+            recipient: options.to,
+            amountZatoshis,
+            feeZatoshis,
+            endpoint: (0, redact_1.redactSecretUrl)(endpoint),
+            memo: options.memo,
+        };
+    }
+    // Broadcast mode (--yes passed)
+    if (network === 'mainnet' && !options.mainnet) {
+        throw new Error('Sending on mainnet requires the explicit --mainnet flag.');
+    }
+    const activeMnemonic = mnemonic || (network === 'regtest' ? sdk_1.KNOWN_TEST_MNEMONICS[accountIndex] || sdk_1.KNOWN_TEST_MNEMONICS[0] : '');
+    const account = (0, sdk_1.accountFromMnemonic)(activeMnemonic, accountIndex, effectiveNetwork);
+    const client = deps?.client ?? (0, sdk_1.createClient)({ endpoint, network: effectiveNetwork });
+    const openFn = deps?.openWalletFn ?? ((...args) => sdk_1.WalletHandle.open(...args));
+    const syncFn = deps?.syncWalletFn ?? sdk_1.syncWallet;
+    const sendFn = deps?.sendFn ?? sdk_1.send;
+    const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'zcash-dev-wallet-'));
+    const dbPath = path_1.default.join(tempDir, 'wallet.db');
+    let result;
+    try {
+        const wallet = openFn(dbPath, effectiveNetwork, account.getUnifiedFullViewingKey(), `acct${accountIndex}`, birthday);
+        await syncFn(client, wallet);
+        result = await sendFn({
+            client,
+            wallet,
+            from: account,
+            to: options.to,
+            amount: amountZatoshis,
+            memo: options.memo,
+        });
+    }
+    finally {
+        if (!deps?.client) {
+            await client.close().catch(() => { });
+        }
+        try {
+            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+    return {
+        isDryRun: false,
+        network,
+        recipient: options.to,
+        amountZatoshis,
+        feeZatoshis: result.fee ? BigInt(result.fee) : feeZatoshis,
+        endpoint: (0, redact_1.redactSecretUrl)(endpoint),
+        memo: options.memo,
+        txid: result.txid,
+    };
+}
+program
+    .command('address')
+    .description('Display the derived address for the configured account')
+    .option('-i, --index <n>', 'Account index')
+    .action((options) => {
+    try {
+        (0, env_1.applyProjectEnv)();
+        const network = (process.env.ZCASH_NETWORK ?? 'regtest').trim().toLowerCase();
+        const regtestStack = (process.env.ZCASH_REGTEST_STACK ?? '').trim().toLowerCase();
+        const endpoint = process.env.ZCASH_ENDPOINT ?? '';
+        const isNu7 = network === 'regtest' && (regtestStack === 'nu7' || endpoint.includes('39067') || (!regtestStack && !endpoint.includes('28137')));
+        const effectiveNetwork = isNu7 ? 'regtest-nu7' : network;
+        const rawIndex = options.index ?? process.env.ZCASH_ACCOUNT_INDEX ?? '0';
+        const accountIndex = parseInt(rawIndex, 10) || 0;
+        const mnemonic = (process.env.ZCASH_MNEMONIC ?? '').trim();
+        const ufvk = (process.env.ZCASH_UFVK ?? '').trim();
+        if (!mnemonic && !ufvk) {
+            if (network === 'regtest') {
+                const acct = sdk_1.dev.fixtures.account(accountIndex, effectiveNetwork);
+                console.log(`\n--- Configured Account Address ---`);
+                console.log(`Network:          ${network}`);
+                console.log(`Account Index:    ${accountIndex} (regtest default fixture)`);
+                console.log(`Unified Address:  ${acct.getUnifiedAddress()}`);
+                const tAddr = acct.getTransparentAddress?.();
+                if (tAddr)
+                    console.log(`Transparent:      ${tAddr}`);
+                console.log('');
+                return;
+            }
+            throw new Error(`Neither ZCASH_MNEMONIC nor ZCASH_UFVK is configured for ${network}. Set ZCASH_MNEMONIC or ZCASH_UFVK in .env.local.`);
+        }
+        if (mnemonic) {
+            const acct = (0, sdk_1.accountFromMnemonic)(mnemonic, accountIndex, effectiveNetwork);
+            console.log(`\n--- Configured Account Address ---`);
+            console.log(`Network:          ${network}`);
+            console.log(`Account Index:    ${accountIndex}`);
+            console.log(`Unified Address:  ${acct.getUnifiedAddress()}`);
+            const tAddr = acct.getTransparentAddress?.();
+            if (tAddr)
+                console.log(`Transparent:      ${tAddr}`);
+            console.log('');
+            return;
+        }
+        if (ufvk) {
+            const watchAcct = (0, sdk_1.accountFromUfvk)(ufvk, effectiveNetwork);
+            console.log(`\n--- Configured Account Address (Watch-Only) ---`);
+            console.log(`Network:          ${network}`);
+            console.log(`Account Index:    ${accountIndex} (UFVK)`);
+            console.log(`Unified Address:  ${watchAcct.getUnifiedAddress()}`);
+            const tAddr = watchAcct.getTransparentAddress?.();
+            if (tAddr)
+                console.log(`Transparent:      ${tAddr}`);
+            console.log('');
+            return;
+        }
+    }
+    catch (err) {
+        const sanitized = (0, redact_1.sanitizeError)(err, process.env.ZCASH_MNEMONIC);
+        console.error('Address derivation failed:', sanitized.message);
+        process.exit(1);
+    }
+});
+program
+    .command('balance')
+    .description('Check balance for the configured account')
+    .option('-e, --endpoint <endpoint>', 'Zaino / lightwalletd gRPC endpoint')
+    .action(async (options) => {
+    let client;
+    try {
+        (0, env_1.applyProjectEnv)();
+        const network = (process.env.ZCASH_NETWORK ?? 'regtest').trim().toLowerCase();
+        const regtestStack = (process.env.ZCASH_REGTEST_STACK ?? '').trim().toLowerCase();
+        const endpoint = options.endpoint || process.env.ZCASH_ENDPOINT || REMOTE_ENDPOINTS[network] || '127.0.0.1:39067';
+        const isNu7 = network === 'regtest' && (regtestStack === 'nu7' || endpoint.includes('39067') || (!regtestStack && !endpoint.includes('28137')));
+        const effectiveNetwork = isNu7 ? 'regtest-nu7' : network;
+        const birthdayRaw = (process.env.ZCASH_BIRTHDAY ?? '').trim();
+        const birthday = /^\d+$/.test(birthdayRaw) ? parseInt(birthdayRaw, 10) : undefined;
+        const accountIndex = parseInt(process.env.ZCASH_ACCOUNT_INDEX ?? '0', 10) || 0;
+        const mnemonic = (process.env.ZCASH_MNEMONIC ?? '').trim();
+        const ufvk = (process.env.ZCASH_UFVK ?? '').trim();
+        let account;
+        if (mnemonic) {
+            account = (0, sdk_1.accountFromMnemonic)(mnemonic, accountIndex, effectiveNetwork);
+        }
+        else if (ufvk) {
+            account = (0, sdk_1.accountFromUfvk)(ufvk, effectiveNetwork);
+        }
+        else if (network === 'regtest') {
+            account = sdk_1.dev.fixtures.account(accountIndex, effectiveNetwork);
+        }
+        else {
+            throw new Error(`Neither ZCASH_MNEMONIC nor ZCASH_UFVK is configured for ${network}. Set ZCASH_MNEMONIC or ZCASH_UFVK in .env.local.`);
+        }
+        console.log(`Querying balance on ${network} via ${(0, redact_1.redactSecretUrl)(endpoint)}...`);
+        client = (0, sdk_1.createClient)({ endpoint, network: effectiveNetwork });
+        const b = await (0, sdk_1.getBalance)(client, account, { sinceHeight: birthday });
+        console.log('\n--- Account Balance ---');
+        console.log(`Network:     ${network}`);
+        console.log(`Total:       ${(0, env_1.formatZec)(b.total)} ZEC (${b.total} zatoshis)`);
+        console.log(`Ironwood:    ${(0, env_1.formatZec)(b.ironwood)} ZEC`);
+        console.log(`Orchard:     ${(0, env_1.formatZec)(b.orchard)} ZEC`);
+        console.log(`Sapling:     ${(0, env_1.formatZec)(b.sapling)} ZEC`);
+        console.log(`Transparent: ${(0, env_1.formatZec)(b.transparent)} ZEC`);
+        if (b.confirmed && b.pending) {
+            console.log(`Confirmed:   ${(0, env_1.formatZec)(b.confirmed.total)} ZEC`);
+            console.log(`Pending:     ${(0, env_1.formatZec)(b.pending.total)} ZEC`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        const sanitized = (0, redact_1.sanitizeError)(err, process.env.ZCASH_MNEMONIC);
+        console.error('Balance check failed:', sanitized.message);
+        process.exit(1);
+    }
+    finally {
+        if (client) {
+            await client.close().catch(() => { });
+        }
+    }
+});
+program
+    .command('send')
+    .description('Send ZEC or perform a transaction dry run')
+    .requiredOption('--to <address>', 'Recipient address (unified, sapling, or transparent)')
+    .requiredOption('--amount <zec>', 'Amount to send in ZEC')
+    .option('--memo <memo>', 'Optional memo for shielded recipient')
+    .option('--yes', 'Broadcast the transaction (without --yes, runs in dry-run mode)')
+    .option('--mainnet', 'Safety confirmation flag required when broadcasting on mainnet')
+    .option('-e, --endpoint <endpoint>', 'Zaino / lightwalletd gRPC endpoint')
+    .action(async (options) => {
+    try {
+        (0, env_1.applyProjectEnv)();
+        const config = (0, env_1.loadProjectEnv)();
+        const res = await executeSend(options, config);
+        if (res.isDryRun) {
+            console.log('\n=== Transaction Dry Run ===');
+            console.log(`Network:   ${res.network}`);
+            console.log(`Recipient: ${res.recipient}`);
+            console.log(`Amount:    ${options.amount} ZEC (${res.amountZatoshis} zatoshis)`);
+            console.log(`Fee:       ${(0, env_1.formatZec)(res.feeZatoshis)} ZEC (${res.feeZatoshis} zatoshis) [estimated (ZIP-317, 2 outputs assumed)]`);
+            console.log(`Endpoint:  ${res.endpoint}`);
+            if (res.memo) {
+                console.log(`Memo:      ${res.memo}`);
+            }
+            console.log('Status:    DRY RUN ONLY — transaction was NOT broadcast.');
+            console.log(`Pass --yes to sign and broadcast this transaction${res.network === 'mainnet' ? ' (requires --mainnet)' : ''}.\n`);
+        }
+        else {
+            console.log('\n✅ Transaction broadcast successfully!');
+            console.log(`Txid:      ${res.txid}`);
+            console.log(`Fee:       ${(0, env_1.formatZec)(res.feeZatoshis)} ZEC (${res.feeZatoshis} zatoshis)\n`);
+        }
+    }
+    catch (err) {
+        const sanitized = (0, redact_1.sanitizeError)(err, process.env.ZCASH_MNEMONIC);
+        console.error('Send failed:', sanitized.message);
+        process.exit(1);
+    }
+});
+async function executeFund(options, config, deps) {
+    const env = config ?? (0, env_1.loadProjectEnv)();
+    const network = (env.ZCASH_NETWORK ?? 'regtest').trim().toLowerCase();
+    if (network !== 'regtest' && network !== 'regtest-nu7') {
+        throw new Error(`Fund is only available on regtest (current network: ${network}).`);
+    }
+    let stack = (options.stack || env.ZCASH_REGTEST_STACK || '').trim().toLowerCase();
+    const endpointOpt = options.endpoint || env.ZCASH_ENDPOINT;
+    if (!stack) {
+        if (endpointOpt && (endpointOpt.includes('39067') || endpointOpt.includes('39232'))) {
+            stack = 'nu7';
+        }
+        else if (endpointOpt && (endpointOpt.includes('28137') || endpointOpt.includes('8181'))) {
+            stack = 'z3';
+        }
+        else {
+            stack = 'nu7';
+        }
+    }
+    if (stack !== 'nu7' && stack !== 'z3') {
+        throw new Error(`Invalid regtest stack "${stack}". Must be "nu7" or "z3".`);
+    }
+    const zatoshis = (0, env_1.parseZecToZatoshis)(options.amount);
+    const effectiveFetch = deps?.fetchFn ?? fetch;
+    if (stack === 'nu7') {
+        const effectiveEndpoint = options.endpoint || env.ZCASH_ENDPOINT || '127.0.0.1:39067';
+        const minerAccount = (0, sdk_1.accountFromMnemonic)(sdk_1.KNOWN_TEST_MNEMONICS[0], 0, 'regtest-nu7');
+        const client = deps?.client ?? (0, sdk_1.createClient)({ endpoint: effectiveEndpoint, network: 'regtest-nu7' });
+        const openFn = deps?.openWalletFn ?? ((...args) => sdk_1.WalletHandle.open(...args));
+        const syncFn = deps?.syncWalletFn ?? sdk_1.syncWallet;
+        const sendFn = deps?.sendFn ?? sdk_1.send;
+        const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'zcash-dev-fund-'));
+        const dbPath = path_1.default.join(tempDir, 'wallet.db');
+        let result;
+        try {
+            const wallet = openFn(dbPath, 'regtest-nu7', minerAccount.getUnifiedFullViewingKey(), 'miner0', 0);
+            await syncFn(client, wallet);
+            result = await sendFn({
+                client,
+                wallet,
+                from: minerAccount,
+                to: options.address,
+                amount: zatoshis,
+            });
+        }
+        catch (err) {
+            const msg = err.message || String(err);
+            if (msg.includes('ECONNREFUSED') || msg.includes('UNAVAILABLE') || msg.includes('connect')) {
+                throw new Error(`Could not connect to NU7 lightwalletd indexer at ${(0, redact_1.redactSecretUrl)(effectiveEndpoint)}. Is the NU7 stack running? Run: zcash-dev regtest up --stack nu7 (${msg})`);
+            }
+            throw err;
+        }
+        finally {
+            if (!deps?.client) {
+                await client.close().catch(() => { });
+            }
+            try {
+                fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+        return {
+            txid: result.txid,
+            stack: 'nu7',
+            recipient: options.address,
+            amountZec: options.amount,
+            zatoshis,
+            endpoint: (0, redact_1.redactSecretUrl)(effectiveEndpoint),
+        };
+    }
+    else {
+        const rpcRouterUrl = 'http://127.0.0.1:8181';
+        let addrData;
+        try {
+            const addrRes = await effectiveFetch(rpcRouterUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: 'Basic ' + Buffer.from('zebra:zebra').toString('base64'),
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 'fund-listaddresses',
+                    method: 'listaddresses',
+                    params: [],
+                }),
+            });
+            if (!addrRes.ok) {
+                throw new Error(`Zallet HTTP ${addrRes.status}: ${addrRes.statusText}`);
+            }
+            addrData = await addrRes.json();
+        }
+        catch (err) {
+            throw new Error(`Could not connect to Z3 RPC router / Zallet at ${rpcRouterUrl}. Is the Z3 stack running? Run: zcash-dev regtest up --stack nu6 (${err.message || err})`);
+        }
+        const accounts = addrData?.result?.[0]?.unified;
+        const senderUa = accounts?.[0]?.addresses?.[0]?.address;
+        if (!senderUa) {
+            throw new Error('No sender address found in Zallet regtest wallet');
+        }
+        const isNegative = zatoshis < 0n;
+        const abs = isNegative ? -zatoshis : zatoshis;
+        const whole = abs / 100000000n;
+        const frac = abs % 100000000n;
+        const amountZec = `${isNegative ? '-' : ''}${whole}.${frac.toString().padStart(8, '0')}`;
+        const sendRes = await effectiveFetch(rpcRouterUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: 'Basic ' + Buffer.from('zebra:zebra').toString('base64'),
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'fund-sendmany',
+                method: 'z_sendmany',
+                params: [senderUa, [{ address: options.address, amount: amountZec }]],
+            }),
+        });
+        if (!sendRes.ok) {
+            throw new Error(`Zallet z_sendmany HTTP ${sendRes.status}: ${sendRes.statusText}`);
+        }
+        const sendData = await sendRes.json();
+        if (sendData.error) {
+            throw new Error(`Zallet z_sendmany RPC error: ${sendData.error.message || JSON.stringify(sendData.error)}`);
+        }
+        const txid = sendData.result;
+        return {
+            txid,
+            stack: 'z3',
+            recipient: options.address,
+            amountZec: options.amount,
+            zatoshis,
+            endpoint: rpcRouterUrl,
+        };
+    }
+}
 program
     .command('mine')
     .description('Mine blocks on regtest')
     .argument('[blocks]', 'Number of blocks to mine', '1')
-    .option('-e, --endpoint <endpoint>', 'Zaino gRPC endpoint', '127.0.0.1:28137')
+    .option('-e, --endpoint <endpoint>', 'Zebra RPC or Zaino endpoint')
+    .option('--stack <stack>', 'Regtest stack (nu7 | z3)')
     .action(async (blocksStr, options) => {
-    const blocks = parseInt(blocksStr, 10);
-    const client = (0, sdk_1.createClient)({
-        endpoint: options.endpoint,
-        network: 'regtest',
-    });
     try {
-        console.log(`Mining ${blocks} block(s)...`);
-        await sdk_1.dev.mine(client, blocks);
-        console.log(`✅ Successfully mined ${blocks} block(s).`);
+        (0, env_1.applyProjectEnv)();
+        const env = (0, env_1.loadProjectEnv)();
+        const blocks = parseInt(blocksStr, 10);
+        let stack = (options.stack || env.ZCASH_REGTEST_STACK || '').trim().toLowerCase();
+        const endpointOpt = options.endpoint || env.ZCASH_ENDPOINT;
+        const zebraRpcOpt = env.ZCASH_ZEBRA_RPC;
+        if (!stack) {
+            if ((endpointOpt && (endpointOpt.includes('39067') || endpointOpt.includes('39232'))) || (zebraRpcOpt && zebraRpcOpt.includes('39232'))) {
+                stack = 'nu7';
+            }
+            else if ((endpointOpt && (endpointOpt.includes('28137') || endpointOpt.includes('8181'))) || (zebraRpcOpt && zebraRpcOpt.includes('18232'))) {
+                stack = 'z3';
+            }
+            else {
+                stack = 'nu7';
+            }
+        }
+        console.log(`Mining ${blocks} block(s) on ${stack.toUpperCase()} regtest stack...`);
+        if (stack === 'nu7') {
+            const zebraUrl = (options.endpoint && options.endpoint.startsWith('http'))
+                ? options.endpoint
+                : (zebraRpcOpt || 'http://127.0.0.1:39232');
+            let res;
+            try {
+                res = await fetch(zebraUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: 'zcash-dev-mine',
+                        method: 'generate',
+                        params: [blocks],
+                    }),
+                });
+            }
+            catch (err) {
+                throw new Error(`Could not connect to Zebra JSON-RPC at ${zebraUrl}. Is the NU7 stack running? Run: zcash-dev regtest up --stack nu7 (${err.message})`);
+            }
+            if (!res.ok) {
+                throw new Error(`Zebra mining HTTP ${res.status}: ${res.statusText}`);
+            }
+            const data = await res.json();
+            if (data.error) {
+                throw new Error(`Zebra mining JSON-RPC error: ${data.error.message || JSON.stringify(data.error)}`);
+            }
+            console.log(`✅ Successfully mined ${blocks} block(s) on Zebra.`);
+        }
+        else {
+            const rpcRouterUrl = 'http://127.0.0.1:8181';
+            let res;
+            try {
+                res = await fetch(rpcRouterUrl, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: 'Basic ' + Buffer.from('zebra:zebra').toString('base64'),
+                    },
+                    body: JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: 'zcash-dev-mine',
+                        method: 'generate',
+                        params: [blocks],
+                    }),
+                });
+            }
+            catch (err) {
+                throw new Error(`Could not connect to Z3 RPC router at ${rpcRouterUrl}. Is the Z3 stack running? Run: zcash-dev regtest up --stack nu6 (${err.message})`);
+            }
+            if (!res.ok) {
+                throw new Error(`Z3 mining HTTP ${res.status}: ${res.statusText}`);
+            }
+            const data = await res.json();
+            if (data.error) {
+                throw new Error(`Z3 mining JSON-RPC error: ${data.error.message || JSON.stringify(data.error)}`);
+            }
+            console.log(`✅ Successfully mined ${blocks} block(s) on Z3 stack.`);
+        }
     }
     catch (err) {
         console.error('Mining failed:', err.message || err);
         process.exit(1);
     }
-    finally {
-        await client.close();
-    }
 });
 program
     .command('fund')
     .description('Fund a Unified Address on regtest')
     .argument('<address>', 'Recipient Unified Address')
     .argument('[amount]', 'Amount in ZEC', '1.0')
-    .option('-e, --endpoint <endpoint>', 'Zaino gRPC endpoint', '127.0.0.1:28137')
+    .option('-e, --endpoint <endpoint>', 'Zaino / lightwalletd gRPC endpoint')
+    .option('--stack <stack>', 'Regtest stack (nu7 | z3)')
     .action(async (address, amountStr, options) => {
-    const zatoshis = BigInt(Math.round(parseFloat(amountStr) * 100000000));
-    const client = (0, sdk_1.createClient)({
-        endpoint: options.endpoint,
-        network: 'regtest',
-    });
     try {
-        console.log(`Funding ${address} with ${amountStr} ZEC (${zatoshis} zatoshis)...`);
-        const res = await sdk_1.dev.fund(client, address, zatoshis);
-        console.log(`✅ Funded successfully. Txid: ${res.txid}`);
+        (0, env_1.applyProjectEnv)();
+        const config = (0, env_1.loadProjectEnv)();
+        const res = await executeFund({ address, amount: amountStr, endpoint: options.endpoint, stack: options.stack }, config);
+        console.log(`\n✅ Funded successfully via ${res.stack.toUpperCase()} stack!`);
+        console.log(`Recipient: ${res.recipient}`);
+        console.log(`Amount:    ${res.amountZec} ZEC (${res.zatoshis} zatoshis)`);
+        console.log(`Txid:      ${res.txid}\n`);
     }
     catch (err) {
-        console.error('Funding failed:', err.message || err);
+        const sanitized = (0, redact_1.sanitizeError)(err, process.env.ZCASH_MNEMONIC);
+        console.error('Funding failed:', sanitized.message);
         process.exit(1);
     }
-    finally {
-        await client.close();
-    }
 });
 program
     .command('fixtures')
@@ -377,7 +820,13 @@ regtestCmd
         console.log('\n🐳 Starting NU7 Regtest containers...');
         const initScript = path_1.default.join(regtestDir, 'regtest-init.sh');
         if (fs_1.default.existsSync(initScript)) {
-            (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+            try {
+                (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+            }
+            catch {
+                console.error('regtest-init.sh failed, see output above');
+                process.exit(1);
+            }
         }
         else {
             (0, child_process_1.execSync)(`cd "${regtestDir}" && docker compose up -d`, { stdio: 'inherit' });
@@ -429,7 +878,13 @@ regtestCmd
     console.log('\n🐳 Starting Regtest containers...');
     const initScript = path_1.default.join(regtestDir, 'regtest-init.sh');
     if (fs_1.default.existsSync(initScript)) {
-        (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+        try {
+            (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+        }
+        catch {
+            console.error('regtest-init.sh failed, see output above');
+            process.exit(1);
+        }
     }
     else {
         (0, child_process_1.execSync)(`cd "${regtestDir}" && docker compose up -d`, { stdio: 'inherit' });
@@ -637,7 +1092,13 @@ regtestCmd
         console.log('\n=== 🛠️  Reinitializing fresh NU7 chain via regtest-init.sh ===\n');
         const initScript = path_1.default.join(regtestDir, 'regtest-init.sh');
         if (fs_1.default.existsSync(initScript)) {
-            (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+            try {
+                (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+            }
+            catch {
+                console.error('regtest-init.sh failed, see output above');
+                process.exit(1);
+            }
         }
         else {
             (0, child_process_1.execSync)(`cd "${regtestDir}" && docker compose up -d`, { stdio: 'inherit' });
@@ -669,11 +1130,17 @@ regtestCmd
     console.log('\n=== 🛠️  Reinitializing fresh chain via regtest-init.sh ===\n');
     const initScript = path_1.default.join(regtestDir, 'regtest-init.sh');
     const legacyInitScript = path_1.default.join(regtestDir, 'scripts/regtest-init.sh');
-    if (fs_1.default.existsSync(initScript)) {
-        (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+    try {
+        if (fs_1.default.existsSync(initScript)) {
+            (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${initScript}"`, { stdio: 'inherit' });
+        }
+        else if (fs_1.default.existsSync(legacyInitScript)) {
+            (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${legacyInitScript}"`, { stdio: 'inherit' });
+        }
     }
-    else if (fs_1.default.existsSync(legacyInitScript)) {
-        (0, child_process_1.execSync)(`cd "${regtestDir}" && bash "${legacyInitScript}"`, { stdio: 'inherit' });
+    catch {
+        console.error('regtest-init.sh failed, see output above');
+        process.exit(1);
     }
     (0, child_process_1.execSync)(`cd "${regtestDir}" && docker compose up -d && docker compose up -d zaino`, { stdio: 'inherit' });
     const waitForRpc = async (payload, maxAttempts = 45) => {

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+export declare function parseEnvContent(content: string): Record<string, string>;
+export declare function loadProjectEnv(cwd?: string, processEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function applyProjectEnv(cwd?: string): Record<string, string>;
+export declare function formatZec(zatoshis: bigint | number): string;
+export declare function parseZecToZatoshis(amountStr: string): bigint;

package/dist/env.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvContent = parseEnvContent;
+exports.loadProjectEnv = loadProjectEnv;
+exports.applyProjectEnv = applyProjectEnv;
+exports.formatZec = formatZec;
+exports.parseZecToZatoshis = parseZecToZatoshis;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function parseEnvContent(content) {
+    const result = {};
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        result[key] = val;
+    }
+    return result;
+}
+function loadProjectEnv(cwd = process.cwd(), processEnv = process.env) {
+    const envPath = path_1.default.join(cwd, '.env');
+    const envLocalPath = path_1.default.join(cwd, '.env.local');
+    const fromEnv = fs_1.default.existsSync(envPath)
+        ? parseEnvContent(fs_1.default.readFileSync(envPath, 'utf8'))
+        : {};
+    const fromLocal = fs_1.default.existsSync(envLocalPath)
+        ? parseEnvContent(fs_1.default.readFileSync(envLocalPath, 'utf8'))
+        : {};
+    // Precedence: processEnv wins > .env.local > .env
+    const merged = { ...fromEnv, ...fromLocal };
+    for (const [k, v] of Object.entries(processEnv)) {
+        if (v !== undefined) {
+            merged[k] = v;
+        }
+    }
+    return merged;
+}
+function applyProjectEnv(cwd = process.cwd()) {
+    const config = loadProjectEnv(cwd);
+    for (const [k, v] of Object.entries(config)) {
+        if (process.env[k] === undefined) {
+            process.env[k] = v;
+        }
+    }
+    return config;
+}
+function formatZec(zatoshis) {
+    try {
+        const val = BigInt(zatoshis);
+        const neg = val < 0n;
+        const abs = neg ? -val : val;
+        const whole = abs / 100000000n;
+        const frac = (abs % 100000000n).toString().padStart(8, '0');
+        return `${neg ? '-' : ''}${whole}.${frac}`;
+    }
+    catch {
+        return String(zatoshis);
+    }
+}
+function parseZecToZatoshis(amountStr) {
+    const trimmed = (amountStr ?? '').trim();
+    if (!trimmed || !/^\d+(\.\d{1,8})?$/.test(trimmed)) {
+        throw new Error(`Invalid ZEC amount: "${amountStr}". Expected decimal number with up to 8 decimal places.`);
+    }
+    const [whole, fraction = ''] = trimmed.split('.');
+    const wholeZat = BigInt(whole) * 100000000n;
+    const fractionZat = BigInt(fraction.padEnd(8, '0'));
+    const total = wholeZat + fractionZat;
+    if (total <= 0n) {
+        throw new Error(`Amount must be greater than zero, got ${amountStr} ZEC`);
+    }
+    return total;
+}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 export * from '@zcash-app/sdk';
 export * from './testnet-lightwalletd';
+export * from './env';
+export * from './redact';
+export { program, executeSend, SendActionOptions, SendDependencies, SendResult, executeFund, FundActionOptions, FundDependencies, FundResult, } from './cli';

package/dist/index.js

@@ -14,5 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeFund = exports.executeSend = exports.program = void 0;
 __exportStar(require("@zcash-app/sdk"), exports);
 __exportStar(require("./testnet-lightwalletd"), exports);
+__exportStar(require("./env"), exports);
+__exportStar(require("./redact"), exports);
+var cli_1 = require("./cli");
+Object.defineProperty(exports, "program", { enumerable: true, get: function () { return cli_1.program; } });
+Object.defineProperty(exports, "executeSend", { enumerable: true, get: function () { return cli_1.executeSend; } });
+Object.defineProperty(exports, "executeFund", { enumerable: true, get: function () { return cli_1.executeFund; } });

package/dist/redact.d.ts

@@ -0,0 +1,2 @@
+export declare function redactSecretUrl(rawUrl: string): string;
+export declare function sanitizeError(err: unknown, mnemonic?: string): Error;

package/dist/redact.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactSecretUrl = redactSecretUrl;
+exports.sanitizeError = sanitizeError;
+function redactSecretUrl(rawUrl) {
+    if (!rawUrl || typeof rawUrl !== 'string')
+        return rawUrl;
+    const trimmed = rawUrl.trim();
+    if (!trimmed.includes('://')) {
+        if (trimmed.includes('@')) {
+            return trimmed.replace(/^[^@]+@/, '<redacted>@');
+        }
+        return trimmed;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        const hasAuth = Boolean(parsed.username || parsed.password);
+        const hasPathSecret = parsed.pathname.length > 1;
+        const hasQuerySecret = parsed.search.length > 1;
+        if (hasAuth || hasPathSecret || hasQuerySecret) {
+            const portPart = parsed.port ? `:${parsed.port}` : '';
+            return `${parsed.protocol}//${parsed.hostname}${portPart}/<redacted>`;
+        }
+        return trimmed;
+    }
+    catch {
+        return trimmed
+            .replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^@]+@([^\s/]+)/, '$1<redacted>@$2')
+            .replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/?]+)\/[^\s]+/, '$1/<redacted>')
+            .replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/?]+)\?[^\s]+/, '$1/<redacted>');
+    }
+}
+function sanitizeError(err, mnemonic) {
+    let message = err instanceof Error ? err.message : String(err);
+    if (mnemonic && mnemonic.trim()) {
+        message = message.split(mnemonic.trim()).join('<redacted>');
+        const words = mnemonic.trim().split(/\s+/);
+        if (words.length >= 12) {
+            const joinedWords = words.join(' ');
+            message = message.split(joinedWords).join('<redacted>');
+        }
+    }
+    // Redact URLs with secrets/paths
+    message = message.replace(/https?:\/\/[^\s"'<>]+/g, (url) => redactSecretUrl(url));
+    const clean = new Error(message);
+    clean.name = err instanceof Error ? err.name : 'Error';
+    return clean;
+}

package/docker/regtest/regtest-init.sh

@@ -23,10 +23,34 @@ done
 echo "   Zebra is ready."
 
 echo "==> Mining 2 blocks to activate NU6.3 at height 2..."
-curl -s \
-    -X POST -H "Content-Type: application/json" \
-    -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \
-    "http://127.0.0.1:29232" | grep -q '"result"'
+GEN_TIMEOUT="${GENERATE_TIMEOUT_SECS:-60}"
+GEN_SUCCESS=0
+LAST_GEN_RESPONSE=""
+START_TIME=$(date +%s)
+while true; do
+  LAST_GEN_RESPONSE="$(curl -s -X POST \
+      -H "Content-Type: application/json" \
+      -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \
+      "http://127.0.0.1:29232" 2>&1 || true)"
+  if echo "$LAST_GEN_RESPONSE" | grep -q '"result"' && ! echo "$LAST_GEN_RESPONSE" | grep -q '"error"'; then
+    GEN_SUCCESS=1
+    break
+  fi
+  NOW=$(date +%s)
+  if [ $((NOW - START_TIME)) -ge "$GEN_TIMEOUT" ]; then
+    break
+  fi
+  sleep 2
+done
+
+if [ "$GEN_SUCCESS" -ne 1 ]; then
+  echo "❌ Failed to mine initial blocks within ${GEN_TIMEOUT}s." >&2
+  echo "Last response body:" >&2
+  echo "$LAST_GEN_RESPONSE" >&2
+  echo "Last 20 lines of docker compose logs zebra:" >&2
+  $COMPOSE logs --tail 20 zebra >&2 || true
+  exit 1
+fi
 echo "   Blocks mined."
 
 echo "==> Preparing Zallet data volume..."

package/docker/regtest-nu7/regtest-init.sh

@@ -25,10 +25,34 @@ done
 echo "   Zebra is ready."
 
 echo "==> Mining 2 initial blocks to activate NU7 at height 2..."
-curl -s \
-    -X POST -H "Content-Type: application/json" \
-    -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \
-    "http://127.0.0.1:${ZEBRA_PORT}" | grep -q '"result"'
+GEN_TIMEOUT="${GENERATE_TIMEOUT_SECS:-60}"
+GEN_SUCCESS=0
+LAST_GEN_RESPONSE=""
+START_TIME=$(date +%s)
+while true; do
+  LAST_GEN_RESPONSE="$(curl -s -X POST \
+      -H "Content-Type: application/json" \
+      -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \
+      "http://127.0.0.1:${ZEBRA_PORT}" 2>&1 || true)"
+  if echo "$LAST_GEN_RESPONSE" | grep -q '"result"' && ! echo "$LAST_GEN_RESPONSE" | grep -q '"error"'; then
+    GEN_SUCCESS=1
+    break
+  fi
+  NOW=$(date +%s)
+  if [ $((NOW - START_TIME)) -ge "$GEN_TIMEOUT" ]; then
+    break
+  fi
+  sleep 2
+done
+
+if [ "$GEN_SUCCESS" -ne 1 ]; then
+  echo "❌ Failed to mine initial blocks within ${GEN_TIMEOUT}s." >&2
+  echo "Last response body:" >&2
+  echo "$LAST_GEN_RESPONSE" >&2
+  echo "Last 20 lines of docker compose logs zebra:" >&2
+  $COMPOSE logs --tail 20 zebra >&2 || true
+  exit 1
+fi
 echo "   Blocks mined. NU7 is now active."
 
 echo "==> Starting lightwalletd service..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcash-dev",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Regtest developer helper CLI for shielded Zcash apps",
   "bin": {
     "zcash-dev": "./dist/cli.js"
@@ -34,7 +34,7 @@
   "dependencies": {
     "commander": "^12.1.0",
     "prompts": "^2.4.2",
-    "@zcash-app/sdk": "0.1.0-alpha.0"
+    "@zcash-app/sdk": "0.1.0-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",