zebra-zcashd-compat

1. Start Zebra In zcashd-compat Mode

   Default path: one Zebra binary. Zebra resolves a hash-pinned compatible zcashd build, starts it as a child process, and supervises restarts.

   zebrad start --zcashd-compat

2. Minimal Config

   Keep supervision enabled so Zebra manages install + lifecycle.

   [zcashd_compat]
   enabled = true
   manage_zcashd = true
   zcashd_source = "managed"
   
   # Optionally, customize zcashd data directory.
   zcashd_datadir = "/path/to/zcashd/datadir"
   
   # Optionally, propagate zcashd CLI arguments via env var.
   ZEBRA_ZCASHD_COMPAT__ZCASHD_EXTRA_ARGS='["-printtoconsole"]'

   For full configuration reference, see full documentation.

1. Build Binaries

   Build Zebra and zcashd from source.

   # in zebrad tree
   cargo build --release
   
   # in zcashd tree
   ./zcutil/build.sh -j"$(nproc)"

2. Run Manually (No Supervision)

   Configure manually and run zcashd against Zebra RPC.

   [zcashd_compat]
   enabled = true
   manage_zcashd = false

   zebrad start --zcashd-compat
   
   # Default location, to which Zebra writes an auth cookie
   ZEBRA_COMPAT_COOKIE="$HOME/.cache/zebra/.zcashd-compat.cookie"
   
   # Ensure Zebra has written it
   test -f "$ZEBRA_COMPAT_COOKIE" && echo "cookie ready: $ZEBRA_COMPAT_COOKIE"
   
   # One-time zcashd datadir setup (zcashd refuses to start without this line)
   mkdir -p ~/.zcash
   echo 'i-am-aware-zcashd-will-be-replaced-by-zebrad-and-zallet-in-2025=1' >> ~/.zcash/zcash.conf
   
   # Start zcashd in compat mode, pointed at Zebra's compat listener
   ./src/zcashd -zebra-compat \
     -zebra-compat-url=http://127.0.0.1:28232 \
     -zebra-compat-cookiefile="$HOME/.cache/zebra/.zcashd-compat.cookie" \
     -printtoconsole
   
   # verify
   ./src/zcash-cli getzebracompatinfo

Artifacts are fetched and hash-verified externally, then passed in as build context. Feel free to follow build from source instructions, if desired too.

1. Install Docker Prerequisites

   Install Docker Buildx and verify it before using the Docker setup mode.

   apt-get update && apt-get install -y docker-buildx && docker buildx version

2. Set Docker Variables

   Set the image tag, choose a hash-pinned zcashd artifact for your platform, and define the local build context path.

   export ZEBRA_DOCKER_IMAGE="zebra:zcashd-compat"
   
   # Pick the matching artifact for your host architecture.
   # x86_64 example:
   export ZCASHD_COMPAT_URL="https://github.com/valargroup/zcashd/releases/download/v6.2.1-alpha/zcashd-zebra-compat-v6.2.1-alpha-linux-x86_64.tar.gz"
   export ZCASHD_COMPAT_SHA256="09e640b55c9af91dee5742e5e9bb6712f92d7073f0fe899ca58d43f62eb9d13c"
   
   # Local Docker build context that will contain ./bin/zcashd.
   export ZCASHD_COMPAT_CONTEXT="${PWD}/target/zcashd-compat/context"
   
   # State directories for Zebra and zcashd.
   export ZEBRA_STATE_CACHE_DIR="/mnt/data/zebra-state"
   export ZCASHD_DATADIR="/mnt/data/.zcashd"

3. Prepare zcashd Build Context

   Download the artifact, verify its SHA256, extract it into a local Docker build context, and confirm the expected binary exists.

   mkdir -p "${ZCASHD_COMPAT_CONTEXT}"
   curl -fsSL "${ZCASHD_COMPAT_URL}" -o /tmp/zcashd-compat.tar.gz
   echo "${ZCASHD_COMPAT_SHA256}  /tmp/zcashd-compat.tar.gz" | sha256sum -c -
   tar -xzf /tmp/zcashd-compat.tar.gz -C "${ZCASHD_COMPAT_CONTEXT}"
   
   # Guardrail: this fails early if ./bin/zcashd is missing or not executable.
   test -x "${ZCASHD_COMPAT_CONTEXT}/bin/zcashd"

4. Build Compat Runtime Image

   Build the runtime-zcashd-compat target and inject the prepared zcashd binary via --build-context.

   docker build \
     -f ./docker/Dockerfile \
     --target runtime-zcashd-compat \
     --build-context "zcashd_compat=${ZCASHD_COMPAT_CONTEXT}" \
     --tag "${ZEBRA_DOCKER_IMAGE}" \
     .

5. Prepare Data Directory Permissions

   Ensure Zebra and zcashd data folders are accessible inside the container.

   # 10001 is the default Dockerfile container user
   # Ensure that zebra and zcashd data folders are accessible inside the container
   mkdir -p "${ZEBRA_STATE_CACHE_DIR}" "${ZCASHD_DATADIR}"
   chown -R 10001:10001 "${ZEBRA_STATE_CACHE_DIR}" "${ZCASHD_DATADIR}"

6. Run Docker Image

   Start Zebra in zcashd compatibility mode with persistent Zebra and zcashd state mounted from the host.

   docker run --rm -it \
     -e ZCASHD_COMPAT_ENABLED=true \
     -e ZEBRA_NETWORK__LISTEN_ADDR="[::]:18233" \
     -e ZEBRA_STATE__CACHE_DIR="/home/zebra/.cache/zebra" \
     -e ZEBRA_ZCASHD_COMPAT__ZCASHD_DATADIR="/home/zebra/.cache/zcashd" \
     -e ZEBRA_ZCASHD_COMPAT__ZCASHD_EXTRA_ARGS='["-rpcbind=0.0.0.0","-rpcallowip=0.0.0.0/0"]' \
     --mount type=bind,src="${ZEBRA_STATE_CACHE_DIR}",dst="/home/zebra/.cache/zebra" \
     --mount type=bind,src="${ZCASHD_DATADIR}",dst="/home/zebra/.cache/zcashd" \
     -p 18233:18233 \
     -p 127.0.0.1:8232:8232 \
     "${ZEBRA_DOCKER_IMAGE}" \
     zebrad start --zcashd-compat