Introduction

zecd is a shielded-first Zcash wallet server that speaks Bitcoin Core's JSON-RPC dialect.

What zecd is

zecd is a wallet daemon for Zcash built on librustzcash (since 0.8.0, the Zakura Common forks of it, published on crates.io as zakura-*): shielded-first (Ironwood by default, at the wallet's Orchard receiver, with opt-in Sapling receivers and opt-in transparent t-address support), exposed through bitcoind's RPC dialect: the same method names, response shapes, JSON-RPC 1.0 envelope, HTTP Basic/cookie auth, and error codes as Bitcoin Core. An integration that drives a coin purely through Bitcoin RPC (getnewaddress, poll listtransactions/gettransaction/getbalance, sendtoaddress) works against zecd with little or no change, and existing Bitcoin RPC client libraries (e.g. python-bitcoinrpc) connect as-is.

It is written for integrators and operators: engineers wiring a payment system, exchange, or service to Zcash, and the SREs who run it. It is a light client: it syncs compact blocks in the background, never speaks P2P, and never indexes the chain itself.

Since 0.7.0 it is also a Rust library: a host process can bring up the wallet and dispatch any RPC in-process, with no socket in between. See Using zecd as a library.

Deployment model

zecd sits between your application and a self-hosted Zebra full node, talking to zebrad's JSON-RPC directly:

+----------------------+            +----------------+            +------------------+
|  your app /          |  JSON-RPC  |      zecd      |  JSON-RPC  |      Zebra       |
|  Bitcoin RPC client  | ---------> | wallet server  | ---------> |  (self-hosted    |
|  (python-bitcoinrpc, |  Bitcoin   | keys, scanning,|  zebra://  |   full node)     |
|   curl, existing     |  Core      | proving, RPC   |  host:port | consensus, P2P,  |
|   bitcoind tooling)  |  dialect   | surface        |  (local)   | blocks, mempool  |
+----------------------+            +----------------+            +------------------+
       port 8232 mainnet /               derives compact blocks,      rpc.listen_addr
       18232 testnet                     tree state, and mempool      8234 mainnet /
                                         from the node RPCs itself    18234 testnet

The default [backend] server = "zebra" is shorthand for zebra://127.0.0.1:8234 on mainnet (:18234 on test/regtest). Point zebrad's rpc.listen_addr there; Zebra ships with RPC disabled. zecd derives compact blocks, tree state, and mempool visibility from the node's RPCs itself, so in this mode there is no lightwalletd and no zaino to operate.

Since 0.6.0 that is the default, not the only option: [backend] server also accepts a lightwalletd gRPC endpoint, for deployments where running a full node is not practical. See Chain backends for both, and the trade-off between them.

Run the node yourself. zecd holds spend authority over real funds, and its entire view of the chain (balances, confirmations, incoming payments) is whatever Zebra serves it. The Zebra connection is plaintext HTTP and deliberately local-only: a cleartext-credential gate refuses to send [zebra] RPC credentials to a globally-routable host (loopback and, by default, private/LAN ranges are allowed).

Defining properties

• Bitcoin Core RPC conformance. Method names, field names/types, the JSON-RPC 1.0 envelope, Basic/cookie auth, error codes, and HTTP status mapping match Bitcoin Core, and a conformance suite drives a live daemon with the same client logic python-bitcoinrpc uses (see Testing & conformance). Intentional divergences are enumerated in the compatibility boundary; the wire format is specified in RPC conventions.
• Shielded-first, transparent opt-in. A default wallet holds Ironwood notes, received at its Orchard receiver: NU6.3 changed the value pool, not the address, which is why [pools] still names orchard. Sapling receivers and transparent (t-address) receiving/spending are enabled per wallet via [pools] config. Legacy Orchard V2 notes remain spendable, and moving them into Ironwood is a real pool crossing. See Addresses & shielded pools and Transparent support.
• Stateless and seed-recoverable. zecd persists no off-chain state that a from-seed restore couldn't rebuild: there are no address labels, and zecd init --restore recovers all funds and history from the chain. Shielded funds are recoverable unconditionally; transparent funds within the configured gap limit / initial-scan window. See Stateless & recoverable.
• A self-hosted Zebra upstream by default. One local zebrad over JSON-RPC, with no zaino and no trusted third-party server in the path. Since 0.6.0 a lightwalletd endpoint is available as an explicit opt-in for deployments that cannot run a node; running your own remains the recommendation. See Chain backends.
• One spending wallet, any number of watch-only wallets. At most one loaded wallet holds spending keys; watch-only replicas are built from an exported Unified Full Viewing Key and addressed bitcoind-style at /wallet/<name>. Since 0.8.0 an experimental fleet monitors large numbers of watch-only wallets in shared databases. See Watch-only wallets.
• Reproducible builds. The release pipeline produces bit-for-bit reproducible static binaries (a full-source-bootstrapped StageX image on amd64, a fully pinned Alpine build on arm64) and deterministic .tar.gz/.deb packages. See Reproducible builds.
• ZIP-317 fees, ZIP-315 confirmations. Fees follow the deterministic ZIP 317 formula and are never client-settable (explicit fee parameters are rejected with -8). Spendability follows ZIP 315's defaults (3 confirmations for the wallet's own change and transactions, 10 for third-party payments), configurable via [spend]. See Sending.

What zecd is not

• Not zcashd-RPC-compatible. zecd is intentionally not a zcashd clone: it does not implement zcashd's z_* surface except a small chosen subset (z_sendmany plus the operation-tracking trio, z_shieldcoinbase, z_mergetoaddress, z_listtransactions, z_getaddressforaccount, z_validateaddress, z_listunifiedreceivers). Migrating an integration is a concept mapping, not a drop-in; see Migrating from zcashd.
• No P2P. zecd never speaks the Zcash peer-to-peer protocol; Zebra is its only upstream, and getpeerinfo reports at most that one connection.
• Not a chain indexer. It tracks a single account per wallet, not arbitrary addresses or xpub derivation schemes, and holds no full-block or address index of its own.
• No per-address key import. Every address derives from the wallet seed (diversified addresses of one ZIP-32 account); there is no importprivkey/importaddress, and the only import path is a whole account via seed restore or UFVK.

Where to go next

• First run: the Quickstart takes you from a Zebra node to a funded wallet answering RPC; the Configuration reference covers every TOML key and CLI flag.
• Coming from zcashd: Migrating from zcashd.
• Building an integration: RPC conventions & wire format, then the method index for the full method-by-method comparison with bitcoind and zcashd.
• Driving it from Rust: Using zecd as a library, for callers who would rather not put an HTTP socket between their process and the wallet.
• Running it in production: Deployment (Docker, .deb/systemd, release binaries) and the Operations runbook (backup/restore, monitoring, health endpoints).
• Understanding the design: Architecture, Stateless & recoverable, the privacy policy ladder, and the threat model.
• Edges and gaps: the compatibility boundary and known limitations.

Quickstart

From zero to a first RPC call: point a local Zebra node's JSON-RPC at zecd, build the binary, initialize a wallet, run the daemon, and talk to it with any Bitcoin RPC client. The Docker compose route at the end does the same with one stack file.

Prerequisites: a local zebrad

zecd is a wallet server: it holds keys and scans compact blocks, but its entire view of the chain comes from a self-hosted Zebra full node's JSON-RPC. Run one on the same host (or private network) and let it sync before starting zecd.

Zebra ships with its RPC endpoint disabled. Enable it in zebrad.toml on the port zecd's default backend expects:

[rpc]
# The port zecd's default `server = "zebra"` dials:
#   mainnet  ->  zebra://127.0.0.1:8234
#   testnet  ->  zebra://127.0.0.1:18234
listen_addr = "127.0.0.1:8234"      # testnet: "127.0.0.1:18234"

Any explicit [backend] server = "zebra://host:port" works too if you prefer a different port or a co-located container host; see Configuration. If zebrad's cookie authentication is enabled, point zecd at the cookie (or set user/password) in the [zebra] config section; with enable_cookie_auth = false on a loopback-only listener, no credentials are needed. The connection is plaintext HTTP and deliberately local-only: never expose a Zebra RPC port publicly (see the Zebra backend for the cleartext-credential gate).

Two port families are in play: 8234/18234 are Zebra's RPC (what zecd dials), while 8232/18232 are zecd's own RPC defaults (what your clients dial), mirroring bitcoind's 8332/18332 convention.

Install

Four ways to get a binary, in rough order of convenience:

cargo install zecd                  # from crates.io

The release tarballs and .deb packages are prebuilt, reproducible static binaries for amd64 and arm64, and the Docker stack below brings up zecd and Zebra together. Building from source (including cargo install) needs Rust 1.91 or later since 0.8.0:

git clone https://github.com/zecrocks/zecd && cd zecd
cargo build --release --bin zecd

Always use --release: a debug build takes more than 20 seconds to prove a single shielded send. The same applies to cargo install, which builds in release mode by default.

Release candidates are opt-in. cargo install zecd resolves to the newest stable release, so a pre-release has to be asked for by name (cargo install zecd --version 0.9.0-rc1). The same holds for a dependency: a zecd = "0.8" requirement will not pick up a -rc.

Check the node is reachable

Before creating anything, confirm zecd can reach the node and agrees with it about which chain this is:

./target/release/zecd --testnet chain-info

It prints the upstream's tip, the chain name, and the birthday a wallet created now would get, and exits non-zero exactly when a wallet created here would not sync: wrong chain, or a consensus upgrade already active that this build does not know. It opens no wallet and writes nothing, so it is also the right probe against a live deployment later. See Probing the chain without a wallet.

Initialize a wallet

zecd init creates the wallet and exits. It needs the zebrad from the previous step reachable (a new wallet's birthday defaults to just below the current chain tip, which init fetches from the node).

# Testnet (drop --testnet for mainnet):
./target/release/zecd --datadir ./data --testnet init --wallet default

This generates three things:

• An age identity at <datadir>/identity.txt (mode 0600), the key that encrypts the wallet seed at rest so the daemon can send unattended.
• A 24-word mnemonic seed phrase, printed to stdout exactly once. Back it up now. It is the only way to recover the wallet: shielded funds are unconditionally recoverable from it on any librustzcash wallet; the on-disk data directory is a rebuildable cache (see Stateless & recoverable).
• The wallet account in <datadir>/default/zec/lrz/data.sqlite, plus keys.toml at <datadir>/default/ holding the age-encrypted mnemonic. (Wallets created before 0.7.0 kept the database flat beside keys.toml and are moved into place automatically on first start; see wallet data layout.)

Variants (see Key custody for the trade-offs):

zecd --datadir ./data --testnet init --restore                  # restore from an existing mnemonic
zecd --datadir ./data --testnet init --restore --birthday 2500000  # much faster: scan from a known height
zecd --datadir ./data --testnet init --encrypt                  # passphrase-encrypted (Bitcoin Core style,
                                                                #   starts locked; unlock via walletpassphrase)
zecd --datadir ./data --testnet init --ufvk "uview1..."         # watch-only wallet from a viewing key

A restore without --birthday scans from the earliest enabled pool's activation height, which is safe but slow; pass any height at or before the wallet's first transaction. For watch-only setups see Watch-only wallets.

Run the daemon

./target/release/zecd --datadir ./data --testnet \
    --rpcuser zec --rpcpassword secret --rpcbind 127.0.0.1 --rpcport 18232

The daemon syncs compact blocks in the background and serves JSON-RPC immediately; balances and history fill in as the scan catches up. Default RPC ports are 8232 (mainnet) and 18232 (testnet). CLI flags override the TOML config (default <datadir>/zecd.toml); --rpcpassword can also come from the ZECD_RPC_PASSWORD environment variable, and bitcoind-style salted credentials from --rpcauth (generate one with zecd rpcauth <user>). The full flag and config reference is in Configuration.

The steps above pass everything on the command line, so no config file is needed to get started. For a persistent setup, have zecd write you a commented one to edit:

zecd example-config -o ./data/zecd.toml

It refuses to overwrite an existing file unless you pass --force, so it is safe to run against a live deployment's datadir.

On mainnet, zecd refuses to start while [rpc] password is still the example placeholder CHANGE-ME.

Talk to it

Exactly like bitcoind (HTTP Basic auth, JSON-RPC 1.0 envelope):

curl -s --user zec:secret --data-binary \
  '{"jsonrpc":"1.0","id":"1","method":"getblockchaininfo","params":[]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18232/

Or with python-bitcoinrpc, unchanged:

from bitcoinrpc.authproxy import AuthServiceProxy

rpc = AuthServiceProxy("http://zec:secret@127.0.0.1:18232")
print(rpc.getblockchaininfo())
addr = rpc.getnewaddress()          # a u1.../utest1... Orchard Unified Address
print(rpc.getbalance())
print(rpc.listtransactions("*", 20))

Two things to know: getnewaddress returns a shielded Unified Address, and a label argument is rejected with -8 because zecd keeps no labels (see Addresses & shielded pools and Stateless & recoverable). Wire-format details (envelope, batching, error codes, multiwallet routing) are in the RPC conventions.

Cookie auth

If you set neither --rpcuser/--rpcpassword nor [rpc] user/password, zecd writes a bitcoind-style cookie file to <datadir>/.cookie (mode 0600, regenerated with a fresh random password on each start) and authenticates against it:

curl -s --user "$(cat ./data/.cookie)" --data-binary \
  '{"jsonrpc":"1.0","id":"1","method":"getblockcount","params":[]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18232/

The cookie's user is the fixed __cookie__, as in bitcoind.

Docker compose quickstart

deploy/docker-compose.yml runs the full self-hosted stack (Zebra and zecd on one private compose network), on testnet by default:

cd deploy
docker compose up -d zebra                        # start the node; let it sync first
docker compose run --rm zecd init --wallet default   # back up the printed mnemonic!
docker compose up -d                              # start zecd
curl localhost:9233/readyz                        # health probe (see guide/operations.md)
curl --user zec:CHANGE-ME --data-binary \
  '{"method":"getblockchaininfo","id":1}' localhost:18232/

For mainnet, add -f docker-compose.mainnet.yml to every command; the overlay swaps each service onto its mainnet config file (zebrad.mainnet.toml, zecd.mainnet.toml) while keeping the ports and volumes identical:

docker compose -f docker-compose.yml -f docker-compose.mainnet.yml up -d zebra
docker compose -f docker-compose.yml -f docker-compose.mainnet.yml run --rm zecd init --wallet default
docker compose -f docker-compose.yml -f docker-compose.mainnet.yml up -d

Before a mainnet deployment, set a real [rpc] password in deploy/zecd.mainnet.toml (zecd refuses to start on mainnet with the shipped CHANGE-ME), and pin the Zebra image tag to a release you have verified. The compose file publishes zecd's RPC (18232 on both networks, to keep the mapping identical) and health (9233) ports on loopback only: RPC credentials are spend authority over plaintext HTTP, so front them with TLS or a network policy before serving other hosts. The image build, ARM variant, and .deb/systemd routes are covered in Deployment.

Ironwood (NU6.3)

Ironwood is compiled in unconditionally: there is no build flag and no [pools] entry. zecd activates it from consensus height alone, and NU6.3 is now active on both networks, at mainnet height 3428143 and testnet height 4134000. A wallet whose shielded funds were received after that point holds ironwood notes. Regtest opts in via the ZECD_REGTEST_NU63_HEIGHT environment variable.

Running it needs an ironwood-capable node; Zebra activates Ironwood at the network's activation height, and the compose stack pins zfnd/zebra:6.3.0.

Ironwood notes are received at ordinary Orchard addresses. Upstream models them as Orchard "V3" notes that reuse Orchard's keys, addresses, and note cryptography, so there is no ironwood receiver to request and nothing to enable in [pools]. What differs is the note's transaction bundle. Received notes report pool == "ironwood" in getbalance, listtransactions, and gettransaction. Sends ride the cached proving key like any other shielded send, so there is no per-send proving penalty.

Because ironwood is a distinct value pool rather than a flavour of Orchard, an ironwood-to-Sapling or ironwood-to-Orchard send is a turnstile crossing that reveals its amount on chain, and FullPrivacy rejects it. See the privacy policy ladder.

NU7

NU7 activates on testnet at block 4,465,026. Mainnet has no NU7 height yet.

Support for it is in 0.9.0-rc1, a release candidate. From that block, transactions commit to the NU7 consensus branch id and keep the V6 format NU6.3 introduced. 0.8.1 and older build transactions that upgraded testnet nodes reject, so a testnet deployment needs 0.9.0-rc1 (or later) before that height, and a node that activates NU7 there. Like NU6.3, it is compiled in and activated by height; there is no flag. Mainnet deployments can stay on 0.8.1.

The 0.9.0-rc1 wallet database cannot be reopened by 0.8.1, so copy the data directory before upgrading if you might go back. See Upgrades.

Regtest opts in with ZECD_REGTEST_NU7_HEIGHT, which must be above ZECD_REGTEST_NU63_HEIGHT (zecd refuses to start otherwise: network upgrades activate in order).

Where to go next

• Configuration: every TOML section and key, CLI flags, environment variables (pools, privacy policy, confirmations, health probes).
• Deployment: reproducible images, release binaries, systemd, Kubernetes probes.
• Operations runbook: backup/restore, monitoring, /healthz /readyz /status, upgrades, failure modes.
• RPC reference: the wire format and the full method reference.

Configuration

zecd is configured by a TOML file plus Bitcoin-Core-style CLI flags and a handful of environment variables. This page is the complete reference: every TOML section and key with its type, default, and semantics, plus the CLI flags and environment variables.

For a fully commented starting point, ask the binary for one:

zecd example-config > ./data/zecd.toml

zecd example-config prints the annotated zecd.example.toml that ships with zecd, so you do not need a source checkout to get it: it works the same from a release tarball, a .deb, or a container. See Subcommands for --output-file and --force.

File location and precedence

The config file is <datadir>/zecd.toml, overridable with --conf <FILE>. Like bitcoind, the file is located before its own datadir key can apply: the lookup uses only the --datadir flag and the ZECD_DATADIR environment variable, never a datadir set inside the file. If the file does not exist, built-in defaults apply.

Unknown keys anywhere in the file are a startup error (fail-fast), not a silent ignore: a typo cannot quietly disable a setting.

General precedence, highest first:

1. CLI flag (some flags read an environment variable as a fallback; see Environment variables)
2. TOML key
3. Built-in default

Per-key exceptions are noted inline below (the RPC password has a three-way precedence; rpcauth entries accumulate rather than override; per-wallet keys override global [pools] keys).

Top-level keys

The default network is testnet; mainnet must be selected explicitly. On mainnet, zecd additionally refuses to start while [rpc] password is still the example placeholder change-me (case-insensitive), since the RPC password is spend authority.

[wallets.<name>]

One section per wallet; each wallet is an independent seed, SQLite database, and directory, served at /wallet/<name>. If no wallet section is declared, an implicit entry for default_wallet is created at <datadir>/<name>. Every [pools] key can be overridden per wallet here.

Per-wallet backend overrides (0.7.0). [backend] used to be daemon-global, so every wallet in a process dialled the same upstream. These keys, written directly in the wallet's own section, override it:

Only the settings that describe which upstream this wallet dials, and the TLS trust that authenticates it, are overridable. Fallback is field by field, so a wallet overriding only server keeps every global TLS setting. Deployment policy stays global and is deliberately not listed above: timeouts, reconnect backoff, the cleartext-locality rules, and the [zebra] credentials are properties of the deployment rather than of one endpoint.

One daemon can therefore serve a zebra-backed spending wallet beside a lightwalletd-backed watch-only replica of the same seed. Existing configurations resolve exactly as before, and a wallet with no overrides emits no backend keys from config show.

At most one loaded wallet may hold spending keys; any number of watch-only (UFVK) wallets may run alongside it; see Watch-only wallets. For thousands of watch-only wallets, see Fleet.

[fleet]

New in 0.8.0, experimental, off by default. Monitoring many watch-only wallets in one daemon, sharing shard databases. The keys are described with the feature in Fleet: enabled (false), manifest_dir (<datadir>/fleet/zec/wallets.d), dir (<datadir>/fleet/zec/shards), shard_size (128) and cohort_depth (10000). They may change in a patch release while the fleet is experimental. fleet is a reserved wallet name.

[backend]

The chain upstream: a single node, either a self-hosted Zebra's JSON-RPC (the default and the recommendation) or, since 0.6.0, a lightwalletd gRPC server. The server token picks which, so read its row below before changing it. See Chain backends for the deployment model, the trade-off between the two, and the cleartext-credential gate.

The remaining keys apply only when server names a lightwalletd endpoint (0.6.x and later); a zebra:// upstream ignores them. See Chain backends.

[zebra]

Credentials for the zebrad endpoint. Omit the whole section when zebrad runs with enable_cookie_auth = false. A cookie file wins over user/password; nothing set means no authentication.

[rpc]

zecd's own JSON-RPC server (the Bitcoin-Core-dialect surface; see Conventions & wire format).

[keys]

Seed custody and unlock behavior. See Key custody for the two at-rest custody models (age identity vs. passphrase).

[pools]

Global defaults for which value pools each wallet uses; every key here can be overridden per wallet in [wallets.<name>]. See Addresses & shielded pools and Transparent support.

[sync]

[spend]

Send policy: confirmations, privacy, and the proving pipeline. See Privacy policy for the five-rung ladder and its enforcement points.

[health]

Unauthenticated liveness/readiness probes on a separate port; see the operations runbook.

[log]

CLI flags

Flags use Bitcoin-Core-style names and always win over the corresponding TOML key.

Subcommands

Running zecd with no subcommand (or zecd run) starts the daemon.

Every flag in the table above is global: it is accepted on either side of the subcommand, so zecd --conf /etc/zecd.toml config check and zecd config check --conf /etc/zecd.toml are the same command. (Before 0.6.0 the flags had to precede the subcommand, which made zecd config check --conf FILE - the way anyone would naturally write it - a usage error.)

init, export-ufvk, rescan, derive-address, chain-info and the config group honor the datadir/network/keys flags; the RPC flags are inert for them. rpcauth, example-config and licenses run before config resolution and ignore all of them, so they work when there is no config file yet.

Reloading on SIGHUP

Since 0.8.0 a running daemon re-reads its configuration on SIGHUP and applies two keys: [spend] orchard_action_limit and [spend] max_tx_bytes. Both bound what one send may build, and a wallet whose notes have fragmented can fail every payout until the cap moves, so restarting a live payment wallet to change a number would be the wrong cost. Every other changed key is logged as needing a restart rather than silently ignored or half-applied. There is deliberately no RPC for this: the caps bound what a single call can make the daemon prove, so raising them takes access to the process.

systemctl kill -s HUP zecd        # or: kill -HUP <pid>, docker kill -s HUP <container>

Validating a config

zecd config check --conf FILE answers "would this build accept this config?" without starting the daemon.

The question is not hypothetical: zecd rejects unknown config keys, which is what keeps a typo'd knob from being silently ignored, but it also means a config valid for one build can be refused by another in either direction - an upgrade may not know a key yet, a rollback may have dropped one. Before 0.6.0 the only way to find out was to start the daemon on the target host.

Two properties are structural rather than promised:

• It reaches the daemon's verdict, not a second opinion. Every check is either the config resolver itself or a helper the daemon calls at startup, so the two cannot drift.
• It changes nothing. No datadir lock (so it runs against a live deployment), no wallet database, and no cookie file - minting one would invalidate the credential a running daemon already handed out.

Errors mean "the daemon would refuse, or would start and never sync". Warnings cover the legal-but-risky shapes: an uninitialized wallet, a transparent_gap_limit wide enough to stall restores, a bare RPC password on a non-loopback bind. Since 0.8.0 they also cover:

• [sync] batch_size above 50,000, enhance_concurrency above 64, and a writer_cache_mib whose total across writer connections passes 2 GiB;
• an orchard_action_limit that max_tx_bytes will always bind first, and a shutdown_drain_secs longer than common supervisors' stop timeouts;
• a proxy combined with a loopback upstream, which the proxy would read as its own loopback;
• default_receivers with several receivers, whose addresses history will not report verbatim;
• fleet manifests present while [fleet] enabled is false, a wallet directory overlapping the fleet's, and the fleet's experimental status when it is on (see Fleet).

--strict fails on warnings too; -q reports through the exit code alone.

A missing config file is an error here, unlike at startup where a missing file falls back to defaults: checking a file that is not there is a typo, and silently validating the defaults would confirm nothing.

zecd config check --conf /etc/zecd/zecd.toml || exit 1     # CI gate
zecd config check --conf /etc/zecd/zecd.toml --strict       # also fail on warnings

stdout carries settings, stderr carries the verdict - the nginx -t / nginx -T split. That is what makes the diff below a diff of configuration and nothing else:

diff <(zecd-old config show --conf zecd.toml 2>/dev/null) \
     <(zecd-new config show --conf zecd.toml 2>/dev/null)

config show is the sshd -T to config check's sshd -t: it prints the effective configuration - the file, CLI flags and environment resolved together, with every unset key filled in by this build's default - as TOML. That is what an operator actually needs before an upgrade, because a config file is only half the configuration and defaults move between versions. Capturing it pins today's behaviour as an explicit file before taking the upgrade:

zecd-old config show --conf zecd.toml > effective.toml

The output re-parses: a round-trip test feeds it back through the resolver and requires an identical second render, so a renderer that drifts from the schema fails a test rather than emitting a config zecd would itself reject. Secrets - the RPC password, rpcauth hashes, [zebra] credentials - are emitted as commented-out key names, never values, since this output is the kind of thing that gets pasted into a bug report. They are commented rather than redacted-in-place because a placeholder that parses would silently become a real, wrong credential if the file were deployed, where an absent password falls back to cookie auth and fails loudly. The cost is that a secret-bearing config does not round-trip byte for byte.

Unlike check, a missing config file is fine for show: "what would this binary do with no config" is well defined, and is the quickest way to see the built-in defaults.

Probing the chain without a wallet

New in 0.7.0. zecd chain-info dials the configured upstream and reports its tip.

Before it, the chain tip was unreachable without a wallet: config check is deliberately offline, and the daemon needs a wallet to start, so both "what height is the chain at?" and "can this deployment reach its backend?" meant creating a wallet first.

$ zecd chain-info --conf /etc/zecd/zecd.toml
server            zebra://127.0.0.1:8234
network           main
chain             main
tip height        3512847
tip hash          0000000000d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f80912
birthday for new  3512747
branch id         c8e71055
round trip        14 ms
OK: reachable, chain matches, consensus rules understood

The summary goes to stdout and the verdict to stderr, so the two can be separated in a script. --json emits an object instead, with network_matches, suggested_birthday, branch_id and an unsupported_upgrades array.

It exits non-zero exactly when a wallet created there would not sync, which is what makes it usable as a deployment gate:

birthday for new is the birthday zecd init would record for a wallet created right now, and it comes from the same function init itself calls, so the two cannot drift apart. Record it alongside a mnemonic you generated yourself.

--server <TOKEN> probes a candidate endpoint instead of [backend] server, using the same token grammar, so a new upstream can be tested before it is committed to a config file. The override is applied by re-resolving the configuration with the token swapped, which means the candidate carries the same [zebra] credentials, TLS settings and cleartext policy the daemon would give it. What is probed is what a daemon on that token would dial, including the no-network refusals: an endpoint this build would never dial fails here for that reason rather than as a connection timeout.

Read-only, like config check: no datadir lock, no wallet database, no cookie file. It is safe to run against a live deployment.

Third-party licenses

New in 0.7.0. zecd licenses prints the license texts of every third-party crate compiled into the binary.

zecd links its dependencies statically, so those crates travel inside the shipped binary, and most of the licenses in the tree require the text and copyright notice to be reproduced when they do. The same text ships as THIRD-PARTY-LICENSES.txt in the release tarball, in the Debian package, and in both container images under /usr/share/doc/zecd/.

zecd licenses | less
zecd licenses > THIRD-PARTY-LICENSES.txt

The container images are built FROM scratch and have no shell, so this subcommand is the one place the notices are readable wherever zecd runs. It needs no datadir and no config file.

The bundle is generated from the lockfile at release time and covers a few hundred crates, so expect a few hundred kilobytes of output. Piping it into a pager that exits early is fine.

Offline address derivation

zecd derive-address answers "what address will this wallet hand out?" before the wallet has a chain.

zecd init needs a live upstream (it anchors the account on the tree state at birthday - 1) and getnewaddress needs a running daemon, so until 0.6.0 there was no way to learn an address first. That is a chicken-and-egg for pre-provisioning deposit addresses, air-gapped and cold setup, pointing a miner at a wallet that does not exist yet, and checking that a keys.toml derives the addresses you expect before trusting it.

It touches no network, no wallet database and no daemon, and takes no datadir lock (like export-ufvk), so it runs safely beside a live daemon.

Key sources, in the order it tries them:

--index and --count derive a batch at consecutive indices (default: one address at index 0). --address-type reuses the same syntax and the same parsing code as getnewaddress's address_type, so the CLI and the RPC cannot drift, and it defaults to what that wallet's getnewaddress would hand out. For a bare t-address the index is the BIP 44 external child index - the same index the daemon exposes and the same one z_getaddressforaccount takes.

stdout is exactly the addresses, one per line, so it pipes; --json reports the derivation key and indices alongside them.

# Ten deposit addresses, before the daemon exists.
zecd derive-address --address-type transparent --index 0 --count 10

# Check a keys.toml derives what you expect, from the mnemonic in your safe.
ZECD_MNEMONIC="$(cat /mnt/secure/phrase)" zecd derive-address --mnemonic --json

What it deliberately cannot reproduce is getnewaddress's next shielded address: those diversifier indices are clock-derived, so only an explicit index is deterministic - which is what an offline caller wants anyway.

Environment variables

Minimal example

A testnet daemon against a local zebrad with cookie auth on both hops:

network = "test"
datadir = "./data"

[backend]
server = "zebra"          # zebra://127.0.0.1:18234 on testnet

[zebra]
rpc_cookie = "/var/lib/zebrad/.cookie"

# No [rpc] user/password: zecd writes its own cookie to ./data/.cookie,
# and local clients authenticate with it like bitcoin-cli does.

Migrating from zcashd

This page maps zcashd concepts and RPC methods onto zecd, and walks through the one supported way to move funds. It is written for teams whose integration code speaks zcashd's RPC today and who are replacing it with a zebra → zecd stack.

Philosophy: a Bitcoin Core dialect, not a zcashd clone

zecd is deliberately not zcashd-RPC-compatible. Instead of re-implementing zcashd's z_* surface, it speaks Bitcoin Core's JSON-RPC dialect (the same method names, response shapes, JSON-RPC 1.0 envelope, HTTP Basic/cookie auth, and error codes as bitcoind) and maps those onto shielded (Orchard-first) operations. The bet is that far more tooling, client libraries, and operational muscle memory exist for Bitcoin Core RPC than for zcashd's wallet API, and that zcashd's own trajectory pointed the same way: current zcashd already deprecates getnewaddress, z_getnewaddress, z_getbalance, and z_listaddresses (denied by default under -allowdeprecated), so "keep calling zcashd methods forever" was never on offer.

zecd keeps a small, deliberately chosen z_* subset where Bitcoin Core has no counterpart for a shielded concept:

• z_sendmany plus the operation-tracking trio z_getoperationstatus / z_getoperationresult / z_listoperationids: zcashd's asynchronous send pattern, kept so opid-based client code keeps working.
• z_listtransactions: per-output history with pool, memo / memoStr, and zatoshi amounts.
• z_getaddressforaccount: deterministic diversified-address derivation at a chosen diversifier index.

Everything else is the bitcoind method under the bitcoind name. The full per-method matrix is in the method index; the boundary itself (what zecd promises to match and where it intentionally diverges) is in Compatibility boundary.

Concept mapping

RPC mapping

For each commonly used zcashd wallet RPC, the zecd equivalent, or the supported alternative where there is none. Methods not listed here (and not in the method index) return method-not-found (-32601, HTTP 404).

Addresses and accounts

Balances

History and unspent

Sending

Keys, backup, and wallet management

Migrating funds

The only supported migration path is an on-chain send from zcashd to an address generated by zecd. There is no key or wallet import, by design: zecd's statelessness and restore guarantees hold only for addresses derived from its own seed.

1. Set up the target: a synced Zebra node, then zecd init (record the mnemonic offline) and start the daemon; see the Quickstart.

2. On zecd, generate a receiving address:

   curl -u user:pass --data-binary \
     '{"jsonrpc":"1.0","id":"m","method":"getnewaddress","params":[]}' \
     http://127.0.0.1:8232/
   

   The result is a Unified Address (u1...).

3. On zcashd, send everything to that UA with z_sendmany. Note zcashd's default privacyPolicy is LegacyCompat, which treats any transaction involving a UA as FullPrivacy, so spending zcashd's transparent funds to zecd's UA fails under the default; pass "AllowRevealedSenders" (this reveals the sending transparent addresses and amounts on-chain). Shielded Sapling funds crossing into Orchard need "AllowRevealedAmounts" (reveals only the amount crossing the pool turnstile).

4. Wait for confirmations, then verify on zecd with getbalance / listtransactions. Remember zecd's spendability policy defaults to 3 confirmations for your own transactions and 10 for third-party ones.

Two seed-related cautions:

• Do not share a seed phrase between apps: do not restore zcashd's mnemonic into zecd or vice versa. zecd's restore guarantees hold only for wallets its own init created.
• As a deliberate escape hatch, a zecd seed phrase works in any other librustzcash-based wallet (for example Zodl): if something goes badly wrong with zecd, funds remain accessible elsewhere. Shielded funds are unconditionally recoverable from seed; transparent funds only within the configured gap-limit / initial-scan window; see Stateless & recoverable.

Operational differences

• You run two processes, not one. zecd needs a self-hosted Zebra node reachable over local/private JSON-RPC (zebra://...; plaintext HTTP guarded by a cleartext-credential gate). Everything zecd believes about the chain comes from that node. See Chain backends and Deployment.
• Light-client sync. zecd derives compact blocks from the node and trial-decrypts them; it keeps no chain index. After a restore, an enhancement backlog (re-fetching full transactions to backfill memos and outgoing details) can keep the wallet in initialblockdownload/scanning state after the block scan reaches the tip. Watch getwalletinfo.scanning and the /readyz health endpoint (Operations runbook).
• Sends take a few seconds. Every shielded send builds a zero-knowledge proof, so sendtoaddress/sendmany hold the HTTP connection for a few seconds; raise client timeouts accordingly. z_sendmany keeps zcashd's asynchronous pattern (returns an opid immediately) if you prefer not to block.
• Sends serialize per wallet. A single-writer actor owns each wallet, so concurrent sends to one wallet queue rather than double-spend (Architecture).
• Multiwallet is bitcoind-style (/wallet/<name> routing), with at most one spending wallet per daemon plus any number of watch-only wallets.
• No P2P, mining, or chain-index RPC: those live on the Zebra node.

Client code changes checklist

For code that drives zcashd today:

1. Endpoint: point the client at zecd (default port 8232 mainnet / 18232 testnet), with /wallet/<name> paths if you configure multiple wallets. Auth is HTTP Basic or cookie, bitcoind-style.
2. Addresses: replace z_getnewaccount + z_getaddressforaccount (or z_getnewaddress) with getnewaddress; expect a UA. Drop any label arguments: getnewaddress rejects them with -8, and the label methods are gone (-32601).
3. Balances: replace z_gettotalbalance / z_getbalanceforaccount with getbalance / getbalances. Keep parsing amounts as exact decimals (e.g. Python Decimal): they are bare JSON numbers with 8 decimal places, never floats.
4. Fees: delete every fee argument. Pass null (or omit) for z_sendmany's fee; an explicit number is -8. Remove settxfee, subtractfeefromamount, and fee_rate usage.
5. Error handling: re-check any hard-coded error numbers against Bitcoin Core's rpc/protocol.h. The money-path codes are unchanged; the notable collision is -18 (zcashd "backup required" vs zecd/Core "wallet not found").
6. Async sends: opid flows keep working, but budget for the per-wallet cap of 16 unfinished operations (-4 beyond it) and remember z_getoperationresult consumes each result exactly once.
7. Timeouts: raise HTTP client timeouts for sendtoaddress / sendmany (proving takes seconds).
8. Confirmation assumptions: zecd's default spend policy is ZIP-315 (3 trusted / 10 untrusted) rather than a flat minconf=10; pass minconf explicitly where your logic depends on it.
9. Removed surface: audit for calls to key import/export, wallet export, migration, and label RPCs; replace with the alternatives in the mapping table or remove. z_shieldcoinbase carries over unchanged apart from the fee argument, and so does z_mergetoaddress apart from the fee argument and the one-source-class-per-call rule.

Addresses & shielded pools

How zecd generates and interprets addresses: one ZIP-32 account per wallet, fresh diversified Unified Addresses from getnewaddress, the [pools] configuration that controls which receivers those addresses carry, and the address behaviors that follow from zecd's stateless design.

One account, many diversified addresses

Each zecd wallet holds a single ZIP-32 account (m/32'/coin_type'/account'). getnewaddress returns a fresh Unified Address (u1... on mainnet, utest1... on testnet) on every call, but these are diversified addresses of the same account, not new derivation paths: each is a different diversifier index of the account's keys. librustzcash advances to the next unused diversifier and persists the cursor, so every call yields a new, unused address, and all of them receive into the same account and are spendable by the same key (ZIP-316 + ZIP-32 diversification).

Practical consequences:

• Handing out a distinct address per counterparty costs nothing and needs no key management: there is no keypool to top up.
• Every address a wallet ever issued is owned by its one account. getaddressinfo.ismine recognizes even an issued-but-never-recorded address cryptographically, by attributing it to the account's incoming viewing key (see getaddressinfo).
• "Multiple accounts" in zecd means multiple wallets; see the multiwallet routing in the RPC overview.

Configuring pools: [pools]

zecd is shielded-first. Each wallet declares which shielded pools it uses and which receivers its Unified Addresses include, via the global [pools] section and/or a per-wallet [wallets.<name>] override:

[pools]
enabled = ["sapling", "orchard"]            # pools the wallet receives into and spends from
default_receivers = ["sapling", "orchard"]  # receivers in the UAs getnewaddress hands out

• Supported shielded pools are sapling and orchard. Ironwood (NU6.3) is not a third name here, now or later: upstream models ironwood notes as Orchard "V3" notes that reuse Orchard's keys, addresses, and note cryptography, so there is no ironwood receiver typecode to request or enable. Ironwood notes are received at ordinary Orchard addresses; the distinction lives at the transaction-bundle level, and surfaces as pool == "ironwood" in balances and history once NU6.3 activates. See Ironwood (NU6.3).
• The default ([pools] omitted entirely) is Orchard-only.
• default_receivers must be a subset of enabled; naming a disabled pool is a startup error. default_receivers omitted defaults to enabled.
• Transparent receiving is not a pool in this list. It is a separate opt-in capability flag (transparent = true) layered on top. See Transparent support.

Balances, listunspent, and the history RPCs always report across every supported pool, not just the enabled ones (the scan trial-decrypts all pools, so funds in a since-disabled pool still show).

address_type: the per-call receiver override

getnewaddress's second argument (Bitcoin Core's address_type position) selects which receivers the returned address carries, constrained to the wallet's enabled pools:

Rejections:

The token syntax (-5 cases) is validated before wallet resolution; enablement (-8 cases) is per-wallet. Full parameter/response reference: getnewaddress and, for zcashd-style fixed-index derivation, z_getaddressforaccount (shielded receivers only; p2pkh is rejected -8 there).

Change and spending

• Change from a shielded send goes to the strongest enabled pool: Orchard if enabled, otherwise the first enabled pool (i.e. Sapling for a Sapling-only wallet).
• Inputs are spent from any enabled pool.
• Recipients can be any address type: a transparent or Sapling recipient is payable from Orchard funds under the default privacy policy. What a send is allowed to reveal is governed by the privacy policy ladder, not by [pools].

Keys always derive all pools

The [pools] config is address-generation and spend policy only. The wallet's spending key (USK) and viewing key (UFVK) always derive key material for all pools regardless of configuration. Two consequences:

• Enabling a pool later (e.g. adding sapling to an Orchard-only wallet) requires no key migration; the wallet starts issuing addresses with the new receiver.
• A watch-only wallet imported from an exported UFVK can derive addresses for any pool the spending wallet could.

Same-seed instances do not hand out identical address sequences

Shielded diversifier indexes are clock-derived: for shielded address requests, zcash_client_sqlite starts the index at the current Unix time (plus a fixed offset) and increments past collisions. So two instances of the same key material (a restored wallet, a watch-only UFVK pair, two same-seed daemons) hand out the same address only if they happen to call getnewaddress within the same second.

This is harmless (every address either instance issues belongs to the same account, and funds sent to any of them are found by both), but do not build anything that assumes cross-instance getnewaddress equality. If you need a deterministic address, derive it at a fixed diversifier index with z_getaddressforaccount, which re-derives the exact same address for the same index and receiver set on any instance.

(Transparent addresses are the exception: the transparent chain is sequential, not clock-derived; see Transparent support.)

Outgoing history shows the single receiver actually paid

When you pay a multi-receiver UA, exactly one receiver is paid on-chain (the pool the transaction selected). The full UA you typed is sender-side metadata that never reaches the chain: the authoring instance could cache it, but a restore-from-seed recovers only the single receiver actually paid. To keep history deterministic across a restore, zecd's history RPCs (listtransactions, gettransaction.details, listsinceblock, z_listtransactions) always report an outgoing recipient as that single paid receiver:

• a bare t... or zs... address for a transparent or Sapling payment, or
• a single-receiver UA for an Orchard payment (Orchard has no standalone encoding).

The reduction is idempotent (a bare or single-receiver address reports as itself). Since 0.8.0 it applies to incoming outputs too, so a payer and a payee print the same string for one output. Under the default Orchard-only default_receivers that is the same string getnewaddress handed out; a wallet configured for several receivers sees the single receiver paid instead, and zecd warns about that configuration at startup and in config check. This is the stateless counterpart of zcashd's persisted recipient mapping, which echoes the typed UA on the authoring instance but degrades to the single receiver after a restore anyway. To match a receipt back to an address you issued, use the integer rather than the string: received entries carry diversifier_index, which every encoding of that address shares, and z_listunifiedreceivers splits a UA into the receiver strings history reports. See also the history RPCs.

Transparent support

Transparent (t-address) receiving and spending is off by default: a zecd wallet is shielded-only until you opt in.

An additive capability, not a mode

Transparent support is a separate per-wallet flag, not a member of the [pools] enabled/default_receivers lists (those stay shielded-only; see Addresses & shielded pools). Setting transparent = true adds the ability to hand out (and, with a further opt-in, spend from) bare transparent addresses alongside whatever shielded pools the wallet uses. A wallet can be Orchard-only plus transparent, Sapling+Orchard plus transparent, and so on.

[pools]
enabled = ["orchard"]           # shielded pools; transparent is NOT listed here
default_receivers = ["orchard"]
transparent = true              # allow bare t-addresses (receive; opt-in spend)
transparent_default = false     # true: no-arg getnewaddress returns a t-address instead of a UA
# transparent_gap_limit = 20                        # restore-recovery window (see below)
# transparent_initial_scan = 0                      # pre-expose external indices 0..N (see below)
# transparent_allow_beyond_recovery_window = true   # issue past the window (warn) vs fail closed
# transparent_gap_warn_threshold = 5                # warn when this few in-window slots remain

All of these can also be set per wallet in [wallets.<name>]; see the configuration reference. transparent_default = true requires transparent = true (a startup error otherwise).

Getting a transparent address

With transparent = true:

curl -s --user "$RPCUSER:$RPCPASS" --data-binary \
  '{"jsonrpc":"1.0","id":"doc","method":"getnewaddress","params":["","transparent"]}' \
  http://127.0.0.1:8232/
# {"result":"t1...","error":null,"id":"doc"}   (tm... on testnet/regtest)

The result is a bare transparent address. Each getnewaddress call yields exactly one address kind, a bare t-address or a shielded UA; a transparent receiver is never mixed into a Unified Address zecd hands out. (ZIP-316 forbids a transparent-only UA, so internally zecd derives a compliant UA carrying a p2pkh receiver and bare-encodes just the transparent receiver.) The shielded address_type forms keep working unchanged, and transparent_default = true merely flips the no-argument default. Requesting "transparent" on a wallet without the flag is rejected -8.

Transparent addresses come from the account's sequential BIP-44 external chain, unlike shielded addresses, whose diversifier indexes are clock-derived. That sequentiality is exactly what makes the gap limit below meaningful.

Asking for a specific index, and asking which index you got

New in 0.6.0. getnewaddress hands out the next address and returns a bare string, which leaves an operator reconciling an issued range against the chain without either half of the loop. Both halves now exist, and neither adds persistent state:

Deriving at an explicit index runs the same exposure path as sequential issuance, so the two agree by construction: the same recovery-horizon classification, the same warnings, the same refusal when transparent_allow_beyond_recovery_window = false would put the index out of restore range, and the same refresh of the address matcher. Directly addressing an index therefore moves the issuance frontier exactly as getnewaddress would, which is what keeps the two windows below coherent - and without the matcher refresh a payment to a directly addressed index would simply be missed.

Receive discovery: block scan + mempool matching

Compact blocks omit transparent inputs/outputs, and librustzcash's shielded scan never records transparent receives, so zecd owns transparent receive discovery and does it the way zcashd does: by scanning blocks, not by per-address node queries. zecd already fetches and parses every full block to derive compact blocks for the shielded scan (see the Zebra backend), so it matches each block's transparent outputs against an in-memory set of the wallet's exposed addresses at no extra request. The cost is O(outputs-per-block) with a constant-time set lookup, independent of how many addresses the wallet holds, so an operator tracking ~100k addresses pays no per-address cost per block.

Incoming transparent payments also show at 0-conf: the mempool poller matches each mempool transaction's transparent outputs against the same address set and records matches unmined, so a payment appears in getunconfirmedbalance / listtransactions / listunspent with minconf=0 before its first confirmation, the same as a shielded receive. Once mined it is confirmed by the block scan. Received transparent funds are reported by getbalance, listunspent, getreceivedbyaddress, and the history RPCs, and getaddressinfo reports the address as ismine.

One caveat: the block scan is forward-only and only matches outputs paying exposed addresses. A payment to an address that becomes exposed only after its funding block was scanned (out-of-order funding deep into the gap, with a small transparent_gap_limit) is missed until a from-seed rescan. transparent_initial_scan (below) is the mitigation; automatic reconciliation against the node's address index is not yet implemented.

The same pass finds spends, including ones this wallet did not author: each block's transparent inputs are tested against the outputs the wallet still holds unspent, so a spend made by another wallet on the same seed, or while this one was down, marks the output spent and records the outgoing entry. That test is bounded by the outputs held rather than the addresses issued, and costs no request of its own, since the block is already parsed for the shielded scan. Shielded spends need none of this: they are found through note nullifiers.

Spending: two ways out, both opt-in

Transparent funds leave the wallet by naming a transparent source on z_sendmany: one of the wallet's own t-addresses to spend that address's coins, or ANY_TADDR for any of them. Which rung of the privacy policy ladder you need depends on where the value lands.

Shielding (t→z), AllowRevealedSenders. With a shielded recipient, the payment and the change both land in the shielded pool. This is the way received transparent funds get shielded, and it is the direction most integrations want: the coins stop being transparent. What it reveals is the sender side, the addresses being spent and the amounts held at them, which is why it is a rung above the default rather than free.

z_sendmany "ANY_TADDR" '[{"address":"<own UA>","amount":1.0}]' null null "AllowRevealedSenders"

Fully transparent (t→t), AllowFullyTransparent. With every recipient a bare transparent address, the change is kept transparent and the transaction never touches a shielded pool. This is the most revealing kind of send (recipient, amount, funding inputs and change all public), which is why it sits on the top rung. It is also the only route for sendtoaddress/sendmany, which take no fromaddress and no per-call policy argument, so for them the config value [spend] privacy_policy = "AllowFullyTransparent" is the whole switch. zcashd's NoPrivacy maps onto the same rung.

Under the default policy (AllowRevealedRecipients) a transparent source is refused with -4, naming the rung that would allow it, and a transparent-only wallet's sendtoaddress/sendmany fails -6: those methods only ever select shielded notes. Paying to a transparent recipient from shielded funds works under the default policy, with shielded change; FullPrivacy and AllowRevealedAmounts reject transparent recipients with -8.

Transparent coinbase is never selected by either route. z_shieldcoinbase is its only spend path, because consensus forbids a transparent output in a transaction spending it.

Because librustzcash's high-level transfer API funds payments from shielded notes only and has no persistent transparent-change form, zecd builds the fully-transparent transaction itself: greedy ZIP-317-aware coin selection over the wallet's spendable transparent UTXOs, recipient plus change outputs, signed with the account's derived transparent keys, then recorded through the normal sent-transaction path (spent UTXOs are locked against double-spend and the transaction rides the rebroadcast loop).

Transparent coinbase is not selectable. Consensus requires a transaction that spends transparent coinbase to have no transparent output at all, so coin selection skips those UTXOs even once they mature: a t-to-t send cannot pay a recipient and return change from them. Mature coinbase still counts as spendable value, so it is reported on its own as getbalances.mine.coinbase and getwalletinfo.transparent.coinbase_balance, and an insufficient-funds -6 names the amount rather than leaving the gap between balance and send unexplained.

Change is routed to the wallet's internal (change) transparent chain, which matters twice: it is recovered on a from-seed restore via the internal gap chain, and the history RPCs recognize the internal key scope as change and hide it, while a deliberate payment to one of your own external t-addresses stays visible as a send+receive pair, matching Bitcoin Core.

Sweeping many transparent UTXOs at once

A wallet paid repeatedly at t-addresses accumulates a long tail of small UTXOs. z_mergetoaddress, new in 0.7.0, consolidates them into one output:

curl -s --user "$RPCUSER:$RPCPASS" --data-binary \
  '{"jsonrpc":"1.0","id":"doc","method":"z_mergetoaddress",
    "params":[["ANY_TADDR"],"u1...",null,0,null,"","AllowRevealedSenders"]}' \
  http://127.0.0.1:8232/

With a shielded destination this is a bulk shield: it needs AllowRevealedSenders, because spending transparent UTXOs reveals the sender either way. With a transparent destination it is a fully transparent transaction and needs AllowFullyTransparent. The default per-call limit is 50 UTXOs and the response's remainingUTXOs says whether to call again.

Coinbase is not included, and cannot be: see the next section.

Coinbase: shielding is the only way to spend it

Transparent coinbase (a block reward or fee paid to one of the wallet's t-addresses) is a special case, and the rule comes from consensus, not from zecd's policy: a transaction that spends a transparent coinbase output may not have any transparent output, change included. There is therefore no valid t-to-t coinbase spend to build, and the whole selected value must move into a single shielded output.

z_shieldcoinbase is the method that does it: it sweeps mature transparent coinbase UTXOs into one shielded output at toaddress, which must have a shielded receiver. It is asynchronous in zcashd's style, returning an opid that z_getoperationstatus / z_getoperationresult resolve. The shielded payment is exactly input_total - fee, with no change in any pool: emitting shielded change would leak how much coinbase the wallet chose to sweep. Use the limit argument (default 50) to sweep in stages.

curl -s --user "$RPCUSER:$RPCPASS" --data-binary \
  '{"jsonrpc":"1.0","id":"doc","method":"z_shieldcoinbase","params":["*","u1..."]}' \
  http://127.0.0.1:8232/
# {"result":{"remainingUTXOs":0,"remainingValue":0.00000000,"shieldingUTXOs":3,
#            "shieldingValue":9.37500000,"opid":"opid-..."},"error":null,"id":"doc"}

The surrounding behavior follows from the same rule:

• Maturity is the standard 100 blocks, enforced during input selection. Immature coinbase is excluded from listunspent entirely (Bitcoin Core's AvailableCoins behavior), and its value is reported in getwalletinfo.immature_balance rather than counted as spendable.
• listunspent marks it. Transparent entries carry zcashd's generated boolean, true when the output came from a coinbase transaction.
• The regular send paths skip it. The transparent-to-transparent spend above always produces transparent outputs, so it never selects a coinbase input; nothing you do with sendtoaddress/sendmany/z_sendmany can build a consensus-invalid coinbase spend by accident.
• Shielded coinbase (ZIP-213) needs none of this. A block reward mined directly to a shielded address has no maturity rule and no spend restriction, so those notes are ordinary Orchard notes and spend through the normal send methods.

The gap limit: transparent recovery is bounded

zecd is stateless: everything on disk must be rebuildable from the seed plus a chain scan. For shielded funds that recovery is unconditional (note trial-decryption needs no address list). Transparent funds are different: a from-seed restore rediscovers them only within the external transparent gap limit: the standard HD-wallet gap mechanism, made sharper by statelessness (there is no persisted keypool to fall back on).

Mechanically, recovery is bounded by which addresses are exposed (present in the matcher's address set). The window is anchored at the wallet's issuance frontier, the highest of:

1. the last funded external index,
2. the highest index getnewaddress has handed out, and
3. the transparent_initial_scan floor.

Indices from the frontier up to frontier + transparent_gap_limit are exposed, and a payment to index N is discovered iff N is exposed. A funded index (or a fresh issuance) advances the frontier and drags the window up with it, as in any HD wallet. The block-scan and mempool matcher carries that window as an in-memory gap lookahead: transparent_gap_limit addresses derived past the frontier, written to the wallet database only when a payment to one actually arrives. A wide gap therefore costs derivation, not stored rows.

[pools] transparent_gap_limit (default 20, applied only to transparent-enabled wallets; librustzcash's own default is 10) sets the external window. Transparent change consumes the internal chain and is recovered via the internal gap (librustzcash's default internal window; zecd only varies the external limit).

The gap limit composes with transparent_initial_scan

Because the transparent_initial_scan floor is one of the frontier's three inputs, the two knobs add rather than compete. A from-seed restore has forgotten which addresses were handed out (that is what statelessness means), and before the scan finds a funded index it has no funded index either, so its frontier starts at the floor. The recovery horizon of a stateless restore is therefore:

transparent_initial_scan + transparent_gap_limit

The window used to be measured from the last funded index alone, and the floor did not count. An operator who pre-exposed, say, 70 000 addresses with transparent_initial_scan had to inflate transparent_gap_limit to ~71 000 before getnewaddress would keep issuing recoverable addresses: every issuance past the floor otherwise tripped the gap limit, was warned about as potentially unrecoverable, and genuinely was unrecoverable from seed. That workaround is no longer needed, and for the reason in the next section it is now actively discouraged.

Two windows: live lookahead vs restore recovery

The running wallet and a from-seed restore do not cover the same range, because the two windows are anchored on different events. Both behaviours are correct, and the difference is what decides whether funds survive a restore.

Issuance leaves no trace on chain, so a restore cannot know which addresses you handed out; it starts its frontier at the floor and works forward from funded indices. A running wallet, by contrast, must credit a receive on any address it handed out, so its lookahead follows issuance.

The consequence is a band that is matched live but not recovered from seed. It opens only when an address is issued at or past the recovery horizon, which is exactly the act transparent_allow_beyond_recovery_window governs and already warns about, so it is an accepted operator choice rather than a surprise. Funding-driven movement never opens the band: funding extends the restore's own window too, so a restore chains forward to it.

getwalletinfo.transparent reports both windows, so this is observable rather than inferred:

"transparent": {
  "gap_limit": 20,
  "lookahead_from": 1,
  "lookahead_through": 20,
  "recovery_horizon": 20,
  "restorable": true
}

• lookahead_from / lookahead_through are the live window, both inclusive. They describe the forward reach only: every address with a database row is matched too, including indices below lookahead_from.
• recovery_horizon is transparent_initial_scan + transparent_gap_limit.
• restorable is the one to watch. It is lookahead_from <= recovery_horizon, and false means the wallet is currently crediting addresses that a restore of the same seed would not rediscover. Alert on it rather than comparing the integers yourself.

Do not read a false as data loss: those funds are held and spendable, and are only at risk if the wallet is later rebuilt from seed alone. Raising transparent_initial_scan (not transparent_gap_limit, for the reason below) is the fix.

Sizing transparent_gap_limit: keep it small

Size the gap limit to the addresses you have handed out that are still unfunded, and no further. Deep restore coverage is what transparent_initial_scan is for: a one-time pre-exposure, not a per-receive cost.

The reason is that the window is re-derived on the receive path. Recording a transparent receive regenerates the entire gap window (a full unified-address derivation per index), and repeats that regeneration once per already-recorded output of the same transaction. At roughly 1200 derivations per second, a 71 000-wide window costs about a minute per received UTXO, and quadratically more for a multi-output transaction, all of it on the wallet's single-writer actor inside the sync batch. In the field (a zecd 0.5.1-rc2 report) this presented as a restore that appeared to stall: one core pegged, block scan frozen for hours.

zecd audits the configured value at startup: above 1000 (a gap limit already costing ~1s of derivation per recorded receive) it logs a warning, and above 10000 (worst case past ~10s per receive) it logs an error. Neither is a hard failure, and the daemon starts either way: the value stays the operator's choice, and what it costs is performance, not correctness.

Large pre-generated runs: transparent_initial_scan

A big gap limit is the wrong tool when you pre-generate many addresses: the gap is a sliding window kept gap_limit past the frontier forever, so an exchange that assigns 10 000 addresses and sizes the gap to match re-derives 10 000 addresses on every recorded receive, indefinitely.

Instead set [pools] transparent_initial_scan = N to pre-expose external indices 0..N once at startup/restore, so the block-scan matcher covers the whole issued range regardless of the (small) steady-state gap_limit. Set N to your issuance high-water mark and keep transparent_gap_limit small: the floor raises the frontier, so issuance continues past N with a normal-sized gap and stays recoverable to N + transparent_gap_limit.

Pre-exposure is incremental and non-blocking: it must complete before the block scan (a restore only finds a high funded index if that index was exposed first), but per-index derivation is slow at depth (~1180 addresses/s, so a 100k run takes minutes), so zecd exposes it in chunks of 1000 indices, servicing queued RPC commands between chunks; reads, sends, and the health endpoints stay live throughout. Progress is observable two ways:

• a throttled heartbeat log (done/total, %, rolling addr/s, ETA), and
• getwalletinfo's transparent.initial_sync object, {"exposed": n, "total": N, "complete": bool}, present whenever an initial-scan depth is configured (absent when the depth is 0).

When transparent receiving is enabled, getwalletinfo also reports the effective transparent block (enabled, default, gap_limit) and the daemon logs the gap limit and initial-scan depth at startup, so coverage can be audited against your issuance records.

At the edge of the recovery window

librustzcash itself fails closed at the gap: once gap_limit consecutive unfunded external addresses (above the initial_scan floor) have been handed out, it refuses to allocate another, precisely because a from-seed restore could not rediscover funds sent there. zecd turns that edge into an operator choice:

• transparent_allow_beyond_recovery_window = true (default): getnewaddress issues the address anyway and logs a loud warning that funds received there may be unrecoverable from seed (downgraded to info when the index is still below transparent_initial_scan, hence recoverable). A payment to such an address is still detected live (issuing it refreshes the matcher's address set); the risk is confined to a later from-seed restore.
• transparent_allow_beyond_recovery_window = false: the call fails -4 with an actionable message naming the knobs (fail-closed; funds can never land on an unrecoverable address).

Independently, transparent_gap_warn_threshold (default 5) makes getnewaddress warn as the last few in-window slots are consumed, and a one-time startup audit re-warns if a wallet is already near or over the window, giving lead time before addresses land outside it. The lead time is best spent raising transparent_initial_scan (or getting a lower index funded), not inflating transparent_gap_limit, for the per-receive derivation reason above.

Not implemented

• Auto-shielding. Ordinary (non-coinbase) transparent UTXOs are not automatically shielded into Orchard, and such a receive cannot fund a shielded send. Those funds can be spent transparently (under AllowFullyTransparent) or left in place. Coinbase is the exception, and it is explicit rather than automatic: z_shieldcoinbase (above).
• Mixed inputs. Transparent UTXOs and shielded notes cannot fund a single send together.
• Automatic address-index reconciliation. No periodic cross-check of exposed addresses against Zebra's transparent address index to backfill receives the forward-only scan missed. Since 0.6.0 the primitives to do it yourself exist - derive or look up an address by index, and ask which index an address is (above) - but nothing runs that loop for you.

See Known limitations for the details and planned direction of each.

Watch-only wallets

A zecd wallet can run watch-only: initialized from a ZIP-316 Unified Full Viewing Key (UFVK) instead of a mnemonic, it sees everything the paired spending wallet sees (balances, incoming payments including 0-conf via the mempool stream, full history) and issues receive addresses of the same account, while holding no spending material on disk or in memory.

Why: split the invoicer from the spender

The typical deployment puts the internet-facing half of a payment system on a machine that cannot lose funds even if fully compromised:

  internet-facing host                      hardened / offline-ish host
 ┌───────────────────────────┐             ┌───────────────────────────┐
 │ payment server / invoicer │             │ payout service            │
 │   getnewaddress           │             │   sendtoaddress, sendmany │
 │   listtransactions        │             │                           │
 │   gettransaction          │             │                           │
 │        │                  │             │        │                  │
 │   zecd (watch-only, UFVK) │             │   zecd (spending wallet)  │
 └────────┼──────────────────┘             └────────┼──────────────────┘
          └──────────────► Zebra node(s) ◄──────────┘

The watch-only instance issues invoice addresses and detects payments; the spending wallet, the only holder of key material, lives elsewhere and signs payouts. Because both wallets carry the same account's viewing key, every invoice the watch-only instance hands out is detected and spendable by the spending wallet (see the pairing guarantee below). A compromise of the invoicer host leaks your transaction graph (see the privacy warning) but never funds.

Watch-only wallets can also be loaded in the same daemon alongside the spending wallet as additional [wallets.<name>] entries, addressed at /wallet/<name>; see multiwallet routing.

Exporting the key: zecd export-ufvk

zecd --datadir ./data export-ufvk --wallet default

Prints the wallet's UFVK (uview1... on mainnet, uviewtest1... on testnet) to stdout, with an explanatory warning on stderr. --wallet defaults to default. Properties, all deliberate:

• Offline. It reads the UFVK from the wallet DB (where it is stored for scanning anyway) over a read-only connection. No upstream connection is made and no identity file or passphrase is needed. It works for locked and passphrase-encrypted wallets alike, and never touches spending material.
• Works while the daemon runs. export-ufvk is deliberately exempt from the exclusive datadir lock that zecd init and the daemon take, so you can export from a live wallet.
• Network-checked. It refuses to run if the configured network contradicts the wallet on disk (the UFVK encoding is network-scoped, so a mismatched key would be rejected by the watch-only side anyway).

Creating the watch-only wallet: zecd init --ufvk

On the watch-only host, initialize a fresh datadir from the exported key:

zecd --datadir ./watch init --ufvk "uview1..." --birthday 2500000

• --ufvk conflicts with --restore and --encrypt (there is no mnemonic and nothing to encrypt). The malformed-key check runs before any directory or network I/O.
• Unlike export-ufvk, init --ufvk needs the chain backend reachable: it fetches the chain tip and the tree state at the birthday to anchor the wallet.
• An imported key may have history, so it is treated like a restore: pass --birthday (a height at or before the account's first transaction) to avoid the safe-but-slow default, which scans from the earliest enabled pool's activation (Orchard/NU5 for the default Orchard-only configuration; Sapling activation if Sapling is enabled) and logs a warning.
• The result is a seedless keys.toml with the UFVK pinned into it (the same account-to-keys binding check spending wallets get: every startup verifies the DB account against the pin, so a swapped database fails closed).

No mnemonic is printed; there is none. Init confirms (one line, on stderr):

Watch-only wallet (imported UFVK): balances, history, and addresses are available; spending and wallet-encryption RPCs are disabled.

RPC semantics

zecd follows Bitcoin Core's modern model: a wallet without private keys (createwallet ... disable_private_keys=true in Core). Watch-only is a property of the whole wallet, never of individual addresses.

The pairing guarantee

Every address the watch-only instance issues is a diversified address of the same account as the spending wallet (the UFVK can only derive its own account's addresses), so an invoice issued by the watch-only instance is always detected and spendable by the paired spending wallet, whose note detection is viewing-key-based and does not depend on which instance issued the address.

What is not guaranteed is that the two instances hand out the same address sequence: librustzcash picks shielded diversifier indexes from the clock, so two same-key wallets return identical getnewaddress results only when called within the same second. To verify a pairing, compare key material (export-ufvk on both sides returns the identical string), not getnewaddress output. See Addresses & shielded pools for the diversifier mechanics.

One spender, many watchers

A single daemon may load at most one wallet with spending keys, plus any number of watch-only wallets alongside it. This keeps spend authority unambiguous: there is never a question of which key signs. Two enforcement points:

1. At zecd init: creating a spending wallet is refused up front (before any directory or network I/O) when another configured wallet already holds spending keys. The error suggests --ufvk instead. Watch-only inits are exempt: any number are allowed.
2. At daemon startup, as a backstop for wallets created out-of-band (independent inits later merged into one config, restores, external DB edits): after every wallet reports its watch-only flag, a second spender is fatal for the whole daemon. zecd will not silently pick which one is "the" spender; the error names both offending wallets.

Each watch-only wallet configured this way is a full stack of its own: a database, an actor and a scan. For a large number of them, an experimental fleet (since 0.8.0) shares one database and one scan per shard of wallets, and adds them at runtime with createwallet instead of a config edit and a restart.

To resolve a violation, convert one spending wallet to watch-only (zecd export-ufvk + zecd init --ufvk into a fresh datadir, then delete the spending datadir) or remove it from the configuration.

A UFVK grants full view access

A Unified Full Viewing Key reveals everything: all balances, all addresses (incoming and outgoing sides), and the full transaction history of the account, forever. export-ufvk emits the account's full viewing key; there is no reduced-visibility export. It cannot spend, but treat it as a privacy secret:

• Share it only with hosts that may see your entire transaction graph.
• A watch-only datadir still deserves protection (filesystem permissions, encryption at rest): it contains the decrypted history, even though it holds no spending material.
• There is no way to revoke a leaked UFVK short of moving all funds to a new seed.

For the custody models and what a spending wallet protects beyond this, see Key custody.

Fleet: many watch-only wallets

Experimental. New in 0.8.0, off unless [fleet] enabled = true. While it carries this label, the manifest format, the [fleet] keys and the createwallet, loadwallet, unloadwallet and listwalletdir RPCs may change in a patch release, with no migration. A deployment with one wallet, or a handful of [wallets.<name>] entries, does not need it and is unaffected by it.

A fleet lets one daemon monitor a large number of watch-only wallets: a service that watches viewing keys on other people's behalf, for example. Spending is untouched. The one spending wallet stays a conventional wallet with its own database and actor.

Why it exists

A conventional view wallet costs a full stack of its own: a database, an actor, a scan pass, note-commitment trees and a memo backlog. At thousands of wallets against one upstream, that duplication is what stops zecd scaling.

A fleet puts many viewing keys into one shard: one database holding one account per wallet, behind one actor, scanned in one pass. librustzcash's scanner already trial-decrypts each block once against every account in a database, so a block is fetched once and decrypted once against every key in the shard. Trial decryption itself is per key and cannot be shared; everything around it is.

Shards stay bounded because adding an account rewinds its database to that account's birthday. In one database for everything, onboarding a wallet with an old birthday would make every other wallet re-scan with it.

Enabling it

[fleet]
enabled = true
# manifest_dir = "fleet/zec/wallets.d"   # relative to the datadir
# dir = "fleet/zec/shards"               # relative to the datadir
# shard_size = 128
# cohort_depth = 10000

Both directories sit under <datadir>/fleet/<coin>/ because a viewing key serves one currency and placement is decided by a birthday, which is a height on one chain.

fleet is a reserved wallet name. A [wallets.fleet] entry would resolve to <datadir>/fleet. With the fleet enabled, zecd refuses to start on that overlap; with it disabled, zecd config check warns, since enabling it later would make the daemon refuse to start. config check also warns when manifests are present while the fleet is disabled, and restates the experimental status when it is enabled.

Manifests

Each fleet wallet is one file, <manifest_dir>/<name>.toml:

# <datadir>/fleet/zec/wallets.d/acct-00417.toml
ufvk = "uview1..."
birthday = 2837400

• The file stem is the wallet name, served at /wallet/<name>. Names are ASCII letters, digits, -, _ and ..
• ufvk and birthday are both required and nothing else is accepted. The birthday is required because defaulting it would choose between a full-chain rescan and a scan that misses the wallet's funds.
• Files not ending in .toml are ignored.
• An unreadable or malformed manifest is skipped with a warning and reported by listwalletdir, so one bad file does not hide every other wallet. An unreadable directory, or two manifests for one name, is fatal at startup.
• Manifests are written atomically (temporary file, fsync, rename) and never overwritten, so an interrupted createwallet cannot leave a torn viewing key.

Add a wallet by writing a manifest and restarting, or without a restart with createwallet.

Placement

Which shard holds a wallet is read back from the shard databases, not recorded in a side file, so there is nothing to disagree with them. A new wallet joins an open shard unless the shard is full (shard_size) or the wallet's birthday is more than cohort_depth blocks below the shard's oldest birthday, in which case it starts a new shard and rescans only against its own key.

Two limitations are why the fleet is experimental:

• Placement groups wallets by arrival, not by birthday. A shard's scan floor is its oldest member's birthday, so a wallet born at today's tip that lands beside a 2018 wallet waits for that shard to scan from 2018. A wide spread of birthdays places poorly.
• A wallet cannot be removed once imported. unloadwallet stops serving it but deletes nothing: the manifest and the account stay, and the shard keeps scanning its key. Removing it means deleting its manifest and rebuilding the shard.

What a fleet wallet can do

Fleet wallets are watch-only and shielded-only. They answer the read RPCs (balances, history, listunspent, getaddressinfo) for their own account and nothing else, and they cannot sign. Every read that reports a wallet's own money, history or addresses is scoped to that wallet's account, so a wallet never sees its shard-mates' funds.

A watch-only daemon builds no Sapling prover and, when no loaded wallet can spend, does not warm the Orchard proving keys either.

Readiness after onboarding

A new wallet is served the moment it is placed, before its account exists: importing needs tree state below its birthday and waits for the shard's next connected pass. In that window its balances and history are empty. Two fields say which state it is in:

• imported on waitforsync: false until the wallet's account exists. synced is never true before it.
• import_error on waitforsync and getwalletinfo: present only when the import failed. It is terminal, so waitforsync returns immediately rather than waiting out its timeout.

A restart adopts every account already in its shard database rather than importing it again.

Backup

manifest_dir holds viewing keys that exist nowhere else in zecd, and createwallet writes to it at runtime. Back it up continuously, like keys.toml. It is the exception to the rule that the data directory is a disposable cache (see what to back up).

dir is a cache: delete it and the shards are rebuilt from the manifests plus a rescan. Put it on scratch storage if that helps, and keep the manifests somewhere backed up.

Embedding

An embedder reaches a fleet wallet's database through Node::wallet_location, the only supported route to a shard directory. See embedding.

Deployment

How to run zecd in production: the Docker Compose stack, the container images and how to extract bare binaries from them, the prebuilt .tar.gz/.deb release artifacts, and the health-probe wiring for Kubernetes and load balancers. Day-2 concerns (backups, monitoring, upgrades, failure modes) are in the operations runbook.

The Docker Compose stack

deploy/docker-compose.yml runs the two-service stack: a Zebra full node and zecd talking straight to Zebra's JSON-RPC over the private compose network. Testnet by default. The config files it mounts (deploy/zebrad.toml, deploy/zecd.toml) are part of the stack; the mainnet variants (*.mainnet.toml) are swapped in by the docker-compose.mainnet.yml overlay.

First run is init-then-up: Zebra must be synced far enough before zecd can create a wallet (a new wallet's birthday defaults to just below the current chain tip, 100 blocks back).

cd deploy
docker compose up -d zebra                        # let it sync
docker compose run --rm zecd init --wallet default
docker compose up -d                              # start zecd

curl localhost:9233/healthz
curl localhost:9233/readyz
curl --user zec:CHANGE-ME --data-binary \
    '{"method":"getblockchaininfo","id":1}' localhost:18232/

zecd init prints the wallet mnemonic to stdout once. Record it offline; it is the only way to restore the wallet. See operations for what else to back up.

For mainnet, add -f docker-compose.mainnet.yml to every command. The overlay only swaps each service's mounted config file; ports and wiring are unchanged (the mainnet configs deliberately keep zecd on 18232 and Zebra on 18234 so the compose port mapping is identical across networks):

docker compose -f docker-compose.yml -f docker-compose.mainnet.yml up -d zebra
docker compose -f docker-compose.yml -f docker-compose.mainnet.yml run --rm zecd init --wallet default
docker compose -f docker-compose.yml -f docker-compose.mainnet.yml up -d

Three things to change before trusting the stack with real funds:

• Pin Zebra. The compose file pins zfnd/zebra:6.3.0 for both networks, which activates Ironwood (NU6.3) at the network's activation height (see Zebra's source and release notes). The tag is an example. Pin to a release you have verified; Zebra's flags can vary between versions. On testnet, past NU7's activation (block 4,465,026) both the node and zecd must support NU7; see NU7. (Zebra tags have no v prefix.)
• Set a real RPC password. The shipped configs use password = "CHANGE-ME". On mainnet zecd refuses to start while the [rpc] password is still that placeholder (case-insensitive): the RPC credential is spend authority. On testnet it starts, but change it anyway before exposing the port.
• Keep the RPC port private. The compose file publishes 18232 and 9233 on loopback only. RPC credentials travel as plaintext HTTP Basic auth; to serve other hosts, front zecd with TLS or a reverse proxy, or accept the exposure knowingly.

The compose configs bind [rpc] and [health] to 0.0.0.0 inside the container (so the published ports are reachable) and point [backend] server at zebra://zebra:18234. That connection carries no credentials (enable_cookie_auth = false on the Zebra side), which is what the cleartext-credential gate expects for a non-local hostname.

zecd takes an exclusive lock on its data directory: never run two zecd instances (or replicas) against the same volume. The second one refuses to start rather than corrupt the wallet DB.

Container images

Two Dockerfiles produce interchangeable images:

• Dockerfile (amd64): a reproducible StageX build. Full-source-bootstrapped base images pinned by digest, a statically linked musl zecd, deterministic flags (SOURCE_DATE_EPOCH=1, codegen-units=1, --build-id=none), and a bare scratch runtime. Independent builders can reproduce the binary bit-for-bit.
• Dockerfile.arm64 (arm64): StageX publishes amd64 images only, so ARM uses a static-musl Alpine build (rust:alpine, base image pinned by digest, toolchain pinned to exact apk versions, Rust pinned via RUSTUP_TOOLCHAIN). Same output shape and the same runtime contract, and still bit-for-bit reproducible, but the toolchain is upstream binaries rather than StageX's full-source bootstrap. Both are published as one multi-arch image, so the same tag pulls the right architecture.

How the reproducibility works (and what to verify) is covered in reproducible builds.

Runtime contract

Both images honor the same contract, so they are drop-in interchangeable:

The image also ships a world-writable /tmp for SQLite's temporary files. Because the runtime is scratch, there is no shell: debugging happens through the RPC and health endpoints, or by mounting the datadir elsewhere.

Extracting bare binaries

Each Dockerfile has an export stage that copies the static binary to the image root, so you can build and extract without running a container:

docker build --target export -o ./out .                       # amd64: ./out/zecd
docker build -f Dockerfile.arm64 --target export -o ./out .   # arm64

This is exactly how the release workflow produces the published binaries, so a local export should reproduce the binary inside the released .tar.gz/.deb bit-for-bit for the same source.

Prebuilt release artifacts

Pushing a v* tag runs the Release workflow. It extracts the binary from each Dockerfile's export stage (so published binaries inherit the reproducible image pipeline) and attaches, per architecture (amd64 and arm64, both static musl builds):

• zecd-<version>-linux-<amd64|arm64>.tar.gz: the binary plus README.md, CHANGELOG.md, both license files, THIRD-PARTY-LICENSES.txt, and zecd.example.toml. The tar is reproducible (sorted entries, fixed mtime, root-owned, gzip -n).
• zecd_<version>_<amd64|arm64>.deb: a reproducible Debian package (scripts/build-deb.sh: fixed mtimes, --root-owner-group, SOURCE_DATE_EPOCH anchored; verified bit-for-bit).
• SHA256SUMS: one file covering every artifact in the release, in the standard sha256sum -c format.

Changed in 0.6.0. Artifacts now use the Debian/Go architecture names (amd64/arm64) rather than Rust target triples, so the tarball and the .deb agree on how they spell an architecture and the redundant unknown-linux-musl segment is gone. The per-file .sha256 sidecars were replaced by the single SHA256SUMS. Through 0.5.2 the tarball was named zecd-<version>-x86_64-unknown-linux-musl.tar.gz with a .sha256 beside it; a script that fetches release assets by filename needs updating.

Verify the checksums, then install:

sha256sum -c SHA256SUMS --ignore-missing    # `shasum -a 256 -c` on macOS/BSD
sudo apt install ./zecd_<version>_amd64.deb     # or _arm64.deb on ARM

--ignore-missing checks only the files you actually downloaded; drop it to require every artifact in the release to be present.

The .deb installs:

• /usr/bin/zecd
• /lib/systemd/system/zecd.service: installed but not enabled; it runs zecd --datadir /var/lib/zecd as the zecd user with systemd hardening (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, writable only in /var/lib/zecd)
• /usr/share/doc/zecd/: zecd.example.toml, README.md, THIRD-PARTY-LICENSES.txt, copyright, changelog

The postinst script creates the zecd system user/group and /var/lib/zecd (mode 0750). No config file is installed under /etc; put your config at /var/lib/zecd/zecd.toml (the datadir default) or point the unit at one with --conf. Then:

sudo -u zecd zecd init --datadir /var/lib/zecd    # one-time wallet creation
sudo systemctl enable --now zecd

The same workflow pushes the GHCR image as one multi-arch manifest (amd64 and arm64) under bare semver tags (<major>.<minor>.<patch> and <major>.<minor>), with no per-architecture suffix. A manual workflow_dispatch run can dry-run the packaging without a tag; image pushes are opt-in for those runs.

Ports

Zebra ships with RPC disabled and has no default RPC port; 8234/18234 are the ports zecd's default server = "zebra" preset dials, chosen next to Zebra's P2P ports (8233/18233). Any explicit zebra://host:port works.

Health and readiness probes

zecd serves unauthenticated probes on a separate port (default 9233), designed for Kubernetes probes and load-balancer health checks:

• GET /healthz: liveness. Always 200 while the process runs.
• GET /readyz: readiness. 200/503 plus a JSON body with ready, locked, a per-wallet map, and (when not ready) a reason of actor_down, upstream_down, enhancing, or syncing.
• GET /status: a JSON snapshot of per-wallet sync state, for humans and dashboards (see operations).

Defaults are [health] enabled = true, bind = "127.0.0.1", port = 9233. In a container or behind a probe, set bind = "0.0.0.0" (the deploy configs do).

What /readyz means is a deployment choice, [health] readiness:

• "synced" (default): ready only once every wallet is connected, within max_scan_lag blocks of the tip (default 4), and its transaction-enhancement backlog has drained. Strict: a from-birthday restore stays not-ready until the memo backfill finishes, which on a large wallet takes a long time (reason distinguishes syncing from enhancing). Use it when clients must not see stale balances or incomplete history.
• "scanned" (new in 0.6.4): connected and within max_scan_lag of the tip, without the drained-backlog term. Balances and note spendability are current in this state, since both come from the block scan; only history completeness lags. Use it when a wallet holds many transparent UTXOs and sends regularly, where the backlog term makes /readyz flap after routine sends and takes a working node out of rotation. See the operations runbook.
• "connected": ready as soon as the backend is connected and its chain tip is past the wallet's birthday (a sanity check that zecd is talking to the right, live network). Does not wait for the wallet scan at all, so RPC clients can reach zecd while it catches up. Reads may lag the tip arbitrarily.

A locked encrypted wallet is still ready (reads work); /readyz reports it via the locked flag so a controller can drive a walletpassphrase without misreading it as a sync stall. A dead wallet writer actor fails readiness (reason: "actor_down") even though reads still answer; that needs a process restart.

[health]
bind = "0.0.0.0"
port = 9233
readiness = "synced"   # the default; or "scanned", or "connected"
max_scan_lag = 4       # applies in "synced" and "scanned" modes

Kubernetes example:

startupProbe:
  httpGet: { path: /healthz, port: 9233 }
  periodSeconds: 2
  failureThreshold: 30
livenessProbe:
  httpGet: { path: /healthz, port: 9233 }
readinessProbe:
  httpGet: { path: /readyz, port: 9233 }
  periodSeconds: 10

Changed in 0.6.0: the proving key no longer delays startup. It is built on a background task, so the daemon spawns its wallet actors and binds the health and RPC listeners immediately; /healthz answers within the first moments of process life. Through 0.5.2 the keygen ran before the listeners bound - seconds of CPU on a fast machine and considerably more on a small VPS at the time - during which the process was unreachable and not syncing, and startup probes had to be sized around it. If you widened failureThreshold or initialDelaySeconds for that reason, you can tighten it back.

Only the first send can now observe the build, and only if it arrives before the build finishes, which on any real deployment it does not.

Startup-probe headroom is still worth keeping for the scan, which is unrelated to keygen: after a restore or an upgrade with a long offline gap, prefer readiness = "connected" or a generous readiness budget, since in the default "synced" mode a catching-up wallet answers 503 until it reaches the tip and finishes backfilling memos.

Allocator: why the images use mimalloc-secure

Both images build with --features mimalloc-secure. The static-musl binaries would otherwise use musl's default allocator, which serializes on a lock under Orchard proving's multi-threaded allocation churn: roughly 80x more futex syscalls per proof than mimalloc, measured as about a 10% cost per shielded send on bare metal and several times worse in syscall-expensive sandboxes (gVisor, nested virtualization, some CI). The -secure variant adds heap hardening (guard pages, canary free-lists) for under 4% on the proving path, recovering mitigations that replacing musl's hardened allocator would otherwise drop. Native glibc builds (from source, outside the images) do not need the feature; glibc's allocator already scales.

Operations runbook

Running zecd on mainnet: what to back up, how to restore, what to monitor, how sends behave under failure, and how to upgrade. For getting the stack up in the first place, see Deployment; for config keys, see the configuration reference.

What to back up

Funds are recoverable from the mnemonic alone. Everything else is convenience.

Do not back up data.sqlite (since 0.7.0 it lives under <wallet dir>/zec/lrz/; see wallet data layout). It is a cache derived from the chain: zecd is stateless, so with the mnemonic (and birthday) the whole data directory can be recreated. Shielded funds are unconditionally recoverable from seed; transparent funds only within the gap-limit / initial-scan window (see Transparent support).

Minimal runtime file set

Per wallet directory <dir>:

Keep secrets out of the TOML (which typically lives in a ConfigMap):

• RPC password: ZECD_RPC_PASSWORD, --rpcpassword, or [rpc] password_file (flag/env > password_file > inline password). Prefer the env var or password_file: a password on the command line is visible to any local user via ps, and zecd warns at startup when it is passed that way.
• keys.toml location: ZECD_KEYS_FILE / --keys-file / [keys] keys_file (per-wallet [wallets.<name>] keys_file).
• age identity: ZECD_AGE_IDENTITY / --age-identity / [keys] age_identity.

Wallet data layout

Since 0.7.0 a wallet directory nests its derived state one coin and one engine deep:

<datadir>/<wallet>/keys.toml                                    <- the seed. Stays at the root.
<datadir>/<wallet>/zec/lrz/data.sqlite

Before 0.7.0 these sat flat in the wallet directory, together with an on-disk block cache (blockmeta.sqlite, blocks/). Since 0.8.0 the block cache is in memory, so 0.7.x leaves those two in zec/lrz/ and nothing reads them; zecd rescan deletes them.

The split follows what can be rebuilt from what. keys.toml wraps a BIP-39 seed that serves every coin and that nothing on any chain can reconstruct, so it stays at the top. Everything below it is derived state, namespaced first by the coin that owns it and then by the library that wrote it, so a second coin gets a sibling directory rather than a share of one flat namespace, and replacing the storage library becomes a sibling directory plus a rescan.

The migration

Existing wallets migrate themselves on first start. No configuration changes, including for a wallet with an explicit dir. What it guarantees:

• It runs under the datadir lock, before anything opens a wallet, and also at zecd init and zecd rescan.
• Artifacts are renamed within the wallet directory, never copied, so no free disk space is needed and nothing is deleted.
• The SQLite -wal and -shm sidecars travel with their databases. A -wal holds committed transactions not yet checkpointed back, so moving a database without it would silently discard the most recent writes.
• An interrupted run resumes: the next start moves whatever is left.
• A failure is fatal by design. It is not a silent fallback to rebuilding an empty database, because that would look like a working daemon with a wallet that has lost its history. The one case it cannot resolve on its own is an error leaving copies in both places, which it reports for an operator to settle.

Take the usual datadir backup before the upgrade anyway. The worst case is a from-seed restore, not lost funds, but a restore costs a scan.

zecd config check reports a pending move as a warning and the both-places state as an error, so an upgrade can be dry-run against a live deployment before anything is stopped.

Read-only commands take no datadir lock and therefore cannot migrate. zecd export-ufvk reads an un-migrated wallet database where it lies; zecd derive-address needs no fallback at all, since it reads only keys.toml, which the migration never moves.

If you compute these paths yourself

Backup scripts, log shippers, and volume mounts that hard-code <wallet>/data.sqlite need updating to <wallet>/zec/lrz/data.sqlite. The exclusion advice above is unchanged in substance: exclude the engine directory, keep keys.toml.

Embedders must use config::engine_dir or config::WalletEntry::engine_dir rather than joining the components by hand, since the layout is versioned by coin and engine. See embedding.

Restore procedures

Server restore (you have keys.toml + identity.txt)

Put both files back at their configured paths and start the daemon. With [keys] bootstrap_from_keys (default true), an empty data directory next to a present keys.toml is rebuilt automatically on boot: zecd recreates the account from the seed and rescans from the stored birthday. No init needed. This is the disposable-datadir pattern: mount one Secret, start with an empty volume.

When the rebuild runs depends on the custody model:

• Identity / auto_unlock: the seed decrypts at startup, so the rebuild runs as soon as Zebra is reachable. No human action.
• Encrypted (init --encrypt): the wallet starts locked with no account yet; address and spend RPCs return "account is not ready", and /status reports locked: true. The rebuild runs at the first walletpassphrase, after which the wallet syncs (and stays synced while locked). zecd probes datadir writability when it loads the wallet, so a read-only datadir fails at startup rather than at unlock time.
• Watch-only (--ufvk): no seed, not covered by bootstrap. Recreate with zecd init --ufvk against an empty datadir (see Watch-only wallets).

Set bootstrap_from_keys = false to fail fast on an empty datadir instead.

From-seed restore (you have only the mnemonic)

zecd init --datadir /var/lib/zecd --restore --birthday <height>
# paste the mnemonic when prompted

Always pass --birthday (any height at or before the wallet's first transaction). Without it, the restore scans from the activation height of the wallet's earliest enabled pool (Orchard/NU5 for the default Orchard-only config, Sapling activation when Sapling is enabled): safe (it can never miss notes) but slow on mainnet. History reappears as the scan progresses; do not trust balances until the scan and enhancement backlog finish ("synced" readiness, which is the default, or /status showing fully_scanned at the tip and pending_enhancements 0. The looser "scanned" and "connected" modes report ready before that point.)

Non-interactive restore: set ZECD_MNEMONIC, or pass --mnemonic-file <path> (ZECD_MNEMONIC takes precedence; stdin is the fallback). For init --encrypt, set ZECD_WALLET_PASSPHRASE instead of answering the prompt.

Watch-only replica

Export the viewing key on the spending host with zecd export-ufvk, then zecd init --ufvk "uview1..." --birthday <height> on the replica. A watch-only wallet is fully reconstructable from UFVK + birthday; record both. The UFVK cannot spend but reveals the wallet's entire transaction graph, so treat it as confidential.

Monitoring and alerting

zecd serves unauthenticated probes on a separate port (default 9233) when [health] enabled (the default):

Where sync time goes (since 0.8.0). /status carries two cumulative per-wallet objects, so a slow restore can be attributed to the upstream or to this host from one read:

• sync_totals, for the block scan: batches, blocks, bytes, txs, sapling_outputs, orchard_actions, and the time split download_ms, tree_state_ms, scan_ms, transparent_ms, total_ms. Each batch also logs a batch complete line with the same split for that range.
• enhance_totals, for the memo drain that follows: passes, serviced, and requests_ms (reading the request table), upstream_ms (waiting on fetches), apply_ms (storing the results), per_request_ms. The drain is bound by upstream round trips and the single writer, so it does not scale with this host's cores the way the scan does.

Readiness modes, strictest first:

• "synced" (default): ready only once every wallet is connected, within [health] max_scan_lag blocks of the tip (default 4), and with an empty enhancement backlog. A from-birthday restore stays not-ready until it has scanned to its own funds and finished backfilling memos.
• "scanned" (new in 0.6.4): connected and within max_scan_lag of the tip, without the empty-backlog term. Balances and note spendability come from the block scan and are current in this state; only history completeness lags. Choose it for a deployment that sends regularly from a wallet holding many transparent UTXOs, where the strict mode's backlog term flaps readiness after routine sends (see below).
• "connected": ready once the backend is connected and its tip is past the wallet's birthday. Does not wait for the scan at all, so readiness never flaps during a long catch-up; reads may lag the tip arbitrarily.

A 503 body carries a reason. Route alerts on it:

"Scanned to tip" is not "ready". Compact blocks carry no memos, so after the block scan catches up, an enhancement pass fetches each transaction's full data from Zebra and decrypts it to backfill memos. On a from-birthday restore of a busy wallet that is one fetch + decrypt per transaction, which can take a long time after scan_progress hits 1.0 (since 0.8.0 it runs [sync] enhance_concurrency fetches at once; a deployment that never reads memos can skip it with [sync] fetch_memos = false). While the backlog drains, conn_state stays syncing, getwalletinfo.scanning and getblockchaininfo.initialblockdownload stay truthy, and "synced" readiness holds 503 with reason="enhancing". Watch /status pending_enhancements; if it drains slowly, check that Zebra's getrawtransaction is fast.

The backlog is not restore-only. A wallet holding many transparent UTXOs re-emits its recurring spend-search requests every time the chain tip advances past an unspent output's observed height, so pending_enhancements rises transiently after ordinary sends and new blocks, in steady state, on a wallet that has been synced for weeks. Under the default "synced" readiness that is enough to answer 503 with reason="enhancing" for as long as the drain takes, which on a busy address is long enough for an orchestrator to pull the node out of its service while every balance RPC is answering correctly.

If you see readiness flapping after sends rather than after a restore, that is this, and readiness = "scanned" is the answer: it keeps the height gate and drops the backlog term, so a node that is scanned to the tip stays in rotation while memos land behind it. Clamp any consumer that needs complete history to pending_enhancements reaching zero rather than to readiness.

Fixed in 0.6.4, separately from the mode: the backlog count previously included duplicate requests, several thousand of them on a wallet with a reused transparent address, because the upstream query that generates them matched on transaction id alone. A count in the tens of thousands on such a wallet was mostly an artifact. pending_enhancements now reports distinct outstanding requests, so figures from 0.6.3 and earlier are not comparable with figures from 0.6.4.

Bounding history completeness precisely. Since 0.7.0, getwalletinfo reports a top-level enhanced_through height, and pending_enhancements appears inside its scanning object. That matters for two readers the health server does not serve: a library consumer running with default-features = false has no health port at all, and anyone driving zecd purely over JSON-RPC previously had to run one just for this number.

enhanced_through is the height below which history is complete, so a consumer replaying wallet history as a log clamps its cursor to it rather than to readiness. It is null when not currently determinable, which must be read as hold the cursor, never as "everything is enhanced".

waitforsync (also 0.7.0) blocks until both the scan and the backlog are done and returns all of these in one object, which is usually what a restore script wants instead of a poll loop.

locked (top-level on both /readyz and /status, plus per-wallet) is true when a passphrase-encrypted wallet needs a walletpassphrase before it can spend. It is reported independently of readiness (a locked wallet can be ready: true), so a controller can drive an unlock without mistaking it for a sync stall.

For load visibility, getrpcinfo returns active_commands: one entry per executing call with method and duration (microseconds).

Logs: set [log] format = "json" for aggregation (Loki/CloudWatch/Elastic). Every RPC call logs method, wallet, elapsed_ms: debug on success, except a call taking 2 s or more, which logs rpc ok (slow) at info (since 0.8.0); errors log at info and add code/message, except method-not-found (-32601), which logs at debug so a client probing an absent method does not write one line per poll. Sync and connection lifecycle events log at info; connection failures at warn.

Suggested alerts:

• /readyz 503 with reason=upstream_down for more than 5 minutes.
• /status sync lag (chain tip minus scanned height) not shrinking for 30 minutes.
• Sustained HTTP 503 from the RPC port (work queue exhausted).
• Daemon restarts.

The health server starts after wallets load, so cover startup at boot with a startupProbe / initialDelaySeconds. The port is unauthenticated by design and exposes sync status only; keep it off the public internet anyway.

Structured logging

Reworked in 0.7.0. Text output looks much as it did; JSON output ([log] format = "json") is now queryable without matching on message strings.

Context lives on spans, not in prose. Everything emitted while an RPC is handled, the sanitized error detail lines included, is attributed to that call's method and wallet through an rpc span. Every event from a wallet's actor carries the wallet name as a real field on a wallet span, rather than a [name] prefix pasted onto the message text.

Numbers are fields. Durations, counts, and the rates on the send profile, the scan batches, and the periodic heartbeats used to be baked into sentences. They are now fields you can aggregate on.

The zecd::audit target

A stable tracing target carries the security-relevant events, so an operator routes them to a separate sink with a one-line filter instead of matching on message text:

• the RPC authentication mode chosen at startup, and per-request outcomes;
• the account-to-keys binding pin;
• seed unlock and relock, including the walletpassphrase timeout auto-lock;
• transparent issuance past the recovery horizon;
• every process-hardening step that was a no-op or was opted out of;
• the loaded spending wallets, when allow_multiple_spending_wallets is on.

Route it with a RUST_LOG directive, which overrides [log] level entirely when set:

RUST_LOG='warn,zecd::audit=info'     # audit trail only, plus real problems

Two log levels moved

Both changes reduce steady-state volume, and both are worth knowing before you write an alert on the old behaviour:

• Per-request authentication success dropped from INFO to DEBUG, removing one line per authenticated request. Failures stay at WARN.
• Reconnect attempts during an upstream outage no longer stream WARNs. The first failure warns and names the demotion; the paced retries after it log at DEBUG with their attempt number and delay. An alert that counted reconnect WARNs will now fire once per outage rather than continuously, which is the intent.

Two more moved in 0.8.0:

• A slow successful RPC logs at INFO. A call that takes 2 seconds or more logs rpc ok (slow) at INFO, where every success used to be DEBUG only. Seconds on a read means a wallet has outgrown a query, and this makes it visible at the default level.
• Method-not-found dropped from INFO to DEBUG. A client whose dialect fallback polls a method zecd does not serve would otherwise write one INFO line per poll. Every other error code stays at INFO.

Each send's send complete line also carries tx_bytes, the built transaction's size, beside est_tx_bytes, the estimate [spend] max_tx_bytes was checked against, and warns when the estimate came in under the real size.

New TRACE events exist for one-per-downloaded-block and one-per-serviced-transaction-data request. They are off unless asked for, and are verbose enough that you want a narrow filter.

Startup and shutdown

One identifying line is logged at startup with the version, network, datadir, and upstream, which nothing did before. Shutdown warns when async operations are still unfinished.

Send semantics under failure

See Sending for the RPC surface; this is the operational contract.

• sendtoaddress and sendmany are synchronous and compute Orchard proofs, so a call holds the HTTP connection for a few seconds plus any queueing behind other sends (sends serialize per wallet). Set client-side send timeouts well above that. (z_sendmany returns an operation id immediately; see async operations.)
• A client timeout is not a failure. The send may still complete on the server. Retrying a send that actually succeeded pays twice, exactly as with bitcoind, but the longer proving window makes it likelier. On timeout, reconcile with listtransactions (or gettransaction) before retrying.
• A send whose initial broadcast fails in transport still returns the txid. The transaction is already committed to the wallet, its inputs are locked, and the rebroadcast loop re-submits it (at most once per [sync] rebroadcast_secs, default 60) while it is unmined and unexpired. Never retry a send that returned a txid.
• Only an explicit upstream rejection (Zebra examined the tx and refused it) errors, with -26. The tx's notes stay locked until its expiry height, then become spendable again; an immediate retry fails with -6 rather than double-paying.
• An expired unmined tx reports confirmations: -1 and abandoned: true. Treat it as failed and safe to re-send.
• Rapid back-to-back sends exhaust spendable notes and return -6 until change confirms (freshly created shielded change is not spendable unmined). The -6 message appends any balance awaiting confirmations, so "retry after the next block" is distinguishable from "the wallet needs funding".

Shutdown and in-flight sends

New in 0.8.0. z_sendmany returns an opid immediately and proves on a background task. A stop signal arriving in that window used to discard the send: nothing had been broadcast, so no funds were at risk, but the record of whether it happened was lost.

On shutdown the wallet now finishes the sends it has already accepted, bounded by [spend] shutdown_drain_secs (default 60). Set it below your supervisor's stop timeout, because that is what actually bounds it:

Killed mid-drain, nothing is corrupted: a send that had not been stored is lost, as before the drain existed. zecd config check warns when the value exceeds every common default, and 0 disables the drain. Operation status objects are in memory and do not survive a restart either way, so reconcile by txid (gettransaction), not by opid.

Reorgs

zecd follows reorgs automatically: the scanner detects the fork, rewinds, and rescans the replacement chain. Transactions in reorged-away blocks revert to unconfirmed (confirmations: 0) until re-mined; confirmation thresholds keep doing their job. One operator-visible consequence: a listsinceblock cursor pointing at a reorged-away block returns -5 Block not found (zecd keeps no stale-header history to walk back through, unlike bitcoind). A deep reorg is walked back in a few rounds: the rewind margin doubles while reorgs keep coming (since 0.8.0). Treat -5 as "cursor invalid": re-baseline with a parameterless listsinceblock, dedupe by txid, and store the fresh lastblock. See Wallet: history & unspent.

Recovering a stuck sync

A sync that fails, retries, and fails again on the same block is reported with the cause rather than left as a bare error. There are two shapes, and they need different responses.

An unsupported network upgrade. At every connect zecd compares the upgrades the node reports against the consensus rules the build knows. An unknown pending upgrade logs a warning ahead of its activation height, which is your notice to upgrade zecd before then. An unknown active one logs an error naming it, and sync failures under it are attributed to the outdated build. The fix is to upgrade zecd; if you are already on the latest release, report it at https://forum.zcashcommunity.com.

A wallet database that cannot apply otherwise-valid blocks. If the upstream is serving blocks and the failure is in applying them (a commitment-tree conflict, say), no amount of retrying or upgrading will clear it, because the damage is local. Rebuild the database:

# Stop the daemon first: rescan takes the datadir lock and will refuse otherwise.
zecd --datadir ./data rescan --wallet default

That deletes the wallet database only. keys.toml and the seed are kept, and the next start recreates the account from the seed and rescans from the wallet birthday, re-deriving every balance and all history from the chain. Nothing is lost that a seed restore could not rebuild, which is the same guarantee described in Stateless & recoverable; the cost is the rescan time. Pass --yes to skip the confirmation prompt in automated recovery.

Slow sends on a busy transparent address

A wallet holding many unspent outputs on a reused transparent address could see an ordinary sendtoaddress block for a minute or more before answering, sometimes only to report insufficient funds. Through 0.6.3 the cause was the spend-search path: the wallet asks the chain for transactions involving an address once per unspent output it holds, which is how a spend authored elsewhere gets noticed, but the address index answers each request with every transaction in the range rather than only the unseen ones, and all of them were fetched and re-stored. That work runs on the wallet's single writer, so it starved every command queued behind it. Measured against an address paid in every block, a send waited 109 seconds.

Fixed in 0.6.4, which skips transactions already recorded as mined. Nothing about the configuration changes and no action is needed beyond upgrading. It matters most to deposit and payout addresses, which are exactly the ones that accumulate outputs on a single address.

If sends are still slow after upgrading, the cause is elsewhere: check that the node's getrawtransaction is fast (the same dependency the enhancement backlog has), and check /status for a wallet still catching up.

Upgrades

1. Check the new binary against your existing config, before stopping anything. zecd config check resolves the file with the exact build you are about to deploy and exits non-zero if that build would refuse it. It takes no datadir lock and writes nothing, so it is safe to run against a live deployment:

   ./zecd-new config check --conf /etc/zecd/zecd.toml
   

   This matters because zecd rejects unknown config keys. That is what stops a typo'd knob from being silently ignored, but it also means a config valid for one build can be refused by another in either direction: an upgrade may not know a key yet, a rollback may have dropped one. Catching that here turns a failed restart into a no-op.

2. Diff the effective configuration to see which defaults the upgrade moves. Your file is only half the configuration; every key it leaves unset takes the binary's default:

   diff <(./zecd-old config show --conf /etc/zecd/zecd.toml 2>/dev/null) \
        <(./zecd-new config show --conf /etc/zecd/zecd.toml 2>/dev/null)
   

   To pin today's behaviour explicitly before upgrading, capture zecd-old config show > effective.toml and deploy that: it is round-trippable TOML that zecd itself accepts. (Secrets come out as commented-out key names, so a captured file needs its credentials re-added.)

3. Stop with SIGINT or SIGTERM (both are graceful: in-flight requests finish, new ones get 503, and since 0.8.0 the wallet finishes sends it had already accepted; see shutdown). The stop RPC is regtest-only, so a stray RPC call cannot take down a production daemon.

4. Replace the binary or pull the new image.

5. Start. Wallet DB migrations run automatically at open; the first start after a large librustzcash bump can take longer.

Upgrading onto 0.7.0 specifically, the first start also moves each wallet's databases into a per-coin subdirectory. It is automatic and needs no configuration change, but read wallet data layout first: a failure there is deliberately fatal rather than a silent rebuild, and any backup script or volume mount that names <wallet>/data.sqlite by hand needs its path updated. Step 1's config check reports a pending move as a warning, so the dry run tells you it is coming.

Upgrading onto 0.8.0, three things change under an existing deployment:

• Building from source needs Rust 1.91 (0.7.x needed 1.88). Binary and package users are unaffected.
• The block cache is in memory, so 0.7.x's blocks/ and blockmeta.sqlite are left behind unused; zecd rescan removes them, or delete them with the daemon stopped.
• [spend] orchard_action_limit now counts a two-bundle send as the prover does, so a wallet holding pre-NU6.3 Orchard notes can have a send refused that 0.7.x accepted. Raise the cap and send SIGHUP, or consolidate with z_mergetoaddress.

Every 0.7.0 configuration key and response shape still resolves as it did, and every new key defaults to the previous behaviour.

Upgrading onto 0.9.0-rc1 (a release candidate, needed on testnet past NU7; see NU7): the wallet database gains two migrations on first start that 0.8.1 does not know, so a database 0.9.0-rc1 has opened cannot be reopened by 0.8.1. Copy the data directory first if you might need to go back. No configuration key, RPC or response shape changes.

Downgrades across DB migrations are not supported. If you need a rollback path, stop the daemon and snapshot the datadir first. The worst case of a lost datadir is a from-seed restore, not lost funds.

Steps 1 and 2 need zecd 0.6.0 or later on the new side; config show on the old side only works if the old binary is also 0.6.0+, so the first upgrade onto 0.6.0 has nothing to diff against.

Single-instance datadir lock

zecd takes an exclusive advisory lock on <datadir>/.lock while it owns the data directory (the daemon for its whole lifetime, zecd init for the init). A second zecd run or zecd init on the same datadir fails fast with Cannot lock data directory .... The lock is an OS advisory lock the kernel releases when the process exits, including a crash or kill, so there is never a stale lockfile to delete: if the error appears and no zecd is running, just retry. Several commands are exempt because they never write the datadir: zecd export-ufvk (read-only DB access, so you can export a UFVK while the daemon runs), zecd rpcauth, and, since 0.6.0, zecd derive-address, zecd config check and zecd config show. Since 0.7.0 zecd chain-info and zecd licenses join them: chain-info opens no wallet database and writes no cookie file, and licenses never reaches a datadir at all. All of them are safe to run against a live deployment. config check deliberately does not mint a cookie file either, which would otherwise invalidate the credential a running daemon already handed out.

Mainnet checklist

• zecd config check --conf <file> --strict passes against the exact binary being deployed (--strict also fails on warnings, which is the right setting for a CI gate).
• network = "main" and a real [rpc] password (the daemon refuses to start with the CHANGE-ME placeholder).
• RPC bound to 127.0.0.1 or a private network; TLS or a reverse proxy in front if it must cross a network boundary. RPC credentials are spend authority (see the threat model).
• Key custody chosen deliberately: for unattended sending, the age identity stored outside the datadir (secrets manager, separate mount, ZECD_AGE_IDENTITY); for human-operated wallets, zecd init --encrypt so spending requires walletpassphrase with a timeout. See Key custody.
• Mnemonic and birthday recorded offline; restore procedure tested on testnet.
• Local Zebra full node configured (server = "zebra" or zebra://host:port); Docker images pinned to verified releases.
• /readyz wired into the orchestrator with a startupProbe covering initial sync; alerts on upstream_down.

Conventions & wire format

zecd speaks Bitcoin Core's JSON-RPC dialect: the JSON-RPC 1.0 envelope, HTTP Basic/cookie authentication, Bitcoin Core's error codes, and its HTTP status mapping. This page defines the wire format shared by every method; the methods themselves are in the method index.

JSON-RPC envelope

Requests are POSTed as a JSON object (or an array of objects, for a batch):

{"jsonrpc": "1.0", "id": "curltest", "method": "getblockcount", "params": []}

• method is required; a missing or non-string method is rejected with -32600.
• params is a positional array, as with Bitcoin Core. It may be omitted or null (treated as empty). Handlers read positional arguments only, so pass an array; an object-shaped params is accepted at the framing level but yields zero positional arguments. Any other type is -32600.
• id is echoed back verbatim, including on errors (null when it could not be parsed).
• A call carrying more positional arguments than the method declares is rejected with -1, matching Bitcoin Core's help-text error for over-arity calls.

Every response carries both result and error, one of them null (the JSON-RPC 1.0 behavior real Bitcoin clients such as python-bitcoinrpc parse):

{"result": 2500000, "error": null, "id": "curltest"}

{"result": null, "error": {"code": -32601, "message": "Method not found: no_such"}, "id": "curltest"}

HTTP transport

The RPC port defaults to 8232 on mainnet and 18232 on testnet/regtest, bound to [rpc] bind (see configuration). Responses are Content-Type: application/json (overload/shutdown rejections are text/plain). zecd does not validate the request Content-Type; send application/json as clients conventionally do. Request bodies are capped at 2 MiB; oversize requests get HTTP 413 before auth or dispatch.

A /wallet/<name> request naming a wallet that is not configured and loaded fails every wallet-routed method on it with -18 (Requested wallet does not exist or is not loaded: <name>), Bitcoin Core's RPC_WALLET_NOT_FOUND. Methods that never touch a wallet (uptime, getnetworkinfo, ping, getrpcinfo, the fee estimators) ignore the path and still answer, as in bitcoind. Each [wallets.<name>] section is an independent wallet; see Wallet: addresses & keys for listwallets.

Authentication

Every RPC request requires HTTP Basic authentication. Accepted credentials are the union of:

• [rpc] user + password (or --rpcuser/--rpcpassword): a single plaintext pair. Hashed at startup; verification only ever compares salted hashes.

• [rpc] auth entries (or repeated --rpcauth): bitcoind-style salted credentials in the <user>:<salt>$<hmac-sha256 hex> format of share/rpcauth/rpcauth.py, so no plaintext password lives in the config. zecd ships the generator built in:

  zecd rpcauth alice            # mints a random password, prints it once
  zecd rpcauth alice hunter2    # hashes a password you chose
  

  Either prints the auth = ["alice:<salt>$<hash>"] line to drop into [rpc].

• Cookie: when no user/password pair is set, zecd mints a random secret at startup and writes __cookie__:<random> to [rpc] cookiefile (default <datadir>/.cookie), mode 0600, regenerated on every startup. This happens alongside auth entries too, matching bitcoind's behavior whenever rpcpassword is empty. A local process reads the file and authenticates as __cookie__ (how bitcoin-cli talks to a local node by default).

Credential checks are constant-time (the password HMAC is always computed, and every configured user is checked without short-circuiting). A failed attempt gets HTTP 401 with WWW-Authenticate: Basic realm="jsonrpc" after a 250 ms delay, the same anti-bruteforce values as Bitcoin Core's httprpc.cpp. Failures are logged with the claimed username, peer address, and X-Forwarded-For when a reverse proxy sets it.

RPC credentials are spend authority: any authenticated caller can reach sendtoaddress unless the safelist removes it. See the threat model.

HTTP status and error codes

The mapping is Bitcoin Core's (httprpc.cpp JSONErrorReply): -32600 is 400, -32601 is 404, and every other RPC error is 500 with the error object in the body. Clients must read the body of non-200 responses.

Error numbering: Bitcoin Core's, not zcashd's

Error codes are Bitcoin Core's rpc/protocol.h values, because zecd's conformance target is bitcoind, not zcashd. Two conventions carried over from Core:

• -32602 (RPC_INVALID_PARAMS) is never emitted by a method handler. A missing required argument is -1 (Core answers with the method help text there) and a wrong-typed argument is -3 (RPC_TYPE_ERROR).
• Wallet, parameter, and verification codes are Core's numbers.

The -18 collision. zcashd numbers some codes differently in its own protocol.h. The one divergence zecd actually emits is -18: in Bitcoin Core (and zecd) it means "wallet not found" (an unknown /wallet/<name>), while in zcashd -18 is RPC_WALLET_BACKUP_REQUIRED. Since zcashd has no multiwallet routing, a zcashd-derived client never triggers zecd's -18 in normal use, but tooling that hard-codes zcashd's numbering should be aware. zcashd's -11 (RPC_WALLET_ACCOUNTS_UNSUPPORTED, vs Core's "invalid label name") is never returned by zecd at all: zecd is stateless and has no labels. The codes integrations branch on for the money path (-4, -5, -6, -8, -13 through -15, -20, -26) are identical across Bitcoin Core, zcashd, and zecd.

Amounts

Amounts are bare JSON numbers in decimal ZEC with exactly 8 decimal places (1 ZEC = 100,000,000 zatoshis), never strings and never floats internally. Serialization writes the decimal digits directly (via serde_json's arbitrary_precision), and parsing is an exact port of Bitcoin Core's ParseFixedPoint, so values round-trip with zero drift: 0.1 is exactly 0.10000000, and 21000000.00000000 survives untouched.

Use a client that decodes JSON numbers as exact decimals, not IEEE 754 doubles. In Python that is python-bitcoinrpc's behavior, or plain json.loads(raw, parse_float=decimal.Decimal); the conformance suite (scripts/conformance.py) asserts amount fields arrive as Decimal. A client that parses amounts as float will see values like 0.30000000000000004 and misprice payments.

Batching

An array body is a batch. The response is always HTTP 200 with an array of envelopes in request order; per-item failures ride in each item's error:

[
  {"result": 2500000, "error": null, "id": 0},
  {"result": null, "error": {"code": -32601, "message": "Method not found: no_such"}, "id": 1}
]

An empty batch ([]) is rejected with -32600. Batch items are processed sequentially, and the whole batch consumes a single work-queue slot.

Work queue

zecd bounds concurrent in-flight requests like bitcoind's -rpcworkqueue: at most [rpc] work_queue requests (default 100) are admitted; beyond that the server answers HTTP 503 Work queue depth exceeded without doing any work (the bound is enforced before authentication, so unauthenticated floods cannot starve real clients). During shutdown, new requests get 503 Request rejected during server shutdown. Both 503 bodies are plain text, not JSON.

Sends hold their slot for the whole call (a shielded send computes proofs for a few seconds), so a burst of concurrent sends can exhaust the queue; see Sending for the serialization semantics. getrpcinfo.active_commands shows what is executing right now.

Method safelist

[rpc] allowed_methods is an optional server-wide safelist. Empty (the default) serves every implemented method. Non-empty serves only the listed methods; anything else, implemented or not, is rejected with -32601 (HTTP 404), exactly as if it did not exist, so a locked-down server discloses nothing about the surface it disabled. Names are validated against the implemented method set at startup, so a typo is a fatal config error rather than a silently dead entry. The safelist check runs before argument validation, so a disabled method never leaks arity hints.

This is coarse and server-wide, not per-user. Its value is shrinking the blast radius of a leaked credential: an invoicing integration can be limited to getnewaddress plus read methods, keeping sendtoaddress and stop unreachable. The example config ships a commented-out safelist grouped by use case.

Method index

Every implemented method, with its Bitcoin Core status and nearest zcashd equivalent, is in the method index. Unimplemented bitcoind methods (including the label methods, removed deliberately) return -32601.

Method index: zecd vs bitcoind vs zcashd

Every RPC method zecd dispatches (58 methods as of 0.8.0, the ALL_METHODS table in src/rpc/mod.rs), compared against Bitcoin Core master and zcashd. Each method name links to its full reference entry.

Column legend:

• Bitcoin Core: ✓ = exists in current master with the semantics zecd mirrors; removed = no longer exists in current bitcoind (zecd keeps it for older clients); n/a = never existed there.
• zcashd: ✓ = same method name, compatible semantics; same name, differs = the name exists but the semantics diverge (usually transparent-only in zcashd, with a z_* method for shielded); n/a = no such method (nearest equivalent in parentheses). On chain and network rows a ✓ means zcashd serves the method with bitcoind's full-node semantics; zecd's wallet-scoped view (scanned heights, one Zebra "peer") is in the zecd column.

An [rpc] allowed_methods safelist, when set, answers -32601 for any method off the list, indistinguishable from a method that does not exist. Multiwallet routing (/wallet/<name>) is covered in Conventions & wire format.

Deliberately absent method families

These answer method-not-found (-32601), the same as any unknown method.

• Label methods (setlabel, getaddressesbylabel, listlabels, getreceivedbylabel, listreceivedbylabel): zecd keeps no off-chain label store, by the statelessness invariant. Embedded label/labels fields on other methods remain, always ""/[].
• Key import/export (dumpprivkey, importprivkey, importaddress, importpubkey, z_exportkey, z_importkey, z_exportviewingkey, z_importviewingkey): each wallet is one ZIP-32 account from one mnemonic; key material moves only through the CLI (zecd init, zecd export-ufvk), never over the RPC channel. See key custody and watch-only wallets.
• dumpwallet / backupwallet / importwallet: the backup is the mnemonic; everything else is rebuilt from seed plus chain, so there is no wallet file worth dumping.
• Wallet encryption RPCs (encryptwallet, walletpassphrasechange): at-rest encryption is set once at zecd init --encrypt, so the passphrase never crosses the network.
• Raw transaction construction (createrawtransaction, fundrawtransaction, signrawtransaction, decoderawtransaction, decodescript): shielded transactions cannot be assembled from public outpoints. sendrawtransaction still broadcasts externally built bytes.
• Mining (getblocktemplate, submitblock, generate, getmininginfo): zecd is a wallet server, not a validator; mine against the Zebra node.
• P2P management (addnode, disconnectnode, setban, listbanned, getnettotals, getaddednodeinfo): zecd has no P2P stack; its only peer is one Zebra node over JSON-RPC.

The help introspection gap

help <method> ignores its argument and returns a static one-line blurb naming only a few methods. bitcoind lists every command and returns per-method usage for help <method>, so tooling that introspects via help gets nothing useful from zecd today. Use this index and the per-category reference pages instead. (The blurb ends by pointing at the README for the full list, which is now a stub that points here; treat this index as the list it means.)

Wallet: addresses & keys

Reference for the address-generation, address-inspection, wallet-metadata, and lock/unlock methods. For the wire format, auth, and multiwallet /wallet/<name> routing, see Conventions & wire format; for background on Unified Addresses, diversified addresses, and pool configuration, see Addresses & shielded pools.

getnewaddress

getnewaddress ( "" address_type )

Returns a fresh receiving address for the wallet's account: a new diversified Unified Address (new diversifier, same account key), or a bare transparent address when requested. Works on watch-only wallets and on locked encrypted wallets (addresses derive from the viewing key, not the seed).

Parameters

With no address_type, the wallet's [pools] configuration decides: the default (Orchard-only) config returns an Orchard-only UA; a wallet with transparent_default = true returns a bare transparent address. Every requested shielded receiver must be a pool enabled on the wallet. "transparent" requires [pools] transparent = true and cannot be combined with shielded pool names (zecd hands out one receiver type at a time; ZIP-316 forbids a transparent-only UA, so the transparent receiver is bare-encoded as t1.../tm...).

There is no "ironwood" receiver. Ironwood notes are received at ordinary Orchard addresses, so an Orchard receiver is all a payer needs to send you ironwood funds. See Addresses & shielded pools.

Transparent addresses come from the gap-limited external chain. Once the recovery window is full of unfunded addresses, zecd by default issues past it with a loud log warning (such an address may be unrecoverable from seed); with [pools] transparent_allow_beyond_recovery_window = false it returns -4 instead. See Transparent support.

Result: the address as a JSON string.

"u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx"

Errors

The address_type syntax is validated before the wallet is resolved, so an unknown token is -5 regardless of which wallet is targeted; pool enablement is checked per wallet.

vs Bitcoin Core: same signature (label, address_type) and the same -5 Unknown address type '...' for a bad type, but zecd rejects a non-empty label with -8 where Core records it in the address book. The type values differ: pool names instead of legacy/p2sh-segwit/bech32/bech32m.

vs zcashd: zcashd's getnewaddress is deprecated and only produces transparent addresses; its shielded flow is z_getnewaccount + z_getaddressforaccount. zecd's getnewaddress is the primary shielded path.

z_getaddressforaccount

z_getaddressforaccount account ( ["receiver_type",...] diversifier_index )

Derives an address for the wallet's account in zcashd's syntax, optionally at an exact index. Unlike getnewaddress, the returned object includes the index, so a client can re-derive the same address deterministically later.

It serves two distinct cases depending on receiver_types:

• Shielded (the default). A Unified Address carrying the requested shielded receivers, indexed by ZIP-32 diversifier index.
• Transparent (["p2pkh"], new in 0.6.0). A bare t-address at a BIP 44 external child index. See transparent derivation below - the parameter is the same slot, but it means a different thing.

Parameters

Re-deriving at the same index with the same receiver set is idempotent (byte-identical response, zcashd's invariant). Requesting a different receiver set at an already-exposed index is a -4 reuse error. Auto-selected shielded indices are not sequential (the next-unused selection is clock-seeded; see Addresses & shielded pools), so record the returned diversifier_index if you need to re-derive. Transparent indices are sequential.

Transparent derivation at an explicit index

New in 0.6.0. On a wallet with [pools] transparent = true, z_getaddressforaccount 0 ["p2pkh"] N returns the bare t-address at BIP 44 external child index N.

Why the receiver set must be exactly ["p2pkh"]. ZIP-316 forbids a transparent-only unified address, and zecd never mixes a transparent receiver into a UA, so there is no address shape that could carry both. Asking for ["p2pkh", "orchard"] is therefore -8 rather than something zecd could silently reinterpret.

It shares the exposure path with sequential issuance. Deriving here and calling getnewaddress "" "transparent" run the same code, so the two agree by construction: the same recovery-horizon classification, the same warnings, the same -4 when transparent_allow_beyond_recovery_window = false would put the index out of restore range, and the same refresh of the address matcher. That last one matters - without it a payment to a directly addressed index would be silently dropped by the scanner. See Transparent support for the two windows involved.

Together with getaddressinfo's address_index, this closes the loop for an operator reconciling an issued range against the chain: ask for index N, and ask which index an address was.

Result

{
  "account": 0,
  "diversifier_index": 1000000,
  "receiver_types": ["orchard"],
  "address": "u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx"
}

Errors

Example

# The t-address at BIP 44 external child index 7.
curl -u u:p -d '{
  "jsonrpc": "1.0", "id": 1, "method": "z_getaddressforaccount",
  "params": [0, ["p2pkh"], 7]
}' http://127.0.0.1:8232/

vs Bitcoin Core: no equivalent.

vs zcashd: same syntax and result shape, and the reuse/no-address error strings match zcashd's wording under the same -4. Deliberate divergences: zcashd accepts any previously generated account number, zecd only account 0; zcashd can return a UA that includes a p2pkh receiver alongside shielded ones, while zecd treats ["p2pkh"] as a request for a bare t-address and rejects the mixture, because it never puts a transparent receiver in a UA.

getaddressinfo

getaddressinfo "address"

Returns ownership and validity details for an address. ismine is cryptographic, not just a lookup: after the recorded-address fast path, zecd attributes the address to the account's incoming viewing key by decrypting its diversifier, so an address the account can derive but never recorded (for example one handed out before a from-seed restore and never funded) still reports ismine: true. Bare transparent addresses are recognized via recorded addresses only.

Parameters

Result

{
  "address": "u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx",
  "scriptPubKey": "",
  "ismine": true,
  "solvable": true,
  "iswatchonly": false,
  "isscript": false,
  "iswitness": false,
  "isvalid_orchard": true,
  "receiver_types": ["orchard"],
  "labels": []
}

• scriptPubKey: the real hex script for transparent addresses; empty for shielded addresses, which have no script form.
• solvable: equals ismine, including on watch-only wallets (Core's definition ignores the lack of private keys; the wallet-level signal is getwalletinfo.private_keys_enabled).
• iswatchonly: always false, matching Core master where the field is deprecated.
• isvalid_orchard, receiver_types: zecd extensions mirroring validateaddress: whether the address carries an Orchard receiver, and the full list of pools it can receive into (transparent/sapling/orchard).
• labels: always [] (zecd is stateless; the field is kept for shape conformance).
• receivers_consistent (optional, extension): present only for a multi-receiver UA whose consistency against this wallet's keys is computable. false flags a hand-spliced UA (receivers from different diversifier indices, or one of ours mixed with a stranger's) that this wallet can never have issued.

Derivation fields for an own transparent address (new in 0.6.0)

On a bare t-address this wallet owns, three more fields report where it came from:

{
  "address": "tmEjFVCkiVKmTPMHtnFHYJgvvyRJvpUZ4nD",
  "ismine": true,
  "hdkeypath": "m/44'/133'/0'/0/7",
  "ischange": false,
  "address_index": 7,
  "receiver_types": ["transparent"]
}

• hdkeypath and ischange are Bitcoin Core's fields, with Core's meaning: the full BIP 44 path, and whether the address is on the internal (change) chain rather than the external one.
• address_index is a zecd extension carrying the BIP 44 child index on its own, so a caller does not have to parse it back out of the path string. It is the same index z_getaddressforaccount takes, which is what makes issuance and reconciliation a closed loop.

All three are absent for shielded addresses (a diversifier index is not a BIP 44 path) and for transparent addresses this wallet does not own.

diversifier_index (new in 0.8.0) is present on any address this wallet owns: the shielded diversifier index for a Unified or Sapling address, or the BIP 44 child index for a bare transparent one (the same number as address_index; ZIP 32 reuses it), so a caller need not branch on the kind. It is the index received history entries report, and the one z_getaddressforaccount takes, so storing it at issuance lets every later receipt be matched by integer rather than by address string. A shielded index can reach 2^88, so parse it as an arbitrary-precision integer.

Errors

vs Bitcoin Core: same core fields and the same -5 on an undecodable address, plus Core's hdkeypath/ischange on own transparent addresses. zecd still emits a subset overall: no desc/parent_desc, no pubkey fields, no timestamp. isvalid_orchard/receiver_types/receivers_consistent/address_index/diversifier_index are additions.

vs zcashd: no equivalent; zcashd has only validateaddress/z_validateaddress, with no ownership attribution for Unified Addresses in this shape.

getwalletinfo

getwalletinfo

Wallet metadata and balances. scanning reports sync progress and stays truthy while the transaction-enhancement backlog drains (the wallet is at the tip but still backfilling memos and full transaction data), not just during the block scan.

Result

{
  "walletname": "default",
  "walletversion": 169900,
  "format": "sqlite",
  "balance": 1.25000000,
  "unconfirmed_balance": 0.10000000,
  "immature_balance": 0.00000000,
  "txcount": 12,
  "keypoolsize": 1,
  "keypoolsize_hd_internal": 0,
  "paytxfee": 0.00000000,
  "private_keys_enabled": true,
  "avoid_reuse": false,
  "scanning": { "duration": 0, "progress": 0.9731, "pending_enhancements": 84 },
  "enhanced_through": 2912916,
  "descriptors": false,
  "unlocked_until": 1751629200
}

• balance/unconfirmed_balance/immature_balance: decimal ZEC, 8 places, under the wallet's confirmations policy. immature_balance carries transparent coinbase that has not yet reached the 100-block maturity. It is never counted as spendable and never appears in listunspent; once mature the value becomes shieldable with z_shieldcoinbase.

• keypoolsize is always 1 and keypoolsize_hd_internal always 0: addresses are diversified on demand from the account key; there is no key pool.

• paytxfee is always 0 (fees are ZIP-317, never client-settable).

• private_keys_enabled: false for a watch-only (imported UFVK) wallet; the wallet-level cannot-sign signal, as with Core's disable_private_keys wallets.

• scanning: an object (duration always 0, progress the block-scan ratio in [0,1]) while scanning or while the enhancement backlog is nonzero; false when idle.

• scanning.pending_enhancements (extension, 0.7.0): distinct outstanding transaction-data requests. progress is a [0,1] block-scan ratio and cannot express this open-ended work, and until 0.7.0 the count existed only on the health server's /status, which is unreachable for a default-features = false embedder and for anyone driving zecd purely over JSON-RPC. progress holds at 1.0 through the drain.

• enhanced_through (extension, 0.7.0): the height below which history is complete. It is the difference between "scanned to the tip" and "serving complete history", since a scanned but un-enhanced output still has a null memo.

  It is top-level rather than inside scanning deliberately: that object is Core's, and it is the literal false once the wallet is idle, which is exactly the moment a consumer following wallet history as a log is ready to advance its cursor, and therefore exactly when it needs this. Nesting it there would make the field unreachable at the only time it matters.

  null means "not currently determinable", which a consumer must read as hold the cursor, never as "everything is enhanced". waitforsync blocks until the backlog is empty and returns the same fields.

• import_error (extension, 0.8.0): present only when a fleet wallet's import failed; see waitforsync.

• fetch_memos (extension, 0.8.0): present, as false, only when [sync] fetch_memos = false. enhanced_through is then null, since it promises that memos at or below it are readable.

• descriptors: always false.

• unlocked_until: present only for passphrase-encrypted wallets; the unix time the wallet auto-relocks, or 0 while locked. Absent on unencrypted and watch-only wallets.

• transparent (extension): present only when [pools] transparent = true, so a shielded-only wallet's shape is unchanged. {"enabled": true, "default": <bool>, "gap_limit": <n>, "coinbase_balance": <amount>, "recovery_horizon": <n>}, plus the lookahead fields below and, when transparent_initial_scan is set, an initial_sync object {"exposed": <n>, "total": <n>, "complete": <bool>} for polling the address pre-exposure. See Transparent support.

• transparent.recovery_horizon / .lookahead_from / .lookahead_through / .restorable (extension): the two address windows, which are anchored differently and can disagree. recovery_horizon (transparent_initial_scan + transparent_gap_limit) is what a from-seed restore rediscovers within, anchored on funding, so handing an address out does not move it. lookahead_from/lookahead_through are the forward lookahead the running wallet scans ahead of its recorded addresses, both inclusive and anchored on exposure, so issuance does move them. They describe forward reach only: every address with a database row is matched too, including indices below lookahead_from. restorable is lookahead_from <= recovery_horizon, and false means the wallet is crediting addresses a from-seed restore would not rediscover, which is the field to alert on. The lookahead fields are absent until the matcher is first built, and lookahead_through/restorable are omitted when gap_limit is 0. See Two windows.

• transparent.coinbase_balance (extension): the unspent mature transparent coinbase value, the same number as getbalances.mine.coinbase. It is already inside balance, and is reported separately because no ordinary send can select it: consensus forbids a transaction spending transparent coinbase from having any transparent output.

vs Bitcoin Core: walletversion 169900 and format: "sqlite" match Core's values. Core master has dropped the balance/unconfirmed_balance/immature_balance/paytxfee fields from this method (balances live on getbalances); zecd still emits them, in the older Core shape. zecd omits Core's external_signer, blank, birthtime, flags, and lastprocessedblock (the latter appears on zecd's getbalances). The transparent block, enhanced_through, and scanning.pending_enhancements are additions.

vs zcashd: zcashd's getwalletinfo keeps the old pre-0.19 Core shape plus its own split (balance is transparent-only, with a separate shielded_balance), a real key pool (keypoololdest), and a settable paytxfee; zecd follows modern Core instead.

listwallets

listwallets

Returns the names of all loaded wallets: every [wallets.<name>] in the config (plus the default wallet) and, with a fleet enabled, every loaded fleet wallet. Target a specific wallet with the /wallet/<name> URL path, as in Bitcoin Core; see Conventions & wire format.

Result

["default", "watch1"]

vs Bitcoin Core: identical shape. Configured wallets are fixed at startup; only fleet wallets can be created, loaded and unloaded at runtime (below). At most one loaded wallet may hold spending keys.

vs zcashd: no equivalent (zcashd is single-wallet).

Fleet wallet management

New in 0.8.0, experimental. The four methods below manage fleet wallets: watch-only, shielded-only wallets defined by a viewing key, sharing shard databases. createwallet and loadwallet refuse with -4 unless [fleet] enabled = true, and these methods may change in a patch release while the fleet is experimental.

They follow Bitcoin Core's dialect where a Zcash wallet allows it. The difference is forced: Core creates a wallet that generates its own keys, while a monitored Zcash wallet is defined by the viewing key it is given, so createwallet requires one.

createwallet

createwallet "wallet_name" ( disable_private_keys blank passphrase avoid_reuse descriptors load_on_startup external_signer {"ufvk":..,"birthday":..} )

Onboard a view wallet without restarting the daemon. It writes the wallet's manifest, places it in a shard (opening a new one when none has room), and serves it immediately at /wallet/<name>. Its account is imported on the shard's next connected pass; until then its balances and history are empty and waitforsync reports imported: false.

Parameters

Result

{
  "name": "acct-00417",
  "warning": "the wallet is loaded; its balance and history are empty until the shard scans from its birthday"
}

Errors

vs Bitcoin Core: same name, result shape and positional flags, plus the options object carrying the viewing key and birthday. Every flag that would ask for a spending wallet is refused.

loadwallet

loadwallet "wallet_name"

Serve a fleet wallet that is provisioned but not loaded: one whose manifest was added while the daemon ran, or one unloadwallet dropped. A reloaded wallet's history is intact, since its account never left its shard.

Result

{ "name": "acct-00417", "warning": "" }

Errors

unloadwallet

unloadwallet ( "wallet_name" load_on_startup )

Stop serving a fleet wallet. Nothing is deleted: the manifest and the account stay, and the shard keeps scanning for the wallet, so unloading frees no scanning work and a restart or loadwallet serves it again. To retire a wallet for good, delete its manifest and rebuild its shard.

The wallet is named by the argument or by the /wallet/<name> endpoint. The arguments are validated before the wallet is resolved.

Result

{
  "name": "acct-00417",
  "warning": "the wallet is no longer served; its account stays in its shard and is still scanned, so unloading frees no scanning work, and a restart or loadwallet serves this wallet again"
}

Errors

vs Bitcoin Core: same shape and the same refusal when the endpoint and the argument disagree. load_on_startup = false is refused rather than silently ignored, since ignoring it would bring the wallet back at the next restart.

listwalletdir

listwalletdir

The wallets available on disk, loaded or not: the configured wallets plus every readable fleet manifest, sorted. Works with the fleet disabled, listing configured wallets only.

Result

{
  "wallets": [{ "name": "acct-00417" }, { "name": "default" }],
  "warnings": ["/var/lib/zecd/fleet/zec/wallets.d/acct-00999.toml: <reason>"]
}

warnings (zecd extension) names each manifest that could not be read, which is how an operator learns that a file they wrote is not being served. It is absent when there are none, so a healthy fleet gets Bitcoin Core's exact shape.

walletpassphrase

walletpassphrase "passphrase" timeout

Decrypts the seed of a passphrase-encrypted wallet into (mlocked) memory for timeout seconds, after which it auto-relocks. Re-running it resets the timer; a timeout of 0 relocks almost immediately. Only wallets created with zecd init --encrypt are passphrase-encrypted; there is no passphrase-setting or passphrase-changing RPC, so the passphrase is chosen at init and never crosses the network in any other call. See Key custody.

Before holding the seed unlocked, zecd verifies it derives the account's pinned UFVK; a mismatch (a replaced keys.toml or wallet database) fails with -4 and the wallet stays locked.

Parameters

Result: null.

Errors

Argument validation runs before the encryption-state check, so a negative timeout is -8 even on an unencrypted wallet.

Example

curl -u user:pass -d '{"jsonrpc":"1.0","id":1,"method":"walletpassphrase","params":["correct horse battery staple",600]}' http://127.0.0.1:8232/

vs Bitcoin Core: same semantics, the same 100,000,000-second clamp, and the same -14/-15 messages. zecd unlocks a seed (scrypt-derived key over an age-encrypted mnemonic) rather than a wallet.dat master key.

vs zcashd: same method and error codes, but zcashd has no timeout clamp, and its wallet encryption (encryptwallet/walletpassphrasechange) is an experimental feature disabled by default; zecd sets encryption once at init --encrypt.

walletlock

walletlock

Drops the decrypted seed immediately and cancels the pending relock. Subsequent sends fail with -13 ("unlock needed") until the next walletpassphrase.

The zeroization takes a fast path: wallet commands normally serialize through the per-wallet actor, so a lock queued behind a send that is mid-proof would wait out the whole proving window. walletlock instead zeroizes the shared in-memory seed immediately, bypassing the queue. The in-flight send already derived its spending key before proving, so it completes; any queued send then fails -13 at key derivation, which is the correct post-lock behavior. The actor still processes the lock command afterward as the authoritative writer of the relock deadline and published status.

Result: null.

Errors

vs Bitcoin Core: same semantics and the same -15 on an unencrypted wallet.

vs zcashd: same method; zcashd locks its wallet.dat master key, zecd zeroizes the in-memory seed.

Wallet: balances

Reference for the balance and received-by-address methods. All five are read-only: they run on short-lived SQLite connections that bypass the wallet actor, so they never block on a sync or an in-flight send. For the wire format, auth, and multiwallet /wallet/<name> routing, see Conventions & wire format.

Balances aggregate every pool the wallet holds funds in: Orchard, Sapling, Ironwood (once NU6.3 activates; those notes arrive at ordinary Orchard addresses, so no extra receiver is involved), and (when transparent receiving is enabled) transparent UTXOs. Amounts are bare JSON numbers in decimal ZEC, 8 places, exact (no float drift).

getbalance

getbalance ( "*" minconf include_watchonly avoid_reuse )

Returns the wallet's spendable balance. With no minconf, spendability follows the wallet's configured confirmations policy (ZIP-315 defaults: 3 confirmations for trusted notes, meaning your own change and every output of a transaction the wallet authored, 10 for third-party receipts; [spend] trusted_confirmations / untrusted_confirmations in the configuration). The no-argument result therefore always equals what a send can actually spend, and agrees with the -6 insufficient funds accounting on the send methods.

Parameters

Because the default policy is stricter than any single minconf, getbalance "*" 1 is always greater than or equal to getbalance.

Result

1.25000000

Errors

vs Bitcoin Core: same signature and the same -32 with the identical message for a bad dummy. Core's minconf defaults to 0 and its no-argument result is the trusted balance; zecd's default is the ZIP-315 policy, and minconf 0 is served as 1. include_watchonly and avoid_reuse are ignored (Core master also ignores include_watchonly).

vs zcashd: zcashd's getbalance is transparent-only; its shielded balances live in z_gettotalbalance / z_getbalanceforaccount. zecd's getbalance is the account-wide spendable total across all pools, so it is closer to z_getbalanceforaccount than to zcashd's getbalance. zcashd also accepts "" for the dummy and rejects a bad one with -8, and has extra inZat / asOfHeight arguments that zecd does not.

getbalances

getbalances

Returns the Bitcoin Core 0.19+ balance object. Everything reports under mine, including on a watch-only (UFVK) wallet: like Core's descriptor wallets, the addresses are the wallet's own and only signing is impossible, so there is no watchonly object.

Result

{
  "mine": {
    "trusted": 1.25000000,
    "untrusted_pending": 0.10000000,
    "immature": 0.05000000,
    "coinbase": 0.00000000
  },
  "lastprocessedblock": {
    "hash": "00000000012f2e9d7a9ba447d1da6a2c31ec26bd8d0a55a259d3ab1741e5cdcc",
    "height": 2412345
  }
}

• trusted: spendable under the wallet's confirmations policy; equals getbalance.
• untrusted_pending: received but not yet spendable under the policy; equals getunconfirmedbalance. Incoming 0-conf payments seen by the mempool stream land here.
• immature: change awaiting confirmation; unconfirmed change from your own sends reports here. For transparent coinbase held below the 100-block maturity, see getwalletinfo.immature_balance and Transparent support.
• coinbase (extension): the unspent mature transparent coinbase value, a subset of trusted by construction (see below).
• lastprocessedblock (Core 26+): the fully-scanned block the balances are anchored to, the same anchor as getblockcount. Omitted while the wallet has not yet scanned a block.

Why coinbase is broken out. Mature transparent coinbase is spendable value and counts toward trusted, but no ordinary send can select it: consensus requires a transaction that spends transparent coinbase to have no transparent output at all, so the wallet's coin selection skips those UTXOs. Without the field, getbalance could report funds that sendtoaddress then refused to spend, with nothing in the API explaining the difference. The same value is mirrored at getwalletinfo.transparent.coinbase_balance, and the -6 insufficient-funds message on the send methods names the mature-coinbase amount and points at shielding (z_shieldcoinbase) as the route that can move it.

vs Bitcoin Core: same shape minus Core master's mine.nonmempool and the optional mine.used (zecd has no avoid-reuse flag), plus the coinbase extension. The Core triple still totals the wallet (coinbase is a subset of trusted, not a fourth bucket), so a client reading only trusted/untrusted_pending/immature is unaffected. Core's legacy watchonly object is likewise gone from Core master; zecd never emits it.

vs zcashd: no equivalent. The nearest is z_gettotalbalance, which splits transparent/private/total rather than trusted/pending.

getunconfirmedbalance

getunconfirmedbalance

Returns value received but not yet spendable under the wallet's confirmations policy, across all pools. Identical to getbalances.mine.untrusted_pending. An incoming payment appears here at 0 confirmations via the mempool stream, before its funding block is scanned.

Result

0.10000000

vs Bitcoin Core: removed in Core 30.0 (its release notes point callers at getbalances.mine.untrusted_pending). zecd keeps it for older clients; prefer getbalances in new code.

vs zcashd: exists, but returns the unconfirmed transparent balance only; zecd's spans shielded pools too.

getreceivedbyaddress

getreceivedbyaddress "address" ( minconf include_immature_coinbase )

Returns the total received by one of the wallet's own addresses, summed over transactions with at least minconf confirmations. Internal change is not counted; a payment to one of the wallet's own external addresses is.

Matching is by diversifier index (since 0.8.0; 0.7.3 on the 0.7 line). Any encoding of an index the wallet owns answers with that index's receipts: the exact value getnewaddress returned, a re-encoding with a different receiver subset, or a single receiver of it. Before, matching was whole-string, and after a from-seed restore or zecd rescan the wallet's own getnewaddress address could answer 0.00000000 while the balance was correct. A bare transparent address is still its own key. A spliced UA (this wallet's receivers combined across diversifier indices, or mixed with a stranger's) is rejected with -5 rather than silently treated as foreign.

Parameters

Unlike getbalance, minconf 0 is meaningful here: this method totals receipts, not spendability.

Result

0.50000000

Errors

vs Bitcoin Core: same signature, same -4 Address not found in wallet for a foreign address, and the same treatment of include_immature_coinbase: immature transparent coinbase is left out of the total unless it is set.

vs zcashd: zcashd's getreceivedbyaddress covers transparent addresses only; shielded receipts are enumerated per-note by z_listreceivedbyaddress (a list, not a total). zcashd's extra inZat / asOfHeight arguments do not exist in zecd.

listreceivedbyaddress

listreceivedbyaddress ( minconf include_empty include_watchonly "address_filter" include_immature_coinbase )

Per-address received totals with the txids that paid them. With include_empty it also lists every address the wallet has generated, which makes it the address-enumeration idiom: zecd has no listaddresses, so listreceivedbyaddress 1 true is how you enumerate the wallet's known addresses. The set is what this wallet database has recorded; after a from-seed restore, handed-out addresses that were never funded are forgotten (zecd is stateless).

Parameters

Result

[
  {
    "address": "u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx",
    "amount": 0.50000000,
    "confirmations": 4,
    "label": "",
    "txids": [
      "1f5e1f7b9d0f0c2f0a3f4f4b8f9f6d3e2c1b0a998877665544332211ffeeddcc"
    ]
  }
]

• amount: total received by the address at minconf, decimal ZEC.
• confirmations: confirmations of the most recently counted payment (the minimum across the counted transactions); 0 for an empty entry.
• label: always ""; zecd keeps no labels, the field is retained for Core shape.
• txids: the counted transactions, [] for an empty entry.

Errors

vs Bitcoin Core: same parameter list and entry shape. address_filter is a plain string match, not validated: a filter that matches nothing (including an address the wallet has never seen) returns [], where Core rejects an invalid filter address with -4. label is always empty, and the by-label variants (listreceivedbylabel, getreceivedbylabel) are not implemented (-32601).

vs zcashd: zcashd's listreceivedbyaddress is transparent-only and rejects a non-default addressFilter; per-address shielded receipts come from z_listreceivedbyaddress (one entry per note, with memos). zecd folds all pools into the one Core-shaped method; for per-output history with memos use z_listtransactions.

Example

curl -s --user u:p --data-binary \
  '{"jsonrpc":"1.0","id":"1","method":"listreceivedbyaddress","params":[1,true]}' \
  http://127.0.0.1:8232/

Wallet: history & unspent

Reference for the wallet history and unspent-output methods: listtransactions, z_listtransactions, listsinceblock, gettransaction, and listunspent. All five are read-only: they run on short-lived SQLite connections and never block on the sync loop.

Shared conventions

These apply to every method on this page.

• Categories. Only send and receive are emitted. A self-transfer (a payment to one of the wallet's own external addresses) appears as Bitcoin Core's send + receive pair. True change (internal key scope) is hidden from history but still counted in balances and listunspent. Core's coinbase categories (generate/immature/orphan) never appear.

• Confirmations are anchored to the wallet's fully-scanned height, the same height getblockcount reports, so getblockcount() - blockheight + 1 agrees with the field. An expired unmined transaction reports -1 (it can never confirm; Core's "conflicted" signal, so pollers terminate).

• time / timereceived are the block time once mined. For an unmined transaction they are the wall-clock time the wallet first saw it in the mempool, held in a transient in-memory map (never persisted; see statelessness), falling back to the creation time for wallet-authored sends. After a restart, an unmined foreign transaction reports 0 until the mempool stream re-observes it or it mines. The two fields are always equal.

• memo / memoStr are extension fields beyond Bitcoin Core's set, using zcashd's z_viewtransaction names: memo is the raw stored memo bytes in hex, memoStr the decoded text when the memo is a valid ZIP-302 text memo. An output carrying no memo, or the canonical empty memo every memoless shielded output carries, adds neither field.

  memo is emitted from the stored bytes and does not depend on the ZIP-302 parse succeeding; only memoStr does. The two are different questions: a memo whose lead byte is at or below 0xF4 is declared to be UTF-8 text, but nothing on the consensus side enforces that, so a protocol embedding arbitrary bytes in that lead-byte space produces a memo that fails the parse while still being perfectly good data. Through 0.6.3 the hex field was gated on that parse, so such a memo came back with no memo, no memoStr and no error, which is indistinguishable from an output that carried none. Fixed in 0.6.4: an absent memo field now means "no memo", never "unparseable memo". If you built a workaround that fetches the raw transaction to recover memos this dropped, you can retire it.

• Outgoing address is the single receiver actually paid, not the full Unified Address the caller typed. A multi-receiver UA is sender-side metadata that never reaches the chain, so history reduces each outgoing output to the paid receiver (a bare t/zs address, or a single-receiver UA for Orchard). This makes history identical on the authoring instance and after a restore-from-seed. Since 0.8.0 received entries follow the same rule, so a payer and a payee print the same string for one output (byte-identical to the issued address under the default Orchard-only receivers). See statelessness.

• diversifier_index (new in 0.8.0, zecd extension) is on receive entries in listtransactions, listsinceblock, z_listtransactions and gettransaction.details: the index of the wallet's own address the output landed on. Every encoding of an address shares it, and the scanner recovers it from the note, so it is identical after a from-seed restore. Store the index at issuance (z_getaddressforaccount returns it, getaddressinfo reads it back) and match receipts by integer. Send entries, including the send half of a self-transfer, never carry it: a recipient's index is theirs. A shielded index can reach 2^88, so parse it as an arbitrary-precision integer.

• With [sync] fetch_memos = false (0.8.0), memo and memoStr are omitted everywhere, not only where a fetch was skipped. See configuration.

• label is always "" and walletconflicts always []: zecd keeps no address labels and tracks no conflict set. bip125-replaceable is always "no" (Zcash has no RBF).

• Amounts are bare JSON numbers in decimal ZEC, 8 places.

• History ordering is total, and is a contract. For the four history methods (listtransactions, z_listtransactions, listsinceblock, gettransaction, but not listunspent, which builds its list from the note and UTXO sets and promises no order), results are ordered by height, then transaction id, then output pool, then output index. Height alone is not injective, since a block holds many wallet transactions, so through 0.6.3 two transactions mined at the same height came back in whatever order SQLite happened to produce. That was stable enough within one call and not stable across calls, which meant a count/from page boundary landing inside a same-height tie could show a transaction twice or skip it entirely between adjacent pages. Fixed in 0.6.4. A consumer replaying history as a log therefore gets a stable (height, txid, pool, outindex) sequence and can resume from the last entry it processed. The transaction-id comparison is over the stored internal byte order, which is an arbitrary but stable permutation of display order; do not read it as alphabetical by displayed txid. Reversing the order (newest-first) reverses the height and txid keys together, leaving the within-transaction output order unchanged.

listtransactions

listtransactions ( "label" count skip include_watchonly )

The most recent wallet history entries, one entry per non-change output, oldest-to-newest. Covers shielded notes and (when enabled) transparent outputs in one list.

Parameters

Result

[
  {
    "address": "u1a7pqnnzcdev3ka5jyv2q0kag0k8qvyw2s0z1erdhfmwzmp8dip5rk5632cxutlyf6jz062cu5qnkcs2857vy0mnhxen8993rvxmqedqu",
    "category": "receive",
    "amount": 1.25000000,
    "label": "",
    "vout": 0,
    "confirmations": 12,
    "txid": "8ab1c74952e723459d5e18b975bff21af07a90ba1eec368bcb2d3d6d7b0e0c17",
    "bip125-replaceable": "no",
    "memo": "696e766f6963652034322070616964",
    "memoStr": "invoice 42 paid",
    "blockhash": "0000000001d4f81c8494ba9cd02c0ea936f1ba52e6a186a538d3c3e2ab5b91f7",
    "blockheight": 2914301,
    "blockindex": 1,
    "blocktime": 1751581200,
    "walletconflicts": [],
    "time": 1751581200,
    "timereceived": 1751581200
  },
  {
    "address": "u1v40svyy8lqhy4gyq5vysyz39yqwf4ypw9zvhqjmwlqk9vqvyfrgc6yz6e2spwwrjxpwyfwjt3u4nrpydp0hnzqge0ptr9y8yavgvpr7ux",
    "category": "send",
    "amount": -0.50000000,
    "label": "",
    "vout": 0,
    "confirmations": 3,
    "txid": "e37b006aa754e982f2c19152fbd80f26e6a3fe9c418b1ce3f5aab3ad4d7e9b52",
    "bip125-replaceable": "no",
    "abandoned": false,
    "fee": -0.00015000,
    "blockhash": "00000000023a1b6d81c62f1c22f0a3e9a83f6de960e60d357ce09b3c73ef14a8",
    "blockheight": 2914310,
    "blockindex": 2,
    "blocktime": 1751583450,
    "walletconflicts": [],
    "time": 1751583450,
    "timereceived": 1751583450
  }
]

• Sends are negative (Core's sign convention); fee (negative) and abandoned appear on send entries only. abandoned is true for an expired unmined send.
• Mined entries carry blockhash/blockheight/blockindex/blocktime; unmined entries carry trusted instead (true iff the wallet authored the transaction and it can still be mined).

Errors

vs Bitcoin Core: same arguments and paging (count most recent after skipping skip from the newest end, returned oldest-first). Entries omit wtxid and parent_descs; abandoned appears only on send entries (Core master also puts it on receives); categories are limited to send/receive; memo/memoStr are extensions.

vs zcashd: zcashd's listtransactions covers transparent activity only (shielded receipts need per-address z_listreceivedbyaddress) and adds amountZat, status, and expiryheight to each entry. zecd lists shielded and transparent activity in one Core-shaped list; use z_listtransactions for the zcashd vocabulary.

z_listtransactions

z_listtransactions ( count from includeWatchonly )

A zecd extension (no such method exists in zcashd or Bitcoin Core): per-output wallet history in zcashd's z_* vocabulary. Same content as listtransactions, different field names, plus the value pool and zatoshi amounts. Pagination is identical (newest-first cursor, oldest-first output).

Parameters

There is no account or address argument: results span the wallet's single account.

Result

[
  {
    "txid": "e37b006aa754e982f2c19152fbd80f26e6a3fe9c418b1ce3f5aab3ad4d7e9b52",
    "status": "mined",
    "confirmations": 3,
    "time": 1751583450,
    "walletconflicts": [],
    "pool": "orchard",
    "category": "send",
    "amount": -0.50000000,
    "amountZat": -50000000,
    "address": "u1v40svyy8lqhy4gyq5vysyz39yqwf4ypw9zvhqjmwlqk9vqvyfrgc6yz6e2spwwrjxpwyfwjt3u4nrpydp0hnzqge0ptr9y8yavgvpr7ux",
    "outindex": 0,
    "change": false,
    "outgoing": true,
    "blockhash": "00000000023a1b6d81c62f1c22f0a3e9a83f6de960e60d357ce09b3c73ef14a8",
    "blockheight": 2914310,
    "blockindex": 2,
    "blocktime": 1751583450,
    "expiryheight": 2914350,
    "fee": -0.00015000,
    "feeZat": -15000
  }
]

• pool is transparent, sapling, orchard, or ironwood. ironwood appears once NU6.3 activates (testnet). Those notes arrive at ordinary Orchard addresses, so pool labels the note's bundle, not a distinct receiver. See Addresses & shielded pools.
• status is mined, waiting, or expired. zcashd's fourth value expiringsoon is never emitted.
• amountZat is an integer (zatoshis), negative on sends; outgoing is true on the send side of a self-transfer pair.
• change is always false (change outputs are filtered before this point; the key is kept for shape compatibility with zcashd's walletInternal/change convention).
• expiryheight appears when the transaction has a non-zero expiry; fee/feeZat (negative) on send entries only; memo/memoStr on shielded outputs as elsewhere.

Errors

vs Bitcoin Core: no equivalent; this is the zcashd-vocabulary view of the same history listtransactions serves.

vs zcashd: zcashd has no z_listtransactions. The entry shape borrows from z_listreceivedbyaddress (pool/amount/amountZat/memo/memoStr/outindex/change/ block fields), z_viewtransaction (outgoing), and zcashd's per-transaction status/expiryheight. Unlike z_listreceivedbyaddress it is not per-address and includes sends; unlike z_viewtransaction it is a flat paged list, not a per-transaction spends/outputs breakdown.

listsinceblock

listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed )

The restart-safe payment poller: every wallet transaction in blocks after blockhash (plus all unmined transactions), and a lastblock cursor to feed into the next call.

Parameters

Result

{
  "transactions": [],
  "removed": [],
  "lastblock": "0000000001d4f81c8494ba9cd02c0ea936f1ba52e6a186a538d3c3e2ab5b91f7"
}

transactions entries have exactly the listtransactions shape (no label filter applies). removed is always empty: reorged-away transactions are rescanned and re-reported by the sync engine rather than tracked separately. lastblock is the hash of the block that currently has target_confirmations confirmations, anchored to the fully-scanned height; when the requested depth predates the wallet's scan range it falls back to the earliest scanned block, and a wallet with nothing scanned returns the all-zero hash.

Cursor semantics after a reorg. zecd keeps only the current chain's scanned blocks, so it cannot walk a stale cursor back to the fork point the way Bitcoin Core's findCommonAncestor does. Instead, a well-formed 64-hex hash that is not among the wallet's scanned blocks (a reorged-away cursor, or one below the wallet birthday) is treated as "since the earliest scanned block": everything is listed. A lower cursor only ever re-reports, never misses, so the poller self-heals instead of wedging. Only a malformed hash, which can never be a cursor zecd handed out, is a -5 Block not found. Consequence for integrators: process listsinceblock output idempotently, keyed by txid. A target_confirmations of, say, 6 keeps re-reporting transactions until they reach 6 confirmations, which is the intended Core usage pattern and absorbs the re-baseline case for free.

Errors

vs Bitcoin Core: same cursor pattern and lastblock semantics. Core walks a stale hash back to the fork point and can populate removed; zecd re-baselines to the earliest scanned block and keeps removed always []. Core master's two extra positional arguments (include_change, label) exceed zecd's four-argument arity and are rejected with -1.

vs zcashd: zcashd's listsinceblock is the inherited transparent-only Bitcoin method; zecd's covers shielded activity too and adds the reorg re-baseline behavior above.

gettransaction

gettransaction "txid" ( include_watchonly verbose )

Detailed information on one wallet transaction: net amount, per-output details, and the raw hex.

Parameters

Result

{
  "amount": -0.50000000,
  "fee": -0.00015000,
  "confirmations": 3,
  "txid": "e37b006aa754e982f2c19152fbd80f26e6a3fe9c418b1ce3f5aab3ad4d7e9b52",
  "bip125-replaceable": "no",
  "details": [
    {
      "address": "u1v40svyy8lqhy4gyq5vysyz39yqwf4ypw9zvhqjmwlqk9vqvyfrgc6yz6e2spwwrjxpwyfwjt3u4nrpydp0hnzqge0ptr9y8yavgvpr7ux",
      "category": "send",
      "amount": -0.50000000,
      "vout": 0,
      "pool": "ironwood",
      "label": "",
      "abandoned": false,
      "fee": -0.00015000
    }
  ],
  "hex": "050000800a27a726b4d0d6c2...",
  "blockhash": "00000000023a1b6d81c62f1c22f0a3e9a83f6de960e60d357ce09b3c73ef14a8",
  "blockheight": 2914310,
  "blockindex": 2,
  "blocktime": 1751583450,
  "walletconflicts": [],
  "time": 1751583450,
  "timereceived": 1751583450
}

• amount is fee-exclusive, per Core: for a wallet-funded transaction it is the negated sum of payments (the balance delta with the fee added back); for a pure receive it is the received amount; a self-transfer nets to 0.
• fee (negative) appears only when the wallet funded the transaction. librustzcash records a derived fee even on pure receives, but zecd gates the field on the balance-delta signal so a deposit is never reported with a fee the wallet did not pay.
• details has one entry per non-change output and category, with the listtransactions entry shape minus the per-transaction fields (confirmations, txid, times), which sit at the top level. memo/memoStr appear per detail entry.
• details[].pool (extension, 0.7.0): "transparent", "sapling", "orchard" or "ironwood". vout is the output index within its own pool's bundle, not a transparent outpoint index, so on a transaction with outputs in more than one pool (txid, vout) does not identify an output. (txid, pool, vout) does, which is the key a consumer following listsinceblock as an incremental cursor reaches for. History entries already carried pool; this brings details into line with them.
• hex is the stored raw transaction when the wallet has it (wallet-authored sends, and receives stored via the mempool stream or the enhancement pass). For a transaction the wallet only ever saw as a compact block, the bytes are fetched on demand from the chain backend. The fetch is best-effort: an unreachable upstream yields "", not an error.
• Mined/unmined block fields and trusted follow the shared conventions above.

Errors

vs Bitcoin Core: same top-level shape; omits wtxid, parent_descs, generated, comment, and (since verbose is ignored) decoded. fee appears only on wallet-funded transactions, as in Core. details entries add memo/memoStr and pool.

vs zcashd: zcashd's gettransaction reports the transparent parts and defers shielded detail to z_viewtransaction. zecd's details cover shielded outputs (with memos) directly; there is no separate z_viewtransaction.

listunspent

listunspent ( minconf maxconf ["address",...] include_unsafe query_options )

The wallet's unspent funds in Bitcoin Core's UTXO shape: every unspent shielded note (all enabled pools) plus, for transparent-enabled wallets, every unspent transparent UTXO.

Parameters

Result

[
  {
    "txid": "8ab1c74952e723459d5e18b975bff21af07a90ba1eec368bcb2d3d6d7b0e0c17",
    "vout": 0,
    "address": "u1a7pqnnzcdev3ka5jyv2q0kag0k8qvyw2s0z1erdhfmwzmp8dip5rk5632cxutlyf6jz062cu5qnkcs2857vy0mnhxen8993rvxmqedqu",
    "amount": 1.25000000,
    "confirmations": 12,
    "spendable": true,
    "solvable": true,
    "safe": true
  }
]

• Synthesized outpoints for notes. Shielded notes are not bitcoin-style outpoints, so (txid, vout) is synthesized: vout is the note's index within its pool's bundle (the Sapling output index or the Orchard action index). It identifies the note stably but cannot be fed to raw-transaction spending. Transparent UTXOs carry their real (txid, vout) and a bare t-address.
• address is the receiving diversified address when the wallet recorded one. Change and internal notes report "", which an addresses filter never matches, so a filtered call naturally excludes change.
• generated rides on transparent entries, carrying zcashd's meaning: true when the output came from a coinbase transaction, false otherwise. Shielded notes have no such field. Immature coinbase is not listed at all: a coinbase UTXO with fewer than 100 confirmations is excluded from listunspent entirely, matching Bitcoin Core's AvailableCoins, and its value is reported in getwalletinfo.immature_balance until it matures. A mature coinbase entry does appear, but consensus forbids spending it into any transparent output, so the only way to spend it is z_shieldcoinbase; the ordinary send paths never select it. See Transparent support.
• safe is true for confirmed outputs and for unconfirmed outputs whose creating transaction the wallet itself authored (its own change or self-send); a foreign output surfaced at 0-conf by the mempool stream is safe: false. include_unsafe: false hides those.
• spendable and solvable are always true. They are nominal: whether a send can actually select an output is governed by the wallet's confirmations policy ([spend] trusted_confirmations/untrusted_confirmations, ZIP-315 defaults 3/10), so an entry with 1 confirmation can appear here while a send still returns -6 until it reaches policy depth (see Sending). A transparent UTXO is additionally spendable only under the AllowFullyTransparent privacy policy; under the default policy it is receive-only (see Transparent support).

Errors

vs Bitcoin Core: same arguments and filtering; entries omit label, scriptPubKey, redeemScript, desc, and parent_descs (shielded notes have no script form). query_options is accepted but has no effect, where Core applies minimumAmount and friends. generated is an addition (Core carries it on gettransaction, not here), but the immature-coinbase exclusion follows Core's AvailableCoins exactly. The synthesized note outpoints are the largest semantic difference; see Compatibility boundary.

vs zcashd: zcashd splits this surface into listunspent (transparent) and z_listunspent (shielded, with pool/outindex/memo/change per note). zecd merges both into one Core-shaped list; for pool and memo detail use z_listtransactions. The generated flag on transparent entries is zcashd's, with zcashd's meaning.

Sending

Reference for the synchronous send methods sendtoaddress and sendmany. For the asynchronous zcashd-style methods (z_sendmany, z_shieldcoinbase, and the operation-tracking trio), see async operations.

Send semantics

Everything in this section applies to both methods.

Synchronous. The call builds the transaction, computes the Orchard proof, commits it to the wallet, and broadcasts it, all inside the HTTP request; the txid returns only after broadcast is attempted. Unlike bitcoind's millisecond sends, the proof takes on the order of seconds (far longer in debug builds), plus any queueing behind other sends. Set client-side send timeouts well above that. A client that times out and blindly retries a send that actually succeeded pays twice: on timeout, reconcile with listtransactions before retrying. Once the transaction is committed, a transport failure during initial relay does not surface as an error; the txid is returned and a background loop rebroadcasts until the transaction mines or expires. Only an explicit rejection by the Zebra node returns an error (-26), and the spent notes stay locked until the transaction's expiry height.

Sends serialize per wallet. Each wallet is owned by a single-writer actor, the analog of Bitcoin Core's cs_wallet: concurrent sends to one wallet are processed one at a time and never select the same note, so there is no double-spend and no note-locking API to manage. Queued sends hold their HTTP connection longer.

Fees are ZIP-317, never client-settable. The wallet computes the conventional fee; there is no estimator and no fee knob. subtractfeefromamount (sendtoaddress) and subtractfeefrom (sendmany) are rejected with -8 when engaged, because silently ignoring them would move different amounts than the caller intended. fee_rate is rejected with -8 for the same reason. These guards fire before any wallet access, so passing the defaults (false, null, []) still works. conf_target and estimate_mode are estimation hints and are silently ignored; settxfee always returns -8.

Insufficient funds is self-diagnosing. Shielded change is unspendable until it confirms (3 confirmations for trusted change by default, see configuration), so rapid back-to-back sends exhaust spendable notes and return -6 until a block arrives. The -6 message appends any balance awaiting confirmations, so a client can tell "retry after the next block" from "the wallet needs funding":

Insufficient funds: 0 zatoshis spendable, 10001000 required (including fee);
awaiting confirmations: 0 zatoshis incoming, 49990000 zatoshis change

Change is split into several notes. A send leaves up to [spend] target_note_count change notes (default 4) rather than one, so the next send has several notes to spend in turn instead of serializing on one note's confirmation depth. The split only happens above [spend] min_split_output_value (default 0.1 ZEC), since splitting a small balance into dust helps nobody. Both were hard-coded before 0.7.0 and are now configurable; the defaults are the old hard-coded values, so nothing changes unless you set them. A deployment built on small balances is the case that wants the floor lowered: below it, one change note comes back, and back-to-back sends then hit the -6 above.

Consolidating the other direction. Many small notes and UTXOs accumulate on a wallet that receives a lot of payments, and no send method gathers them up, because they all select inputs to cover an amount you name. z_mergetoaddress, new in 0.7.0, is the sweep that does.

Coinbase inputs are never selected here. Consensus forbids a transaction that spends a transparent coinbase output from having any transparent output, change included, so the transparent-to-transparent path (which always writes transparent outputs) skips coinbase UTXOs entirely; selecting one would build a consensus-invalid transaction. Mature transparent coinbase is spendable only by shielding it with z_shieldcoinbase, which moves the whole selected value into a single shielded output. Coinbase below the 100-block maturity is not spendable at all: it is excluded from listunspent and reported in getwalletinfo.immature_balance.

Because that value still counts toward getbalance, the -6 insufficient-funds message names the mature-coinbase amount and points at z_shieldcoinbase, so a balance the wallet reports but refuses to spend explains itself. The same amount is readable as getbalances.mine.coinbase and getwalletinfo.transparent.coinbase_balance.

Privacy policy is enforced per recipient. Under the wallet's configured [spend] privacy_policy (default AllowRevealedRecipients), a recipient with no shielded receiver (a bare t1/t3 address) is rejected up front with -8 when the policy is FullPrivacy or AllowRevealedAmounts. FullPrivacy additionally rejects, on the built proposal, any send that crosses a turnstile between two shielded pools (Sapling, Orchard and Ironwood are three distinct pools). Neither method takes a per-call policy argument; the config value applies. See the privacy policy ladder.

Neither method selects a funding source. They have no fromaddress, so they spend the account's shielded notes, with the one legacy exception below. Spending transparent UTXOs, and shielding them, is z_sendmany's fromaddress.

Action limit. [spend] orchard_action_limit (default 50, 0 disables) caps the Orchard actions of a single send to bound its memory and proving cost. The count is per bundle and summed, as the builder proves them: since NU6.3 a send that spends legacy Orchard notes into Ironwood outputs builds two bundles, so it can be refused with far fewer recipients than the cap. A proposal that exceeds it returns -8 naming the count, and the two bundles when there are two. Consolidate with z_mergetoaddress, or raise the cap and send SIGHUP, which reloads it without a restart (since 0.8.0).

Common errors (both methods; verified in the handlers and src/error.rs):

sendtoaddress

sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode" avoid_reuse fee_rate verbose "memo" )

Pay one recipient from the wallet's shielded notes (or, under AllowFullyTransparent with a transparent recipient, from transparent UTXOs; see transparent). Returns the txid after proving and broadcast.

Parameters

Result

"85a13a0895c9ef2e26b1a29321581e19b6cb51b0e6b1e4f0d68f4d5cba1b7f4e"

With verbose = true (fee_reason is always the ZIP-317 conventional fee):

{
  "txid": "85a13a0895c9ef2e26b1a29321581e19b6cb51b0e6b1e4f0d68f4d5cba1b7f4e",
  "fee_reason": "ZIP 317"
}

Errors (beyond the common table)

vs Bitcoin Core

Parameter positions 1-11 match Core master's sendtoaddress exactly (verified against src/wallet/rpc/spend.cpp), including the verbose result shape. Differences: comment/ comment_to are accepted but never stored; subtractfeefromamount and fee_rate are hard -8 rejections instead of honored; replaceable/conf_target/estimate_mode/ avoid_reuse are ignored; position 12 (memo) does not exist in Core.

vs zcashd

zcashd retains sendtoaddress but as a transparent-only legacy method: it selects funds exclusively from the transparent pool, its help says "THIS API PROVIDES NO PRIVACY", and it takes only 5 arguments (through subtractfeefromamount, which it honors). The recommended zcashd send is z_sendmany. zecd inverts this: sendtoaddress is the primary, shielded send, and its memo parameter follows z_sendmany's conventions (hex, 512-byte cap). Unlike z_sendmany, zecd's sendtoaddress keeps Core's rejection of zero amounts (-3), so a memo-only send needs z_sendmany.

Example

curl -u u:p --max-time 120 -d '{
  "jsonrpc": "1.0", "id": 1, "method": "sendtoaddress",
  "params": ["u1abc...", 0.1, "", "", false, false, null, "", false, null, false,
             "74616b652074686520686f626269747320746f2069736574686172"]
}' http://127.0.0.1:8232/

sendmany

sendmany "" {"address":amount,...} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode" fee_rate verbose )

Pay several recipients in one transaction: one ZIP-317 fee, one anchor. Recipients may mix shielded and transparent addresses (under the default policy a transparent recipient is paid from shielded notes, with shielded change).

Parameters

Duplicate recipient keys collapse silently. Recipients arrive as a JSON object, and JSON parsing keeps only the last occurrence of a duplicated key before zecd sees it, so listing the same address twice sends only the last amount. Bitcoin Core's Invalid parameter, duplicated address error cannot be reproduced here. Do not list an address twice; combine the amounts instead. (z_sendmany, whose recipients are an array, does reject duplicates with -8.)

Transparent-to-transparent spends. sendmany has no per-call privacy argument, so its only route to a fully transparent spend (transparent UTXOs in, transparent change) is the [spend] privacy_policy = "AllowFullyTransparent" config knob, and it engages only when every recipient is a bare transparent address. Under the default policy a wallet holding only transparent funds gets -6. See transparent.

Result

Same shape as sendtoaddress: a bare txid string, or {"txid", "fee_reason"} with verbose = true.

Errors (beyond the common table)

vs Bitcoin Core

Parameter positions 1-10 match Core master exactly (verified against src/wallet/rpc/spend.cpp); Core also treats minconf as an ignored dummy. Differences: zecd never validates the dummy argument (Core returns -8 for a non-empty one), rejects subtractfeefrom/fee_rate with -8 instead of honoring them, and does not store the comment.

vs zcashd

zcashd's sendmany is a discouraged transparent-only legacy method ("Prefer to use z_sendmany instead"); it takes 5 arguments, honors minconf, and honors subtractfeefromamount. zecd's nearest zcashd equivalent for a multi-recipient shielded send is z_sendmany, which zecd also implements (async operations) with per-output memos, a per-call minconf and privacyPolicy, and zero-amount outputs.

Example

curl -u u:p --max-time 120 -d '{
  "jsonrpc": "1.0", "id": 1, "method": "sendmany",
  "params": ["", {"u1abc...": 0.05, "t1M72Sfpbz1BPpXFHz9m3CdqATR44Jvaydd": 0.02}]
}' http://127.0.0.1:8232/

Async operations

Reference for z_sendmany, z_shieldcoinbase, z_mergetoaddress, and the operation-tracking trio z_getoperationstatus / z_getoperationresult / z_listoperationids. These six methods adopt zcashd's asynchronous send model: they match zcashd's syntax, status shapes, and state strings, so clients written for zcashd's z_sendmany work unchanged. For synchronous sends in Bitcoin Core's dialect, see Sending.

A seventh method, z_waitforoperation, is a zecd extension with no zcashd counterpart: it blocks until one operation finishes, so a client does not have to write a poll-sleep loop.

The operation model

z_sendmany, z_shieldcoinbase and z_mergetoaddress validate their arguments, then return an operation id (opid- followed by a UUID, identical to zcashd) immediately. The transaction is selected, proved, and broadcast on a background task; its outcome is fetched later through the tracking methods. The background task still funnels through the wallet's single-writer actor, so an async send cannot double-spend against a concurrent sendtoaddress (see Architecture).

An operation moves through the zcashd state strings queued, executing, and then success or failed. The cancelled state exists in the schema (and as a z_listoperationids filter) for zcashd compatibility, but zecd has no cancellation path, so no operation ever reports it.

Properties of the registry:

• In-memory and transient. Operations are lost on restart, exactly as in zcashd. A send that was already committed to the wallet DB still broadcasts via the rebroadcast loop even if its status object is gone; only the tracking record is lost. This is one of the two deliberate transient exceptions to zecd's statelessness invariant.

• Wallet-scoped. Each operation is tagged with the wallet that created it. The tracking methods, routed per-wallet via /wallet/<name>, only ever see their own wallet's operations, even when an opid from another wallet is named explicitly (it is silently omitted). zcashd's queue is node-wide; zcashd only has one wallet.

• Poll, wait, or reap. z_getoperationstatus is non-destructive: call it as often as you like. z_waitforoperation is also non-destructive, and blocks instead of returning immediately, which is usually what you want for a single send. z_getoperationresult is destructive and one-shot: it returns each finished operation's status once and removes it; a second call for the same opid returns nothing. This matches zcashd exactly. Waiting never reaps, so a wait followed by a z_getoperationresult still gets the result.

• Bounded. Two caps protect the daemon from an authenticated flood of z_sendmany:

  • At most 1024 operations are retained. Past that, the oldest finished results are auto-evicted (logged at WARN). A client that never reaps cannot wedge the daemon; the only cost is that old unread status objects may be discarded (the transactions themselves already broadcast).
  • At most 16 unfinished (queued + executing) operations per wallet. An in-flight operation owns a real pending send and cannot be evicted, so past this cap new async-send calls are rejected with -4 back-pressure until some finish. Finished operations never count toward this cap, so forgetting to reap never blocks new sends.

  zcashd has neither cap. Sends serialize on the wallet actor regardless, so 16 in flight is far above any useful concurrency.

z_sendmany

z_sendmany "fromaddress" [{"address":..,"amount":..,"memo":..},...] ( minconf ) ( fee ) ( privacyPolicy )

Send to one or more recipients asynchronously. Returns an opid immediately; the outcome (txid or error) surfaces through the tracking methods.

fromaddress selects the funding source, as it does in zcashd:

A transparent source requires privacy policy AllowRevealedSenders or weaker, since spending transparent inputs reveals the sender's addresses and amounts; see the privacy policy ladder. Paired with a shielded recipient it is the shielding (t-to-z) send: the payment and the change both land in the shielded pool, which is how received transparent funds get shielded. Paired with an all-transparent recipient set it is a fully transparent transaction and additionally needs AllowFullyTransparent.

One source funds one send. Shielded notes and transparent UTXOs are never mixed, so if the named source cannot cover the payment the operation fails -6 rather than quietly topping up from the other pool. Transparent coinbase is never selected here; it is z_shieldcoinbase's alone, because consensus forbids a transparent output in a transaction spending it.

Shielded coin control is per account, not per address: notes are account-scoped, so a shielded fromaddress names the account and any of the wallet's shielded addresses selects the same notes.

Parameters

privacyPolicy accepts every zcashd policy name and maps it onto zecd's five-rung ladder:

Since 0.6.1 AllowRevealedSenders is a rung of its own; earlier versions accepted the name and treated it as AllowRevealedRecipients.

Result

"opid-9c2f0d61-1c2b-4f3e-9a3e-2d4b8c7a5e10"

Only argument validation fails synchronously. Everything downstream, including -6 insufficient funds, a locked wallet, the -4 "Private keys are disabled" refusal on a watch-only wallet, proving failures, and broadcast rejection, surfaces later in the operation's error object, never as an error on this call. So do the two size bounds checked when the transaction is planned: a send over [spend] orchard_action_limit or [spend] max_tx_bytes fails the operation with -8, naming the bound it hit, before anything is proved.

Errors (synchronous)

vs Bitcoin Core: no equivalent; Core has no asynchronous RPC model. The synchronous counterparts are sendtoaddress and sendmany.

vs zcashd: same signature, same opid model, same status shapes; this is the page where zecd tracks zcashd rather than Bitcoin Core. Differences:

• fromaddress must be this wallet's own address (ANY_TADDR aside); zcashd will also spend from an address in another of its accounts. Selection itself matches: a t-address funds from that address, ANY_TADDR from any of them, a shielded address from the account's notes.
• fee may be an explicit amount in zcashd (default null means ZIP-317); zecd rejects any explicit fee with -8.
• minconf defaults to 10 in zcashd (DEFAULT_NOTE_CONFIRMATIONS); zecd defaults to the wallet's configured ZIP-315 policy and clamps explicit values to at least 1.
• zcashd's LegacyCompat default resolves to FullPrivacy when a Unified Address is involved and AllowFullyTransparent otherwise; zecd's resolves to the configured [spend] privacy_policy.
• zecd's ladder is linear, so AllowRevealedSenders also permits a transparent recipient paid from shielded notes; zcashd treats the two disclosures as incomparable lattice points. AllowLinkingAccountAddresses has no separate meaning here, since there is one account.
• The zero-valued memo-only output is accepted by both.

Example

opid = rpc.z_sendmany(my_ua, [
    {"address": dest_ua, "amount": 0.5,
     "memo": "7a6563642070617965652072656631323334"},
])
status = rpc.z_waitforoperation(opid)       # blocks; no poll loop
if not status["finished"]:
    ...                                     # timed out, still running: call again
elif status["status"] == "failed":
    raise RuntimeError(status["error"]["message"])
txid = status["result"]["txid"]
rpc.z_getoperationresult([opid])            # optional: reap it

Example: shielding received transparent funds

Move transparent coins into the wallet's own shielded pool. The source is transparent and the recipient is shielded, so this is the shielding send; the change shields too.

opid = rpc.z_sendmany("ANY_TADDR",
                      [{"address": rpc.z_getnewaddress(), "amount": 1.0}],
                      None, None, "AllowRevealedSenders")
status = rpc.z_waitforoperation(opid)

Drop the "AllowRevealedSenders" argument if [spend] privacy_policy already permits a transparent source; passing it makes the call work whatever the wallet is configured for, since the argument is a per-call override. Naming one of the wallet's own t1 addresses instead of ANY_TADDR shields only that address's coins and leaves the rest untouched.

There is no "shield everything" amount: the ZIP-317 fee comes out of the inputs, so a sweep has to ask for slightly less than the transparent total. Sum the transparent entries of listunspent (they are the ones carrying a bare t-address, and skip any with generated: true, which only z_shieldcoinbase can spend) and leave room for the fee.

z_shieldcoinbase

z_shieldcoinbase "fromaddress" "toaddress" ( fee ) ( limit ) ( "memo" ) ( privacyPolicy )

Sweep the wallet's mature transparent coinbase UTXOs into a single shielded output. Returns an opid immediately; the txid or error surfaces through the tracking methods, exactly as with z_sendmany.

Why this method exists at all. Zcash consensus forbids a transaction that spends a transparent coinbase output from having any transparent output, change included. A coinbase spend therefore cannot pay a t-address and cannot keep transparent change: the whole selected value has to land in one shielded output. That is not a shape the ordinary send methods can produce, so shielding is the only way to spend transparent coinbase, and this is the method that does it. The regular transparent-to-transparent path never selects coinbase inputs for the same reason (see Sending).

No change, in any pool. The shielded payment is exactly input_total - fee. Emitting shielded change instead would leak how much coinbase the wallet chose to sweep, so the selected value is moved whole. Sweep in stages with limit if you do not want it all in one note.

Maturity. Transparent coinbase must reach the standard 100-block maturity before it can be shielded; the bound is enforced during input selection. Immature coinbase is excluded from listunspent and reported in getwalletinfo.immature_balance until it matures.

Shielded coinbase (ZIP-213), a block reward mined directly to a shielded address, needs none of this: it has no maturity rule and no spend restriction, so those notes spend as ordinary Orchard notes through the normal send methods.

Parameters

Result

{
  "remainingUTXOs": 12,
  "remainingValue": 3.75000000,
  "shieldingUTXOs": 50,
  "shieldingValue": 15.62500000,
  "opid": "opid-9c2f0d61-1c2b-4f3e-9a3e-2d4b8c7a5e10"
}

• shieldingUTXOs / shieldingValue: what this operation is sweeping.
• remainingUTXOs / remainingValue: mature coinbase left over because limit or the block-space cap cut the selection short. Non-zero means call again once this operation finishes.
• opid: feed it to z_getoperationstatus / z_getoperationresult.

As with z_sendmany, only argument validation fails synchronously; proving and broadcast failures surface in the operation's error object.

Errors (synchronous)