Zebra

Zebra is an independent implementation of the Zcash protocol, written in Rust by the Zcash Foundation. Its binary, zebrad, is a full node: it downloads every block from the peer-to-peer network, checks it against the consensus rules of the protocol specification and the ZIPs, and maintains the resulting chain state. The original node, zcashd, has reached end of life.

What Zebra does

• Validation. Blocks pass structural checks while parsing, semantic checks that need no chain context (proofs, signatures, scripts), and contextual checks against the chain they extend (double spends, value pools, difficulty). By default, blocks up to the last hard-coded checkpoint get only proof-of-work and Merkle-root checks and are accepted once their hashes chain to a checkpoint. Architecture describes the pipeline.
• Chain state. The finalized chain lives in RocksDB; the most recent blocks of every competing chain stay in memory, so Zebra can switch to a chain with more work.
• Network. Zebra speaks the Zcash peer-to-peer protocol and relays blocks and, once near the tip, unmined transactions from its mempool.
• Interfaces. A JSON-RPC server that follows the zcashd API serves light-wallet servers, wallets, explorers, exchanges, and mining pools.

Zebra holds no keys. Wallets use Zallet; light clients use a light-wallet server such as Zaino or lightwalletd, both backed by Zebra. Systems that still depend on the zcashd wallet RPC can run zcashd behind Zebra in zcashd-compat mode; the API migration guide records which component now owns each zcashd method.

Networks and network upgrades

Zebra runs on Mainnet, Testnet, Regtest, and custom test networks. Zebra 7.0.0 implements every network upgrade through NU7, at these compiled-in heights:

A release that does not implement an upgrade cannot follow the chain past its activation height, and on Mainnet every release halts at its end-of-support height. Upgrading Zebra covers both deadlines.

Getting started

Run the latest release in Docker, with the P2P port published and the state on a named volume:

docker run -d --name zebra \
  -p 8233:8233 \
  -v zebrad-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:latest

Or install the pre-built binary for Linux on x86_64 or aarch64:

cargo binstall zebrad
zebrad start

Installing Zebra, Running Zebra, and Zebra with Docker cover the details.

Documentation

The user documentation is for operators and integrators, the developer documentation for contributors, and the API reference points to the crates’ rustdoc.

Support and security

Report bugs in the issue tracker; Troubleshooting lists known problems. Discussion happens in the zebra-support channel of the Zcash Foundation Discord. Report vulnerabilities privately, as the security policy describes.

Zebra is dual-licensed under MIT and Apache 2.0; some crates are MIT-only, as their Cargo.toml states.

User documentation

These pages describe Zebra 7.0.0 for node operators and for the software that depends on their nodes.

• Deploy: requirements, platforms, installation, configuration, running, Docker. A state snapshot avoids a sync from genesis.
• Operate: upgrading, tracing, metrics, health endpoints, troubleshooting.
• Integrate: JSON-RPC, Zallet, lightwalletd, mining. Operators leaving zcashd start with the API migration guide and zcashd-compat mode.
• Test networks: custom testnets, Regtest, forking the Testnet.

System requirements

Size the host for initial synchronization and the services that share it, not only for an idle node at the chain tip. See platform support for operating-system coverage.

Resource use

The configuration reference documents these controls. Monitor metrics and host resource usage while synchronizing and under the expected RPC load.

Reference deployment

The Zcash Foundation’s node deployment and integration-test use Google Compute Engine c2d-standard-2 instances (2 vCPUs, 8 GB RAM) with a 400 GB balanced persistent state disk. This is not a minimum or an RPC-load capacity guarantee.

Disk capacity

The published Mainnet state snapshot of 2026-10-23 reports a source-node height of 3,527,378 and an archive size of 273,763,413,895 bytes (255 GiB). The Testnet archive of the same day, at finalized height 4,531,081, is 12,221,184,309 bytes (11.4 GiB). These are zstd-compressed tar archive sizes, not measurements of the extracted databases. The snapshot index at https://snapshots.zfnd.org/ lists current archive sizes. The database grows with every block.

Store state on persistent storage configured with [state] cache_dir. Mainnet and Testnet have separate databases. Running both requires space for both. The zebra.state.rocksdb.total_disk_size_bytes metric measures the RocksDB table files, not all files on the filesystem. Check filesystem free space as well.

A state snapshot needs space for the downloaded archive and the extracted database at the same time. Retaining an existing database during replacement needs additional space. Do not use the compressed archive size as the required capacity of the destination disk.

zcashd-compat requirements

The zcashd-compat mode runs Zebra with a zcashd sidecar. Its Linux preflight checks enforce these thresholds; they are not standalone Zebra benchmarks.

Effective RAM is the smaller of host RAM and the detected container memory limit. The disk check measures total filesystem capacity, not free space. Shared-filesystem minimums add: 550 GiB on Mainnet or 60 GiB on Testnet and Regtest. Each filesystem counts once toward the combined recommendation. Zebra checks the sidecar’s disk only when it manages the sidecar or [zcashd_compat] zcashd_datadir identifies the external sidecar’s data directory. A remote or otherwise unspecified sidecar needs separate capacity planning.

A failed minimum check stops startup. Values below the recommendation produce warnings. The zebrad start --unsafe-low-specs option bypasses preflight failures; it does not reduce resource use or make an undersized host safe.

Network requirements and ports

Zebra needs outbound TCP connections to Zcash peers to synchronize. Default peer discovery also needs working DNS resolution. Inbound peer connections are optional for synchronization; enable them to let other nodes connect to Zebra.

Configure the P2P listener and advertised address, then permit its port through the firewall and publish it when running in Docker. Do not expose management endpoints merely to make peer-to-peer networking reachable.

Platform support

The platform tier policy defines maintenance commitments; the tables below list Zebra 7.0.0 release targets and CI coverage. A Rust target triple does not specify a Linux distribution or library versions.

Minimum supported Rust version (MSRV)

The workspace and library crates require Rust 1.89. For the daemon’s minimum and pinned toolchain, see building from source. CI toolchains are listed below.

Tier 1

The production release targets are 64-bit GNU/Linux on x86 and ARM:

See pre-built binary requirements and Docker images. The GNU/Linux archives do not run natively on Alpine Linux.

The release-binary workflow builds both targets natively. The Docker workflow builds test images only for AMD64; the main unit-test workflow has no per-change ARM64 job. See the Tier 1 policy.

Tier 2

The additional CI environment, x86-64 Ubuntu 26.04, runs workspace and crate builds, minimum-version checks, Clippy, and unit tests. It produces no separate Ubuntu-specific release archive.

The target triple is the same as the x86-64 Tier 1 release target; the tier here describes an additional OS/toolchain environment. See the Tier 2 policy.

Scheduled or manually triggered advisory jobs run Clippy and unit tests with beta Rust on Ubuntu 26.04. They do not guarantee that each change builds with beta.

Tier 3

The following platforms have no official zebrad release archives and no full-node build-and-test guarantee:

Build from source on macOS; use a supported Linux environment for production. The zcashd-compat preflight supports Linux only, independently of these native-node tiers. See the Tier 3 policy.

Platform tier policy

General

Zebra’s platform tiers define maintenance commitments, following the model of the Rust target tier policy. A platform includes its architecture, operating system, toolchain, and required native libraries. The platform support matrix lists the release targets and the CI coverage for Zebra 7.0.0.

The Zebra team approves additions, promotions, demotions, and removals. Each tier inherits the requirements of the tier below it. A platform must first be accepted at the lower tier and demonstrate sustained maintenance before promotion; the Zebra team determines the required period. Meeting a checklist does not automatically confer a tier.

The words must and must not express requirements. The words should and should not express requirements for which the Zebra team can approve an exception. The word may expresses permission. This terminology follows RFC 2119.

Tier 3 platform policy

Tier 3 offers no build, test, or release guarantee. Other contributors need not maintain or test its platform-specific support.

• A platform must have identified maintainers who can receive reports of platform-specific issues.
• Target names should identify the actual environment without ambiguity.
• Changes must not break Tier 1 or Tier 2 platforms. A known regression on another Tier 3 platform requires agreement from that platform’s maintainers or the Zebra team.
• Tier 3 failures must not block unrelated pull requests. Automated failure notifications must go only to people who have opted into them.
• Support must not impose a disproportionate maintenance burden on the rest of Zebra.

The Zebra team may remove an inactive or unmaintained Tier 3 platform, or one whose support impedes the codebase. A removal proposal must notify the platform maintainers so they can respond.

Tier 2 platform policy

Tier 2 requires reliable builds in CI. A platform-specific build failure in a required job blocks acceptance of the affected change. Tier 2 does not promise that every test passes or that the project publishes binaries for that platform.

The DevOps team must approve the platform’s CI integration.

• The platform must implement Zcash consensus rules. The Zebra team may approve excluding other features or development tools.
• At least one designated developer must maintain the platform and respond to platform-specific build failures.
• The platform must be a Rust Tier 1 target and have a usable Rust toolchain.
• Documentation must specify CPU and OS baselines, native dependencies, build commands, and test commands. It must identify required hardware or emulation when an ordinary development host cannot run the target.
• Required CI builds must be reliable. Their duration and infrastructure cost must not impose an excessive burden on the project.
• Platform maintainers should run the test suite regularly and fix failures. The Zebra team may require selected tests as part of the platform’s CI contract.

Contributors need not become platform experts. The Zebra team handles test failures according to their impact: it may require a fix, disable a test, or demote the platform.

Tier 1 platform policy

Tier 1 adds production support and release artifacts to the Tier 2 requirements. The Zebra team, release team, and DevOps team must approve a promotion and the infrastructure needed to sustain it.

• The platform must support the standard production feature set: peer-to-peer networking, consensus verification, the mempool, persistent state, and RPC services. The Zebra team must approve exceptions.
• The platform must provide adequate security, performance, and reliability for production use, and serve users across multiple organizations or projects.
• Required builds and tests must pass reliably. The platform must not achieve this by disabling an excessive part of the test suite.
• Building and running tests must not take substantially longer than on other supported platforms.
• Release artifacts must have a documented runtime baseline and a maintained build and publication path.
• Maintainers must provide any additional hardware, cloud capacity, or emulation needed for CI and platform-specific debugging. CI resources must be continuously available for the project’s exclusive use; debugging resources must be exclusive while in use.
• Emulation used for required checks must accurately represent native behavior. Discrepancies affecting test results must be treated as high-priority platform, compiler, or emulator defects.

The Zebra team decides whether a failure requires a fix before other changes merge, a fix before release, a test exception, or a tier change. Changes to a Tier 1 CPU or OS baseline require team approval and communication to users.

Tier 1 or Tier 2 demotion or removal proposals must notify maintainers and the Zcash community before a stable release. Notice depends on severity and urgency. Changes normally apply to development and future releases, not retroactively.

Building and installing Zebra

Install a release archive on supported Linux systems, use the Docker image, or build from source. Check system requirements and platform support before provisioning the node.

Pre-built binaries

The GitHub release provides these archives:

Both require glibc 2.34 or newer and the C++ runtime library, libstdc++. Documented runtime baselines include Ubuntu 22.04, Debian 12, RHEL 9, and Amazon Linux 2023, or newer releases. RocksDB and the Zcash C++ script library are linked statically. These are GNU/Linux binaries, not macOS, Windows, or musl binaries.

Each archive contains zebrad, both license files, and a README. The release also supplies a checksum sidecar for each archive, a combined SHA256SUMS, and its Cosign signature bundle, SHA256SUMS.sigstore.json. GitHub stores a build-provenance attestation for each archive.

Install with cargo-binstall

After installing cargo-binstall, install the latest published Zebra release:

cargo binstall zebrad

To select this release explicitly:

cargo binstall --version 7.0.0 zebrad

The package metadata does not configure verification of Zebra’s signed checksum manifest. Use the manual procedure below when that verification is required.

Download and verify an archive

Install GitHub CLI and Cosign. The following Linux procedure also uses GNU sha256sum, tar, and install. Select aarch64-unknown-linux-gnu instead of x86_64-unknown-linux-gnu on ARM64. Run the commands in a new directory so unrelated files do not affect checksum verification.

set -eu
version=7.0.0
target=x86_64-unknown-linux-gnu
archive="zebrad-${version}-${target}.tar.gz"
mkdir "zebrad-${version}-${target}"
cd "zebrad-${version}-${target}"

gh release download "v${version}" --repo ZcashFoundation/zebra \
  --pattern "${archive}" \
  --pattern SHA256SUMS \
  --pattern SHA256SUMS.sigstore.json

gh attestation verify "${archive}" \
  --repo ZcashFoundation/zebra \
  --signer-workflow ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml \
  --source-ref "refs/tags/v${version}"

cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity="https://github.com/ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml@refs/tags/v${version}" \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com'

sha256sum --ignore-missing --check SHA256SUMS
tar -xzf "${archive}"
install -d "${HOME}/.local/bin"
install -m 755 zebrad "${HOME}/.local/bin/zebrad"
export PATH="${HOME}/.local/bin:${PATH}"
zebrad --version

Stop if any verification fails. The attestation binds the archive to the expected repository, builder workflow, and release tag. Cosign authenticates the checksum manifest; the checksum check then compares the downloaded archive with that signed manifest. An unsigned checksum alone detects file corruption but does not authenticate the publisher.

An attestation is not an independent rebuild.

Keep ${HOME}/.local/bin in the service or shell’s PATH, or invoke the installed binary by its full path. Continue with running Zebra.

Building from source

The zebrad binary requires Rust 1.91 or newer; Zebra 7.0.0 pins Rust 1.91.0 in rust-toolchain.toml. Install rustup, then select the release toolchain:

rustup toolchain install 1.91.0
rustup default 1.91.0

The bundled RocksDB and Zcash script library require a C compiler, a C++17 compiler, and Clang’s shared library, libclang, for generated Rust bindings. Install Git for the tagged-source procedure below.

The RPC build script uses checked-in generated files unless the Protocol Buffers compiler, protoc, and source .proto files are available. Install protoc only to regenerate these files or build with the lightwalletd-grpc-tests feature:

Debian and Ubuntu

sudo apt-get update
sudo apt-get install build-essential clang libclang-dev git

Arch Linux

sudo pacman -Syu --needed base-devel clang git

Fedora and RHEL

On Fedora:

sudo dnf install gcc gcc-c++ make clang clang-libs clang-devel git

On RHEL 9, install the LLVM toolset and libclang runtime from the enabled RHEL repositories:

sudo dnf install gcc gcc-c++ make llvm-toolset clang-libs git

macOS

Install the Xcode Command Line Tools for the compiler and SDK, and Homebrew LLVM for libclang:

xcode-select --install
brew install llvm
export LIBCLANG_PATH="$(brew --prefix llvm)/lib"

Complete the Command Line Tools installation before building.

Install from crates.io

Build and install the latest published release with its dependency lockfile:

cargo install --locked zebrad

To pin Zebra 7.0.0:

cargo install --locked --version 7.0.0 zebrad

Cargo installs the executable in its installation root, normally ${HOME}/.cargo/bin. Keep that directory in PATH. The --locked option retains the release’s dependency versions; do not remove it as a generic workaround for a build failure.

Install from a release tag

Build and install directly from the Git tag:

cargo install --locked \
  --git https://github.com/ZcashFoundation/zebra \
  --tag v7.0.0 zebrad

Alternatively, build a checkout without installing it:

git clone --branch v7.0.0 https://github.com/ZcashFoundation/zebra.git
cd zebra
cargo build --locked --release --bin zebrad
target/release/zebrad --version

Run the installed binary with zebrad start, or the checkout build with target/release/zebrad start. See running Zebra for configuration, network selection, and shutdown.

Dynamic RocksDB linking

The default build statically links bundled RocksDB. To avoid recompiling it, link an installed shared library instead.

Zebra 7.0.0 locks rocksdb to 0.24.0 and librocksdb-sys to 0.17.3+10.4.2, which bundles RocksDB 10.4.2. Use matching 10.4.2 headers and a shared library built with LZ4 support. Do not assume that an arbitrary system package supplies the required API; the build script does not validate the library’s version.

For a matching installation under /opt/rocksdb-10.4.2, with libraries in lib and headers in include:

unset ROCKSDB_STATIC ROCKSDB_COMPILE
export ROCKSDB_LIB_DIR=/opt/rocksdb-10.4.2/lib
export ROCKSDB_INCLUDE_DIR=/opt/rocksdb-10.4.2/include
cargo build --locked --release --bin zebrad

The librocksdb-sys build script uses ROCKSDB_LIB_DIR to skip the bundled C++ build. It selects dynamic linking when ROCKSDB_STATIC is absent; even 0 selects static linking. The ROCKSDB_INCLUDE_DIR variable selects bindgen’s headers; libclang is still required. Set both paths to the actual installation.

Configure the operating system’s dynamic-library loader to find RocksDB and its dependencies when Zebra starts. The resulting binary depends on those libraries remaining installed. Unset ROCKSDB_LIB_DIR and ROCKSDB_INCLUDE_DIR to return to the bundled build.

Building on ARM

Use a native 64-bit ARM Rust toolchain and native C/C++ dependencies: aarch64-unknown-linux-gnu for Linux or aarch64-apple-darwin for Apple silicon. Do not select an x86-64 toolchain. There is no official 32-bit ARM archive.

Build troubleshooting

Tor feature

Zebra 7.0.0 has no buildable zebra-network/tor feature; selecting it fails Cargo feature resolution. See Arti support.

Cargo features

Cargo features select code at build time; configuration selects runtime behavior. The table covers every explicit feature in zebrad/Cargo.toml. “Default” includes features enabled transitively by default. Mining RPCs require no optional Cargo feature; internal-miner adds the built-in solver, not the mining API.

Cargo also exposes implicit features for optional dependencies. The default bundle enables howudoin, indicatif, and metrics-exporter-prometheus. The remaining dependency features are console-subscriber, inferno, proptest, proptest-derive, thread-priority, tonic-prost-build, tracing-flame, tracing-journald, and zebra-utils. Selecting a dependency alone does not activate the corresponding Zebra feature; use the functional features in the table.

Add features without removing the default bundle:

cargo install --locked --version 7.0.0 --features "indexer,journald" zebrad

Features are additive. To retain debug logging in a release build, remove the default info ceiling and select the desired production components explicitly:

cargo install --locked --version 7.0.0 --no-default-features \
  --features "progress-bar,prometheus,sentry,opentelemetry,release_max_level_debug" \
  zebrad

Set [tracing] filter to request the retained debug events. Avoid --all-features for an operator build: it includes test features and incompatible logging/instrumentation choices.

Configuring Zebra

Zebra 7.0.0 reads configuration from a TOML file and environment variables. The file represents the ZebradConfig Rust type. Keep only settings that must differ from the defaults; copying every generated value into a permanent configuration prevents later releases from updating those values automatically.

Without -c or --config, Zebra looks for zebrad.toml in the user’s preference directory:

Zebra uses defaults and environment variables when the default file is absent. Starting a node with an explicitly selected file requires that file to exist and be readable. Select a file with:

zebrad --config /path/to/zebrad.toml start

Generate a default configuration with:

zebrad generate --output-file zebrad.toml

The command overwrites the output file. Without --output-file, it writes to standard output. It generates built-in defaults, not the merged configuration of a running node. Optional fields whose default is absent are not included. The generated file reflects the features compiled into that binary. The generate command ignores configuration-loading errors so it can produce a replacement for an invalid configuration.

The loader applies these sources, from highest to lowest priority:

1. Environment variables with the ZEBRA_ prefix.
2. The selected TOML file.
3. Built-in defaults for omitted fields and sections.

Command-specific overrides apply afterward. See Tracing for filter syntax and Docker for container configuration.

Every top-level section listed below rejects unknown keys, and the root rejects unknown sections. The nested network-parameter, activation-height, funding-stream, recipient, and lockbox-disbursement structs also reject unknown keys. The Regtest selector wrapper described below is an exception: it does not reject unknown sibling keys beside params and regtest. A field compiled out of the schema, such as an Elasticsearch state field without the elasticsearch feature, is an unknown field. Fields whose implementation is feature-gated can still be accepted; their behavior is specified below. Unknown fields and invalid types fail configuration loading rather than silently using defaults.

