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.

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

[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 and the config group honor the datadir/network/keys flags; the RPC flags are inert for them. rpcauth and example-config run before config resolution and ignore all of them, so they work when there is no config file yet.

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. --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.

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.