Edit this page on GitHub (opens in a new tab)
Lo Stack Z3 è la piattaforma di nodi preconfezionata di Zcash Foundation: Zebra (full node (nodo completo)) + Zallet (portafoglio per full node), con un indicizzatore Zaino opzionale. È il sostituto previsto di un processo zcashd indipendente, che riuniva consenso e portafoglio in un unico binario e ha raggiunto la fine del ciclo di vita il 18 luglio 2026.
L'implementazione di riferimento è il progetto Docker Compose disponibile su github.com/ZcashFoundation/z3.
zcashd: Zebra convalida la chain, Zallet conserva le chiavi e offre RPC del portafoglio, e Zaino (opzionale) parla il protocollo gRPC lightwalletd.zcashd riuniva nodo + portafoglio. Z3 separa questi ruoli. Gli exchange, le pool di mining e altri operatori di portafogli per full node migrano a questa combinazione anziché a Zebra da solo.Per gran parte della vita di Zcash, zcashd è stato sia il full node di riferimento sia l'unico portafoglio per full node di produzione. Questo design è quello con cui si sono integrati gli exchange, le pool e i custodi.
zcashd è ritirato. Il consenso è passato a (e ora anche a ). Il portafoglio integrato è passato a Zallet. Il servizio per portafogli light sta passando da a .
Questi tre componenti sono repository separati, con cicli di rilascio e configurazioni separati. Z3 è il collante: immagini fissate, controlli di integrità che tengono il portafoglio inattivo finché il nodo non è sincronizzato, porte e volumi per rete e un percorso operativo documentato.
Il nome è un'abbreviazione informale nell'ecosistema — Zebra, Zaino, Zallet — anche se il file Compose predefinito avvia solo Zebra e Zallet. Zaino è un profilo Compose, non un terzo processo obbligatorio.
┌──────────────────────── 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
| Componente | Ruolo in Z3 | Obbligatorio? |
|---|---|---|
| Zebra | Sincronizza e convalida la chain, gossip, JSON-RPC, endpoint di integrità | Sì |
| Zallet | Portafoglio per full node. Incorpora librerie Zaino. Si connette direttamente al JSON-RPC di Zebra. Non chiama il container Zaino indipendente | Sì |
| Zaino | Indicizzatore indipendente. gRPC compatibile con lightwalletd per client leggeri esterni, più un proxy JSON-RPC per explorer e faucet | No — --profile indexer |
Z3 fissa le versioni delle immagini in docker-compose.yml. Sostituiscile con Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE o Z3_ZALLET_IMAGE se hai bisogno di un tag diverso.
| zcashd | Z3 | |
|---|---|---|
| Linguaggio | C++ (fork di Bitcoin) | Servizi Rust, orchestrati con Docker Compose |
| Modello di processo | Un binario: nodo + portafoglio | Container separati per nodo e portafoglio |
| Consenso | Ritirato (EOS 18 luglio 2026) | Zebra (o un altro nodo compatibile) |
| Wallet | wallet.dat integrato | Zallet, directory dei dati crittografata con age |
| Client leggeri | Solitamente un lightwalletd separato | Profilo Zaino opzionale |
| Configurazione | zcash.conf | File per rete in config/<network>/ più file env Compose |
Se possiedi ancora un portafoglio zcashd, usa la guida alla migrazione ZecHub e il comando migrate-zcashd-wallet di Zallet anziché copiare wallet.dat nel volume Z3.
Z3 consiste di tre progetti Compose indipendenti. Non condividono porte né volumi.
| Rete | Nome del progetto | Utilizzo | Prima sincronizzazione | Fondi reali |
|---|---|---|---|---|
| mainnet | z3-mainnet | Produzione | 24–72 ore | Sì |
| testnet | z3-testnet | Staging sulla rete di test pubblica | 2–12 ore | No (ZEC di test) |
| regtest | z3-regtest | Esercitazione locale: blocchi istantanei, nessun peer | Secondi | No |
I nuovi operatori dovrebbero iniziare su regtest, verificare i flussi RPC e del portafoglio, quindi passare a testnet o mainnet.
Tutte e tre le reti sono progettate per coesistere sulla stessa macchina. I valori riportati sotto sono le impostazioni predefinite pubblicate; ciascuno può essere sostituito tramite la variabile env Z3_* corrispondente. La matrice canonica è z3-contract.yaml.
| Servizio | Mainnet | Testnet | Regtest |
|---|---|---|---|
| JSON-RPC di Zebra | 8232 | 18232 | 29232 |
| P2P di Zebra | 8233 | 18233 | (non pubblicato) |
Integrità di Zebra (/ready) | 8080 | 18080 | 28080 |
| gRPC di Zaino (profilo indicizzatore) | 8137 | 18137 | 28137 |
| JSON-RPC di Zaino (profilo indicizzatore) | 8237 | 18237 | 28237 |
| RPC di Zallet | 28232 | 40232 | 50232 |
All'interno della rete Compose, i servizi vengono risolti per nome (zebra, zaino, zallet).
| Volume | Contenuto | Backup? |
|---|---|---|
z3-<network>-chain | Stato della chain di Zebra (~300 GB mainnet) | Facoltativo — risincronizzabile |
z3-<network>-zallet | Database del portafoglio crittografato e identità age che lo sblocca | Sì — questo è l'unico volume di cui è necessario eseguire il backup |
z3-<network>-zaino | Stato dell'indicizzatore (solo con il profilo indicizzatore) | Facoltativo — ricostruibile |
z3-<network>-cookie | Cookie RPC di Zebra | No — rigenerato |
Per collocare lo stato della chain su un altro disco prima del primo avvio:
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 arresta lo stack e conserva i volumi. L'aggiunta di -v li elimina e forza una risincronizzazione completa. Includi --profile "*" affinché i servizi gestiti dal profilo (indicizzatore, monitoraggio) vengano effettivamente arrestati.
Prerequisiti: Docker Engine, Docker Compose v2.24.4+, Git. openssl è necessario solo per regtest.
git clone https://github.com/ZcashFoundation/z3 && cd z3
./scripts/regtest-init.sh
docker compose --env-file .env.regtest up -d
Consulta docs/regtest.md per i comandi di test.
Zebra deve terminare la sincronizzazione prima che Zallet sia utile. Avviare Zallet troppo presto lo farà entrare in un ciclo di riavvio finché /ready non sarà vero.
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
Testnet segue lo stesso flusso con .env.testnet e ./scripts/check-zebra-readiness.sh 18080.
Le modifiche in config/<network>/ restano locali e sopravvivono a 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
Le porte Grafana predefinite sono 3000 (mainnet), 13000 (testnet), 23000 (regtest).
:latest. Aggiorna un pin in una modifica revisionata oppure imposta Z3_<SERVICE>_IMAGE.ZEBRA_NETWORK__EXTERNAL_ADDR all'indirizzo che i peer devono contattare. Regtest non ha peer.linux/amd64. Su Apple Silicon viene eseguita in emulazione, a meno che tu non compili dai sorgenti. Zebra e Zallet sono multi-arch.deploy.resources.limits in un file di override se la macchina non è dedicata al nodo.Checklist orientata alla produzione e FAQ: docs/faq.md, docs/docker-architecture.md.
Adatto
zcashd come nodo più portafoglioSolitamente lo strumento sbagliato
| Reti su un unico host |
| Conflitti di porte problematici |
Supporto nativo: z3-mainnet, z3-testnet, z3-regtest |