Zebra 4.1.0

Zebra 4.1.0 - 2026-02-05

This release has no breaking changes for node operators. It expands Zebra's
observability with new Prometheus metrics and Grafana dashboards. It also adds
mempool checks for standard transparent scripts to match zcashd.

Listed below are all user-visible changes.

Changed

• Check that SENTRY_DSN env variable is present before initializing sentry (#10256)

Added

• Add RocksDB I/O latency and sync distance metrics (#10181)
• Add performance histograms for bottleneck identification (#10179)
• Add value pool, RPC, and peer health metrics (#10175)
• Add standardness checks and configurable OP_RETURN policy (#10224)
• Add zaino to the qa rpc framework (#10199)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@Bashmunta, @MozirDmitriy, @gustavovalverde, @mpguerra, @oxarbitrage, @syszery, @upbqdn and @zlyzol

Zebra 4.0.0

This release fixes the type of a field in the getinfo RPC and adds support for
the pingtime and pingwait fields of the getpeerinfo RPC.

It also changes the Grafana dashboards to add auto-provisioning and AlertManager
support.

This release also adds a new mainnet DNS seeder from Shielded Labs to the default
configuration. However, if you already have a config in place, you will need
to add it manually; add "mainnet.seeder.shieldedinfra.net:8233" to
initial_mainnet_peers.

The new OpenTelemetry support must be enabled at compile time with the
opentelemetry feature, e.g. cargo build --features=opentelemetry --release.

Breaking Changes

This release has the following breaking changes:

• Changed the getinfo RPC errorstimestamp field from a string timestamp (ISO
  UTC timestamp) to a i64 (seconds from Unix epoch) to match zcashd
  (#10079). If you rely
  on this field, you will need to change your code to be able to interpret
  the i64 result.
• Always parse Zebra's config file as TOML (#10222). This allows using a config
  file with an extension different than .toml. Previously, it would use the
  format detected from the extension, so in the unlikely case you were using
  a format different than TOML you will need to change your config to TOML.

Added

• Added pingtime and pingwait to getpeerinfo RPC (#9880)
• Added Grafana auto-provisioning and AlertManager (#10171)
• Added OpenTelemetry distributed tracing support (#10174)
• Added new Shielded Labs mainnet seeder (#10228)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@conradoplg, @gustavovalverde and @syszery

Zebra 3.1.0

This release fixes how Docker images are published for ARM64 platforms, increases the maximum size of RPC responses and allows configuring it, and filters out dust transactions in the mempool.

Added

• Implemented filter for dust transactions in the mempool (#10134)

Changed

• Updated Debian from bookworm to trixie in Docker (#10111)
• Configured Zebra to listen on the all-zero IPv6 address in Docker by default (#10095)
• Increased allowed RPC response size (#10118)

Fixed

• Fixed publishing workflow for ARM64 and AMD64 Docker images (#10125)
• Fixed logging of commit IDs (#10135 and [#10115)
• Prevented static IP assignment step from failing on read command (#10123)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@conradoplg, @gustavovalverde, @imcdona, @oxarbitrage and @upbqdn

Zebra 3.0.0

Zebra 3.0.0 - 2025-11-17

This release is a stable version of the release candidate deploying NU6.1 on Mainnet. It fixes some issues that were found after
the release candidate was published but otherwise mostly includes technical improvements and cleanup with relatively few user-visible changes.

Changed

• Gated code behind the tx_v6 feature flag behind the zcash_unstable=nu7 config flag too (#10060)

Added

• Added ZIP 233 (Network Sustainability Mechanism) implementation (#8930)
• Populated asm field returned by Zebra's RPC methods with code in script outputs as well as script types (#10019)
• Added a CHANGELOG file to track changes in the python QA framework (#10076)
• Enabled backtraces and added debug info by default in production builds (#10097)

Fixed

• Updated Dockerfile to accept Cargo features for release builds (#10075)
• Fixed the docker build command (#10007)
• Fixed a bug in z_validateaddress around parsing Testnet transparent addresses on Regtest (#10022)
• Re-enabled Docker provenance and SBOM attestations (#10071)
• Fixed an issue where Zebra would panic in some edge cases around mempool transactions depending on other mempool transactions (#10049)
• Fixed a DDoS vulnerability and panic issue around error handling in proof verifiers (#10099)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@AloeareV, @arya2, @conradoplg, @dorianvp, @gustavovalverde, @mariopil, @oxarbitrage, @syszery, and @upbqdn

Zebra 3.0.0-rc.0

Zebra 3.0.0-rc.0 - 2025-10-15

In this release, we add the Mainnet activation height for Network Upgrade 6.1 (NU6.1), which will activate at block 3,146,400.

This is a release candidate. Its support is set to expire before the activation height. If no issues are found, this candidate will become the final release for NU6.1.

This release also includes significant updates to Zebra's CI and Docker setup, as well as performance optimizations.

Breaking Changes

• Migrate zebrad to a layered configuration using config-rs. Environment variables must use the ZEBRA_SECTION__KEY format (double underscore for nesting), for example: ZEBRA_NETWORK__NETWORK, ZEBRA_RPC__LISTEN_ADDR, ZEBRA_RPC__ENABLE_COOKIE_AUTH, ZEBRA_RPC__COOKIE_DIR ZEBRA_TRACING__FILTER ZEBRA_STATE__CACHE_DIR, ZEBRA_MINING__MINER_ADDRESS. Legacy ZEBRA_* test/path variables and ZEBRA_RUST_LOG are no longer honored. Update any scripts, Docker configs, or systemd units that relied on the old names (#9768).
• Docker entrypoint simplified: it no longer generates a zebrad.toml or translates legacy Docker environment variables. To use a file, set CONFIG_FILE_PATH (the entrypoint forwards it via --config). Otherwise, configure via ZEBRA_* variables. ZEBRA_CONF_PATH has been removed in favor of CONFIG_FILE_PATH. Docker setups that used variables like ZEBRA_RPC_PORT, ZEBRA_COOKIE_DIR, NETWORK, ENABLE_COOKIE_AUTH, or MINER_ADDRESS must switch to the config-rs equivalents shown above (#9768).
• Fully removed the getblocktemplate-rpcs feature flag from zebrad/Cargo.toml. All functionality previously guarded by this flag has already been made the default. As a result, the following build command is no longer supported:

  cargo build --features getblocktemplate-rpcs
  

  (#9964)

Changed

• zebrad now loads configuration from defaults, an optional TOML file, and environment variables, with precedence: Env > TOML > Defaults (#9768).
• Docker and book documentation updated to describe CONFIG_FILE_PATH and ZEBRA_* environment variable usage; removed references to ZEBRA_CONF_PATH and legacy Docker variables (#9768).
• Implemented nextest and optimized Docker test builds (#9435)
• Replaced light wallet .proto files with canonical versions obtained from https://github.com/zcash/lightwallet-protocol (#9783)
• Allow zebra-rpc to be compiled without protoc (#9819)
• Switched Sapling verifier (#9737)
• Refactor Sapling parameters loading (#9678)
• Adopt upstream types for sapling commitments where possible (#9828)
• Updated transaction verifier to use orchard::bundle::BatchValidator (#9308)
• Improved error propagations (#9921, #9919, #9848)
• Broadcast block submissions to all peers in the peer set (#9907)
• Removed outdated seeders (#9932)
• Apply suggestions for code cleanup from NU6.1 audit. (#9952)
• Always return 1.0 from getblockchaininfo as the verification progress on Regtest (#9908)
• Corrected number of addresses for the FPF funding stream extension on Testnet (#9786)
• Simplified a test to use regtest instead of fake activation heights (#9792)
• Re-enable and update disconnects_from_misbehaving_peers test (#9735)
• Improve connection times in regtest framework (#9917)
• Always wait for RPC port to open in cached state tests (#9903)
• Allow configuration of funding streams on Regtest (#9710)
• Implemented draft ZIP 2003 for NU7 and use Testnet network protocol versions on Regtest (#9787)

Added

• NU6.1 activation height, funding streams, lockbox disbursments, and current network protocol version (#9987)
• Backup non-finalized blocks in state cache directory (#9809)
• Complete z_gettreestate (#9798)
• getmempoolinfo RPC method (#9870)
• getnetworkinfo RPC method (#9887)
• Support side chains in getrawtransaction (#9884)
• Support single-string or object params in getaddresstxids (#9854)
• Exposed z_validateaddress logic for library consumers (#9859)
• Missing Orchard fields to getrawtransaction (#9808)
• vjoinsplit field to getrawtransaction (#9805)
• Use specific error code for addnode; reuse message in response filter (#9931)
• Support for the chainInfo field in getaddressutxos RPC method (#9875)
• Allow for cycling through configured funding stream addresses (#9989)
• Introduce BytesInDisplayOrder trait to standardize byte-reversed encoding in RPC (#9810)
• MappedRequest helper trait and refactors error types used by CommitSemanticallyVerifiedBlock requests (#9923)
• Useful standard trait implementations to ease downstream use (#9926)
• Added ZFuture variant to NetworkUpgrade (#9814)
• Allow configuration of checkpoints on test networks (#9888)
• Added HTTP /healthy and /ready endpoints (#9895, #9886)
• New book page on profiling Zebra (#9983)
• Deserialization logic to call extend_funding_streams() when the flag is true for both configured Testnets and Regtest (#9989)

Fixed

• Restore initial sync performance by avoiding RocksDB merge operations when the on-disk database format is up-to-date (#9973)
• Use STANDARD Base64 for RPC auth encoding/decoding (#9968)
• Expects the block commitment bytes of Heartwood activation blocks to be the hashBlockCommitments after NU5 activation (#9982)
• Fixed UTXO selection loop to iterate over entries instead of repeating first (#9826)
• Improve extra argument passing to zebra in qa framework(#9858)
• Avoid heap allocations in expand_zero_be_bytes() (#9951)
• Fixed sanitize_avoids_leaks test to validate sanitized MetaAddr (#9867)
• Corrected at_least_one! count-form and add unit test (#9871)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@Fibonacci747, @Galoretka, @GarmashAlex, @JacksonEi, @MozirDmitriy, @Olexandr88, @arya2, @conradoplg, @gap-editor, @gustavovalverde, @natalieesk, @nuttycom, @oxarbitrage, @radik878, @sashass1315, @str4d, @syszery, @upbqdn and @zancas

zebra-rpc v2.0.1

This release removes zebra-rpc's build dependency on protoc by copying the pre-generated protoc files into the build output directory if protoc is unavailable in the build environment.

Changed

• Removed build dependency on protoc

Zebra 2.5.0

Zebra 2.5.0 - 2025-08-07

This release includes the implementation of Zcash Network Upgrade 6.1 (NU6.1) on Testnet and sets its activation height on the public Testnet at block 3,536,500. Please update your Testnet nodes as soon as possible to ensure compatibility.

Breaking Changes

• Value pool "deferred" changes its identifier to "lockbox". getblock and getblockchaininfo RPC methods will now return lockbox as the FS_DEFERRED value pool to match zcashd. (#9684)

Added

• Implement one-time lockbox disbursement mechanism for NU6.1 (#9603, #9757, #9747, #9754)
• NU6.1 Testnet implementation and deployment (#9762, #9759)

Fixed

• validateaddress RPC bug (#9734)
• Count sigops using generics (#9670)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@Galoretka, @arya2, @conradoplg, @dorianvp, @gustavovalverde, @oxarbitrage, @pacu and @upbqdn

Zebra 2.4.2

This release fixes a database upgrade bug that was introduced in the 2.4.0
release (which has been removed). If you have upgraded to 2.4.0, your Zebra
address index has become corrupted. This does not affect consensus, but will
make the RPC interface return invalid data for calls like getaddressutxos and
other address-related calls.

(Also refer to the 2.4.0 release notes below for important breaking changes.)

Zebra 2.4.2 prints a warning upon starting if you have been impacted by the bug.
The log line will look like:

2025-07-17T17:12:41.636549Z  WARN zebra_state::service::finalized_state::zebra_db: You have been impacted by the Zebra 2.4.0 address indexer corruption bug. If you rely on the data from the RPC interface, you will need to recover your database. Follow the instructions in the 2.4.2 release notes: https://github.com/ZcashFoundation/zebra/releases/tag/v2.4.2 If you just run the node for consensus and don't use data from the RPC interface, you can ignore this warning.

If you rely on the RPC data, you will need to restore your database. If you have
backed up the state up before upgrading to 2.4.0, you can simply restore the backup
and run 2.4.2 from it. If you have not, you have two options:

• Stop Zebra, delete the state (e.g. ~/.cache/zebra/state/v27/mainnet and
  testnet too if applicable), upgrade to 2.4.2 (if you haven't already), and
  start Zebra. It will sync from scratch, which will take around 48 hours to
  complete, depending on the machine specifications.
• Use the copy-state subcommand to regenerate a valid state.
  This will require an additional ~300 GB of free disk size. It is likely that
  it will take around the same time as syncing from scratch, but it has the
  advantage of not depending on the network.
  • Stop Zebra.
  • Rename the old corrupted state folder, e.g. mv ~/.cache/zebra ~/.cache/zebra.old
  • Copy your current zebrad.toml file to a zebrad-source.toml file and edit
    the cache_dir config to the renamed folder, e.g. cache_dir = '/home/zebrad/.cache/zebra.old'
  • The copy-state command that will be run requires a bigger amount of opened
    files. Increase the limit by running ulimit -n 2048; refer to your OS
    documentation if that does not work.
  • Run the copy-state command: zebrad -c zebrad-source.toml copy-state --target-config-path zebrad.toml. The command will take several hours to
    complete.

Fixed

• Fix 2.4.0 DB upgrade; add warning if impacted (#9709)
• Downgrade verbose mempool message (#9700)

Contributors

Thanks to @ebfull for reporting the bug and helping investigating its cause.

Zebra 2.4.1 - [REMOVED]

This version of Zebra wasn't fully published; it was tagged but the tag was
removed, and it was published on crates.io but it was yanked. It was not
published on Docker Hub.

We removed it due to a panic that happened during the pre-release validation.
However, we determined that the panic was caused by an external tool (ldb checkpoint) being used internally to make database backups and it was not a bug
in Zebra.

Zebra 2.4.0 - 2025-07-11 [REMOVED]

Breaking Changes

This release has the following breaking changes:

• This release contains a major database upgrade. It will upgrade an existing
  database, automatically moving it from the v26/ folder to a new v27/
  folder. However, downgrading is not possible. If you want to keep the
  possibility of reverting Zebra in case of an unexpected issue, backup the
  v26/ folder before running the upgraded Zebra. Note that the upgrade is slow
  and could take several hours or more to complete on smaller machines. Zebra will
  operate normally during that time; the only difference is that some RPC
  responses might return empty or not accurate data (pool values for arbitrary
  block heights and received balances for addresses).
• While this was never documented as an option for backups, if you relied on the
  ldb checkpoint tool to generate database backups, be advised that the tool
  is no longer supported and will corrupt databases generated or touched by
  Zebra 2.4.0 or later releases.
• The debug_like_zcashd config option for mining is no longer available. It
  was not enabled by default; if it is now present in the config file, Zebra
  will panic. Simply delete the config option to fix.
• The cm_u field byte order was fixed in getrawtransaction/getblock
  response, so if you relied on the wrong order, you will need to fix your
  application.
• The zebra-scan and zebra-grpc crates are no longer supported and were
  removed from the codebase.

Security

• Fix a consensus rule violation in V5 coinbase transactions at low heights. This issue could only occur on Regtest or custom testnets and is now resolved (#9620)

Added

• Implemented deserialization for Zebra's block and transaction types (#9522)
• Update getaddressbalance RPC to return received field (#9295, #9539)
• Added a mempool_change() gRPC method for listening to changes in the mempool (#9494)
• Added raw_value feature to serde_json (#9538)
• Modified zebra_network::Config type to use IPv6 listen_addr by default (#9609)
• Added invalidateblock and reconsiderblock RPC methods (#9551)
• Updated (z_)validateaddress to validate TEX addresses (#9483)
• Added a addnode RPC method (#9604)
• Added missing fields to getrawtransaction (#9636)
• Added value pool balances to getblock RPC output (#9432, #9539)
• Added support for configuring shielded addresses for mining (#9574)
• Added binding_sig, joinsplit_pub_key and joinsplit_sig fields to getrawtransaction/getblock response (#9652)
• Added a method in zebra-rpc to allow validating addresses (#9658)

Changed

• Allow Zebra crates to be compiled with alternative versions of their dependencies (#9484)
• Updated README with Arch build patch (#9513)
• Renamed and moved exports in zebra-rpc (#9568)
• Upgraded DB format to support new fields in RPC outputs (#9539)
• Moved GBT RPCs into the main RPC server (#9459)
• Added a Nu6_1 variant to NetworkUpgrade (#9526)
• Use zcash_script’s new Script trait (#8751)
• Removed debug_like_zcashd config option (#9627)
• Sync all chains in TrustedChainSync::sync, add NonFinalizedStateChange gRPC method (#9654)
• Added prometheus as a default feature in zebrad (#9677)

Fixed

• Preserve order of RPC output fields (#9474)
• Fixed cm_u field byte order in getrawtransaction/getblock response (#9667)
• Avoid repeatedly converting transactions to librustzcash types when computing sighashes (#9594)
• Correctly set optional scriptPubKey fields of transactions in getblock and getrawtransaction RPC outputs (#9536)
• Allow local outbound connections on Regtest (#9580)
• Allow for parsing z_gettreestate output type where optional fields are omitted (#9451)

Removed

• Removed zebra-scan and zebra-grpc (#9683)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@ala-mode, @arya2, @conradoplg, @elijahhampton, @gustavovalverde, @idky137, @mpguerra, @oxarbitrage, @sellout, @str4d and @upbqdn

Zebra 2.3.0

Zebra 2.3.0 - 2025-05-06

Breaking Changes

• The RPC endpoint is no longer enabled by default in Docker. To enable it,
  follow the docs here.
• We will no longer be publishing Docker images tagged with the sha- or v
  prefixes. If you use tags starting with the v prefix, please update to
  images tagged N.N.N. For example, use 2.3.0 instead of v2.3.0. If you
  need a specific hash, each tag has a digest that you can use instead.
• All functionality that used to be guarded by the getblocktemplate-rpcs Cargo
  feature was moved out, and the feature is no longer present in the codebase.
  Note that all release builds following Zebra 1.3.0 had this feature enabled by
  default.

Added

• Track misbehaving peer connections and ban them past a threshold (#9201)
• Restore internal miner (#9311)
• Add reconsider_block method (#9260)
• Add NU7 constants (#9256)
• Add invalidate_block_method and invalidated_blocks field to non-finalized state (#9167)
• Add Transaction::V6 variants only (#9339)

Changed

• Downgrade verbose info message (#9448)
• Use read-only db instance when running tip-height or copy-state commands (#9359)
• Refactor format upgrades into trait (#9263)
• Remove the getblocktemplate-rpcs Cargo feature (#9401)
• Improve cache dir and database startup panics (#9441)

Fixed

• Remove a redundant startup warning (#9397)
• Advertise mined blocks (#9176)
• Ensure secondary rocksdb instance has caught up to the primary instance (#9346)
• Use network kind of TestnetKind in transparent addresses on Regtest (#9175)
• Fix redundant attributes on enum variants (#9309)

RPCs

• Add time and size fields to TransactionObject (#9458)
• Add inbound peers to getpeerinfo response (#9214)
• Extend getinfo (#9261)
• Add fields to getblockchaininfo RPC output (#9215)
• Add some missing fields to transaction object (#9329)
• Support negative heights in HashOrHeight (#9316)
• Add verbose support to getrawmempool (#9249)
• Fill size field in getblock with verbosity=2 (#9327)
• Add blockcommitments field to getblock output (#9217)
• Accept an unused second param in sendrawtransaction RPC (#9242)
• Make start and end fields optional and apply range rules to match zcashd (#9408)
• Return only the history tree root in GetBlockTemplateChainInfo response (#9444)
• Correctly map JSON-RPC to/from 2.0 (#9216)
• Permit JSON-RPC IDs to be non-strings (#9341)
• Match coinbase outputs order in Getblocktemplate (#9272)

Docker

• Refactor Dockerfile and entrypoint (#8923)
• Enhance Zebra configuration options and entrypoint logic (#9344)
• Better permission and cache dirs handling in Docker (#9323)
• Allow r/w access in mounted volumes (#9281)

Documentation

• Update examples for running Zebra in Docker (#9269)
• Add architectural decision records structure (#9310)
• Add Mempool Specification to Zebra Book (#9336)
• Complete the Treestate RFC documentation (#9340)

Contributors

@AloeareV, @Metalcape, @PaulLaux, @VolodymyrBg, @aphelionz, @arya2, @conradoplg,
@crStiv, @elijahhampton, @gustavovalverde, @mdqst, @natalieesk, @nuttycom,
@oxarbitrage, @podZzzzz, @sellout, @str4d, @upbqdn and @zeroprooff.

Zebra 2.2.0

Zebra 2.2.0 - 2025-02-05

In this release, Zebra introduced an additional consensus check on the branch ID of Nu6 transactions
(which is currently also checked elsewhere; but we believe it's important to check on its own to protect
against future code changes), along with important refactors and improvements.

Added

• An index to track spending transaction ids by spent outpoints and revealed nullifiers (#8895)
• Accessor methods to zebra-rpc request/response types (#9113)
• getblock RPC method now can return transaction details with verbosity=2 (#9083)
• Serialized NU5 blocks to test vectors (#9098)

Changed

• Migrated from deprecated jsonrpc_* crates to jsonrpsee (#9059, #9151)
• Optimized checks for coinbase transactions (#9126)
• Avoid re-verifying transactions in blocks if those transactions are in the mempool (#8951, #9118)
• Allow transactions spending coinbase outputs to have transparent outputs on Regtest (#9085)

Fixed

• Respond to getblockchaininfo with genesis block when empty state (#9138)
• Verify consensus branch ID in SIGHASH precomputation (#9139)
• More closely match zcashd RPC errors and getrawtransaction RPC behaviour (#9049)
• Fixes bugs in the lightwalletd integration tests (#9052)

Contributors

Thank you to everyone who contributed to this release, we couldn't make Zebra without you:
@Fallengirl, @arya2, @conradoplg, @elijahhampton, @futreall, @gustavovalverde, @idky137, @mpguerra, @oxarbitrage, @rex4539, @rootdiae, @sandakersmann and @upbqdn