In the tables, absent means None: omit the key to leave it unset. TOML has no null; an empty string, false, or empty array is a value, not an unset instruction. Optional fields can have nonempty defaults. Removing a file setting does not cancel an environment override.

Write durations as quoted humantime strings, such as "5m", "1h", or "1m 1s". Address fields are strings containing an IP address and port, with brackets around IPv6 addresses. Only the two peer-to-peer (P2P) address fields permit an omitted port. A block height is an integer; validated consensus heights are at most 2147483647. Amounts are in zatoshis, with 100000000 zatoshis per ZEC.

The default cache directory used below is:

On Linux, the XDG directory variables must contain absolute paths. Empty or relative values use the corresponding home-directory fallback.

The P2P cache, state database, and RPC cookie have separate settings even when their defaults share this directory. Give each concurrently running node a separate state directory and RPC cookie directory. Protect configuration files containing credentials and directories writable by a privileged Zebra process from modification by other users.

Environment variables

• Zebra strips the exact, case-sensitive ZEBRA_ prefix, lowercases the key, and replaces each __ with a nested-table separator. Single underscores remain in field names.
• Use leaf variables or TOML, not JSON or TOML objects as whole-table values. Configure activation heights in TOML: lowercasing loses case-sensitive names such as Canopy and NU7.
• Values are parsed as case-insensitive booleans, signed 64-bit integers, floating-point numbers, then strings. Empty values are not ignored. Shell-quote spaces in durations and filters; shell quotes are not part of the value.
• There is no list separator or general array parser. Put peer arrays, network magic, checkpoints, and funding streams in TOML, not comma-separated or JSON-array environment values. Only the two JSON-array-string fields in [zcashd_compat] accept arrays through environment values.
• Zebra rejects leaf keys ending in password, secret, token, cookie, or private_key, ignoring case, even for unknown fields. Store these values in the file. This rejects ZEBRA_STATE__ELASTICSEARCH_PASSWORD, but not path fields such as cookie_dir.
• For copy-state, use ZEBRA_TARGET_ variables with --target-config-path to override target settings, for example ZEBRA_TARGET_STATE__CACHE_DIR=/srv/zebra-target. The source/base loader ignores this prefix. Only the target’s [state] settings are used, although the whole file is deserialized. Without --target-config-path, the target uses an ephemeral state configuration and ignores target overrides.

export ZEBRA_ZCASHD_COMPAT__ZCASHD_EXTRA_ARGS='["-debug=1"]'
export ZEBRA_ZCASHD_COMPAT__BLOCK_GOSSIP_PEER_IPS='["127.0.0.1","::1"]'

[consensus]

Rust API: zebra_consensus::Config.

[network]

Rust API: zebra_network::Config and CacheDir.

The exact default Mainnet seed list is:

initial_mainnet_peers = [
    "dnsseed.str4d.xyz:8233",
    "dnsseed.z.cash:8233",
    "mainnet.seeder.shieldedinfra.net:8233",
    "mainnet.seeder.zfnd.org:8233",
    "seeder.zec.rocks:8233",
]

The exact default Testnet seed list is:

initial_testnet_peers = [
    "dnsseed.testnet.z.cash:18233",
    "seeder.testnet.zec.rocks:18233",
    "testnet.seeder.zfnd.org:18233",
]

Place either array in [network]. An empty array removes those seeds; it does not disable inbound connections or the disk peer cache. Regtest skips loading the peer cache. Peer cache files use <cache_dir>/network/<network-directory>.peers.

The listener and external address parsers accept IP literals, not DNS names. The default unspecified listener accepts connections without advertising an unspecified address.

Configured network layouts

Use Custom Testnets or Regtest for complete network examples. Both of these layouts select the same parameter schema:

[network]
network = "Testnet"

[network.testnet_parameters]
checkpoints = true

[network.network]
checkpoints = true

A table-valued selector with a params child selects Regtest instead:

[network.network.params.activation_heights]
NU5 = 1

The Regtest selector wrapper has these fields:

[network.testnet_parameters]

These fields also apply under [network.network] for configured Testnet or [network.network.params] for Regtest.

See Custom Testnets for cross-field validation and activation, subsidy, funding-stream, and checkpoint rules.

For inline checkpoint pairs, each hash is an array of 32 u8 values in serialized byte order: reverse the byte order of the displayed hexadecimal hash, not its individual digits. A hexadecimal string is not accepted here. For human-readable hashes, use a checkpoint file: each line contains a height and its displayed hexadecimal hash, separated by one space.

Activation heights

The activation table is [network.testnet_parameters.activation_heights] in the compatibility layout. All fields are optional u32 heights and default to absent in an explicitly supplied table. The public schedule column applies only when the whole table is omitted on Testnet.

Quote upgrade names containing dots so TOML does not interpret them as nested keys. Each supplied height must be in 1..=2147483647.

Funding streams and lockbox outputs

Each funding_streams array element or legacy table configures one group:

Each supplied height_range has these required fields:

Each supplied recipient has these fields:

On Testnet and Regtest, Zebra rejects invalid ranges, missing defaults, numerator totals above 100, and malformed addresses during loading. Non-deferred recipients need Testnet addresses covering every address period. Extension can repeat a nonempty list but cannot fill a required empty list.

The three public Testnet groups are, in order:

Public address sequences are consensus data, not operator payout addresses.

Each lockbox_disbursements element has these fields:

Zebra validates lockbox addresses during loading. The sum of all disbursements must not exceed 2100000000000000 zatoshis.

The default Testnet list contains ten identical outputs, each paying 787500000000 zatoshis to t2RnBRiqrN1nW4ecZs1Fj3WWjNdnSs4kiX8.

Rust API: ConfiguredActivationHeights, ConfiguredFundingStreams, ConfiguredFundingStreamRecipient, and ConfiguredLockboxDisbursement.

[state]

Rust API: zebra_state::Config.

Persistent state uses <cache_dir>/state/v29/<network-directory> in Zebra 7.0.0. Non-finalized backups use <cache_dir>/non_finalized_state/<network-directory>. Do not share a live state directory between node processes. Deleting state forces the node to download and verify the chain again; it is not a configuration-reset procedure.

The Elasticsearch client validates HTTPS certificates by default. Configure a trusted server certificate, or explicitly opt out for a trusted local cluster with elasticsearch_skip_cert_validation = true. HTTP never protects credentials. See Elasticsearch indexing.

[sync]

Rust API: zebrad::components::sync::Config.

Do not supply both an alias and its current key: they deserialize as duplicate fields.

With zero threads configured, Rayon uses a positive RAYON_NUM_THREADS environment value, otherwise the available logical CPU count, with a one-thread fallback if detection fails. If that environment variable is absent or invalid, Rayon also checks the deprecated RAYON_RS_NUM_CPUS before detecting the CPU count. An explicit RAYON_NUM_THREADS=0 selects CPU detection without checking the deprecated variable.

[mempool]

Rust API: zebrad::components::mempool::Config.

[rpc]

Rust API: zebra_rpc::config::rpc::Config.

Bind RPC listeners to loopback or a restricted private interface; see JSON-RPC authentication. Neither gRPC listener uses cookie authentication. The lightwalletd-compatible listener serves plaintext HTTP/2 without authentication or TLS; terminate TLS at a controlled proxy before exposing it to clients. See Mining and Docker RPC.

[mining]

Rust API: zebra_rpc::config::mining::Config.

The obsolete miner_data key is rejected. Coinbase tag and memo strings are not hex-decoded: "4142" means four UTF-8 bytes, not two.

See Mining for payout validation and template behavior. The internal miner uses one solver; its thread count is not configurable. Treat coinbase metadata as public, including shielded memos; see ZIP 213.

[tracing]

Rust API: zebrad::components::tracing::Config and InnerConfig.

The progress-bar log fallback is $XDG_STATE_HOME/zebrad.log or $HOME/.local/state/zebrad.log on Linux, $HOME/Library/Application Support/zebrad.log on macOS, and %LOCALAPPDATA%\zebrad.log on Windows. Selecting a progress mode changes this log destination even when the binary lacks progress rendering. If no platform state directory is available, Zebra tries the local data directory; if neither path is available, logs remain on standard output.

All tracing fields remain recognized without their optional implementation features. An OpenTelemetry endpoint configured without the feature produces a warning. Exporter initialization failure disables export, not the node. The fallback OTEL_TRACES_SAMPLER_ARG is an integer percentage: 10 means 10%; 0.1 fails parsing and falls back to 100%. Prefer the explicit Zebra setting.

The filter-control endpoint has no authentication. Keep it private: remote changes can increase log volume and reveal operational details. Log files, flamegraphs, and exported traces can also contain node data.

Sentry has no TOML field or [sentry] section. With the sentry feature, set SENTRY_DSN to configure reporting; SENTRY_ENVIRONMENT supplies its environment metadata. See Tracing, Sentry monitoring, and OpenTelemetry export.

[metrics]

Rust API: zebrad::components::metrics::Config.

The listener has no configured authentication or TLS. Restrict access to the monitoring network. Failure to bind a configured listener stops startup. See Metrics.

[health]

Rust API: zebrad::components::health::Config.

An enforced readiness check also requires a populated state and sync status close to the network tip. The HTTP endpoints are unauthenticated. Bind them to a private interface and restrict access with network policy. See Health checks.

[notify]

Rust API: zebrad::components::notify::Config.

Zebra executes the command through /bin/sh -c on Unix or cmd /C on Windows, with the node process’s privileges. Standard input, output, and error are redirected to the null device. Treat this setting as executable code; use only a trusted command or script.

Notification commands run independently of block validation. Notifications are best effort: fast synchronization and reorganizations can coalesce intermediate tips, and a slow command does not prevent later commands from starting. Do not use notifications as an exactly-once block index.

ZMQ notifications follow the same rules, and the publisher also drops messages when its bounded queue overflows. Subscribers must reconcile through RPC after a gap or a reconnect.

[zcashd_compat]

Rust API: zebrad::components::zcashd_compat::Config.

The embedded source supports Linux x86-64. Startup runs compatibility-mode preflight checks.

The extra-argument validator rejects -connect, -addnode, and -seednode, including negated forms and variants with extra leading dashes or different case. The supervisor sets its own peer connection, disables incoming P2P, DNS seeding, onion listening, and discovery, and forces foreground operation. For data-directory and configuration-file preparation, Zebra uses the last valid -datadir=<path> or -conf=<path> argument, also accepting -- forms. It warns about duplicates, empty paths, or paired arguments such as ["-conf", "file"]; paired values are passed through but not inferred for preparation. Relative configuration paths resolve under the selected sidecar data directory.

Trust every process able to connect from a listed sidecar IP; never list an address shared with untrusted tenants. The zcashd-compat page describes the sidecar’s reserved inbound capacity, reconnection exemptions, and pinned block gossip.

The connect-address override describes the address the sidecar dials. It does not identify the sidecar’s source IP for privileges. Across containers or hosts, configure the source IP list separately. A non-loopback connect override with an empty trusted list produces a warning because privileges still default to loopback.

Running Zebra

Zebra downloads, verifies, stores, and relays the Zcash chain. The zebrad process runs continuously; it does not stop when the initial sync finishes. Enable JSON-RPC to serve applications such as lightwalletd, Zallet, and mining pools.

Commands

Run Zebra with its default Mainnet configuration:

zebrad start

Omitting the subcommand also starts Zebra. Put top-level options, including --config, before the subcommand:

zebrad --config /path/to/zebrad.toml start

The tip-height command opens a read-only state instance, does not connect to peers, and does not upgrade an older database. Its output is not the live, non-finalized chain tip. On a read failure it logs an error rather than printing a height; check for numeric output, not only its exit status.

The copy-state command is an expert diagnostic tool, not a snapshot download or full revalidation command. Use a distinct target cache directory. With --target-config-path, ZEBRA_TARGET_ environment variables override target settings without changing the source. Without that option, the command ignores target overrides and uses temporary state that is deleted on a successful exit. The --max-source-height HEIGHT option limits the copy.

Configuration and network

See configuration for file selection, precedence, and environment overrides.

Generate a starting configuration on Linux:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}"
zebrad generate --output-file "${XDG_CONFIG_HOME:-$HOME/.config}/zebrad.toml"

Keep only fields that need an explicit setting.

The [network] network field selects "Mainnet" by default. To use public Testnet, set:

[network]
network = "Testnet"

When switching networks, remove an explicit [network] listen_addr to use the new network’s default port, or change its port. To select Testnet through the environment:

ZEBRA_NETWORK__NETWORK=Testnet zebrad start

Use "Regtest" for a local development chain; see Regtest. See custom Testnets for networks with other consensus parameters. Separate processes need separate listener addresses and must not write the same state database. Give each RPC server its own [rpc] cookie_dir, even on different networks, so one server does not overwrite another’s cookie.

State directory

The state cache contains a finalized RocksDB database of blocks, unspent transaction outputs, and validation/query indexes, plus backups of recent blocks that can still be reorganized.

Zebra’s chain state contains no wallet keys. Deleting it requires downloading and verifying the chain again. Do not enable [state] ephemeral for a persistent node. See state snapshots for restoration and upgrading for format migrations and rollback.

First sync

An empty node starts with the genesis block and downloads the chain from peers. A checkpoint is a block height and hash compiled into Zebra that identifies a known chain. With the default [consensus] checkpoint_sync = true, Zebra checks the chain of block hashes against those checkpoints through the last checkpoint. It does not repeat all proof and signature checks for those blocks. Above that height, Zebra fully verifies new blocks, including their transactions, before accepting them.

The protocol’s blockchain rules require validators to follow the chain containing the settled network upgrades. Zebra’s checkpoint routing enforces known checkpoint hashes both while syncing and when checking existing state at startup.

The checkpoint_sync = false setting is for development. It starts full verification after the first checkpoint at or above the block immediately before Canopy activation. It does not disable mandatory checkpoints or provide full verification from genesis: Zebra does not implement every legacy pre-Canopy validation rule. Disabling checkpoint sync is slower and removes protection provided by later checkpoints; keep the default for production.

A state snapshot replaces the initial download and validation of archived blocks with trust in the snapshot producer. See Startup and sync for the task sequence and log messages.

Progress and readiness

Zebra logs sync progress approximately once a minute; see progress messages for the fields. Keep the system clock synchronized: progress estimates use local time.

For automated readiness checks, configure the health server and query /ready. A listening RPC port alone does not establish that the node is synced.

Enable terminal progress bars with:

[tracing]
progress_bar = "summary"

Progress bars require the progress-bar Cargo feature and redirect logs to a file. See tracing configuration for modes and log paths, and metrics for monitoring without a terminal.

Ports

The table describes native zebrad defaults, not container port mappings. All endpoints use TCP.

The P2P wildcard listener accepts IPv6 and IPv4 connections where the operating system supports dual-stack sockets. Set a specific address to restrict the listener. Zebra’s Regtest default differs from zcashd’s port 18344.

Bind administrative and monitoring endpoints to loopback or a protected network. See RPC authentication before exposing RPC; the indexer, lightwalletd-compatible, and health endpoints do not inherit JSON-RPC authentication.

Stopping Zebra

On Unix, press Ctrl-C or send SIGINT or SIGTERM to the zebrad process. Zebra logs received SIGINT, starting shutdown or the corresponding SIGTERM message. On Windows, Ctrl-C starts shutdown; Zebra does not implement Windows service-control messages directly.

Zebra stops its asynchronous runtime and waits up to 20 seconds for runtime-owned work to stop. Asynchronous tasks are canceled rather than drained. State cleanup closes the block-write channels and flushes RocksDB data and its write-ahead log. This does not guarantee that every in-flight block or latest non-finalized block has reached disk: cleanup can be interrupted, and the non-finalized backup is periodic. Zebra resumes from persisted state on restart.

Wait for the process to exit before moving, copying, or replacing its state. Avoid SIGKILL for routine shutdown because it skips cleanup. If Zebra manages a zcashd child in compatibility mode, shutdown also waits for that child using [zcashd_compat] shutdown_grace_period.

Exit codes

A panic is not reliably exit code 2. Zebra’s development and release profiles use panic = "abort"; a panic terminates the process without normal unwinding. On Unix, process supervisors distinguish this signal termination from a normal exit status. Do not interpret every code 2 as a crash or every code 0 as proof that a utility produced valid output; in particular, check tip-height output.

End of support

Zebra enforces a height-based support window on Mainnet. Zebra 7.0.0 uses these compiled constants:

The calculation advances from the starting height using each network upgrade’s target block spacing, including spacing changes within the window. It is not a timer measured from installation, process startup, or the release’s calendar date. The last supported height is inclusive; the first unsupported height is one block higher.

The task waits ten seconds after startup, then checks the local best tip once per hour when a tip exists. It does not enforce expiry on Testnet, configured Testnets, or Regtest. Mainnet warnings begin with Your Zebra release is too old and it will stop running; expiry panics begin with Zebra refuses to run. Upgrade to a supported release before reaching the reported cutoff. Restarting the same binary does not extend its support window.

Startup and sync

An open listener does not establish readiness; use the health checks. Startup tasks run concurrently, so log messages interleave. The examples omit timestamps, tracing spans, and variable fields. See tracing for filters and metrics for dashboards.

Load configuration and diagnostics

Zebra loads configuration, applies command-line overrides, and initializes logging and the CPU thread pool. It logs the build version, network, compiled features, state format, and loaded configuration.

Without a configuration file, the log includes:

No config file provided, using default configuration
initialized rayon thread pool for CPU-bound tasks

Environment overrides still apply when this message says “default configuration.” With a file, Zebra instead logs Using config file at: and the selected path. Configured metrics and tracing-filter reload listeners start during this application initialization, before the node state opens.

The startup command then logs:

Starting zebrad

On Linux, it checks the TCP slow-start-after-idle setting and warns if it is enabled. See Linux TCP tuning. In zcashd-compat mode, Zebra performs its preflight checks before opening state. It also resolves the zcashd binary when supervision is enabled.

Open the state

Zebra selects the checkpoint boundary and opens or creates the state database, restoring eligible non-finalized block backups. See upgrading for format migrations.

initializing node state
opening database, this may take a few minutes
loaded Zebra state cache
logging database metrics on startup

The Opened Zebra state cache at message identifies the actual database path. The loaded Zebra state cache event includes chain_tip: None for empty state, or the restored block hash and height. Check these fields after restoring a snapshot or changing [state] cache_dir.

Database opening precedes block downloads; a pause here is not a peer-discovery failure. Format upgrades and checks run on a separate thread and overlap syncing.

Initialize peer connections

Zebra opens [network] listen_addr and combines configured seed peers with cached peer addresses.

initializing network
starting the address book updater
resolved seed peer IP addresses
connecting to initial peer set
starting the peer address crawler

The DNS message appears when a seed resolves. The loaded cached peer IP addresses event appears when Zebra reads a usable cache. The listener reports Opened Zcash protocol endpoint at followed by its bound address. Individual seed lookups and peer connections can fail while other connections succeed.

Initialize verification and the mempool

The mempool holds verified, unmined transactions.

initializing verifiers
initializing block verifier router
initializing syncer
initializing mempool
fully initializing inbound peer request handler

The router’s log includes tip and max_checkpoint_height; see first sync for checkpoint and full verification rules.

A separate startup task checks stored block hashes against the compiled checkpoints. Its first message is:

starting state checkpoint validation

This check does not fully revalidate the stored database. A mismatch aborts startup or operation with an invalid-chain error. With incomplete state and checkpoint sync enabled, Zebra reports that remaining checkpoints will be verified during syncing.

On Mainnet and public Testnet, the mempool activates when Zebra is near the chain tip, rather than during the bulk initial download. Regtest enables it from height zero. Transactions admitted to the mempool use transaction verification, not checkpoint verification.

