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.