Edit this page on GitHub (opens in a new tab)
O Z3 Stack é a plataforma de nó empacotada da Zcash Foundation: Zebra (nó integral) + Zallet (carteira de nó integral), com um indexador Zaino opcional. Ele é o substituto previsto para um processo zcashd independente, que reunia consenso e uma carteira em um único binário e chegou ao fim da vida útil em 18 de julho de 2026.
A implementação de referência é o projeto Docker Compose em github.com/ZcashFoundation/z3.
zcashd: o Zebra valida a chain, a Zallet guarda as chaves e fornece o RPC da carteira, e o Zaino (opcional) fala o protocolo gRPC do lightwalletd.zcashd reunia nó + carteira. O Z3 separa essas funções. Corretoras, pools de mineração e outros operadores de carteiras de nó integral migram para essa combinação, e não apenas para o Zebra.Durante a maior parte da vida do Zcash, o zcashd foi ao mesmo tempo o nó integral de referência e a única carteira de nó integral em produção. Foi com esse design que corretoras, pools e custodiantes fizeram suas integrações.
O zcashd foi aposentado. O consenso passou para o (e agora também para o ). A carteira embutida passou para a Zallet. O serviço para light wallets está passando do para o .
Essas três peças são repositórios separados, ciclos de lançamento separados e configurações separadas. O Z3 é o que as une: imagens fixadas, verificações de saúde que mantêm a carteira desligada até o nó estar sincronizado, portas e volumes por rede, e um caminho documentado para operadores.
O nome é uma abreviação informal do ecossistema — Zebra, Zaino, Zallet —, embora o arquivo Compose padrão inicie apenas o Zebra e a Zallet. O Zaino é um perfil do Compose, não um terceiro processo obrigatório.
┌──────────────────────── 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 | Função no Z3 | Obrigatório? |
|---|---|---|
| Zebra | Sincroniza e valida a chain, gossip, JSON-RPC, endpoint de saúde | Sim |
| Zallet | Carteira de nó integral. Incorpora bibliotecas do Zaino. Conecta-se diretamente ao JSON-RPC do Zebra. Não chama o contêiner Zaino independente | Sim |
| Zaino | Indexador independente. gRPC compatível com o lightwalletd para light clients externos, além de um proxy JSON-RPC para exploradores e faucets | Não — --profile indexer |
O Z3 fixa as versões das imagens em docker-compose.yml. Substitua com Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE ou Z3_ZALLET_IMAGE se precisar de outra tag.
| zcashd | Z3 | |
|---|---|---|
| Linguagem | C++ (fork do Bitcoin) | Serviços em Rust, orquestrados com Docker Compose |
| Modelo de processo | Um binário: nó + carteira | Contêineres separados para nó e carteira |
| Consenso | Aposentado (EOS em 18 de julho de 2026) | Zebra (ou outro nó compatível) |
| Carteira | wallet.dat embutida | Zallet, datadir criptografado com age |
| Light clients | Normalmente um lightwalletd separado | Perfil Zaino opcional |
| Configuração | zcash.conf | Arquivos por rede em config/<network>/ mais arquivos env do Compose |
Se você ainda tem uma carteira zcashd, use o da ZecHub e o comando migrate-zcashd-wallet da Zallet, em vez de copiar o wallet.dat para o volume do Z3.
O Z3 é composto por três projetos Compose independentes. Eles não compartilham portas nem volumes.
| Rede | Nome do projeto | Use para | Primeira sincronização | Fundos reais |
|---|---|---|---|---|
| mainnet | z3-mainnet | Produção | 24–72 horas | Sim |
| testnet | z3-testnet | Homologação na rede de testes pública | 2–12 horas | Não (ZEC de teste) |
| regtest | z3-regtest | Prática local: blocos instantâneos, sem peers | Segundos | Não |
Novos operadores devem começar pela regtest, confirmar os fluxos de RPC e da carteira e depois passar para a testnet ou a mainnet.
As três redes foram pensadas para coexistir em uma única máquina. Os valores abaixo são os padrões publicados; cada um pode ser substituído pela variável de ambiente Z3_* correspondente. A matriz canônica é z3-contract.yaml.
| Serviço | Mainnet | Testnet | Regtest |
|---|---|---|---|
| JSON-RPC do Zebra | 8232 | 18232 | 29232 |
| P2P do Zebra | 8233 | 18233 | (não publicada) |
Saúde do Zebra (/ready) | 8080 | 18080 | 28080 |
| gRPC do Zaino (perfil indexer) | 8137 | 18137 | 28137 |
| JSON-RPC do Zaino (perfil indexer) | 8237 | 18237 | 28237 |
| RPC da Zallet | 28232 | 40232 | 50232 |
Dentro da rede do Compose, os serviços são resolvidos pelo nome (zebra, zaino, zallet).
| Volume | O que contém | Fazer backup? |
|---|---|---|
z3-<network>-chain | Estado da chain do Zebra (~300 GB na mainnet) | Opcional — pode ser ressincronizado |
z3-<network>-zallet | Banco de dados criptografado da carteira e a identidade age que o desbloqueia | Sim — este é o único volume que precisa de backup |
z3-<network>-zaino | Estado do indexador (apenas com o perfil indexer) | Opcional — pode ser reconstruído |
z3-<network>-cookie | Cookie RPC do Zebra | Não — é regenerado |
Para colocar o estado da chain em outro disco antes da primeira inicialização:
export Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state
./scripts/fix-permissions.sh zebra /mnt/ssd/zebra-state
O docker compose --env-file .env.<network> --profile "*" down para o stack e mantém os volumes. Adicionar -v os exclui e força uma ressincronização completa. Inclua --profile "*" para que os serviços condicionados a perfis (indexador, monitoramento) sejam realmente desmontados.
Pré-requisitos: Docker Engine, Docker Compose v2.24.4+, Git. O openssl é necessário apenas para a regtest.
git clone https://github.com/ZcashFoundation/z3 && cd z3
./scripts/regtest-init.sh
docker compose --env-file .env.regtest up -d
Consulte docs/regtest.md para ver os comandos de teste.
O Zebra precisa terminar a sincronização antes que a Zallet seja útil. Iniciar a Zallet antes da hora faz com que ela entre em loop de reinicialização até que /ready seja verdadeiro.
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
A testnet segue o mesmo fluxo com .env.testnet e ./scripts/check-zebra-readiness.sh 18080.
As edições em config/<network>/ permanecem locais e sobrevivem a um 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
As portas padrão do Grafana são 3000 (mainnet), 13000 (testnet) e 23000 (regtest).
:latest. Atualize uma versão fixada em uma alteração revisada ou defina Z3_<SERVICE>_IMAGE.ZEBRA_NETWORK__EXTERNAL_ADDR com o endereço que os peers devem discar. A regtest não tem peers.linux/amd64. No Apple Silicon, ela roda sob emulação, a menos que você compile a partir do código-fonte. O Zebra e a Zallet são multiarquitetura.deploy.resources.limits em um arquivo de override se a máquina não for dedicada ao nó.Checklist e FAQ orientados para produção: docs/faq.md, docs/docker-architecture.md.
Indicado para
zcashd como nó mais carteiraNormalmente a ferramenta errada
| Redes em um único host |
| Conflitos de porta trabalhosos |
Suporte nativo: z3-mainnet, z3-testnet, z3-regtest |