zcash-zip321-alpha

Alpha JavaScript/Node.js SDK for Zcash light-wallet flows, backed by upstream Rust crates from librustzcash.

This SDK is for builders who want a technical, scriptable Zcash integration with:

• wallet database initialization
• account creation from seed
• lightwalletd sync
• transaction enhancement and transparent UTXO discovery
• wallet summary, balances, and transaction history
• ZIP-317 transfer proposal creation
• transaction proving, signing, and broadcast
• Zcash address and ZIP-321 utilities

Status

alpha

The SDK is functional and tested, but the API is still moving. It is not audited.

Why choose this SDK

This package is optimized for the actual builder path, not just primitives:

• initialize a wallet
• derive addresses
• sync from lightwalletd
• inspect balances and history
• propose a payment
• prove, sign, and broadcast it

The native layer is not a rewrite. It calls upstream Zcash Rust wallet code for the wallet-critical path.

Capability summary

| Area | Status | | :--- | :---: | | Wallet DB initialization | ✓ | | Account creation from seed | ✓ | | Unified / Sapling / Orchard / Transparent address access | ✓ | | Address validation and classification | ✓ | | ZIP-321 parsing | ✓ | | Seed fingerprint derivation | ✓ | | UFVK derivation | ✓ | | Compact block sync via lightwalletd | ✓ | | Transaction enhancement | ✓ | | Transparent UTXO staging | ✓ | | Wallet summary and balances | ✓ | | Transaction history and output inspection | ✓ | | ZIP-317 transfer proposal creation | ✓ | | Transaction proving and signing | ✓ | | Broadcast via lightwalletd | ✓ | | High-level send helper | ✓ | | Prebuilt-native install path | ✓ | | Multi-platform release asset automation | ✓ |

Install

npm install zcash-zip321-alpha

Install resolution order:

1. packaged prebuilt native library
2. matching GitHub release asset for the package version
3. local Rust build fallback during npm install

The runtime searches for the native library in:

• ZCASH_ZIP321_LIB
• prebuilds/<platform>-<arch>
• target/release
• target/debug

Quickstart

1. Utilities

const {
  parseAddress,
  parseZip321,
  generateUnifiedAddress,
  seedFingerprint,
  deriveUnifiedFullViewingKey
} = require('zcash-zip321-alpha');

const address = parseAddress('t1PKtYdJJHhc3Pxowmznkg7vdTwnhEsCvR4');
const request = parseZip321('zcash:t1PKtYdJJHhc3Pxowmznkg7vdTwnhEsCvR4?amount=1.23&label=Coffee');
const generated = generateUnifiedAddress({
  seedHex: '00'.repeat(32),
  network: 'testnet',
  account: 0,
  receivers: 'all'
});
const fingerprint = seedFingerprint(
  '000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
);
const ufvk = deriveUnifiedFullViewingKey({
  seedHex: '00'.repeat(32),
  network: 'testnet',
  account: 0
});

2. Wallet initialization and sync

const {
  LightWalletClient,
  ZcashSynchronizer,
  ZcashWallet
} = require('zcash-zip321-alpha');

const wallet = new ZcashWallet({
  dbPath: './wallet.db',
  network: 'testnet'
});

wallet.initDatabase();

const client = new LightWalletClient(
  'lightwalletd.testnet.electriccoin.co:9067',
  true
);

const synchronizer = new ZcashSynchronizer(wallet, client, {
  batchSize: 500
});

const syncResult = await synchronizer.syncAndEnhance();
const summary = wallet.getWalletSummary();

console.log(syncResult);
console.log(summary);

3. Transfer proposal, build, sign, and broadcast

const result = await wallet.sendTransfer({
  accountUuid: '123e4567-e89b-12d3-a456-426614174000',
  toAddress: 'u1...',
  value: 100000,
  memo: 'hello',
  seedHex: '00'.repeat(32),
  client
});

console.log(result.txids);

Builder flow

The intended builder flow is:

const wallet = new ZcashWallet({ dbPath, network: 'testnet' });
wallet.initDatabase();

const accountUuid = wallet.createAccount({
  seedHex,
  accountName: 'default',
  treeState
});

const client = new LightWalletClient(lightwalletdHost, true);
const sync = new ZcashSynchronizer(wallet, client);

await sync.syncAndEnhance();

const summary = wallet.getWalletSummary();
const history = wallet.getTransactions(accountUuid);

const sent = await wallet.sendTransfer({
  accountUuid,
  toAddress,
  value,
  memo,
  seedHex,
  client
});

Public API