Start application interfaces

Zebra starts JSON-RPC when [rpc] listen_addr is set, logging Opened RPC endpoint at and its bound address without waiting for sync.

Additional services depend on configuration:

See RPC, mining, and zcashd compatibility for the interface contracts. The indexer warning configure an indexer_listen_addr to start the indexer RPC server means that this optional listener is disabled; it is not a sync error.

Launch background tasks

These markers indicate task startup, not completed work:

The block-notification marker appears even without a configured command. The health marker appears even when disabled; an enabled listener also logs opened health endpoint at and its address. See end of support for the release cutoff.

On Regtest, Zebra commits the genesis block locally if it is absent, then runs the syncer to recover blocks from peers. The internal miner starts last when its build feature and configuration enable it, with spawning Zcash miner.

Once these tasks have been launched, Zebra logs:

spawned initial Zebra tasks

This marks task startup, not readiness. Ordinary sync retries do not require restarting the process.

Sync the chain

Download genesis and discover extensions

On Mainnet or Testnet with empty state, Zebra downloads and verifies the genesis block. The syncer and progress reporter emit:

starting genesis block download and verify
initial sync is waiting to download the genesis block

With existing state, Zebra resumes from its stored chain. It sends block locators, which identify known chain ancestors, to peers and requests hashes of later blocks. Responses contain at most 500 block hashes. The syncer schedules downloads and verification concurrently within [sync] limits, then asks for further extensions:

starting sync, obtaining new tips
extending tips

Verify checkpoint ranges

Successful checkpoint ranges produce:

verified checkpoint range

This event includes block_count and current_range. Range verification and state writes are separate stages; incoming blocks do not immediately imply a higher committed tip.

Fully verify recent blocks

Above the checkpoint boundary, Zebra fully verifies blocks and transactions. The progress reporter logs:

estimated progress to chain tip

Its fields include current_height, remaining_sync_blocks, sync_percent, and time_since_last_state_block. The estimate uses block times, target block spacing, and the local clock. It is not a guaranteed completion percentage or remaining-time prediction.

Follow new blocks

Near the chain tip, the bulk syncer and block announcements from peers overlap. Zebra reports the transition with:

close to finishing initial sync, confirming using syncer and gossiped blocks
finished initial sync to chain tip, using gossiped blocks

The syncer remains active to recover missing blocks while the inbound handler downloads and verifies announced blocks. Monitor tip freshness and peers; see troubleshooting if height stops advancing.

Syncing from a state snapshot

The Zcash Foundation publishes compressed Zebra state archives at https://snapshots.zfnd.org/. Zebra resumes syncing from the archived tip. Check database compatibility before downloading.

On trust

A snapshot substitutes the producer’s validation for your own initial sync. Zebra checks database structure and stored checkpoint hashes on startup, but it does not fully revalidate every stored block and index. Those checks do not make an untrusted snapshot safe. Sync from genesis if your security policy requires validating the chain without trusting a state provider.

A SHA-256 checksum detects a damaged or incomplete download. A checksum served beside an archive does not authenticate its producer: a compromised server can replace both files.

A GitHub artifact attestation authenticates the manifest’s producing workflow; the manifest’s archive digest binds it to the archive. It does not prove that the chain data is valid. For unsigned manifests, obtain the expected digest through an independent trusted channel if you need protection against compromise of the download server.

Check the database format version

Zebra 7.0.0 uses database format 29.0.0, with finalized state under <cache_dir>/state/v29/<network>/. Compare the manifest’s database_format_major_version with the state format, not the producer’s Zebra release number.

Zebra also reuses compatible format 28 state without a resync, moving state/v28/<network>/ to state/v29/<network>/ when no usable format 29 database exists there. The old state must resolve inside the cache root; symlinks outside it are skipped. Reuse considers only the immediately preceding major version, not format 27 or older. Do not rename a database directory manually to claim compatibility.

Restore into a fresh cache root. Keep an independent backup for rollback: reuse moves the database rather than copying it. See upgrading for migration and rollback procedures.

Resolve the archive

Install curl, jq, GNU tar with Zstandard support, zstd, and sha256sum. Run the following commands in the same shell and download directory. Use network=testnet for public Testnet.

The per-network index is newest first. The latest role is not filtered by database version, so select the newest format that Zebra 7.0.0 can restore:

network=mainnet
curl -fLsS "https://snapshots.zfnd.org/$network/snapshots.json" \
  -o snapshots.json
