feat(zebrad): add zcashd-compat mode with a supervised zcashd wallet sidecar

.config/nextest.toml

@@ -52,6 +52,20 @@ slow-timeout = { period = "30m", terminate-after = 2 }
 
 [test-groups]
 serial-state = { max-threads = 1 }
+# zcashd-compat integration tests each spawn a zebrad + zcashd on
+# bind-probed-then-released ports, so they must never run concurrently, even
+# under a parallel profile invoked with --run-ignored=all.
+serial-zcashd-compat = { max-threads = 1 }
+
+# Force zcashd-compat integration tests serial in every profile, so a parallel
+# --run-ignored=all run cannot collide on their released RPC/P2P ports.
+[[profile.default.overrides]]
+filter = 'test(~integration::zcashd_compat::)'
+test-group = 'serial-zcashd-compat'
+
+[[profile.ci.overrides]]
+filter = 'test(~integration::zcashd_compat::)'
+test-group = 'serial-zcashd-compat'
 
 # Stateful tests share on-disk state, so run them serially. This override sets
 # only the test-group: adding slow-timeout here would shadow every per-test
@@ -103,3 +117,29 @@ slow-timeout = { period = "90m", terminate-after = 1 }
 
 [profile.check-no-git-dependencies]
 default-filter = 'test(=unit::end_of_support::check_no_git_dependencies)'
+
+# --- zcashd-compat Profiles ---
+
+[profile.zcashd-compat-integration]
+# Run zcashd-compat tests one at a time to avoid port conflicts and resource exhaustion.
+test-threads = 1
+slow-timeout = { period = "15m", terminate-after = 2 }
+failure-output = "immediate"
+default-filter = 'package(zebrad) and test(~zcashd_compat)'
+
+[profile.zcashd-compat-soak]
+# Long-running local soak for the reorg churn stress test.
+test-threads = 1
+slow-timeout = { period = "4h", terminate-after = 1 }
+failure-output = "immediate"
+default-filter = 'package(zebrad) and test(=integration::zcashd_compat::zcashd_compat_reorg_churn)'
+
+[profile.zcashd-compat-external]
+# External mode: connect to pre-running mainnet/testnet zebrad + zcashd.
+# Set TEST_ZCASHD_COMPAT_NETWORK, TEST_ZEBRAD_RPC_ADDR,
+# TEST_ZCASHD_RPC_ADDR, and auth env vars before running.
+# No block mining — 5 minutes per test is sufficient.
+test-threads = 1
+slow-timeout = { period = "5m", terminate-after = 2 }
+failure-output = "immediate"
+default-filter = 'package(zebrad) and test(~zcashd_compat)'

.github/workflows/zcashd-compat-regtest.yml

@@ -0,0 +1,58 @@
+name: zcashd-compat Regtest
+
+# Runs the managed zcashd-compat Regtest integration suite.
+#
+# The test harness spawns a fresh zebrad and zcashd on randomised ports, so no
+# external infrastructure is required. The sidecar zcashd binary is the
+# SHA256-pinned build from zebrad/zcashd-compat-manifest.json.
+#
+# Manual and scheduled only for now: the suite is new and not yet required.
+# Add a pull_request paths trigger once it has a green track record.
+on:
+  workflow_dispatch:
+  schedule:
+    # Weekly, Monday 04:00 UTC.
+    - cron: "0 4 * * 1"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+  RUST_LIB_BACKTRACE: 1
+  RUST_LOG: info
+  COLORBT_SHOW_HIDDEN: 1
+
+jobs:
+  zcashd-compat-regtest:
+    name: zcashd-compat regtest suite
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 #v1.16.1
+        with:
+          toolchain: stable
+          cache-key: zcashd-compat-regtest
+          cache-on-failure: true
+
+      - uses: taiki-e/install-action@65851e10cd6c377f11a60e600abc07cb08643468 #v2.79.3
+        with:
+          tool: cargo-nextest
+
+      - name: Fetch the pinned sidecar zcashd
+        run: make compat-zcashd-prepare
+
+      - name: Run zcashd-compat regtest suite
+        run: make compat-test-regtest TEST_ZCASHD_PATH="$PWD/target/zcashd-compat/extracted/bin/zcashd"

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to Zebra are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org).
 