Top-level utilities

parseZip321(uri) => Zip321Request

Parses a zcash: payment URI with upstream Rust ZIP-321 parsing.

parseAddress(address) => ParsedAddress

Validates and classifies a Zcash address.

Returns:

• normalized
• network
• kind
• canReceiveMemo

generateUnifiedAddress({ seedHex, network, account, receivers }) => GeneratedUnifiedAddress

Derives a unified address and UFVK from seed material.

seedFingerprint(seedHex) => string

Returns the ZIP-32 seed fingerprint.

deriveUnifiedFullViewingKey({ seedHex, network, account }) => string

Derives an encoded UFVK.

ZcashWallet

Builder-facing wallet/database wrapper.

Lifecycle

• initDatabase({ seedHex? })
• createAccount({ seedHex, accountName, treeState, recoverUntilHeight? })
• listAccounts()

Address access

• getCurrentAddress(accountUuid)
• getNextAvailableAddress(accountUuid)
• getSaplingAddress(accountUuid)
• getOrchardAddress(accountUuid)
• getTransparentAddress(accountUuid)
• getAllTransparentAddresses()

Sync state

• updateChainTip(tipHeight)
• suggestScanRanges()
• scanCachedBlocks({ blocksHex, treeState, limit })
• putSaplingSubtreeRoots(startIndex, roots)
• putOrchardSubtreeRoots(startIndex, roots)
• transactionDataRequests()

Wallet inspection

• getWalletSummary()
• latestHeight()
• getTransactions(accountUuid, { offset?, limit? })
• getTransactionOutputs(txidHex)

Transaction enhancement

• decryptAndStoreTransaction({ txHex, minedHeight? })
• setTransactionStatus({ txidHex, status, minedHeight? })
• putUtxo({ txidHex, index, scriptHex, value, height })

Sending

• proposeTransfer({ accountUuid, toAddress, value, memo?, changeMemo?, fallbackChangePool? })
• createProposedTransactions({ accountUuid, proposalHex, seedHex, ovkPolicy?, spendParamPath?, outputParamPath? })
• sendProposedTransactions({ accountUuid, proposalHex, seedHex, client, ovkPolicy?, spendParamPath?, outputParamPath?, height? })
• sendTransfer({ accountUuid, toAddress, value, memo?, changeMemo?, fallbackChangePool?, seedHex, client, ovkPolicy?, spendParamPath?, outputParamPath?, height? })

LightWalletClient

Minimal lightwalletd gRPC client.

Methods:

• getLatestBlock()
• getBlock(height)
• getTransaction(txid)
• sendTransaction(data, height?)
• getTreeState(height)
• getLatestTreeState()
• getLightdInfo()
• getTaddressBalance(addresses)
• getAddressUtxos(addresses, startHeight, maxEntries?)
• getBlockRange(startHeight, endHeight)
• getSubtreeRoots(protocol, startIndex?, maxEntries?)
• getTaddressTransactions(address, startHeight, endHeight)
• getAddressUtxosStream(addresses, startHeight, maxEntries?)
• getMempoolTx(excludeTxidSuffixes?)
• getMempoolStream()

ZcashSynchronizer

Minimal sync engine around wallet scan ranges and lightwalletd.

Methods:

• syncOnce()
• enhanceTransactions()
• syncAndEnhance()

Architecture

This package uses:

• JavaScript for the builder-facing SDK surface
• koffi for the native binding layer
• Rust for wallet-critical logic
• zcash_client_backend and zcash_client_sqlite for wallet semantics
• zcash_address, zcash_keys, zip321, and related crates for protocol utilities

The send path is upstream-backed:

1. build a transfer proposal
2. decode proposal protobuf
3. execute upstream create_proposed_transactions
4. retrieve signed transactions from the wallet DB
5. broadcast through lightwalletd

Sapling proving parameters are bundled into the native library. External proving-parameter setup is not required for the default send flow.

Verification

Current local verification:

• cargo fmt --check
• cargo check
• cargo build --release
• node --test

The repo includes:

• JS unit tests
• native-backed integration tests
• GitHub Actions CI on Linux, macOS Intel, macOS Apple Silicon, and Windows
• tagged-release workflow for native asset publishing

Platform and distribution

The repo includes release automation that builds native assets for:

• linux-x64
• darwin-x64
• darwin-arm64
• win32-x64

The npm installer can download matching GitHub release assets automatically when they exist for the package version.

Alpha notes

This SDK is still alpha:

• API names may still change
• the package is not audited
• broader platform prebuild coverage may expand over time

License

MIT