snapshot=$(jq -ce '
  map(select(.db_major == 29 or .db_major == 28))
  | first // error("no compatible snapshot")
' snapshots.json)
url=$(printf '%s\n' "$snapshot" | jq -er '.url')
manifest_url=$(printf '%s\n' "$snapshot" | jq -er '.manifest_url')
archive=${url##*/}
manifest=${manifest_url##*/}
curl -fLsS "$manifest_url" -o "$manifest"
jq '{network, chain_tip, database_format_version, archive}' "$manifest"

Stop if a command fails. Confirm the manifest’s network, database format, archive.extraction_path, and chain_tip.note.

Allocate space for the compressed archive, extracted database, and ongoing growth. The manifest’s archive.size_bytes is only the compressed size.

Verify and download

Signed manifests

If the publication site lists an attestation for the selected manifest, download its bundle and verify it with the GitHub CLI. Obtain the trusted roots from the CLI itself, not from the snapshot server:

curl -fLsS "$manifest_url.sigstore.json" -o "$manifest.sigstore.json"
gh attestation trusted-root > trusted_root.jsonl
gh attestation verify "$manifest" \
  --bundle "$manifest.sigstore.json" \
  --custom-trusted-root trusted_root.jsonl \
  --repo ZcashFoundation/zcash-fleet-ops \
  --signer-workflow ZcashFoundation/zcash-fleet-ops/.github/workflows/snapshot-cut.yml \
  --source-ref refs/heads/main

Do not use a snapshot whose manifest verification fails. An unsigned manifest cannot pass this step; use the trust policy described in On trust rather than treating a missing attestation as successful verification.

Archive checksum

Download the archive and verify it against the manifest’s digest before extracting it:

curl -fL "$url" -o "$archive"
printf '%s  %s\n' "$(jq -er '.archive.sha256' "$manifest")" "$archive" \
  | sha256sum --check

For an unsigned manifest, this checks transfer integrity only. For a verified manifest, it also checks that the archive matches the authenticated digest. Do not extract a file that fails verification. Re-download it and investigate persistent mismatches.

Do not pipe an unverified download directly into the live state directory. Streaming extraction writes files before the complete archive digest is known and can leave partial state after a failed transfer.

Extract into your cache directory

Stop Zebra before replacing its state. Extract into a new cache root, not over an existing RocksDB database. Keep the old root until the restored node works and any rollback requirements are satisfied.

Replace /path/to/zebra-cache with the new cache root:

cache_dir=/path/to/zebra-cache
mkdir -p "$cache_dir"
tar --zstd -xf "$archive" -C "$cache_dir"

The archives contain the state/v<major>/<network>/ prefix. Do not extract into that subdirectory a second time; the resulting path is, for example, /path/to/zebra-cache/state/v28/mainnet/.

Make the extracted files writable by the account that runs Zebra. Set the same root in its configuration, leaving persistent state enabled:

[state]
cache_dir = "/path/to/zebra-cache"
ephemeral = false

Match [network] network to the archive. Check environment overrides, container mounts, and state paths.

Start Zebra with that configuration:

zebrad --config /path/to/zebrad.toml start

Check Opened Zebra state cache at for the selected path and chain_tip in loaded Zebra state cache for the restored height. Reuse logs moved state cache from with the old and new paths.

Docker

Stop the Zebra container before restoring its volume. The example below uses the zebrad-cache volume and /home/zebra/.cache/zebra mount from the Docker quick start. Use a new volume when replacing an existing database, then update the Zebra container’s volume mapping.

After downloading and verifying the archive on the host, extract it through a temporary container:

docker run --rm \
  -v zebrad-cache:/home/zebra/.cache/zebra \
  -v "$PWD":/snapshots:ro \
  -e ARCHIVE="$archive" \
  alpine sh -c 'apk add --no-cache zstd tar &&
    tar --zstd -xf "/snapshots/$ARCHIVE" -C /home/zebra/.cache/zebra'

The standard image entrypoint repairs cache ownership on startup. A custom non-root entrypoint must arrange write permissions itself. Keep the volume mount and ZEBRA_STATE__CACHE_DIR consistent.

Troubleshooting

• Zebra syncs from genesis. Check the network, effective cache root, extraction prefix, and database format. An unsupported major directory is not a substitute for the directory Zebra opens. A missing usable database causes Zebra to create an empty one.
• Zebra ignores the restored database. Check the reuse conditions; restore into a fresh root rather than combining databases.
• The database cannot open. Preserve the full error and follow database troubleshooting.
• The starting height differs from the manifest. Read chain_tip.note. Older manifests can describe a live source-node tip rather than the archived finalized tip. A restart can also restore separately cached non-finalized blocks; do not mix unrelated backups into the new root.

See troubleshooting for runtime failures after restoration.

Upgrading Zebra

Two deadlines force upgrades. A network upgrade changes the consensus rules at a fixed height, and only releases that implement it can follow the chain past that height. On Mainnet, each release also halts once the chain passes its end-of-support height. Releases can also change the state format, the configuration schema, RPC responses, metrics, and logs; the release notes list every change that needs operator action under Breaking Changes.

When to upgrade

Zebra logs Your Zebra release is too old and it will stop running at block N from 14 days before the support height. The getdeprecationinfo field end_of_service.estimated_time reports the halt as a Unix timestamp, 24 hours early. Both estimates assume the node is synced to the network tip.

The zebrad version is a SemVer version. A major release adds Mainnet network-upgrade support or breaks an operator interface: configuration, CLI, RPC, or a state format that older releases cannot read. Minor and patch releases are compatible; see Zebra versioning. Release candidates are prereleases for testing and do not move the Docker latest tag.

Before upgrading

Choose a supported release that implements upgrades active now and those activating before your next planned update.

1. Read the release notes of every release after the one you run, up to the target. Act on each Breaking Changes entry: Zebra refuses to start with a configuration field it does not recognize, and dashboards, alerts, and RPC clients break on renamed metrics, log lines, or response fields.
2. Check whether the target changes the major state format. The release notes say so; the running format is the v<major> directory under <[state] cache_dir>/state/. If the major changes, take a backup: no older release can read the upgraded state. If your state is older than the target’s immediately preceding major, the target cannot reuse it; see first start.
3. Upgrade the software that depends on Zebra in the same window (see dependent software).
4. Download and verify the new release as for a new installation.

Backing up the state

A backup is a copy of one network’s state directory, taken while no process has the database open. Keep it outside [state] cache_dir, where no Zebra process moves, upgrades, or deletes it.

1. Stop Zebra (Stopping Zebra) and every process that opens its database directly.

2. Copy the directory into a new, dated backup directory. For a Mainnet node with the default cache directory on Linux, before upgrading to Zebra 7.0.0:

   backup=/srv/zebra-backup/$(date +%F)-v28
   mkdir -p /srv/zebra-backup
   mkdir "$backup" && cp -a ~/.cache/zebra/state/v28/mainnet "$backup/"
   

   For the Docker image, copy out of the state volume:

   docker run --rm \
     -v zebrad-cache:/cache -v /srv/zebra-backup:/backup alpine \
     sh -c 'b="/backup/$(date +%F)-v28" &&
       mkdir "$b" && cp -a /cache/state/v28/mainnet "$b/"'
   

   The mkdir of the dated directory fails if that backup already exists, so a repeated command never mixes two copies.

The copy needs as much free space as the directory occupies (du -sh it first). A recent snapshot of the old format can replace a backup for rollback, at the cost of syncing the blocks after its height.

Upgrading

Stop the old release, replace it, and start the new one with the same configuration and state directory. Never run two zebrad processes on the same state.

Binary installations

Replace the executable with one of:

cargo binstall [email protected]
cargo install --locked --version 7.0.0 zebrad

or with the verified release archive. Then start zebrad as before.

Docker

Stop the container without Docker’s default 10-second kill deadline, then recreate it from the new tag with the same volume, ports, and environment:

docker stop --timeout -1 zebra
docker rm zebra
docker run -d --name zebra --restart unless-stopped \
  -p 8233:8233 -v zebrad-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

Zebra with Docker documents the image and its tags.

What happens on first start

The new release looks for its own major-version directory, <cache_dir>/state/v<major>/<network>, and acts on what it finds:

Format upgrades log trying to open older database format: launching upgrade task, then Zebra automatically upgraded the database format and database format is valid when done. Stopping Zebra during an upgrade is safe: the version file advances only after each step completes, and the next start resumes the remaining work.

The setting [state] delete_old_database (default true) makes each start delete older major-version directories under the cache directory, except the predecessors of registered reusable upgrades (v25 to v28 in 7.0.0). Setting it to false keeps every directory, but does not prevent the rename above. Renaming or symlinking a versioned directory by hand does not convert its format.

To avoid a sync from genesis when skipping majors, restore a snapshot whose format the target can open or reuse, instead of starting from the old directory.

Dependent software

Record the Zebra revision used to build each direct reader, including cached binaries; the downstream application’s revision alone does not establish state-format compatibility.

Verifying the upgrade

• The executable reports its version: zebrad --version. A running node reports it in the getinfo RPC field build, in the Prometheus metric zebrad_build_info{version="…"}, and in its peer user agent /Zebra:<version>/.
• The logs show the state handling above and then sync progress.
• The readiness endpoint returns 200 once the node is back near the network tip.
• The getblockchaininfo RPC lists the network upgrades the release knows in upgrades, with their activation heights.

Rolling back

Rolling back is limited by the same deadlines: the older release cannot follow the chain past a network upgrade it does not implement, and on Mainnet it halts at its own support height.

Within the same major state format, start the older release on the existing state. It opens a newer minor or patch format and records the downgrade (trying to open newer database format: data should be compatible).

Across a major format change, the older release looks for its own, older directory, which the upgrade renamed away. Without the backup it syncs from genesis. To restore the backup:

1. Stop Zebra and every process that opens its database directly.

2. Move the new major directory aside, so that a later upgrade reuses the restored directory instead, then restore the backup. Each mkdir fails instead of reusing an existing directory:

   state=~/.cache/zebra/state
   backup=/srv/zebra-backup/2026-10-23-v28   # the backup to restore
   mkdir /srv/zebra-backup/abandoned-v29 &&
     mv "$state/v29/mainnet" /srv/zebra-backup/abandoned-v29/
   mkdir -p "$state/v28"
   mkdir "$state/v28/mainnet" &&
     cp -a "$backup/mainnet/." "$state/v28/mainnet/"
   

3. Start the older release.

Roll back direct readers to builds for the older format at the same time.

Zebra 7.0.0

• NU7. Mainnet activates NU7 at height 3,543,405; 6.x releases cannot follow the chain past it. After activation, Mainnet nodes disconnect peers that advertise a protocol version below 170190.
• State format 28 → 29. The first start renames state/v28/<network> to state/v29/<network> without a resync. Zebra 6.x cannot read format 29: back up state/v28 first. A format-27 state (Zebra 2.4 to 5.x) is not reused; restore a snapshot instead of syncing from genesis.
• Support window. 7.0.0 is supported for 56 days after its estimated release height, instead of the usual 12 weeks.
• Dependent software.
  • The zcashd-compat sidecar must be zebra-compat-v1.3.0; earlier builds stop at NU7.
  • Zallet 0.1.0-beta.3’s zebra backend reads format 28 and cannot read a 7.0.0 state; its RPC-based zaino backend is unaffected.
• Breaking changes. These are in the notes for 7.0.0 and 7.0.0-rc.0:
  • Per-peer labels are removed from the network metrics.
  • getblocktemplate advertises only time as mutable.
  • Custom testnets reject configurations that were previously accepted and store their state in new directories; resync custom networks.

Zebra with Docker

The Zebra runtime image packages zebrad and its startup script. It includes no configuration file, including docker/default-zebra-config.toml, no chain database, and no zcashd. Containerized nodes have the same resource requirements as native nodes.

Images and tags

Releases and pre-releases publish to Docker Hub as zfnd/zebra; the same tag selects linux/amd64 or linux/arm64.

Release builds do not publish commit-SHA tags. Pre-releases never move latest, and publishing workflows do not maintain moving beta or rc tags.

Use a version tag for an explicit upgrade policy, or an image digest to pin exact image content. Pulling a newer image does not replace a running container; recreate the container with its existing state volume.

Non-release image publishing belongs to continuous delivery.

Quick start

Run a Mainnet node with a persistent named volume:

docker run -d \
  --name zebra \
  --restart unless-stopped \
  -p 8233:8233 \
  -v zebrad-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

To start from existing state, populate the volume from a state snapshot before starting Zebra.

Use a separate volume and port for a Testnet node:

docker run -d \
  --name zebra-testnet \
  --restart unless-stopped \
  -e ZEBRA_NETWORK__NETWORK=Testnet \
  -e 'ZEBRA_NETWORK__LISTEN_ADDR=[::]:18233' \
  -p 18233:18233 \
  -v zebrad-testnet-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

Inspect startup and synchronization logs with docker logs -f zebra. Stop Zebra without Docker’s forced-kill deadline before replacing its container or restoring state:

docker stop --timeout -1 zebra

Docker’s default Linux stop timeout is ten seconds; use -1 to allow Zebra’s shutdown to finish. Stop and remove the old container before reusing its name and state volume. Never run two Zebra processes against the same state database.

Paths and permissions

The image’s zebra account has UID and GID 10001 and home /home/zebra:

The entrypoint starts as root, prepares writable directories, then executes Zebra through setpriv --reuid=10001 --regid=10001 --init-groups.

Before dropping privileges, the entrypoint recursively changes ownership of the state-cache directory, cookie directory, and configured log-file directory. It also changes ownership of each immediate parent unless that parent is / or $HOME. Bind mounts therefore change ownership on the host, not just inside the container. Mount dedicated directories, not a shared home or log tree. Recursive ownership changes also traverse an existing state database on every startup.

Mount cache directories read-write. Mount configuration files read-only and make them readable by UID 10001; the entrypoint does not repair config-file permissions. Paths configured only in TOML must already be writable by the container user because directory preparation reads environment variables, not the TOML file.

The Docker --user option bypasses root startup but does not skip the entrypoint’s ownership operations. It can therefore fail on mounts whose ownership the selected user cannot change. To bypass preparation deliberately, use both --user 10001:10001 and --entrypoint /usr/local/bin/zebrad, and prepare every writable mount beforehand. This also bypasses CONFIG_FILE_PATH; pass --config directly when using that override.

Configuring Zebra

Use Zebra’s environment variables or mount a TOML configuration.

Mounted configuration

Generate a configuration on the host:

docker run --rm zfnd/zebra:7.0.0 zebrad generate > zebrad.toml

Edit the fields you need, then mount the file at the default discovery path:

docker run -d \
  --name zebra \
  -p 8233:8233 \
  -v zebrad-cache:/home/zebra/.cache/zebra \
  --mount type=bind,src="$PWD/zebrad.toml",dst=/home/zebra/.config/zebrad.toml,readonly \
  zfnd/zebra:7.0.0

For a different path, mount the file there and set CONFIG_FILE_PATH to its container path. The entrypoint supplies --config only when that path is an existing regular file. A missing path does not cause the entrypoint to fail; Zebra falls back to normal configuration discovery. To require a particular file, pass zebrad --config /path/in/container/zebrad.toml start after the image name instead.

Include zebrad before CLI options or subcommands in Docker commands. The entrypoint removes its first argument when that argument starts with -, so passing a bare --config or --help after the image name loses that option.

Entrypoint environment variables

The entrypoint interprets these variables; other settings go to Zebra’s configuration loader.

Use docker/.env for node configuration examples and docker/test.env for test settings. ZEBRA_SECTION__KEY variables override values in mounted configuration files; unknown ZEBRA_* configuration fields fail loading.

RPC

Enable RPC on the container’s network interface so Docker forwarding or other containers can reach it. Publish it only on host loopback, never on a public interface:

docker run -d \
  --name zebra \
  -p 8233:8233 \
  -p 127.0.0.1:8232:8232 \
  -e ZEBRA_RPC__LISTEN_ADDR=0.0.0.0:8232 \
  -v zebrad-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

For clients on the same private Docker network, omit the RPC -p mapping entirely and connect to Zebra’s service name and container port. Container loopback (127.0.0.1) is not the host loopback or another container’s loopback.

Use cookie authentication; the container’s default cookie path is listed above.

Make an authenticated request inside the container without publishing RPC:

docker exec --user 10001:10001 zebra sh -c '
  curl --fail --silent --show-error \
    --user "$(cat /home/zebra/.cache/zebra/.cookie)" \
    --header "Content-Type: application/json" \
    --data '\''{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}'\'' \
    http://127.0.0.1:8232
'

For a client in another container, mount a dedicated ZEBRA_RPC__COOKIE_DIR read-only and give its UID permission to read the cookie. This avoids sharing the state database. Share the directory, not a copied credential, so the client can reload the cookie after Zebra restarts.

Set ZEBRA_RPC__ENABLE_COOKIE_AUTH=false only for a client that cannot use cookie authentication, on an isolated network with trusted clients. Cookie authentication is not a reason to publish RPC publicly.

Health endpoints

The runtime image includes curl but no Docker HEALTHCHECK. To enable health checks, add these fields to the Zebra service in a Compose file:

environment:
  - ZEBRA_HEALTH__LISTEN_ADDR=127.0.0.1:8080
healthcheck:
  test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:8080/healthy"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 90s

Use /ready to gate dependent traffic, not to require a new node to finish synchronizing during startup. Health checks need no RPC or cookie. For probes outside the container, bind to 0.0.0.0:8080 and restrict exposure to the probe network.

P2P networking

Without a published P2P port, a bridge-networked container synchronizes through outbound connections but cannot receive unsolicited connections from outside its Docker network.

When a firewall, network address translation (NAT), or load balancer changes the externally reachable address, configure [network] external_addr with the public IP and mapped port. For example, add -e ZEBRA_NETWORK__EXTERNAL_ADDR=203.0.113.42:8233, replacing the documentation address with your node’s actual address. Open the corresponding P2P port in the firewall. Publishing a port does not enable its listener.

Custom images

Build from the repository root using the multi-stage Dockerfile:

git clone --depth 1 --branch v7.0.0 https://github.com/ZcashFoundation/zebra.git
cd zebra
docker build --file docker/Dockerfile --target runtime --tag zebra:local .

The build uses BuildKit bind and cache mounts. Select runtime for a node; other stages serve the build and test pipeline:

Building with custom features

The FEATURES build argument adds Cargo features. The Dockerfile does not pass --no-default-features, so an empty argument does not disable the default feature set.

For example, add spend indexing with the indexer feature:

docker build \
  --file docker/Dockerfile \
  --target runtime \
  --build-arg FEATURES="default-release-binaries indexer" \
  --tag zebra:custom-features \
  .

The Dockerfile declares these build arguments:

To use different filesystem IDs, build with both --build-arg UID=... and --build-arg GID=.... Update mount permissions and any hard-coded Compose paths when changing the account or home directory.

zcashd-compat image removal

Zebra 7.0.0 removes the runtime-zcashd-compat Docker target and its ZCASHD_COMPAT_ARCHIVE_URL and ZCASHD_COMPAT_ARCHIVE_SHA256 build arguments. The runtime image no longer bundles zcashd or zcash-cli.

Use zcashd-compat mode with a separately supplied zcashd process and configuration; the image no longer fills in sidecar configuration.

Compose deployments

Run these commands from the repository root. Before running examples concurrently, give each unique container names, port mappings, and state volumes.

For the base node, pin the service’s image to zfnd/zebra:7.0.0 if a moving latest tag is not appropriate. Remove or change its platform: linux/amd64 setting to select the ARM64 runtime image on an ARM64 host. Then start it:

docker compose -f docker/docker-compose.yml up -d

To switch the base Compose file to Testnet, change the network, its explicitly configured listen address, and the published P2P port.

Running Zebra with lightwalletd

The supplied example disables Zebra’s cookie authentication but does not publish RPC to the host. Lightwalletd connects to zebra:8232 over the Compose network. Keep that network limited to trusted containers.

The example also runs lightwalletd with --no-tls-very-insecure. For local testing, restrict its port mappings to 127.0.0.1:9067:9067 (gRPC) and 127.0.0.1:9068:9068 (HTTP). Do not expose these plaintext endpoints as a production service. Configure TLS and access controls for an externally accessible deployment; see lightwalletd.

After making these changes, start the example:

docker compose -f docker/docker-compose.lwd.yml up -d

The dependency condition waits for the Zebra container to start, not for Zebra to synchronize. This file does not load docker/.env; put overrides in its service environment settings or explicitly add an env_file.

Running Zebra with Prometheus and Grafana

The observability example exports metrics to Prometheus and traces to Jaeger. It sets ZEBRA_TRACING__OPENTELEMETRY_ENDPOINT=http://jaeger:4318, service name zebra, and sample percentage 100. Reduce ZEBRA_TRACING__OPENTELEMETRY_SAMPLE_PERCENT when full trace collection is not required; see OpenTelemetry export.

Zebra’s RPC and metrics ports are not published to the host; Prometheus scrapes zebra:9999 over the Compose network. Restrict the remaining non-P2P published ports to host loopback by prefixing each mapping with 127.0.0.1:. These include the monitoring interfaces, Jaeger’s receivers, and Jaeger’s span-metrics endpoint. For example, replace 9094:9090 with 127.0.0.1:9094:9090. Keep RPC disabled altogether if no trusted client needs it by removing ZEBRA_RPC__LISTEN_ADDR.

Export GF_SECURITY_ADMIN_PASSWORD with a strong, unique password in the shell running Compose. An unset or empty value prevents startup. Then build and start the stack:

docker compose -f docker/docker-compose.observability.yml up -d --build

Grafana provisions the supplied dashboards and Prometheus/Jaeger data sources. Log in as admin with the password supplied through GF_SECURITY_ADMIN_PASSWORD. This initializes new Grafana volumes only; change existing account passwords in Grafana. Prometheus’s admin and lifecycle APIs are disabled. The supplied Jaeger configuration stores traces in memory, capped at 100000 traces. Alertmanager defines receiver names but no notification destinations; configure receivers before relying on alerts. The configuration and dashboard files are under docker/observability/.

Running CI tests locally

The test image contains the source tree and nextest. Configure test selection in docker/test.env, or pass overrides when starting the container. Select the ci profile to run the current unit and integration test set:

docker compose -f docker/docker-compose.test.yml build
docker compose -f docker/docker-compose.test.yml run --rm \
  -e NEXTEST_PROFILE=ci zebra

The entrypoint runs nextest with --locked --release, the image’s FEATURES, and --run-ignored=all. The ci profile excludes stateful and end-to-end tests through its default filter. Select ci-stateful or ci-e2e with a nonempty NEXTEST_FILTER expression for those suites, and supply their required cached state. See the nextest profiles and continuous integration.

Without NEXTEST_PROFILE, the test image executes its command, which defaults to cargo test; this does not use the prebuilt release-test configuration. The runtime image does not contain Cargo or test binaries.

Mining example limitations

The mining example requires a reward address in docker/mining/.env. S-NOMP waits for Zebra’s internal /healthy endpoint before starting, but mining still requires a synchronized node. See Mining with Docker for configuration and limitations.

Tracing Zebra

Zebra records structured events and spans through Rust’s tracing library. Events are individual log records; spans attach context to an operation and its nested work. Zebra writes formatted logs to standard output unless a log file is configured. Optional exporters send this instrumentation to journald, Sentry, or an OpenTelemetry collector.

Configuration

To write plain-text logs to a file:

[tracing]
filter = "info,zebra_network=warn"
log_file = "/var/log/zebra/zebrad.log"
use_color = false
buffer_limit = 128000

Create a writable log directory owned by the Zebra account. If Zebra runs with elevated permissions, prevent other users from modifying that directory or its parents. Zebra appends to the file; it does not configure log rotation. Set use_color = false for plain-text files: formatted-log color detection uses standard output, even when log_file redirects the logs.

For progress-bar log paths, buffer limits, and color overrides, see the configuration reference.

Filters and compiled log levels

The filter uses tracing-subscriber directives. A bare level sets the global threshold; target=level sets a threshold for a Rust target, usually a module path. Separate directives with commas. Levels are error, warn, info, debug, and trace; off disables a target.

For example, warn,zebrad=info,zebra_network=debug selects warnings globally, information from zebrad, and debug events from zebra_network. Directives can also select spans and their fields; see the syntax reference before using field filters.

Override the configured filter with any of these command forms:

zebrad -c zebrad.toml --filters 'info,zebra_network=debug'
zebrad -c zebrad.toml --filters 'info,zebra_network=debug' start
zebrad -c zebrad.toml start 'info,zebra_network=debug'

The top-level --filters option applies with or without an explicit start. Positional filters after start take precedence over --filters and are joined with commas. An explicit filter takes precedence over the default selected by -v.

The utility commands generate and tip-height use fixed filters and disable flamegraph collection.

Default release builds compile out debug and trace instrumentation through release_max_level_info; neither -v nor runtime filters can restore it. Build from the repository with default features disabled to retain all levels:

cargo install --locked --path zebrad --no-default-features \
  --features 'progress-bar,prometheus,sentry,opentelemetry'

For other compile-time ceilings, see Cargo features.

Dynamic tracing

Build with the filter-reload feature and configure a loopback listener:

[tracing]
endpoint_addr = "127.0.0.1:3000"

Read or replace the running filter:

curl --fail http://127.0.0.1:3000/filter
curl --fail --data 'info,zebra_network=debug' http://127.0.0.1:3000/filter

The server accepts GET /filter and POST /filter; the POST body is the new UTF-8 filter string. A reload changes the running subscriber, not the configuration file. The endpoint has no authentication. Keep it on loopback or a restricted management network.

Filter reloading is disabled in builds using tokio-console with tokio_unstable, even if the HTTP endpoint is enabled. See Tokio console.

Journald logging

Build with the journald Cargo feature and set [tracing] use_journald = true on Linux systems running systemd. Zebra adds a journald subscriber for events and spans; formatted output to standard output or log_file remains enabled. Failure to initialize the journald subscriber fails tracing initialization. Setting the field without the Cargo feature logs a warning instead of activating journald.

Flamegraphs

A flamegraph visualizes time spent in nested tracing spans, not samples of every function on the CPU stack. Build with the flamegraph Cargo feature and set a writable output path:

[tracing]
flamegraph = "/var/log/zebra/spans"

Zebra records folded span stacks in spans.folded and generates spans.svg during its shutdown hook. An extension in the configured path is replaced by these extensions. An abrupt process termination can prevent SVG generation. Use a directory protected against modification by other users, and compile in the span levels needed for the investigation.

OpenTelemetry export

OpenTelemetry collects spans as traces for operation-level analysis. With the opentelemetry feature, configure an endpoint:

[tracing]
opentelemetry_endpoint = "http://127.0.0.1:4318"
opentelemetry_service_name = "zebra"
opentelemetry_sample_percent = 10

Zebra exports batches using OTLP, the OpenTelemetry Protocol, over HTTP with binary Protocol Buffers encoding. It appends /v1/traces unless that suffix is already present. Use an OTLP HTTP receiver, not a gRPC endpoint. The observability stack supplies Jaeger as a receiver and trace viewer.

Set [tracing] opentelemetry_sample_percent to an integer from 0 through 100: Zebra samples no traces at 0, all at 100, and uses trace-ID ratio sampling between them. See the configuration reference for environment fallbacks and their nonstandard integer-percentage syntax.

Sampling cannot recover instrumentation removed by compile-time level features or excluded by the tracing filter. Zebra continues without trace export if exporter initialization fails.

Sentry production monitoring

Sentry receives error reports, diagnostic logs, and release health sessions. With the sentry feature, set SENTRY_DSN to a valid project ingestion address to enable reporting. Leave it unset to disable reporting.

With Sentry enabled, Zebra sends:

• Error events as issues and Sentry Logs; warnings as Logs and breadcrumbs. Breadcrumbs are contextual records attached to later issues.
• Sync progress logs with a 60-second reporting interval, and a log when the best chain tip changes network upgrade. Other information-level events become breadcrumbs rather than standalone Logs. Runtime filters still apply.
• Panics as fatal, unhandled exceptions, with the full panic report and source location as context.
• Release health sessions, rotated every 24 hours. Graceful shutdown ends a session as exited; a panic, crash, or forced shutdown ends it as crashed. Sessions share a random identifier per run, so crash-free users measures runs, not people. A process killed before shutdown handling cannot send its final session update.

Events carry chain.network and, once the progress task observes a chain tip, chain.height and chain.network_upgrade. Logs carry the same information as attributes; the height is numeric for aggregation.

Review the destination and access controls before enabling reporting: error context and panic reports leave the node. For deployment metadata, see GCP deployment operations; for event selection, see the Sentry integration.

Zebra metrics

Zebra exposes counters, gauges, and timing distributions through a Prometheus HTTP exporter. Prometheus stores the samples; Grafana queries Prometheus to render dashboards. Metrics complement health checks: a successful scrape does not establish that the node is ready to serve clients.

Enable the exporter

Use a build with the prometheus feature.

If no configuration file exists, create one:

zebrad generate -o zebrad.toml

In zebrad.toml, set [metrics] endpoint_addr:

[metrics]
endpoint_addr = "127.0.0.1:9999"

Start Zebra with that configuration and retrieve the metrics:

zebrad -c zebrad.toml start

From another terminal:

curl --fail http://127.0.0.1:9999/metrics

The exporter provides no authentication or TLS configuration. Bind it to loopback when Prometheus runs on the same host. For remote scrapes, bind to a private interface and restrict access with a firewall or authenticated proxy. Failure to bind the configured address terminates startup.

For Prometheus running on the same host, use:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: zebra
    metrics_path: /metrics
    static_configs:
      - targets: ["127.0.0.1:9999"]

For container deployments, use an address reachable from Prometheus; the supplied Compose stack uses zebra:9999.

Configure Grafana’s Prometheus data source with the Prometheus server URL, not Zebra’s exporter URL. For a same-host deployment without containers, the usual Prometheus URL is http://127.0.0.1:9090. The Compose stack provisions its own data source automatically.

Metric names and types

Zebra’s source uses dot-separated names, such as sync.estimated_distance_to_tip. The exporter replaces dots with underscores, so Prometheus queries use sync_estimated_distance_to_tip. Counter names are not automatically given a _total suffix: use the exported name as written.

Counters accumulate during a process run; use rate() or increase() for activity over time. Gauges represent a current or most recently measured value. A metric can be absent until its recording path executes; absence is not equivalent to zero.

Zebra exports timing distributions as Prometheus summaries, with a quantile label and _sum and _count series, not _bucket series:

rpc_request_duration_seconds{quantile="0.99"}

Do not apply histogram_quantile() to these Zebra summaries or average their quantiles across nodes. For a mean duration over five minutes, divide the rate of _sum by the rate of _count. Metrics generated separately by Jaeger’s span-metrics connector have their own types and naming.

Principal operator metrics

The table uses source names; replace dots with underscores in Prometheus. Suggested alert conditions are operational choices, not Zebra defaults. Choose sustained thresholds that distinguish initial sync from steady-state operation and accommodate the network’s block production intervals.

Prometheus also generates up{job="zebra"} for scrape success. Alert on zero or missing scrape data separately from chain progress. This metric comes from Prometheus, not Zebra.

Network metric aggregation

Network metrics omit per-peer labels to bound the number of time series. Update dashboards, recording rules, and joins that depend on peer identities:

• Connection-state, request, response, message, and byte metrics have no addr label. The zebra.net.connection.state gauge counts live connections by command; transitions and disconnects decrement the old state. Request, response, and message counters retain command labels.
• The counters zcash.net.peers.connected, zcash.net.peers.obsolete, and zcash.net.peers.missing_services have no remote_ip or user_agent labels. They count handshake activity, not currently connected peers.
• The gauges zcash.net.peers.version.connected and zcash.net.peers.version.obsolete contain the remote protocol version from the most recent corresponding handshake, without remote_ip labels. They are not peer counts or a distribution of connected versions.
• The zebra.net.in.errors counter has no addr label.

The counter zcash.net.peer.version.outcomes.total provides a software breakdown through the bounded implementation values zebra, zakura, legacy_zcashd, and other. Select outcome="success" for successful handshakes. These remain cumulative handshake counts, not current peer counts.

Other bounded labels include:

Mining metrics

Prometheus replaces dots in metric names with underscores. The RPC dashboard includes mining outcomes and mean build and announcement durations. Zebra exports duration metrics as Prometheus summaries, with quantiles plus _sum and _count series.

Submission labels follow the zcashd-compatible result, with accepted representing JSON null. Operational JSON-RPC errors remain in rpc.errors.total; they are not consensus rejections. Some result variants are reserved by the response type and are not currently returned.

Build timing covers the shared constructor used by background and fallback builders, not state or mempool reads, executor scheduling, long-poll waits, or cache hits. It records each completed build, including work superseded before a miner requests it.

First-template latency uses the state’s monotonic publication time, not the block header timestamp or the time the RPC notices a change. It records once per tip transition across RPC clones; repeated requests do not add samples. Tips with no served template and templates on uncommitted candidates are excluded. Returning to an earlier tip after a reorg starts a new interval. At startup, timing begins when the state publishes its loaded tip. The measurement ends when the RPC returns the template, before network delivery or pool job distribution; it also includes time until a miner requests work.

Announcement completion means every selected connection completed its local write, not that peers received, validated, or relayed the block. Failed attempts include write errors and timeouts; a retry records another outcome. Successful retry durations retain the original gossip receipt time, including queueing, peer-readiness waits, and retry delays. Ordinary tip and early-relay adverts are excluded. No peer count is exported because the broadcast response does not carry one.

Watch increases in rejected submissions and failed announcements alongside rising announcement durations. A successful local write is not proof against stale blocks, and a stalled attempt has no completion sample yet. These metrics do not measure network-wide propagation or stale-block rates.

Observability stack

The Compose stack builds Zebra and starts Prometheus, Grafana, Jaeger, and Alertmanager using configuration in docker/observability/. It persists Zebra’s state, Prometheus, Grafana, and Alertmanager in volumes.

The supplied stack is a development deployment, not a hardened public service. Zebra’s RPC and metrics ports stay on the Compose network, and RPC requires cookie authentication. The remaining port mappings bind on all host interfaces; restrict published management ports to loopback or a private network before starting it. Prometheus’s admin and lifecycle APIs are disabled.

Export GF_SECURITY_ADMIN_PASSWORD with a strong, unique password; Compose rejects an unset or empty value. Run from the repository root:

docker compose -f docker/docker-compose.observability.yml up -d
docker compose -f docker/docker-compose.observability.yml logs -f zebra

Log in to Grafana as admin with the password supplied through GF_SECURITY_ADMIN_PASSWORD. It initializes new Grafana volumes only; change existing account passwords in Grafana. The stack provisions the Prometheus and Jaeger data sources and the dashboards in docker/observability/grafana/dashboards/. The home dashboard is zebra_overview.json; other dashboards include peers.json, network_health.json, syncer.json, mempool.json, rocksdb.json, rpc_metrics.json, rpc_tracing.json, and value_pools.json. For a separate Grafana deployment, import the JSON files and select its Prometheus data source.

The file docker/observability/prometheus/prometheus.yaml scrapes zebra:9999 and Jaeger’s span metrics at jaeger:8889, every 15 seconds. Zebra exports traces to http://jaeger:4318 with 100% sampling in this stack. Reduce [tracing] opentelemetry_sample_percent through the Compose environment when lower trace volume is required; see OpenTelemetry export.

Review docker/observability/prometheus/rules/zebra_alerts.yml before relying on its alerts. Its latency rules use exported summary quantiles: RPC p99 above two seconds and successful-handshake p95 above two seconds, each sustained for five minutes. Zebra abandons handshakes after three seconds, so slower ones never reach the handshake series. The RPC latency panels show per-method quantiles, not a combined percentile across methods or nodes. The receivers in docker/observability/alertmanager/alertmanager.yml have no notification destinations; configure them before expecting notifications.

Stop the stack without deleting its volumes:

docker compose -f docker/docker-compose.observability.yml down

Zebra health endpoints

Zebra’s HTTP/1.1 health listener provides liveness and readiness probes. Liveness checks for recently responsive peers; readiness also checks sync progress before a load balancer routes client traffic to the node.

Enable it with [health] listen_addr; no optional Cargo feature is needed:

[health]
listen_addr = "127.0.0.1:8080"
min_connected_peers = 1
ready_max_blocks_behind = 2
ready_max_tip_age = "5m"
enforce_on_test_networks = false

Configuration

See the configuration reference for fields and defaults.

The field [health] ready_max_tip_age measures local progress, not the latest block header’s timestamp. The progress task samples the chain about every five seconds; only a height above its previous maximum resets the timer.

The health server refreshes its peer count from the address book every five seconds. Peers count only while marked as having responded within the network’s response recency window; failed or pending connections do not count. This is not a count of open TCP sockets.

Endpoints

All responses use Content-Type: text/plain; charset=utf-8.

Liveness: GET /healthy

This endpoint does not require a chain tip or a completed initial sync. It applies the same peer check on every network, including Regtest. Setting min_connected_peers = 0 makes it succeed whenever the listener responds, but also removes the peer requirement from readiness.

Readiness: GET /ready

On Mainnet, or when enforce_on_test_networks = true, Zebra evaluates these checks in order and returns the first failure:

The synchronizer’s near-tip signal uses the moving average of recent sync lengths; it is not the same as the estimated block lag. Readiness requires both checks. Negative lag estimates are clamped to zero by the progress task. Equality with either configured maximum passes the corresponding check.

On test networks, the default enforce_on_test_networks = false bypasses all readiness checks: /ready returns 200 OK even with no peers or chain tip. Set it to true before using readiness to gate test-network client traffic. Regtest’s synchronizer always reports near-tip status, but enabling enforcement still applies the peer, tip, age, and lag checks. In a Regtest network that mines only on demand, the tip-age check can fail between blocks.

Other requests

Requests with a method other than GET, including HEAD, return 405 Method Not Allowed. The body is method not allowed, except that HTTP responses to HEAD have no body. Unknown paths requested with GET return 404 Not Found with not found.

Kubernetes and load balancers

Bind [health] listen_addr = "0.0.0.0:8080" inside a pod when the kubelet must reach the listener through the pod IP. Restrict that port with network policies rather than publishing it as a public service.

Use /ready as the readiness probe. Keep the pod out of service during initial sync instead of restarting it for lack of readiness. A TCP liveness probe avoids restarting a functioning node during a peer outage:

livenessProbe:
  tcpSocket:
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Use httpGet with path: /healthy for liveness only when insufficient peers should trigger a restart. Allow enough startup and failure time for peer discovery and temporary network outages; restarting cannot repair an unreachable external network.

Route load-balancer traffic only after /ready returns 200; remove the node on 503. Probe RPC separately: neither health endpoint checks the JSON-RPC listener or executes a client-facing method.

Security

The health listener has no authentication or TLS. It returns coarse node state, including lag or time since progress on a failed readiness check. Bind to loopback or an internal interface, and restrict access with firewall rules or network policies. Failure to bind listen_addr terminates startup.

JSON-RPC server

Zebra serves chain data, transaction submission, and mining operations over HTTP JSON-RPC. Zebra does not hold wallet keys or implement wallet accounting; Zallet provides the wallet API. The zcashd API migration guide records differences from zcashd, including missing fields and unsupported methods.

Enabling the server

JSON-RPC is disabled until [rpc] listen_addr is set to an explicit IP address and port. See Ports for network conventions.

Generate a configuration file:

zebrad generate -o zebrad.toml

Add the listener to its existing [rpc] section:

[rpc]
listen_addr = "127.0.0.1:8232"

Start Zebra with that file:

zebrad -c zebrad.toml start

Keep the listener on loopback. Zebra provides neither TLS encryption nor per-method access control. A client with RPC access can submit transactions and blocks and call state-changing methods such as invalidateblock. Cookie authentication authenticates the caller; it does not encrypt traffic. For remote access, use an authenticated, TLS-terminating reverse proxy or an encrypted tunnel, and prevent clients from reaching the plaintext listener directly. Do not publish an unauthenticated RPC port to the internet.

Authentication

The [rpc] enable_cookie_auth field defaults to true. At JSON-RPC server startup, Zebra generates a random credential and writes <cookie_dir>/.cookie in this format:

__cookie__:<base64-encoded random secret>

The username is __cookie__; the secret encodes 32 random bytes. Zebra creates new cookie files with mode 0600 on Unix and refuses to write through a symlink. Restrict access to the cookie directory to the node operator and trusted clients. Treat the file as a password, not as an HTTP browser cookie. Clients send its contents using HTTP Basic authentication and must read the new credential after a Zebra restart. On clean RPC shutdown, Zebra removes the cookie file; removal failures are logged.

The [rpc] cookie_dir setting is independent of [state] cache_dir: changing the state directory does not move the cookie. Give each Zebra instance a separate cookie directory, even on different networks.

For the Linux default cookie directory, call the server with:

cookie="${XDG_CACHE_HOME:-$HOME/.cache}/zebra/.cookie"
curl --user "$(cat "$cookie")" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}' \
  http://127.0.0.1:8232/

Set cookie to the configured directory’s .cookie file when using a custom [rpc] cookie_dir.

Zebra has no configuration for static RPC usernames and passwords. Setting [rpc] enable_cookie_auth = false disables credential checks; credentials sent by clients then have no effect. This is required by lightwalletd, which does not read Zebra’s cookie. Authentication settings apply only to JSON-RPC, not to either gRPC listener.

Configuration

See the configuration reference for [rpc] fields and defaults. The experimental lightwalletd-compatible gRPC service is covered in Serving light clients directly from Zebra.

Zebra has no [rpc] CORS, allowed-origin, client-IP allowlist, or batch-count configuration. Cross-origin browser restrictions are not a replacement for RPC authentication or network access controls.

Indexer gRPC service

The indexer service is separate from JSON-RPC and from the wallet-facing CompactTxStreamer protocol. Its protocol definition provides four methods:

Indexers use these streams alongside read-only access to Zebra’s finalized state database. Build with the indexer feature for consumers that require the spending-transaction index, including Zallet’s Zebra backend. The listener does not require this feature: successful startup does not establish that the index exists.

Set [rpc] indexer_listen_addr = "127.0.0.1:8230" to enable the service on an example port. It uses plaintext HTTP/2 without authentication; JSON-RPC cookie settings do not protect it. Keep it on loopback or a restricted private network.

Transport and compatibility

Send HTTP POST requests with Content-Type: application/json. Zebra accepts JSON-RPC 2.0 and the legacy request format used by zcashd. For individual legacy requests, include method, params, and id, and omit jsonrpc. Zebra also accepts lightwalletd’s "jsonrpc":"1.0" field. The compatibility middleware converts the response back to the corresponding legacy format, including both result and error. Missing content types and text/plain are treated as JSON. The server does not offer WebSocket transport.

Use JSON-RPC 2.0 for batches. Send an array of request objects, each with its own "jsonrpc":"2.0" and id. The legacy compatibility conversion applies to individual objects, not to an entire batch. Batches have no separate request-count limit, but the request body is limited to 4,001,024 bytes and the response body to [rpc] max_response_body_size.

For example, using the cookie variable from Authentication:

curl --user "$(cat "$cookie")" \
  --header 'Content-Type: application/json' \
  --data '[{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]},{"jsonrpc":"2.0","id":2,"method":"getbestblockhash","params":[]}]' \
  http://127.0.0.1:8232/

Zebra uses zcashd-style application error codes, including -5 for an unknown block hash and -8 for an invalid block height. The RPC middleware rewrites invalid-parameter code -32602 to -1 while preserving the error message, data, and request ID. Other error codes pass through unchanged; this is not a guarantee that every failure matches zcashd byte for byte.

Methods

Zebra 7.0.0 registers the following 42 JSON-RPC method names. The RPC trait and implementation define their parameters and results. The rpc.discover method returns an OpenRPC 1.3.2 document with machine-readable method and type schemas.

Control and discovery

Blockchain

Transactions and mempool

The mempool holds verified transactions that have not yet been mined.

Transparent address index

Mining

See Mining for configuration and block-template use.

Peer networking

Address utilities

A Unified Address contains one or more payment receivers. A TEX address encodes a transparent receiver with a restriction on the source of its funds.

Running Zallet with Zebra

Zallet provides wallet functions; Zebra validates the chain and serves node RPCs. Use the API migration guide to route calls and Zallet’s setup guide to initialize the wallet, encryption, and wallet RPC server.

Keep the versions in step

Zallet 0.1.0-beta.3 is the latest release. Its zebra backend reads Zebra’s database directly and requires format 28 (backend changelog); Zebra 7.0.0 writes format 29. No released zebra backend supports it. Do not deploy the direct-reader configuration below until a compatible backend is released. If its required format is absent, startup fails with no zebra-state v… database found; changing endpoints does not fix it.

The beta.3 zaino backend is unaffected when [indexer.read_state_service] is absent: it fetches chain data over JSON-RPC without reading Zebra’s database. That topology is untested here. The pool payout RPC gaps apply to either backend. For the tested alternative, see pool payouts through the sidecar.

Check the backend’s release notes and zebra-state dependency before upgrading Zebra. Zallet opens state read-only and cannot upgrade it. Do not rename or symlink a versioned directory to bypass the compatibility check.

What Zallet needs from Zebra

The zebra backend runs on Linux and needs three interfaces simultaneously:

The backend does not connect to Zebra’s wallet-facing [rpc] lightwalletd_listen_addr service. That endpoint implements a different protocol for light wallets.

Configuring Zebra

For a compatible direct-reader backend, build Zebra with the indexer feature:

cargo install --locked --version 7.0.0 --features indexer zebrad

For a custom Docker build, pass --build-arg FEATURES="default-release-binaries indexer".

Set the state path and both endpoints in zebrad.toml. Choose directories that Zebra can write and Zallet can access:

[state]
cache_dir = "/srv/zebra/state"

[rpc]
listen_addr = "127.0.0.1:8232"
indexer_listen_addr = "127.0.0.1:8230"
cookie_dir = "/srv/zebra/rpc"
enable_cookie_auth = true

Start Zebra with that configuration:

zebrad -c zebrad.toml start

Give Zallet read access to /srv/zebra/rpc/.cookie without making the credential public. Keep indexer gRPC on loopback: it has no authentication or TLS, and JSON-RPC authentication does not protect it. Port 8230 is an example, not a default.

Configuring Zallet

Set these fields in the Zallet configuration produced by its setup procedure. The root backend key belongs before the first TOML section.

backend = "zebra"

[consensus]
network = "main"

[indexer]
validator_address = "127.0.0.1:8232"
validator_cookie_path = "/srv/zebra/rpc/.cookie"

[indexer.read_state_service]
grpc_address = "127.0.0.1:8230"
zebra_state_path = "/srv/zebra/state"

The [indexer] validator_address field is a host and port, without an http:// prefix. The [indexer] validator_cookie_path field selects cookie authentication; the backend reads the file again for each request, so it picks up a new credential after Zebra restarts. Do not substitute static validator_user and validator_password values for Zebra’s generated cookie.

The [indexer.read_state_service] zebra_state_path field points to the cache root configured by Zebra’s [state] cache_dir, not to a network-specific versioned subdirectory. Use an absolute path to avoid resolving a relative path against Zallet’s data directory. Match Zallet’s consensus network to Zebra’s network.

Zallet’s wallet RPC listener is separate from both of these backend connections. Assign it a different port; applications that need wallet methods must connect to Zallet, not to Zebra.

Index availability and restart behavior

Zebra starts [rpc] indexer_listen_addr even without the indexer feature. A read-only consumer then receives empty results for missing indexes rather than an initialization error (#11155).

Keep the indexer feature enabled on the Zebra process that writes the state. Starting a non-indexer build against an indexed database removes the spending-transaction indexes. Restarting an indexer build rebuilds them from the existing chain state; a wallet reader does not perform that rebuild. Wait for Zebra’s finished checking/adding indexes for spending tx ids log before relying on the indexes.

Every indexed startup checks or builds these indexes, scanning existing blocks even without a format change. Allow for the resulting CPU load when scheduling restarts (#11090).

Running lightwalletd with Zebra

lightwalletd serves compact blocks and transaction queries to light wallets over gRPC. Zebra validates the chain; lightwalletd reads Zebra’s JSON-RPC API and maintains its own compact-block cache. Wallets connect to lightwalletd, not to Zebra’s JSON-RPC port.

Zaino, a Rust indexer, serves the same light-wallet CompactTxStreamer gRPC protocol but uses different backend and server configuration. Follow its deployment instructions.

The Docker deployment runs Zebra and lightwalletd as separate services. Zebra also has an experimental direct gRPC service.

Configure Zebra for lightwalletd

Generate a Zebra configuration file:

zebrad generate -o zebrad.toml

Edit the existing sections rather than adding duplicate TOML tables.

JSON-RPC

Set these fields in zebrad.toml for a Mainnet backend:

[rpc]
listen_addr = "127.0.0.1:8232"
enable_cookie_auth = false

For Testnet, set [network] network = "Testnet" and use the conventional RPC port, 127.0.0.1:18232.

Lightwalletd does not read Zebra’s authentication cookie, so this setup disables authentication. Keep the listener on loopback or an isolated container network; do not expose it to wallet users.

Lightwalletd does not require Zebra’s indexer Cargo feature or the [rpc] indexer_listen_addr endpoint. It uses JSON-RPC rather than direct access to Zebra’s database.

Sync Zebra

Start Zebra with the configured listener:

zebrad -c zebrad.toml start

Keep Zebra running while lightwalletd serves clients. Monitor synchronization, or start from a state snapshot. A successful RPC connection does not establish that Zebra has reached the tip.

Configure lightwalletd

Install the zcash/lightwalletd implementation using its installation instructions. Create its backend connection file, zcash.conf:

rpcbind=127.0.0.1
rpcport=8232
rpcuser=lightwalletd
rpcpassword=unused

Zebra does not read this file. Lightwalletd’s parser requires a nonempty rpcpassword even though Zebra ignores it with authentication disabled; an empty file is insufficient, and the sample password is not access control.

For Testnet, change rpcport to 18232. The parser uses testnet=1 only to choose that port when rpcport is absent; it does not change Zebra’s network. Restart lightwalletd when switching the backend network.

For containers, use the backend service hostname instead of loopback. The repository’s Compose setup connects lightwalletd to zebra:8232 without publishing RPC to the host. It still publishes plaintext gRPC and HTTP; restrict access before using it outside a trusted test environment.

Current upstream lightwalletd also accepts a Zebra .toml file through --zcash-conf-path, reading [rpc] listen_addr, but not Zebra’s cookie.

Sync lightwalletd

For local testing, start lightwalletd with an explicit loopback gRPC listener:

mkdir -p "$HOME/.cache/lightwalletd"
lightwalletd \
  --zcash-conf-path ./zcash.conf \
  --data-dir "$HOME/.cache/lightwalletd" \
  --grpc-bind-addr 127.0.0.1:9067 \
  --http-bind-addr 127.0.0.1:9068 \
  --no-tls-very-insecure \
  --log-file /dev/stdout

Lightwalletd serves requests while filling its compact-block cache; uncached requests read from Zebra. A quiet log does not prove either service is synced.

Query the service with grpcurl:

grpcurl -plaintext 127.0.0.1:9067 \
  cash.z.wallet.sdk.rpc.CompactTxStreamer/GetLightdInfo

At its default log level, lightwalletd enables gRPC reflection, so this command needs no local protocol files. The response reports the backend network, height, and version. Compare the height with Zebra’s sync status before connecting wallets.

Connect a wallet to lightwalletd

Configure the wallet’s server address to point at lightwalletd’s gRPC listener. The local test example uses 127.0.0.1:9067; loopback on another device refers to that device, not to the server.

For a network-facing deployment, remove --no-tls-very-insecure and supply --tls-cert and --tls-key with a certificate and private key trusted by the wallet clients. Keep the backend JSON-RPC listener and lightwalletd’s HTTP listener private. Follow lightwalletd’s production deployment instructions for certificate configuration.

Run tests

Zebra’s lightwalletd integration tests launch a separate lightwalletd process. Install lightwalletd and protoc, enable the lightwalletd-grpc-tests Cargo feature, and set TEST_LIGHTWALLETD=1. These tests are ignored by default; select them using the stateful test instructions.

Sync and wallet tests also need cached Zebra state. Tests that reuse lightwalletd state accept LWD_CACHE_DIR; without it, the harness looks for the platform cache directory, such as $HOME/.cache/lwd on Linux. Use disposable test copies, not the directories of running production services.

Experimental: serving light clients directly from Zebra

Zebra’s experimental CompactTxStreamer service runs without lightwalletd. Its behavior and configuration can change incompatibly in any release.

Enable it in Zebra’s [rpc] section:

[rpc]
lightwalletd_listen_addr = "127.0.0.1:9067"

The listener calls Zebra’s RPC handlers in-process and reads state and mempool services directly. It needs no additional Cargo feature, JSON-RPC listener, zcash.conf, or lightwalletd cache. Do not bind lightwalletd to the same address and port.

This is not Zallet’s indexer gRPC protocol: [rpc] indexer_listen_addr enables a different service.

The port is not protected

The direct gRPC listener serves plaintext HTTP/2 without TLS or authentication. JSON-RPC cookie authentication does not apply. Anyone who can reach it can query chain data and submit transactions; network observers can read or modify unencrypted traffic, including transparent-address queries.

Bind it to loopback or a restricted private interface. For remote wallets, put a reverse proxy with gRPC support in front of it, terminate TLS at the proxy, and block direct access to Zebra’s plaintext port. Configure proxy stream timeouts for long-lived block-range and mempool requests.

Do not run it on a user’s machine

Run this unauthenticated service on infrastructure you administer, not on end users’ computers. A loopback bind limits network reachability but does not isolate the service from untrusted local processes.

Compatibility limits

The direct service differs from lightwalletd:

• The Ping method returns gRPC unimplemented.
• The GetLightdInfo response leaves git_commit, branch, build_date, build_user, and donation_address empty.
• Compact blocks have an empty header field.

Test wallet synchronization, transaction submission, and recovery across chain reorganizations with the intended client before deployment; a successful connection does not establish interoperability.

zcashd API migration guide

Route node, chain, mempool, and mining calls to Zebra; wallet calls to Zallet. Changing the RPC URL alone does not preserve parameters or responses.

The tables cover zcashd 6.20.0, Zebra 7.0.0, and Zallet 0.1.0-beta.3. Zallet’s reference follows development; the release-specific restrictions here take precedence. Its direct zebra backend is incompatible with Zebra 7.0.0; see backend requirements for the unaffected RPC-based zaino backend. For pool integrations, see the payout RPC compatibility table and tested sidecar procedure; ownership does not imply that an unmodified payout processor works with Zallet.

Where the boundary falls today

How to read the table

Method

Method links point to the zcashd RPC reference. The inventory includes hidden and wallet-encryption methods omitted there.

Owner

Rows name Zebra when wallet state is unnecessary, even if Zallet also serves the method (getrawtransaction, validateaddress, z_listunifiedreceivers, and z_converttex).

The sidecar is temporary, not an API owner. Its network and mempool methods describe its own state. Deprecation flags, index requirements, sync gates, and wallet restrictions still apply:

Status

Status describes the named target, not the temporary sidecar.

Decisions and open questions

Node-method dispositions follow #11022. Issue #11033 tracks remaining shared-RPC differences.

RPC methods

Control

Blockchain

Address index

Mining

Generating

Network

Raw transactions

Util

Wallet

Build Zallet with zcashd-import for its wallet-migration CLI. This also enables transparent-key-import; without it, the registered z_importaddress RPC returns an error.

Disclosure

Hidden

Zebra-only methods

preciousblock prefers a non-finalized chain tip only over competing tips with equal cumulative work; higher-work chains always take precedence. The last call for competing equal-work tips wins. Preferences are not persisted and are lost on restart. Finalized blocks and known non-tip blocks succeed without changing the preference; an unknown hash returns Block not found.

Notification transports

Zebra publishes zcashd-compatible ZMQ hashblock notifications when built with the optional zmq feature and configured with [notify] zmqpubhashblock, for example "tcp://127.0.0.1:28332". The publisher is off by default and has no authentication; expose it only to trusted clients. Like block notify, it is suppressed during initial sync. See ZMQ block notifications for framing and best-effort delivery semantics. The other ZMQ topics remain proposed in #11034 and #11036. Zebra’s indexer gRPC streams cover them but require client changes:

Set [rpc] indexer_listen_addr; the streams need no indexer build feature. Keep the unauthenticated, plaintext listener on loopback or a protected private network; JSON-RPC cookie authentication does not apply.

Streams can close when a consumer falls behind. Reconcile state through RPC after reconnecting rather than treating notifications as a durable event log. The non-finalized stream accepts known chain-tip hashes; an empty request streams the current non-finalized state before subsequent updates.

Other integration points

Configuration mappings

Zebra reads TOML, not zcash.conf. These are behavioral mappings, not accepted aliases. See the configuration reference for defaults and environment-variable overrides.

When reusing sidecar data, preserve its transaction-index setting.

zcashd-compat mode

Zebra’s zcashd-compat mode keeps legacy wallet integrations running during migration to Zallet and Zebra’s JSON-RPC API. It uses a separate, restricted zcashd sidecar with shielded-pool limitations. Zebra neither proxies wallet RPCs nor reads wallet.dat.

Process and network boundaries

Zebra validates blocks from public peers; the sidecar receives them over one outbound peer-to-peer (P2P) connection to Zebra. Each node validates and stores its own chain. Both binaries must support the current network upgrade.

public Zcash peers <--- P2P ---> zebrad <--- one P2P connection --- zcashd
                                 ^                                  ^
                           node/mining RPC                    wallet RPC, ZMQ
                                 |                                  |
                              miners                         legacy integration

Configure both nodes for the same network and use distinct RPC listeners. Compat mode does not move or secure RPC credentials or ZMQ endpoints. The migration configuration keeps the legacy wallet endpoint for existing clients; see ports for network defaults.

For mining pools, see the tested reward-to-payout procedure and its wallet RPC, fee, and privacy-policy limits.

Quick start: the installer

Download and inspect the installer, then run it:

curl -fsSL https://raw.githubusercontent.com/ZcashFoundation/zebra/main/scripts/install-zebra.sh -o install-zebra.sh
less install-zebra.sh
bash install-zebra.sh --install-profile zcashd-compat

The installer checks platform, hardware, filesystem capacity, and permissions; it offers discovered data directories and verifies downloaded archives against SHA-256 checksums. It does not start the nodes. For unattended installation, supply the mode and paths explicitly:

bash install-zebra.sh --install-profile zcashd-compat --mode supervised \
  --network Mainnet --zebra-state-dir /var/lib/zebra \
  --zcashd-datadir /var/lib/zcashd --non-interactive

The installer has no compat Docker option, and Zebra publishes no sidecar image. To use a regular Zebra container, provide a compatible sidecar binary or run it separately, mount persistent data, and configure container-reachable addresses.

The sidecar zcashd build

Use the Zcash Foundation sidecar release, not stock zcashd. Zebra 7.0.0 embeds this release manifest:

The pinned build supports NU7; zebra-compat-v1.2.0 and earlier cannot follow it. See activation heights.

The sidecar enforces these restrictions independently of Zebra:

• Exactly one nonempty -connect peer is required. Additional peers through -addnode or -seednode, P2P binds, and -listen=1 are rejected. The addnode RPC is not registered.
• The getblocktemplate, submitblock, getgenerate, setgenerate, and generate methods are not registered; calls return -32601.
• The upstream scheduled end-of-support halt and warning are absent. This does not remove the need to update the sidecar for consensus changes.

The sidecar’s network RPCs describe its connection to Zebra, not Zebra’s public peer set. Its prioritisetransaction method affects only its own mempool, not Zebra’s mining templates.

Running externally managed

Set the compat configuration in Zebra’s TOML file:

[zcashd_compat]
enabled = true
manage_zcashd = false
zcashd_datadir = "/var/lib/zcashd"

Start Zebra with that file, then start the sidecar separately:

zebrad -c zebrad.toml start --zcashd-compat

zcashd -datadir=/var/lib/zcashd -connect=127.0.0.1:8233 \
  -listen=0 -dnsseed=0 -listenonion=0 -discover=0 -printtoconsole

For Testnet, add -testnet and use Zebra’s Testnet P2P address. For Regtest, add -regtest -regtestacceptunvalidatedpow: Zebra’s generated Regtest blocks omit proof of work, so the sidecar must accept them.

The sidecar needs an existing zcash.conf; an empty file is sufficient for peer selection when the arguments above supply it. Preserve existing wallet, index, and RPC settings. Remove conflicting peer-selection settings. The installer prepares a missing config for its externally managed modes; Zebra does not bootstrap or supervise an externally managed process.

Running supervised

Use the supervised configuration and start command. The CLI flag enables compat mode, not supervision; explicitly set [zcashd_compat] manage_zcashd = true.

With zcashd_source = "embedded", Zebra downloads the pinned archive over HTTPS, verifies its digest, and caches the executable under <state.cache_dir>/zcashd-compat/bin/<release>/<target>/zcashd. Cached binaries are checked against their recorded digest before reuse; an invalid cache triggers a fresh download. Downloads have a 10-minute timeout and a 1 GiB size limit. Unsupported targets, failed downloads, and archive digest mismatches fail startup. To supply a verified local build, set zcashd_source = "path" and zcashd_path; an explicit path takes precedence over zcashd_source and bypasses the embedded download and checksum policy.

Zebra creates a missing sidecar data directory and minimal zcash.conf but never overwrites an existing config. Prefer [zcashd_compat] zcashd_datadir to a path in zcashd_extra_args; see the path and extra-argument rules.

The supervisor passes the selected data directory, network flags, and -printtoconsole, followed by extra arguments. It then appends the forced peer settings and -daemon=0, keeping the child in the foreground. Testnet adds -testnet; Regtest adds -regtest -regtestacceptunvalidatedpow. Peer-selection arguments (-connect, -addnode, -seednode, including negated forms) are forbidden in zcashd_extra_args.

The sidecar’s stdout and stderr enter Zebra’s logs under zcashd_compat.zcashd. With the normal -printtoconsole setting, the sidecar writes there instead of debug.log.

Sidecar peer privileges

Set [zcashd_compat] p2p_connect_addr if the sidecar needs a destination other than Zebra’s bound listener. The block_gossip_peer_ips field instead matches the source IP Zebra sees. For a separate host or container, configure that source:

[zcashd_compat]
enabled = true
manage_zcashd = false
block_gossip_peer_ips = ["10.0.0.2"]

Listed IPs receive block inventory broadcasts without random peer sampling. They share a reserved inbound pool with one slot per distinct source IP, capped to preserve at least one public inbound slot. The pool is shared, not a per-IP quota. Reserved connections bypass the recent-IP reconnection limit; overflow connections compete for public slots with normal rate limiting. All listed IPs are exempt from the FindBlocks/FindHeaders sync-stall detector.

Treat this list as a trust boundary. List only addresses whose originating processes are all trusted. Do not grant a shared Docker proxy or NAT address these privileges if untrusted public connections also arrive from it. Use networking that distinguishes the sidecar’s source. Merely raising [network] max_connections_per_ip does not establish that distinction.

Supervision and shutdown

See supervisor timing fields for delays and defaults.

The supervisor retries spawn failures and every pre-shutdown child exit, including success, indefinitely with exponential backoff. Persistent config errors therefore cause restart loops. If supervision itself fails, Zebra logs the failure and keeps running; monitor the wallet process separately.

Stop Zebra rather than stopping its supervised child independently. Normal shutdown sends the child SIGTERM, waits for the grace period, then uses SIGKILL if necessary. An abrupt kill of Zebra cannot perform this cleanup; check for a surviving child before starting another process on the same data directory.

Verify the integration

Query the sidecar with its own credentials:

zcash-cli -datadir=/var/lib/zcashd getpeerinfo
zcash-cli -datadir=/var/lib/zcashd getconnectioncount
zcash-cli -datadir=/var/lib/zcashd getblocktemplate

Check the sidecar’s single-peer and disabled-mining restrictions above. Inspect listeners with ss -tlnp: only Zebra should listen for P2P. Then compare fixed-height block hashes and wallet state.

Mining: Zebra is canonical

Send mining requests to Zebra, not the sidecar; configure its payout address as described in Mining.

Wallet shielded-pool support (Orchard & Ironwood)

The sidecar transaction builder enforces these restrictions:

The Orchard restriction can produce RPC_INVALID_PARAMETER (-8) with the message beginning zcashd does not support the Ironwood pool. An unsupported recipient can instead fail address resolution. A unified address with a supported receiver does not require an Orchard payment: selection also respects the requested privacy policy and available funds.

Migrate affected wallet workflows to Zallet, not an indexer or wallet library.

Initial sync and existing datadirs

Follow Migrating an existing zcashd node for data reuse, sync gates, backup, cutover, troubleshooting, and rollback.

Configuration reference

See the configuration reference for fields, defaults, and array parsing. To override extra arguments through the environment:

export ZEBRA_ZCASHD_COMPAT__ZCASHD_EXTRA_ARGS='["-rpcbind=127.0.0.1","-rpcallowip=127.0.0.1"]'

Hardware preflight (Linux)

Enabled compat mode runs Linux startup checks even without supervision. Preflight checks available CPUs, cgroup-limited RAM, directory permissions, and filesystem capacity, not free space. Check free space separately and allow for growth.

Minimum shortfalls and check errors fail startup. The --unsafe-low-specs flag downgrades errors to warnings; it does not repair permissions, provide missing libraries, bypass checksum validation, or prevent later failures. Preflight checks executable permissions, not dynamic-library loading. Non-Linux compat startup also needs this override; embedded downloads remain Linux x86-64 only.

Migrating an existing zcashd node

Use compat mode while migrating legacy wallet RPC callers; without wallet dependencies, run Zebra directly. Zebra needs its own state database and cannot import zcashd block files.

Zallet beta.3’s direct zebra backend is incompatible with Zebra 7.0.0; the RPC-based zaino backend is unaffected. Review the sidecar’s wallet pool restrictions before moving production traffic.

What you need

• A cleanly stopped zcashd data directory, its configuration, and a verified wallet backup. Record the network, wallet filename, RPC credentials, and index settings.
• Separate storage for Zebra’s state and enough time for its own sync, or a Zebra state snapshot.
• Zebra and a compatible sidecar build.
• Capacity and permissions satisfying compat preflight.

The sidecar reuses the existing chain and wallet state from a compatible zcashd data directory; Zebra still needs its own synchronization.

The procedure below uses Mainnet, /var/lib/zcashd for the existing sidecar root, and /var/lib/zebra for Zebra. Substitute the actual paths. On Testnet or Regtest, preserve the network-specific wallet subdirectory and configure both processes for the same network.

The migration

1. Back up the wallet

Stop the existing node cleanly and wait for it to exit before copying its files. Preserve the entire data directory when rollback must also restore chainstate and indexes. At minimum, back up the actual wallet file and zcash.conf to restricted storage:

install -d -m 700 /secure/zcashd-backup
cp -p /var/lib/zcashd/wallet.dat /secure/zcashd-backup/wallet.dat
cp -p /var/lib/zcashd/zcash.conf /secure/zcashd-backup/zcash.conf

Use the configured wallet filename if it is not wallet.dat. Do not run the old daemon and sidecar against the same directory, and do not overwrite the backup during the migration.

2. Write the config

Create a Zebra config with separate RPC and state paths:

[network]
network = "Mainnet"

[state]
cache_dir = "/var/lib/zebra"

[rpc]
listen_addr = "127.0.0.1:8234"
cookie_dir = "/var/lib/zebra"

[zcashd_compat]
enabled = true
manage_zcashd = true
zcashd_source = "embedded"
zcashd_datadir = "/var/lib/zcashd"
zcashd_extra_args = ["-rpcbind=127.0.0.1", "-rpcallowip=127.0.0.1"]

This Mainnet layout keeps sidecar RPC on port 8232 for existing clients and assigns Zebra port 8234. Keep both on loopback unless an authenticated, encrypted deployment boundary protects them.

For a supplied binary, set zcashd_source = "path" and zcashd_path = "/usr/local/bin/zcashd"; verify it separately because this bypasses embedded archive verification.

Review the existing zcash.conf before startup:

• Preserve the transaction-index setting. The supervisor does not add -txindex; an existing txindex=1 in zcash.conf is sufficient. Add "-txindex=1" to zcashd_extra_args only when needed to preserve the directory’s existing setting. Changing it triggers a reindex requirement.
• Remove connect, addnode, seednode, bind, and whitebind entries that conflict with the supervisor’s sole peer. Multi-valued peer options accumulate; a command-line setting does not erase existing peers.
• Preserve wallet, authentication, and ZMQ settings. The supervisor does not translate them or choose a nonconflicting RPC port.

Give the Zebra service account access to both data directories and the wallet’s existing authentication files.

3. Start

Start the supervised pair:

zebrad -c zebrad.toml start --zcashd-compat

Zebra runs preflight, resolves the binary, initializes its services, and starts the sidecar after the configured delay, without waiting for the tip. Honor reported index-upgrade, wallet-scan, or recovery requirements. Read sidecar output in Zebra’s logs, not the old debug.log.

4. Wait for both nodes to reach the tip

Query the sidecar:

zcash-cli -datadir=/var/lib/zcashd getblockchaininfo
zcash-cli -datadir=/var/lib/zcashd getpeerinfo

The sidecar must have one outbound peer pointing to Zebra. Its initial_block_download_complete field must become true before chain-dependent wallet operations are available. Those methods return -28 with This wallet operation is disabled while reindexing. during initial block download even when no reindex is occurring. Key and address methods such as z_exportkey and listaddresses are not subject to that gate.

Monitor Zebra’s synchronization separately. If both heights stall, inspect Zebra’s sync and peers; if only the sidecar stalls, inspect its connection, consensus version, and logs. Equal heights do not prove either node has reached the network tip.

5. Verify

Check peer and listener isolation, then compare block hashes at a fixed height available on both nodes:

height=$(zcash-cli -datadir=/var/lib/zcashd getblockcount)
zcash-cli -datadir=/var/lib/zcashd getblockhash "$height"
curl --silent --show-error --user "$(cat /var/lib/zebra/.cookie)" \
  --header 'Content-Type: application/json' \
  --data-binary "{\"jsonrpc\":\"2.0\",\"id\":\"migration\",\"method\":\"getblockhash\",\"params\":[$height]}" \
  http://127.0.0.1:8234/

Compare the sidecar’s hash with the JSON result; recheck at a stable height if a reorganization occurs. Protect the RPC cookie; do not put it in a URL.

Query wallet state through the sidecar and compare it with the inventory recorded before migration:

zcash-cli -datadir=/var/lib/zcashd listaddresses
zcash-cli -datadir=/var/lib/zcashd getwalletinfo
zcash-cli -datadir=/var/lib/zcashd z_gettotalbalance

Check addresses, balances, application RPCs, and notification consumers before restoring wallet traffic. A matching tip does not prove the correct wallet was loaded.

After the migration

The sidecar disables deprecated methods such as z_listaddresses by default, but keeps z_gettotalbalance enabled. Migrate callers using the API table. For a required legacy method, append -allowdeprecated=<method> to zcashd_extra_args; do not replace the existing arguments.

Troubleshooting

Rolling back

Stop wallet traffic, then stop the supervised pair. Check for a surviving child before changing binaries or supervision.

To undo supervision without discarding wallet progress:

1. Set [zcashd_compat] manage_zcashd = false; keep compat mode enabled for the sidecar’s trusted-peer handling.
2. Restart Zebra with the same state and RPC configuration.
3. Start the same compatible sidecar externally against its existing data directory, with exactly one -connect peer pointing to Zebra. See Running externally managed.
4. Repeat the fixed-height hash and wallet checks before restoring traffic.

For a binary or data rollback, preserve the failed directory and restore a clean backup separately. Use binaries compatible with current consensus rules and the backup’s format; an obsolete stock zcashd is not a supported replacement. Do not assume on-disk updates are reversible by downgrading.

Reconcile wallet activity since the backup before spending: it can omit later keys and transactions. Retain the original wallet and subsequent backups until migration is complete. Disabling supervision does not convert wallet formats.

Mining Zcash with Zebra

Zebra supplies block templates and validates submitted blocks over JSON-RPC. A mining pool distributes those templates to external Equihash solvers; Zebra does not start a solver when an operator configures a reward address.

Download Zebra

Install Zebra or use the Docker instructions. Miners must follow the rules at the candidate block’s height, including the changes in NU7; see the public activation schedule.

Configure Zebra for mining

Generate a configuration file:

zebrad generate -o zebrad.toml

Set the following fields in the existing sections. Replace the address placeholder with an address controlled by the reward recipient.

[mining]
miner_address = "YOUR_MAINNET_MINING_ADDRESS"
internal_miner = false

[rpc]
listen_addr = "127.0.0.1:8232"
enable_cookie_auth = true

[network]
experimental_early_block_relay = true

See the mining configuration reference for field defaults and limits, and Early block relay and compact blocks for the [network] setting.

Miner address

The coinbase builder supports these address kinds on the selected network:

• Transparent pay-to-public-key-hash (P2PKH) and pay-to-script-hash (P2SH).
• Sapling payment addresses.
• Unified Addresses with a supported receiver. Zebra tries the Orchard receiver first, then Sapling, then transparent.

From NU6.3 onward, Zebra pays an Orchard receiver through the Ironwood shielded pool, not the Orchard pool. Ironwood uses the same receiver address format. Coinbase transactions cannot contain an Orchard component from NU6.3 onward; see ZIP 213 and ZIP 229.

Sprout addresses and transparent-source-only TEX addresses are not supported coinbase destinations. A syntactically valid address is not sufficient: it must match the network and contain a supported receiver. Zebra has no default reward recipient. Non-mining nodes need no address. A missing address, a network mismatch, or an invalid memo prevents template generation.

Extra coinbase data

The coinbase transaction is the first transaction in a block. Its input encodes the block height and arbitrary miner data under the transaction consensus rules. Zebra adds the Unicode U+1F993 marker, encoded as bytes f0 9f a6 93, to this input. A nonempty [mining] extra_coinbase_data follows the marker and a two-byte separator, a colon and a space (3a 20):

extra_coinbase_data = "/MyPoolName/"

The 86-byte limit reserves space for the height, marker, separator, and script push encoding within the 100-byte coinbase input limit. Zebra rejects an oversized value while loading the configuration. An unset or empty value leaves only the marker after the height.

Miner memo

Set [mining] miner_memo to attach a memo to a shielded miner output:

miner_memo = "Mined by MyPoolName"

A coinbase memo is not private. Shielded coinbase outputs must be recoverable with the all-zero outgoing viewing key, so anyone can recover their recipient, value, and memo. Do not include secrets. This differs from ordinary shielded payments; see ZIP 213.

RPC section

Configure the pool to read Zebra’s RPC cookie and reload it after each restart. Bind RPC to loopback for a local pool; use a protected tunnel or TLS proxy for remote connections. Disable authentication only when an isolated network or an authenticating proxy controls access.

A submitted block that exactly matches a successful local proposal verdict, except for the nonce and Equihash solution, reuses that verdict and is advertised before commit. Solved proof of work, size, current time, live parent eligibility and local invalidation are checked before the body becomes available to peers. Changed or uncached proposals undergo normal full validation; checkpoint-era blocks wait for commit. These advertisements use ordinary block gossip; all-peer advertisements are reserved for committed submissions. With early block relay, peers that also enable it can receive an uncached submitted block before its transaction verification finishes. The RPC response still waits for verification and commit.

Committed notifications belong to the state writer, so cancelling an RPC does not discard a later successful commit notification. The default notification channel holds at most 10,000 messages. A full or closed channel produces an operational error before committing a mined block, without blocking ordinary state writes. Notification insertion does not guarantee delivery to peers. Restrict RPC access to trusted miners.

ZMQ block notifications

Pools using zcashd’s hashblock subscription can receive the same multipart messages from Zebra. Build or install Zebra with --features zmq, then add this to zebrad.toml:

[notify]
zmqpubhashblock = "tcp://127.0.0.1:28332"

This is equivalent to zcashd’s -zmqpubhashblock=tcp://127.0.0.1:28332. The Cargo feature is off by default and uses a pure-Rust implementation; no system ZMQ package is needed. Only TCP is supported. Official default binaries and Docker images do not include it. Without the feature, configuring the endpoint is a startup error. With no endpoint configured, no ZMQ socket is opened.

Subscribe to hashblock. Each notification has three frames:

1. The nine ASCII bytes hashblock, with no null terminator.
2. The 32 hash bytes in display order: hex-encoding them gives the getbestblockhash RPC result.
3. A four-byte little-endian sequence number, starting at zero, wrapping after 2^32 - 1, and resetting when Zebra restarts.

Like block notify, notifications are suppressed until Zebra is close to the network tip. Only best-chain tip changes are reported, including reorganizations; this is not a per-block archive or a same-tip transaction update feed. Intermediate tips may be coalesced. A bounded local queue holds up to 1,000 messages and drops on overflow, never delaying validation. Each subscriber has its own 64-message queue. A full queue or a write taking more than one second disconnects only that subscriber; other subscribers continue receiving notifications.

The server accepts at most 64 connections, including handshakes in progress. Handshakes and incomplete incoming frames have five-second deadlines. After the handshake, a client must send its first valid subscription within five seconds; other frames do not extend that deadline. Subscribed clients may remain silent indefinitely without heartbeats. Only ZMTP 3.x NULL connections with a SUB or XSUB socket type are supported. Inbound frames must use short lengths (at most 255 bytes), with at most 16 distinct subscription prefixes of up to 64 bytes each. Each connection may send at most 128 frames and 16 KiB, including frame headers, per one-second window after the handshake. Exceeding either budget disconnects the client. The budgets renew so periodic heartbeats do not exhaust a lifetime allowance. Invalid clients are disconnected. Heartbeat intervals shorter than about 10 ms can exceed the 128-frame-per-second inbound budget and disconnect the subscriber; ordinary intervals of 100 ms or more are unaffected. Heartbeat requests receive bounded PONG replies through the same per-subscriber queue, even when the chain tip is unchanged. Reply contexts are capped at 16 bytes.

Subscribers must fetch fresh work over RPC and reconcile after sequence gaps, reconnects, or restarts. Keep periodic RPC polling as a backstop: coalesced tips do not necessarily create sequence gaps.

ZMQ has no authentication or encryption. Restrict the endpoint to trusted clients using firewall rules or a private network, and account for untrusted local applications even on loopback. Never expose it directly to the public Internet. These limits do not provide fair admission: a misbehaving trusted client can still occupy all slots by subscribing, even to an unused topic or subsequently cancelling, or repeatedly reconnect to obtain fresh inbound budgets. Restrict access to well-behaved clients; the endpoint is not a defense against hostile clients.

Early block relay and compact blocks

Set [network] experimental_early_block_relay = true on every mining node. Between two nodes that both enable it:

• A node advertises a block extending its best tip once the header, proof of work and transaction commitments check out, before transaction verification finishes. Each receiver still verifies the block fully before committing it.
• Up to three such peers per announcement receive a compact block: the header and short transaction IDs. Each rebuilds the block from its mempool and requests missing transactions once; if that fails, it fetches the full block.

Other peers, including zcashd, other node implementations and Zebra releases without this setting, get ordinary full-block relay. Nodes negotiate the feature with experimental service bit 25 and a sendcmpct exchange. Neither is an allocated Zcash protocol, and the encoding may change in later releases; nodes without a common encoding version fall back to full blocks. Experimental early block relay describes the limits and failure handling.

Running Zebra

Start Zebra with the configuration file:

zebrad -c zebrad.toml start

Wait for synchronization before requesting mining work. On Mainnet, getblocktemplate requires the sync service to be close to the tip and the tip timestamp to be no more than 7,500 seconds old. A stale node or an incorrect local clock can produce RPC error -10, indicating that Zebra has not synced to the chain tip.

Testnet still requires synchronization, but it does not apply the Mainnet tip-age limit. This permits mining to resume after a Testnet stall. Networks with proof of work disabled, including default Regtest, bypass this sync check. The [rpc] debug_force_finished_sync field changes only the estimate in getblockchaininfo; it does not bypass the mining check.

Reusing proposal validation

Zebra validates transaction-bearing templates in the background. If you change the coinbase, transactions, timestamp or another header field, submit the modified block with getblocktemplate parameters {"mode":"proposal","data":"<hex-encoded-block>"} before mining it. A successful proposal lets a later submitblock reuse verification when only the nonce and Equihash solution differ. Proof of work, current time, size and state application are still checked. The cache holds up to eight recent successful proposals within a 576 MiB retained-content budget, including spent-output scripts. This uses a conservative retention charge, not measured heap usage. It keeps eight representative full-size proposals with 19,215 transactions using 104-byte one-input/one-P2PKH-output payments, charged at about 66.2 MB per proposal. Proposals packed with smaller consensus-valid transactions or large spent-output scripts can retain fewer entries. An evicted or changed proposal is verified normally: eviction loses cache hits, not correctness.

Template requests share the updater’s work during startup and refreshes, rather than starting a separate coinbase proof for each waiting miner. On-demand construction runs off the async executor and rechecks the committed parent, synchronization, timestamp range and difficulty before returning. Long polls also recheck synchronization after waking. Expanding a clock-capped timestamp range does not cancel still-valid work; a genuine difficulty-boundary transition still replaces it. New committed tips interrupt obsolete snapshot reads without abandoning a started proof. If the updater stops, cached work is refreshed at the normal mempool polling interval. Long polls continue observing shared template publications after switching to on-demand refresh. When no usable work exists, snapshot failures are returned to the RPC caller rather than hidden behind an indefinite cache wait.

Testing the setup

On Linux, with the default cookie directory, request a template:

cookie="${XDG_CACHE_HOME:-$HOME/.cache}/zebra/.cookie"
curl --fail-with-body --silent --show-error \
  --user "$(cat "$cookie")" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[]}' \
  http://127.0.0.1:8232/ | jq

Use the configured cookie path if [rpc] cookie_dir differs. A successful response contains a result object with these mining inputs:

Treat RPC errors as failures; an HTTP success status alone does not establish that the node can generate templates.

Mining RPCs

See the mining RPC reference for method parameters and results.

Proposal mode accepts a request object with "mode":"proposal" and "data" containing the candidate block hex. It checks the candidate without requiring valid proof of work and returns null for a valid proposal or a rejection string. Submit a solved block with submitblock, not with a getblocktemplate submit mode.

A submitblock result of null means Zebra committed the block, including when it is on a side chain. Unlike zcashd’s distinction between accepted and inconclusive submissions, this result does not prove that the block is on Zebra’s best chain.

Long polling and template expiry

Long polling keeps an RPC request open until work changes. Pass the previous template’s longpollid in the next request object:

{"jsonrpc":"2.0","id":2,"method":"getblocktemplate","params":[{"longpollid":"REPLACE_WITH_RETURNED_LONGPOLLID"}]}

Zebra wakes the request when the tip or relevant template state changes. It also returns when the template’s inclusive maxtime expires during the request, even if the tip and mempool do not change. The response can retain the same longpollid for this expiry notification. Repeating a request for that already-expired template waits for changed work rather than repeatedly returning the same expiry notification.

The response’s submitold field is false when the tip changes or the time range expires. Discard old work in that case. A mempool-only change can return submitold: true. Allow long requests through the pool’s HTTP client and any reverse proxy; do not interpret a pending long poll as an RPC failure.

Coinbase and consensus rules

Use the supplied coinbase and transaction set unless the pool implements the current consensus rules. Modifying transactions changes fees and commitment roots; modifying the coinbase also requires recomputing the affected roots. The defaultroots values apply only to the template as returned.

The template marks the coinbase as required and advertises only "time" in its mutable list. Request a fresh template when changing the parent or the transaction set rather than reusing its coinbase.

Zebra constructs mandatory funding-stream outputs and scheduled lockbox disbursements. The lockbox is the deferred value pool: its allocation is accounted for without an ordinary recipient output. Under the active revision-2 funding streams, 12% of the subsidy is deferred and 8% goes to Zcash Community Grants through the Financial Privacy Fund; the miner receives the remainder and claimable fees. Amounts use consensus integer rounding. See ZIP 207, ZIP 214, and ZIP 271.

From NU6 onward, a coinbase must claim its full allowed value; miners cannot silently discard a portion of the subsidy or fees. Preserve the deferred allocation and any disbursement as well as the miner output. See ZIP 236.

Transparent coinbase outputs must mature for 100 blocks and must be shielded when spent on public networks. Shielded coinbase outputs do not have that 100-block maturity rule. See ZIP 213 and the transaction consensus rules.

From NU6.3 (Ironwood) activation, the template’s coinbase is a version 6 transaction, and the template can include version 6 transactions from the mempool. Pool software that parses, checks, or rebuilds template transactions must support the version 6 transaction format.

NU7 mining rules

Zebra 7.0.0 applies these rules from the NU7 activation height on each network:

• Timing and issuance: ZIP 218 changes the target spacing from 75 to 25 seconds and the difficulty averaging window from 17 to 102 blocks. Scheduled subsidy per block is divided by three, with integer rounding, and remaining halving intervals are tripled.
• Block contents: ZIP 218 limits a block to 330 Orchard actions, 330 Ironwood actions, and 300 Sapling inputs plus outputs, with a shared budget of 330 across those pools. The limits include coinbase outputs. Sprout JoinSplits are disallowed. ZIP 2003 disallows version 4 transactions; versions 5 and 6 remain valid.
• Fees: ZIP 235 removes floor(total_transaction_fees * 6 / 10) zatoshis from circulation into the Network Sustainability Mechanism (NSM) reserve. Calculate this once over the block’s aggregate fees, not separately for each transaction. The coinbase claims only the remainder. The template’s coinbasetxn.fee is the negative of those claimable miner fees; non-coinbase fee fields remain gross.
• Reserve reissuance: ZIP 237 adds a rounded-up fraction of the parent block’s NSM reserve to scheduled subsidy from height 8,939,664 on Mainnet or 7,305,222 on Testnet. This is not immediate reissuance at NU7 activation. From that height, getblocksubsidy needs the parent block’s state and cannot calculate subsidies beyond the block after the best tip.
• Funding periods: ZIPs 207 and 214 stretch the remaining funding periods for the faster spacing. The revision-2 streams end at the adjusted third halving: 6,132,390 on Mainnet and 4,497,948 on Testnet, exclusive. ZIP 2008 rotates the Mainnet grants recipient starting with the first funding period after the period containing the last pre-NU7 block. Do not hard-code a single recipient address in a pool.

The NSM reserve is separate from the lockbox. The former tracks funds removed from circulating supply for algorithmic reissuance; the latter holds deferred funding-stream value. Zebra’s generated coinbase applies both mechanisms.

Run a mining pool

Configure the pool’s daemon connection with Zebra’s RPC address and credentials. Confirm that the pool handles the supplied transaction formats, coinbase, commitment roots, long polling, and NU7 fee split. Pool accounting and payments to individual workers are the pool’s responsibility, not Zebra’s.

See Getting new work to mining pools for long polling, block notifications, separate payout wallets, and recovery planning. The s-nomp Testnet setup is experimental.

Testnet, Regtest, and the internal miner

For public Testnet, set [network] network = "Testnet", use a Testnet reward address, and set [rpc] listen_addr = "127.0.0.1:18232". Public Testnet uses real Equihash proof of work and the same upgrade-dependent coinbase rules.

For deterministic local block production, use the Regtest generation RPCs, not the experimental internal miner.

Getting new work to mining pools

First configure and sync Zebra for mining, including the miner address and authenticated RPC access. Then choose a new-work delivery method supported by your pool software, in this order:

1. Long polling: hold a getblocktemplate request until work changes.
2. Block notifications: trigger a template request when Zebra’s best chain tip changes.
3. Polling: periodically request a template as a fallback or backstop.

With a polling interval of I, a new block arriving uniformly between polls leaves miners on stale work for I / 2 on average, before RPC and job-distribution delays. For example, 500 ms polling adds about 250 ms of stale work per block. Notifications remove that polling wait, not all delivery delay; this is a latency estimate, not a guaranteed revenue gain.

Prefer getblocktemplate long polling

The pool’s template provider must explicitly implement long polling; receiving a longpollid does not enable it automatically.

1. Fetch an initial template without a long-poll ID:

   {"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[{}]}
   

2. Publish the template to miners, then make another request with its returned longpollid:

   {
     "jsonrpc": "2.0",
     "id": 2,
     "method": "getblocktemplate",
     "params": [{"longpollid": "<exact ID from the previous response>"}]
   }
   

3. Keep that request open. When it returns, process the template and repeat using its new ID.

Treat the ID as opaque: do not parse it, assume its length, or construct it yourself. Keep one outstanding long poll per backend, with a separate connection or connection-pool capacity for block submissions. Configure client and proxy timeouts for long-held requests, rather than a short ordinary RPC timeout.

A response can reflect a new chain tip, changed transactions, or an expired timestamp range. Ensure the pool forwards updated work to miners even when previousblockhash is unchanged. Honor submitold when deciding whether to retain previous work; do not discard it merely because the transaction selection changed. After a timeout or connection failure, reconnect with bounded retry backoff, fetch a fresh template without an ID, and restart the long-poll loop.

Use block notifications

s-nomp commands

For a pool that supports a block-notification command but not long polling, add this to Zebra’s configuration and restart the node:

[notify]
block_notify_command = "node /path/to/s-nomp/scripts/cli.js blocknotify <coin> %s"

Before using this example, replace the script path and <coin> with the pool’s configured coin name. The CLI connects to s-nomp’s local command listener by default, so this example assumes it is reachable from the Zebra host. Ensure the service account running Zebra can execute Node.js and read the script. The command runs through the system shell; keep its configuration under operator control.

Zebra substitutes the new best-tip block hash for %s. The pool uses the notification to request a fresh template and distribute new jobs; the notification itself is not a template. Commands run asynchronously, only when Zebra is close to the network tip. Delivery is best-effort: intermediate tips can be skipped during rapid changes, and notifications are not a replayable event log.

Keep periodic polling enabled as a backstop for missed notifications or a restarted pool. Block notifications only signal tip changes, so retain the pool’s periodic job refresh for transaction-only updates too. See the s-nomp testnet guide for its compatibility and payment limitations; this command does not make an unsupported pool version production-ready.

ZMQ subscribers

Pools that subscribe to zcashd’s ZMQ hashblock topic, such as Miningcore, can use Zebra’s ZMQ publisher. Build Zebra with --features zmq, then configure:

[notify]
zmqpubhashblock = "tcp://127.0.0.1:28332"

Notifications start when Zebra is close to the network tip. Delivery is best-effort: use the sequence numbers to detect gaps and reconcile through RPC after gaps or reconnects. Keep periodic polling as a backstop; coalesced intermediate tips do not necessarily create sequence gaps.

The endpoint has no authentication; expose it only to trusted clients. See ZMQ block notifications for framing and resource limits.

Resolve equal-work tip races

When backends choose different tips with equal cumulative work, call preciousblock with the same known, non-finalized tip hash on each backend to align the fleet:

{"jsonrpc":"2.0","id":1,"method":"preciousblock","params":["<preferred non-finalized tip hash>"]}

Among equal-work tips the last call wins, but more-work chains always take precedence, so a call on a block with less work than the best tip is a no-op. The preference covers only that block while it is a tip: once a block is added on top of it, the extended chain no longer carries it. If the race continues at the next height with equal work, call preciousblock again on each backend with your new tip. Known non-tip or finalized blocks also return null without changing the preference; unknown hashes return Block not found. Preferences are in memory only and are forgotten on restart.

Keep mining and payouts separate

Zebra validates blocks and serves mining work; it is not a wallet. Point the pool’s mining RPC connection at Zebra, and its payout or payment-processor connection at a compatible wallet that controls the reward address. Configure the same intended reward address on each mining backend.

Use Zebra’s validateaddress or z_validateaddress to check address validity, not wallet ownership. The transparent-address response omits ismine; a valid shielded-address response reports ismine: false. Check ownership with the payout wallet instead.

Wallet RPC compatibility

As of 27 October 2026, no released Zallet direct-state backend reads this Zebra’s database; see the database compatibility table. The beta.3 Zaino backend can fetch over JSON-RPC without reading that database, but that topology is untested here. The payout RPC gaps below apply regardless of backend.

This inventory compares s-nomp at 88187c9 and Miningcore at a553f62 with Zallet 0.1.0-beta.3 at 987382f and the zcashd-compat sidecar, release zebra-compat-v1.3.0.

The processors also query chain RPCs: s-nomp uses getblock, getmininginfo, and getnetworkinfo; Miningcore uses getblockchaininfo. Those are not Zallet wallet methods. The sidecar serves them. Miningcore constructs its payout client from the first daemon entry; it does not provide s-nomp’s separate paymentProcessing.daemon connection.

Miningcore remains inspected-only. Its hard-coded 0.0001 ZEC fee failed a separate shielding probe, and its sends need an explicit privacy policy for transparent recipients. Adapting its fee selection and privacy policy remains untested. The tested s-nomp changes below do not enable legacy privacy behavior.

Tested sidecar payout path

An isolated Regtest run mined through s-nomp, recorded real miner shares in Redis, and let libs/paymentProcessor.js shield rewards, unshield into its payout address, and pay the miner. The test used:

Apply these changes to libs/paymentProcessor.js. They track the shielding operation ID, reserve the configured unshielding fee and permit the transparent staging recipient:

@@ -275 +275 @@
-                    var opid = (result.response || result[0].response);
+                    var opid = (result.response || result[0].response).opid;
@@ -294 +294 @@
-        if ((zBalance - 10000) <= 0)
+        if ((zBalance - coinsToSatoshies(fee)) <= 0)
@@ -303 +303 @@
-        var amount = satoshisToCoins(zBalance - 10000);
+        var amount = satoshisToCoins(zBalance - coinsToSatoshies(fee));
@@ -305 +305,2 @@
-        var params = [poolOptions.zAddress, [{'address': poolOptions.tAddress, 'amount': amount}]];
+        var params = [poolOptions.zAddress, [{'address': poolOptions.tAddress, 'amount': amount}],
+            minConfShield, fee, 'AllowRevealedRecipients'];

1. Run Zebra and an externally managed sidecar. Pin the sidecar’s only peer with connect=<Zebra-P2P-address> and listen=0; keep both RPC endpoints on loopback with separate credentials. Set [zcashd_compat] enabled = true and manage_zcashd = false on Zebra. The sidecar synchronizes over P2P and does not read Zebra’s database, so the database-format mismatch does not affect it.
2. Create two distinct wallet-controlled transparent addresses with getnewaddress and a Sapling address with z_getnewaddress sapling. Enable allowdeprecated=getnewaddress, allowdeprecated=z_getnewaddress, and allowdeprecated=z_getbalance in the sidecar’s zcash.conf. Verify ownership with the wallet’s validateaddress and z_validateaddress. Set the reward address as [mining] miner_address on Zebra and address in s-nomp; set the other transparent address as tAddress and the Sapling address as zAddress.
3. Point s-nomp’s daemons at Zebra and paymentProcessing.daemon at the sidecar’s authenticated RPC endpoint. Enable paymentProcessing.enabled and use paymentMode: "prop", minConf: 10, paymentInterval: 30, minimumPayment: 0.05, and walletInterval: 1. In the coin profile, retain requireShielding: true and txfee: 0.0004. Keep rewardRecipients: {} and poolHex: "": this Stratum adapter preserves Zebra’s coinbase rather than inserting pool-fee outputs. The test used a share difficulty of 1 / 1024, disabled the website and clustering, and enabled cleanJobsOnTemplateUpdate for nheqminer.
4. Connect the miner with its transparent payout address as the username. Let the processor observe maturity through the sidecar, complete shielding and unshielding, and call sendmany. Check its Redis payment record, confirm that transaction on Zebra, and verify the recipient’s output amount. The configured fee covers the tested small withdrawal, not arbitrary batches; size fees under ZIP 317. The privacy policy reveals recipient addresses and amounts.

For reproduction, the run activated Overwinter through NU5 at height 1 on both nodes, left later upgrades inactive, and used fresh state with no funding streams. Zebra used network = "Regtest", rpc.debug_force_finished_sync = true, rpc.enable_cookie_auth = false on loopback only, and mempool.debug_enable_at_height = 0. The sidecar used regtest=1 and six nuparams entries: 5ba81b19:1, 76b809bb:1, 2bb40e60:1, f5b9230b:1, e9ff75a6:1, and c2d6d0b4:1. It also set regtestshieldcoinbase=1, regtestacceptunvalidatedpow=1, and maxtipage=2000000000. These test-only auth, sync, and PoW settings must not be copied to public networks.

The pool mined height 1. After stopping the miner, Zebra generated 101 blocks to mature its reward, then ten blocks for each processor-created transaction. The test waited for matching node tips and the sidecar’s getblockchaininfo.fullyNotified after each batch. Shielding spent the pool coinbase at height 103; unshielding confirmed at 113; the processor’s 6.2496 ZEC miner payment confirmed at 123 and had ten confirmations at 132. The Redis payment record credited the real height-1 round, and the recipient UTXO matched its amount. Additional generated rewards shared the wallet; the test did not fabricate shares or issue shielding, unshielding, or payment calls itself.

This proves one worker’s proportional accounting and scheduled payout, not production readiness. It does not test multiple miners, pool fees, restart or reorg recovery, encrypted wallets, production proof of work, or upgrade transitions. The legacy Node.js version is unsupported. Keep payouts transparent/Sapling: the sidecar never supports Ironwood and rejects Orchard from NU6.3 onward.

Plan for restarts and replacement

• Keep a separately synced standby node with the same network and mining settings, its own state directory, and its own RPC endpoint and credentials. Test the pool’s backend failover before an outage; a reachable RPC port alone does not establish that the node can provide current work.
• Before a planned restart, move mining traffic to the standby. After startup, wait for sync and a fresh successful template before returning traffic. Re-read RPC cookie credentials after a restart when cookie authentication is enabled, and restart long polling with a fresh template.
• After a pool restart, request current work immediately rather than waiting for the next block notification. On backend changes, discard the old backend’s long-poll ID and start a new loop.
• Use the published state snapshots to bootstrap a replacement faster than syncing from genesis. Follow that guide’s network, database-version, checksum, and extraction instructions, then let the node catch up before serving miners. Snapshots require trusting their producer’s validation; checksums detect transfer corruption, not a malicious snapshot. Downloading, extracting, and catching up still take time, so snapshots complement a warm standby rather than replace one.

Monitor mining

Use the mining metrics to watch template build time, new-tip to first-template latency, submission outcomes, and mined-block announcement failures and latency for stale-block risk. Announcement completion measures local writes, not peer receipt or network-wide propagation.

Mining with Zebra in Docker

Configure a reward address in the Zebra image, synchronize the node, then connect a pool and external solver as described in Mining.

Mainnet node

Set MINER_ADDRESS in the shell to a supported Mainnet reward address controlled by the recipient.

docker run -d --name zebra-mainnet \
  -e ZEBRA_NETWORK__NETWORK=Mainnet \
  -e "ZEBRA_MINING__MINER_ADDRESS=${MINER_ADDRESS:?Set MINER_ADDRESS}" \
  -e ZEBRA_RPC__LISTEN_ADDR=0.0.0.0:8232 \
  -p 8233:8233 \
  -p 127.0.0.1:8232:8232 \
  -v zebra-mainnet-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

Keep RPC published only on host loopback unless a protected network or proxy controls access. Never share writable state between running nodes; see Docker paths and permissions.

Inspect node output with:

docker logs --follow zebra-mainnet

Wait for a mining template before starting a pool.

RPC authentication

Request a template from the host using the container’s RPC cookie:

cookie=$(docker exec zebra-mainnet cat /home/zebra/.cache/zebra/.cookie)
curl --fail-with-body --silent --show-error \
  --user "$cookie" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[]}' \
  http://127.0.0.1:8232/ | jq
unset cookie

Configure the pool to reload these credentials when Zebra restarts. Treat them as a password. For container-to-container RPC and isolated deployments without authentication, follow Docker RPC.

Testnet node

Set MINER_ADDRESS to a Testnet address, then use separate container and volume names:

docker run -d --name zebra-testnet \
  -e ZEBRA_NETWORK__NETWORK=Testnet \
  -e "ZEBRA_MINING__MINER_ADDRESS=${MINER_ADDRESS:?Set a Testnet MINER_ADDRESS}" \
  -e ZEBRA_RPC__LISTEN_ADDR=0.0.0.0:18232 \
  -p 18233:18233 \
  -p 127.0.0.1:18232:18232 \
  -v zebra-testnet-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

Use zebra-testnet and port 18232 in the authentication commands. Public Testnet requires real proof of work; use Regtest for local block-generation tests.

Configuration overrides

Use environment overrides for the mining fields. Docker’s --env-file option replaces individual -e options when maintaining these values in a file.

To use a TOML file, mount it read-only and set CONFIG_FILE_PATH to its path inside the container:

docker run -d --name zebra-configured \
  --mount "type=bind,source=$PWD/zebrad.toml,target=/etc/zebra/zebrad.toml,readonly" \
  -e CONFIG_FILE_PATH=/etc/zebra/zebrad.toml \
  -v zebra-configured-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

Configure the file’s network, mining address, and listeners, and publish only the ports required for that deployment. See mounted configuration for file loading.

Repository mining Compose stack

The repository’s docker/mining/docker-compose.yml builds Zebra and the s-nomp pool, starts Redis 7, and defines an optional nheqminer container under the miner profile. Its defaults are Testnet, internal RPC port 18232, P2P port 18233, Stratum port 3333, and pool web port 8080. Stratum is the protocol between the pool and its mining workers. The stack does not publish Zebra’s RPC or Redis ports to the host.

Copy docker/mining/.env.example to docker/mining/.env and set MINER_ADDRESS to a reward address for the selected network. Optional EXTRA_COINBASE_DATA supplies literal UTF-8 data, at most 86 bytes, through ZEBRA_MINING__EXTRA_COINBASE_DATA.

The Zebra service enables its health listener at 127.0.0.1:8080 without publishing it. S-NOMP waits for /healthy to succeed before starting. A successful health check does not replace the mining sync check.

The stack disables RPC authentication inside its Docker network. Do not publish that unauthenticated RPC port. The pool and miner build contexts use moving upstream branches rather than pinned commits. Its s-nomp payment limitations also apply.

Use the s-nomp Testnet procedure for an isolated deployment with compatibility workarounds, independent of this Compose file. Do not use this experimental stack as a production pool.

Mining on Testnet with s-nomp

The Zcash Foundation’s s-nomp fork connects Equihash miners to Zebra through Stratum, a protocol for distributing mining jobs and collecting solutions. This is an experimental Testnet setup, not a production pool: custom coinbase construction and pool-fee outputs are disabled, and this procedure disables worker payments. All miner rewards go to [mining] miner_address in Zebra. A worker’s Stratum username does not select a payment recipient.

Compatibility and limitations

The public fork’s default branch is zebra-mining. Its package version is 0.0.9; the source revision used below is 49fd89bf. Use Node.js 10.24.1 and Python 3.10, selected by the fork’s container recipe, not the README’s Node.js 8.11. Node.js 12 and later have incompatible Equihash native-module APIs.

The pool’s stratum-pool dependency passes Zebra’s coinbasetxn.data and coinbasetxn.hash through unchanged. Its block assembly forwards the supplied transactions and uses the legacy finalsaplingroothash field, which Zebra fills with the current block commitment. This bypasses the obsolete custom coinbase builder. It provides neither a current transaction parser nor a payment implementation.

The fork supplies pool_configs/zcash_testnet.json for native use. Its container entrypoint generates a separate configuration but omits two settings required for this deployment:

• The missing switching object causes Object.keys(portalConfig.switching) to fail at startup.
• Its generated Stratum port omits tls: false. The dependency selects TLS unless that field is explicitly false, so a plain-TCP miner cannot use the generated default.

Use the fork’s container build with Zebra’s s-nomp-entrypoint.sh. The wrapper supplies both settings. The repository Compose stack has separate Zebra startup defects.

Prepare the sources

Use a Linux x86-64 host with Docker, Git, and jq. Keep this old pool runtime on a dedicated Docker network. Do not expose its Redis, RPC, web interface, or Stratum listener to untrusted clients.

Clone the sources into a working directory:

git clone --branch v7.0.0 --depth 1 https://github.com/ZcashFoundation/zebra.git zebra
git clone --branch zebra-mining https://github.com/ZcashFoundation/s-nomp.git s-nomp
git -C s-nomp checkout --detach 49fd89bf32fac6fe2440143d16622650e061e5a0

In s-nomp/package.json, pin the stratum-pool dependency:

"stratum-pool": "git+https://github.com/upbqdn/node-stratum-pool.git#7fbb0685f8895abf1b746d6682de30dd814b9382"

Build the pool image:

docker build -f s-nomp/Dockerfile.arch -t zebra-s-nomp s-nomp

The Dockerfile installs Boost, libsodium, GMP, Redis, and native build tools, sets CXXFLAGS=-std=gnu++17, and patches the RPC transport. Other npm dependencies and the Arch base image remain unpinned; this is not a reproducible dependency build.

The transport patch adds "jsonrpc":"2.0" to the startup batch, as required by Zebra’s batch protocol. A plain npm install leaves that batch incompatible.

Install, run, and sync Zebra

Set MINER_ADDRESS in the shell to a transparent Testnet address that you control. This recipe also uses it for s-nomp’s transparent-address startup check, even though Zebra itself supports additional miner address kinds.

Create a dedicated network and start Zebra:

docker network create zebra-mining

docker run -d --name zebra-testnet \
  --network zebra-mining \
  -e ZEBRA_NETWORK__NETWORK=Testnet \
  -e "ZEBRA_MINING__MINER_ADDRESS=${MINER_ADDRESS:?Set a Testnet MINER_ADDRESS}" \
  -e ZEBRA_RPC__LISTEN_ADDR=0.0.0.0:18232 \
  -e ZEBRA_RPC__ENABLE_COOKIE_AUTH=false \
  -p 18233:18233 \
  -v zebra-testnet-mining-cache:/home/zebra/.cache/zebra \
  zfnd/zebra:7.0.0

The pool’s generated daemon credentials are the fixed strings x and x; it does not load Zebra’s cookie. This example therefore disables RPC authentication but does not publish port 18232. Attach only trusted containers to this network. The authenticated setup in Mining with Docker is preferable for pool software that supports it.

Inspect synchronization:

docker logs --follow zebra-testnet

Before starting s-nomp, request a template from inside the node container:

docker exec zebra-testnet curl --fail-with-body --silent --show-error \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[]}' \
  http://127.0.0.1:18232/ | jq

Wait for a result containing a template, not an RPC error; see the sync requirements. The supplied coinbase handles NU7 funding-stream and NSM fee accounting.

Run s-nomp

Run these commands from the directory containing the zebra and s-nomp checkouts:

docker run -d --name s-nomp-testnet \
  --network zebra-mining \
  -e NETWORK=Testnet \
  -e ZEBRA_HOST=zebra-testnet \
  -e ZEBRA_RPC_PORT=18232 \
  -e STRATUM_PORT=3333 \
  -e "POOL_ADDRESS=${MINER_ADDRESS:?Set a Testnet MINER_ADDRESS}" \
  -p 127.0.0.1:3333:3333 \
  -p 127.0.0.1:8080:8080 \
  --mount "type=bind,source=$PWD/zebra/docker/mining/s-nomp-entrypoint.sh,target=/app/s-nomp-entrypoint.sh,readonly" \
  --entrypoint /bin/bash \
  zebra-s-nomp /app/s-nomp-entrypoint.sh

docker logs --follow s-nomp-testnet

The entrypoint generates /app/config.json and /app/pool_configs/zcash.json, selects coins/testnet/zec.json, disables payment processing, starts Redis on local port 6379, and runs node init.js.

The pool polls for block templates every 500 milliseconds. Its website is available on the host at http://127.0.0.1:8080. The pool’s startup message Stratum Pool Server Started indicates that it has created a job and started the listener; it does not establish that the pool has mined an accepted block.

The entrypoint overwrites generated configuration on each start. Do not edit those files expecting the changes to survive a container restart.

Install and run a CPU miner

The Zcash Foundation’s nheqminer fork supplies a Dockerfile for a CPU-only build with the Xenoncat solver. This solver requires an x86-64 CPU with AVX support; it selects AVX2 when available. The following revision is from the zebra-mining branch:

git clone --branch zebra-mining https://github.com/ZcashFoundation/nheqminer.git nheqminer
git -C nheqminer checkout --detach 72e320aacaa49c9e170be62d28a4189957767d3c
docker build -t zebra-nheqminer nheqminer

docker run -d --name nheqminer-testnet \
  --network zebra-mining \
  zebra-nheqminer \
  -l s-nomp-testnet:3333 \
  -u "${MINER_ADDRESS:?Set a Testnet MINER_ADDRESS}.worker1" \
  -t 1

docker logs --follow nheqminer-testnet

The miner’s -t 1 option selects one CPU thread. A native Equihash miner on the same host can instead connect to 127.0.0.1:3333. Do not use port 18232 as a Stratum endpoint; it belongs to Zebra’s JSON-RPC server.

A share accepted by the pool is not necessarily a block: it can meet the pool’s easier share target without meeting the network target. Check Zebra’s submitblock outcome and best chain when evaluating a mined block.

Diagnose failures

Stop the experiment

Stop the miner before the pool and node:

docker stop --timeout -1 nheqminer-testnet s-nomp-testnet zebra-testnet

The Zebra state volume remains available for reuse. The pool recipe does not mount a persistent Redis volume; do not treat its share statistics as durable payment records.

Custom Testnets

A custom Testnet changes Zebra’s network identity or consensus parameters without changing public Testnet. Use Regtest for a new local chain, or fork public Testnet to reuse existing blocks and balances.

Configuration

Set [network] network = "Testnet" and place overrides in [network.testnet_parameters]; omit the parameter table for public Testnet. With the public activation schedule, supply checkpoints through Canopy minus one: the configured network’s genesis-only default fails the coverage check. Use checkpoints = true when retaining the public chain, or a bounded checkpoint list for a fork.

The following configuration defines an accelerated, proof-of-work-disabled network. Save it as custom-testnet.toml:

[network]
network = "Testnet"
listen_addr = "127.0.0.1:18233"
initial_testnet_peers = []
cache_dir = false

[network.testnet_parameters]
network_name = "ConfiguredTestnet_1"
network_magic = [0, 1, 0, 255]
slow_start_interval = 0
disable_pow = true
funding_streams = []
lockbox_disbursements = []

[network.testnet_parameters.activation_heights]
Canopy = 1
NU5 = 2
NU7 = 9

[mining]
miner_address = "t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v"

[mempool]
debug_enable_at_height = 0

[rpc]
listen_addr = "127.0.0.1:18232"
cookie_dir = "./custom-testnet-rpc"

[state]
cache_dir = "./custom-testnet-state"

Replace the example miner address with an address you control when testing spends. Start Zebra with:

zebrad -c custom-testnet.toml start

Unlike Regtest, a custom Testnet does not insert a genesis block at startup. Provision the matching genesis block before requesting a block template: submit its hex-encoded serialized bytes with submitblock, obtain it from a configured peer, or copy compatible state. This example retains public Testnet’s genesis hash but has no peers. It therefore needs an externally supplied genesis block. Zebra does not construct new genesis blocks from a configured hash.

After genesis is present, use the generation RPCs to produce blocks. The example’s cookie file is ./custom-testnet-rpc/.cookie. Disabling proof of work skips Equihash and block-hash target checks, not target validity or other consensus rules.

Parameter reference

See the network configuration reference for parameter names, types, defaults, input formats, and selector layouts. The rules below govern combinations of parameters.

Activation heights

Use the case-sensitive keys in the activation field reference, quoting names containing dots. Heights must be nondecreasing in upgrade order; equal heights are allowed. An omitted earlier upgrade activates with the next explicitly configured upgrade. Upgrades after the last configured upgrade remain inactive. Height zero is reserved for genesis.

A present activation table replaces all public activation heights. For example, NU6 = 1 activates every upgrade through NU6 at height 1 and leaves later upgrades inactive. Do not supply an empty schedule: Zebra requires Canopy and its predecessors for state verification and block-template generation.

For a fork, retain every historical public Testnet activation explicitly.

Regtest fills omitted early upgrades through Canopy from its defaults: Overwinter defaults to BeforeOverwinter or height 1, and each upgrade through Canopy defaults to the preceding one. Later omitted upgrades activate with the next configured upgrade, or remain inactive if none follows.

Subsidy schedule and NU7

The subsidy slow start and halvings follow the protocol subsidy rules. The block target spacing is 150 seconds before Blossom, 75 seconds from Blossom, and 25 seconds from NU7 under ZIP 218. Spacing is not independently configurable. The post-Blossom halving interval is twice pre_blossom_halving_interval; the post-NU7 interval is six times it. A halving height is not necessarily a multiple of the interval because the schedule accounts for upgrade boundaries and the slow-start shift.

For custom Testnets, Zebra validates that:

• The first halving height is representable and Blossom is scheduled.
• The halving index at the slow-start shift is nonnegative.
• Scheduled issuance through height 2^31 - 1, excluding the unspendable genesis subsidy, does not exceed 21 million coins.
• A nonempty funding-stream schedule has a nonzero address-change interval, calculated as the post-Blossom halving interval divided by 48.
• With NU7 scheduled, the post-NU7 halving interval is positive and no greater than 6_931_680_000, so the integer NSM reissuance coefficient is nonzero.

Early spacing upgrades during slow start can violate these bounds. Set slow_start_interval = 0 for accelerated chains such as the example above. The configuration accepts activation heights through 2^31 - 1, but the current on-disk height encoding supports only 2^24 - 1.

The Network Sustainability Mechanism (NSM) reserve is separate from issued supply. Zebra seeds it at NU7 and applies the mining fee split. Without NU7, no NSM reissuance height is calculated. Unless overridden, reissuance starts at the ZIP 237 crossover, not automatically at NU7; accelerated schedules can have no crossover. An explicit nsm_reissuance_height requires NU7 and must not precede it.