+## [Unreleased]
+
+### Added
+
+- New regtest-only `generatetoaddress` RPC that mines blocks paying the coinbase
+  to a caller-specified address, instead of the configured `mining.miner_address`.
+  This lets a test harness fund several wallets from one node; it is used by the
+  zcashd wallet-conformance harness
+  ([#10952](https://github.com/ZcashFoundation/zebra/pull/10952))
+- New _EXPERIMENTAL_ zcashd-compat mode (`zebrad start --zcashd-compat` or
+  `[zcashd_compat]` config section) for operators migrating from `zcashd` while
+  keeping its wallet and RPC surface: Zebra faces the Zcash network and always
+  includes the configured sidecar peers in block gossip (reserving them an
+  inbound connection slot), while a hard-locked `zcashd` wallet build runs as a
+  P2P sidecar with a single outbound connection to the local Zebra node. Zebra
+  can optionally download (SHA256-pinned), spawn, and supervise the sidecar
+  (`manage_zcashd = true`). Includes an interactive installer
+  (`scripts/install-zebra.sh`) with binary, Docker, and build-from-source modes,
+  a `runtime-zcashd-compat` Docker image stage, make targets, a sync-check
+  script, and a Zebra Book chapter (`user/zcashd-compat.md`)
+  ([#10952](https://github.com/ZcashFoundation/zebra/pull/10952)). Credits to
+  [zakura](https://github.com/zakura-core/zakura) authors for the major part of
+  this implementation.
+
 ## [Zebra 6.1.0](https://github.com/ZcashFoundation/zebra/releases/tag/v6.1.0) - 2026-07-17
 
 ### Added

Cargo.lock

@@ -1609,6 +1609,16 @@ version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
 
+[[package]]
+name = "filetime"
+version = "0.2.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
+dependencies = [
+ "cfg-if",
+ "libc",
+]
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -5466,6 +5476,17 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
 
+[[package]]
+name = "tar"
+version = "0.4.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.27.0"
@@ -7027,6 +7048,16 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "xattr"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
+dependencies = [
+ "libc",
+ "rustix",
+]
+
 [[package]]
 name = "xdg"
 version = "3.0.0"
@@ -7638,6 +7669,7 @@ dependencies = [
  "console-subscriber",
  "derive-new",
  "dirs",
+ "flate2",
  "futures",
  "hex",
  "hex-literal",
@@ -7655,6 +7687,7 @@ dependencies = [
  "log",
  "metrics",
  "metrics-exporter-prometheus",
+ "nix",
  "num-integer",
  "once_cell",
  "opentelemetry",
@@ -7667,12 +7700,15 @@ dependencies = [
  "rand 0.8.6",
  "rayon",
  "regex",
+ "reqwest 0.12.28",
  "semver",
  "sentry",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "strum",
  "strum_macros",
+ "tar",
  "tempfile",
  "thiserror 2.0.18",
  "thread-priority",

Cargo.toml

@@ -69,7 +69,7 @@ ed25519-zebra = "4.2"
 elasticsearch = { version = "8.17.0-alpha.1", default-features = false }
 equihash = "0.3"
 ff = "0.13"
-futures = "0.3.31"
+futures = "0.3.32"
 futures-core = "0.3.31"
 futures-util = "0.3.31"
 group = "0.13"

Makefile

@@ -0,0 +1,21 @@
+.PHONY: help
+
+# Keep `make` with no target printing help: the first rule in an included
+# file would otherwise become the default goal.
+.DEFAULT_GOAL := help
+
+include make/zcashd-compat.mk
+
+help:
+	@echo "Available targets:"
+	@echo ""
+	@echo "  zcashd-compat:"
+	@echo "  compat-docker-build              Build Docker zcashd-compat image"
+	@echo "  compat-zcashd-prepare            Fetch/verify the zcashd-compat sidecar artifact (for tests)"
+	@echo "  compat-docker-start              Start Docker zcashd-compat with mounted snapshots"
+	@echo "  compat-zebrad-start-supervised   Start zebrad with zcashd supervision enabled"
+	@echo "  compat-zebrad-start-unsupervised Start zebrad with zcashd supervision disabled"
+	@echo "  compat-zcashd-start-standalone   Start sidecar zcashd as a standalone process"
+	@echo "  compat-zebrad-status             Check zebrad liveness and RPC health"
+	@echo "  compat-zcashd-status             Check zcashd liveness and RPC health"
+	@echo "  compat-status-sync               Run both status checks and enforce max drift"

book/src/SUMMARY.md

@@ -12,6 +12,7 @@
   - [Tracing Zebra](user/tracing.md)
   - [Zebra Metrics](user/metrics.md)
   - [Zebra Health Endpoints](user/health.md)
+  - [zcashd-compat Mode](user/zcashd-compat.md)
   - [Lightwalletd](user/lightwalletd.md)
   - [zk-SNARK Parameters](user/parameters.md)
   - [Mining](user/mining.md)