Edit this page on GitHub (opens in a new tab)
Der Z3 Stack ist die paketierte Knotenplattform von Zcash Foundation: Zebra (Full Node) + Zallet (Full-Node-Wallet), mit einem optionalen Zaino-Indexer. Er ist als Ersatz für einen eigenständigen zcashd-Prozess vorgesehen, der Konsens und eine Wallet in einer Binärdatei bündelte und am 18. Juli 2026 das Ende seines Lebenszyklus erreichte.
Die Referenzimplementierung ist das Docker-Compose-Projekt unter github.com/ZcashFoundation/z3.
zcashd gemeinsam: Zebra validiert die Chain, Zallet verwaltet Schlüssel und stellt Wallet-RPC bereit, und Zaino (optional) spricht das lightwalletd-gRPC-Protokoll.zcashd bündelte Knoten + Wallet. Z3 trennt diese Rollen. Börsen, Mining-Pools und andere Full-Node-Wallet-Betreiber migrieren zu dieser Kombination statt zu Zebra allein.Während des größten Teils der Lebenszeit von Zcash war zcashd sowohl der Referenz-Full-Node als auch die einzige produktive Full-Node-Wallet. Gegen dieses Design integrierten Börsen, Pools und Verwahrer.
zcashd wurde eingestellt. Der Konsens wechselte zu (und inzwischen auch zu ). Die integrierte Wallet wechselte zu Zallet. Die Bereitstellung für Light Wallets wechselt von zu .
Diese drei Komponenten sind separate Repositories, folgen separaten Release-Zyklen und haben separate Konfigurationen. Z3 ist der Klebstoff: angeheftete Images, Health Checks, die die Wallet erst starten lassen, wenn der Knoten synchronisiert ist, netzwerkspezifische Ports und Volumes sowie ein dokumentierter Pfad für Betreiber.
Der Name ist informeller Kurzgebrauch im Ökosystem — Zebra, Zaino, Zallet — obwohl die Standard-Compose-Datei nur Zebra und Zallet startet. Zaino ist ein Compose-Profil, kein erforderlicher dritter Prozess.
┌──────────────────────── Z3 (per network) ────────────────────────┐
│ │
peers ◄──P2P──► Zebra (zebrad) ──JSON-RPC──► Zallet │
│ full node │ embeds Zaino libraries │
│ │ wallet RPC for operators │
│ └─────────────────────────────────┤
│ │
│ Zaino (optional, --profile indexer) │
│ lightwalletd-compatible gRPC + JSON-RPC proxy │
│ │ │
└────────────┼─────────────────────────────────────────────────────┘
▼
light wallets / explorers
| Komponente | Rolle in Z3 | Erforderlich? |
|---|---|---|
| Zebra | Synchronisiert und validiert die Chain, Gossip, JSON-RPC, Health-Endpunkt | Ja |
| Zallet | Full-Node-Wallet. Integriert Bibliotheken von Zaino. Verbindet sich direkt mit Zebra JSON-RPC. Ruft den eigenständigen Zaino-Container nicht auf | Ja |
| Zaino | Eigenständiger Indexer. Mit lightwalletd kompatibles gRPC für externe Light Clients sowie ein JSON-RPC-Proxy für Explorer und Faucets | Nein — --profile indexer |
Z3 heftet Image-Versionen in docker-compose.yml an. Überschreibe sie mit Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE oder Z3_ZALLET_IMAGE, wenn du einen anderen Tag benötigst.
| zcashd | Z3 | |
|---|---|---|
| Sprache | C++ (Bitcoin-Fork) | Rust-Dienste, orchestriert mit Docker Compose |
| Prozessmodell | Eine Binärdatei: Knoten + Wallet | Getrennte Knoten- und Wallet-Container |
| Konsens | Eingestellt (EOS 18. Juli 2026) | Zebra (oder ein anderer kompatibler Knoten) |
| Wallet | Integriertes wallet.dat | Zallet, mit age verschlüsseltes Datadir |
| Light Clients | Üblicherweise ein separates lightwalletd | Optionales Zaino-Profil |
| Konfiguration | zcash.conf | Netzwerkspezifische Dateien unter config/<network>/ plus Compose-Umgebungsdateien |
Wenn du noch eine zcashd-Wallet hast, nutze den von ZecHub und den Befehl migrate-zcashd-wallet von Zallet, statt wallet.dat in das Z3-Volume zu kopieren.
Z3 besteht aus drei unabhängigen Compose-Projekten. Sie teilen weder Ports noch Volumes.
| Netzwerk | Projektname | Verwende es für | Erste Synchronisierung | Echte Gelder |
|---|---|---|---|---|
| Mainnet | z3-mainnet | Produktion | 24–72 Stunden | Ja |
| Testnet | z3-testnet | Staging im öffentlichen Testnetz | 2–12 Stunden | Nein (Test-ZEC) |
| Regtest | z3-regtest | Lokales Üben: sofortige Blöcke, keine Peers | Sekunden | Nein |
Neue Betreiber sollten mit Regtest beginnen, RPC- und Wallet-Abläufe bestätigen und dann zu Testnet oder Mainnet wechseln.
Alle drei Netzwerke sollen auf einem Rechner parallel bestehen. Die folgenden Werte sind die veröffentlichten Standardwerte; jeder einzelne kann über die entsprechende Umgebungsvariable Z3_* überschrieben werden. Die kanonische Matrix ist z3-contract.yaml.
| Dienst | Mainnet | Testnet | Regtest |
|---|---|---|---|
| Zebra JSON-RPC | 8232 | 18232 | 29232 |
| Zebra P2P | 8233 | 18233 | (nicht veröffentlicht) |
Zebra Health (/ready) | 8080 | 18080 | 28080 |
| Zaino gRPC (Indexer-Profil) | 8137 | 18137 | 28137 |
| Zaino JSON-RPC (Indexer-Profil) | 8237 | 18237 | 28237 |
| Zallet RPC | 28232 | 40232 | 50232 |
Innerhalb des Compose-Netzwerks werden Dienste über ihren Namen aufgelöst (zebra, zaino, zallet).
| Volume | Inhalt | Sichern? |
|---|---|---|
z3-<network>-chain | Chain-Status von Zebra (~300 GB Mainnet) | Optional — erneut synchronisierbar |
z3-<network>-zallet | Verschlüsselte Wallet-Datenbank und die age-Identität, die sie entsperrt | Ja — dies ist das einzige Volume, das gesichert werden muss |
z3-<network>-zaino | Indexer-Status (nur mit dem Indexer-Profil) | Optional — neu aufbaubar |
z3-<network>-cookie | RPC-Cookie von Zebra | Nein — wird neu erzeugt |
Um den Chain-Status vor dem ersten Start auf eine andere Festplatte zu legen:
export Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state
./scripts/fix-permissions.sh zebra /mnt/ssd/zebra-state
docker compose --env-file .env.<network> --profile "*" down stoppt den Stack und behält die Volumes. Das Hinzufügen von -v löscht sie und erzwingt eine vollständige erneute Synchronisierung. Füge --profile "*" ein, damit profilgebundene Dienste (Indexer, Monitoring) tatsächlich heruntergefahren werden.
Voraussetzungen: Docker Engine, Docker Compose v2.24.4+, Git. openssl wird nur für Regtest benötigt.
git clone https://github.com/ZcashFoundation/z3 && cd z3
./scripts/regtest-init.sh
docker compose --env-file .env.regtest up -d
Siehe docs/regtest.md für Testbefehle.
Zebra muss die Synchronisierung abschließen, bevor Zallet sinnvoll nutzbar ist. Ein früher Start von Zallet führt zu einer Neustartschleife, bis /ready wahr ist.
git clone https://github.com/ZcashFoundation/z3 && cd z3
# 1. One-time setup: local config + Zallet wallet identity
./scripts/setup-network.sh mainnet
# 2. Start Zebra and wait until it is synced
docker compose --env-file .env.mainnet up -d zebra
./scripts/check-zebra-readiness.sh
# 3. Start Zallet (and anything else in the default profile)
docker compose --env-file .env.mainnet up -d
Für Testnet gilt derselbe Ablauf mit .env.testnet und ./scripts/check-zebra-readiness.sh 18080.
Änderungen unter config/<network>/ bleiben lokal und überdauern git pull.
# Lightwalletd-compatible gRPC + JSON-RPC proxy
docker compose --env-file .env.mainnet --profile indexer up -d
# Prometheus, Grafana, Jaeger, Alertmanager
docker compose --env-file .env.mainnet --profile monitoring up -d
Die Standard-Grafana-Ports sind 3000 (Mainnet), 13000 (Testnet), 23000 (Regtest).
:latest. Aktualisiere eine Anheftung in einer geprüften Änderung oder setze Z3_<SERVICE>_IMAGE.ZEBRA_NETWORK__EXTERNAL_ADDR auf die Adresse, die Peers anwählen sollen. Regtest hat keine Peers.linux/amd64 verfügbar. Auf Apple Silicon läuft es unter Emulation, sofern du es nicht aus dem Quellcode baust. Zebra und Zallet sind Multi-Arch.deploy.resources.limits in einer Override-Datei hinzu, wenn der Rechner nicht dem Knoten gewidmet ist.Checkliste und FAQ für produktionsähnliche Umgebungen: docs/faq.md, docs/docker-architecture.md.
Gut geeignet
zcashd als Knoten-plus-Wallet nutztenIn der Regel das falsche Werkzeug
| Netzwerke auf einem Host | Schwierige Portkonflikte | Erstklassig: z3-mainnet, z3-testnet, z3-regtest |