zcash-js-bindings

Node.js SDK for Zcash Sapling/keys and a persistent wallet sync layer exposed through a Rust N-API addon.

NPM package: https://www.npmjs.com/package/zcash-js-bindings

SDK goal

Goal: integrate Rust bindings fully into JavaScript so automated tooling (including AI) can one-shot wallet sync and build private payments.

Long-term goal: make the library easy for AI to correctly sync a wallet end-to-end and construct private payments.

Features

• Sapling address generation from a ZIP-32 seed (generateSaplingAddress, generateSaplingAddressWithSeed)
• Deterministic key helpers from seed
• Address validation and address type detection (validateAddress, detectAddressType, isValidZcashAddress)
• ZIP-321 payment URIs (parseZip321Uri, createZip321Uri, parseZip321Multi, createZip321UriTwoPayments)
• ZIP-321 multi-payment parsing helper (parseZip321Payments)
• Memo utilities for ZIP-302 (encodeMemo, decodeMemo, isValidMemoBytes)
• Transaction decoding + block helpers (decodeSaplingTx, parseBlockHeader, verifyEquihash)
• Transparent and unified address helpers (generateTransparentAddress, generateUnifiedAddress, extractUnifiedReceivers)
• Wallet/account helpers: unified view of balances and transaction history via WalletHandle
• Mnemonic helpers (BIP-39) (validateMnemonicPhrase, mnemonicToSeed)
• Network and value utilities (getNetworkConstants, diversifierIndex*, convertZecToZatoshis / convertZatoshisToZec, getNetworkUpgradeForHeight, getMaxMoney, getCoinZatoshis)

Multi-platform builds (GitHub Actions)

GitHub Actions builds platform-specific native binaries and uploads them to GitHub Releases.

Current workflow builds these targets:

• linux-x64-gnu
• linux-arm64-gnu (Docker-based cross-build)
• darwin-arm64 (native)
• win32-x64-msvc (native)

During npm install, postinstall downloads the matching binary for the current platform (see scripts/install-binary.js). If the download is unavailable, it falls back to building from source (npm run build).

Scripts (short)

• scripts/install-binary.js: downloads zcash_js_bindings.<triple>.node from GitHub Releases when available
• scripts/local-test.sh: local packaging/smoke checks (build + test + extra Docker arm64 smoke)

Install

npm install zcash-js-bindings

If prebuilt binaries are unavailable, run:

npm run build

Quick Start

npm run build
npm test

Examples

1) Generate and validate a Sapling address

const zcash = require('zcash-js-bindings');

// Testnet (default)
const addr = zcash.generateSaplingAddress();
console.log('address:', addr);

// Validation
console.log('valid:', zcash.validateAddress(addr));
console.log('details:', zcash.detectAddressType(addr));

2) ZIP-321 URI + memo

const zcash = require('zcash-js-bindings');

const payTo = zcash.generateSaplingAddress();
const uri = zcash.createZip321Uri(payTo, '0.001', 'Payment memo');

const parsed = zcash.parseZip321Uri(uri);
console.log(parsed); // { payTo, amount, memo } (memo is memo bytes as hex)

if (parsed.memo && parsed.memo.length > 0) {
  console.log('memo text:', zcash.decodeMemo(parsed.memo));
}

3) BIP-39 seed + initialize a wallet database

const zcash = require('zcash-js-bindings');

const mnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';

if (!zcash.validateMnemonicPhrase(mnemonic)) {
  throw new Error('Mnemonic is not a valid BIP-39 phrase');
}

const seed64 = zcash.mnemonicToSeed(mnemonic, ''); // 64-byte Buffer
const seed32 = seed64.subarray(0, 32); // Wallet DB init accepts a seed byte array

const wallet = new zcash.WalletHandle('./wallet.sqlite', 1); // 1 = testnet

const initCode = wallet.initDatabase(seed32);
console.log('initDatabase return code:', initCode);

console.log('accounts:', wallet.listAccounts());
wallet.close();

Wallet sync (high level)

WalletHandle persists wallet state locally and exposes scanning/enhancement/decryption entrypoints.

A typical flow is:

• JavaScript orchestrates lightwalletd networking (compact blocks, TreeState, tx bytes, subtree roots)
• JavaScript passes protobuf-encoded data into Rust calls like scanCachedBlocks(...) and decryptAndStoreTransaction(...)
• Wallet results are read from getWalletSummary(), getTransactions(...), and getTransactionMemos(...)

For account creation and scanning, createAccount(...) and scanCachedBlocks(...) require TreeState fields produced by lightwalletd.

Full API Reference

All exported functions, types, and WalletHandle methods are documented here:

• api.md

Next up (post-hackathon)

• mempool streaming
• Tor-based exchange rates
• end-to-end transaction sending from the wallet layer (after the sync pipeline is stable)

Building

npm run build

Testing

npm test