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

.config/nextest.toml

@@ -109,3 +109,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)'

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
+- New 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`)
+
 - Pre-built `zebrad` binaries are attached to each GitHub release for Linux on
   `x86_64` and `aarch64`, so operators can run a node without Docker or a source
   build, also installable with `cargo binstall zebrad`. Each `.tar.gz` carries a

Cargo.lock

@@ -1629,6 +1629,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"
@@ -5508,6 +5518,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"
@@ -7068,6 +7089,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"
@@ -7678,6 +7709,7 @@ dependencies = [
  "console-subscriber",
  "derive-new",
  "dirs",
+ "flate2",
  "futures",
  "hex",
  "hex-literal",
@@ -7695,6 +7727,7 @@ dependencies = [
  "log",
  "metrics",
  "metrics-exporter-prometheus",
+ "nix",
  "num-integer",
  "once_cell",
  "opentelemetry",
@@ -7707,12 +7740,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",

Makefile

@@ -0,0 +1,17 @@
+.PHONY: 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 zcashd-compat artifact for Docker build"
+	@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)