Edit this page on GitHub (opens in a new tab)
El Stack Z3 es la plataforma de nodos empaquetada de Zcash Foundation: Zebra (nodo completo [full node]) + Zallet (billetera de nodo completo [full-node wallet]), con un indexador [indexer] opcional Zaino. Es el reemplazo previsto para un proceso zcashd independiente, que agrupaba el consenso y una billetera en un solo binario y llegó al final de su vida útil el 18 de julio de 2026.
La implementación de referencia es el proyecto Compose de Docker en github.com/ZcashFoundation/z3.
zcashd: Zebra valida la red [chain], Zallet guarda las claves y ofrece RPC de billetera, y Zaino (opcional) utiliza el protocolo gRPC de lightwalletd.zcashd agrupaba nodo + billetera. Z3 separa esas funciones. Los exchanges, pools de minado y otros operadores de billeteras de nodos completos migran a esta combinación en lugar de hacerlo únicamente a Zebra.Durante la mayor parte de la vida de Zcash, zcashd era tanto el nodo completo de referencia como la única billetera de nodo completo de producción. Ese diseño es con el que se integraron exchanges, pools y custodios.
zcashd está retirado. El consenso pasó a (y ahora también a ). La billetera integrada pasó a Zallet. El servicio para billeteras ligeras está migrando de a .
Esas tres piezas son repositorios separados, tienen ciclos de lanzamiento separados y configuraciones separadas. Z3 es el pegamento: imágenes fijadas, comprobaciones de estado que mantienen la billetera inactiva hasta que el nodo se sincronice, puertos y volúmenes por red, y una ruta documentada para operadores.
El nombre es una abreviatura informal del ecosistema — Zebra, Zaino, Zallet — aunque el archivo Compose predeterminado solo inicia Zebra y Zallet. Zaino es un perfil de Compose, no un tercer proceso obligatorio.
┌──────────────────────── 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 | Función en Z3 | ¿Obligatorio? |
|---|---|---|
| Zebra | Sincroniza y valida la red, difusión, JSON-RPC, endpoint de estado | Sí |
| Zallet | Billetera de nodo completo. Incorpora las bibliotecas de Zaino. Se conecta directamente al JSON-RPC de Zebra. No llama al contenedor Zaino independiente | Sí |
| Zaino | Indexador independiente. gRPC compatible con lightwalletd para clientes ligeros externos, además de un proxy JSON-RPC para exploradores y faucets | No — --profile indexer |
Z3 fija las versiones de las imágenes en docker-compose.yml. Sobrescriba con Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE o Z3_ZALLET_IMAGE si necesita una etiqueta diferente.
| zcashd | Z3 | |
|---|---|---|
| Lenguaje | C++ (fork de Bitcoin) | Servicios de Rust, orquestados con Compose de Docker |
| Modelo de proceso | Un binario: nodo + billetera | Contenedores de nodo y billetera separados |
| Consenso | Retirado (fin de vida útil el 18 de julio de 2026) | Zebra (u otro nodo compatible) |
| Billetera | wallet.dat integrada | Zallet, directorio de datos cifrado con age |
| Clientes ligeros | Normalmente un lightwalletd separado | Perfil Zaino opcional |
| Configuración | zcash.conf | Archivos por red en config/<network>/ más archivos de entorno de Compose |
Si todavía tiene una billetera zcashd, utilice la guía de migración de ZecHub y el comando migrate-zcashd-wallet de Zallet en lugar de copiar wallet.dat al volumen de Z3.
Z3 son tres proyectos Compose independientes. No comparten puertos ni volúmenes.
| Red | Nombre del proyecto | Úsela para | Primera sincronización | Fondos reales |
|---|---|---|---|---|
| mainnet | z3-mainnet | Producción | 24–72 horas | Sí |
| testnet | z3-testnet | Entorno de pruebas en la red pública de pruebas | 2–12 horas | No (ZEC de prueba) |
| regtest | z3-regtest | Práctica local: bloques instantáneos, sin pares | Segundos | No |
Los nuevos operadores deberían empezar con regtest, confirmar los flujos de RPC y de billetera, y luego pasar a testnet o mainnet.
Las tres redes están diseñadas para coexistir en una sola máquina. Los valores siguientes son los predeterminados publicados; todos pueden sobrescribirse mediante la variable de entorno Z3_* correspondiente. La matriz canónica es z3-contract.yaml.
| Servicio | Mainnet | Testnet | Regtest |
|---|---|---|---|
| JSON-RPC de Zebra | 8232 | 18232 | 29232 |
| P2P de Zebra | 8233 | 18233 | (no publicado) |
Estado de Zebra (/ready) | 8080 | 18080 | 28080 |
| gRPC de Zaino (perfil de indexador) | 8137 | 18137 | 28137 |
| JSON-RPC de Zaino (perfil de indexador) | 8237 | 18237 | 28237 |
| RPC de Zallet | 28232 | 40232 | 50232 |
Dentro de la red Compose, los servicios se resuelven por nombre (zebra, zaino, zallet).
| Volumen | Qué contiene | ¿Hacer copia de seguridad? |
|---|---|---|
z3-<network>-chain | Estado de la red de Zebra (~300 GB en mainnet) | Opcional — se puede resincronizar |
z3-<network>-zallet | Base de datos de la billetera cifrada y la identidad age que la desbloquea | Sí — este es el único volumen del que se debe hacer copia de seguridad |
z3-<network>-zaino | Estado del indexador (solo con el perfil de indexador) | Opcional — se puede reconstruir |
z3-<network>-cookie | Cookie RPC de Zebra | No — se regenera |
Para colocar el estado de la red en otro disco antes del primer inicio:
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 detiene el stack y conserva los volúmenes. Agregar -v los elimina y fuerza una resincronización completa. Incluya --profile "*" para que los servicios restringidos por perfil (indexador, supervisión) se desmonten realmente.
Requisitos previos: Engine de Docker, Compose de Docker v2.24.4+, Git. openssl solo es obligatorio para 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 los comandos de prueba.
Zebra debe terminar de sincronizarse antes de que Zallet sea útil. Iniciar Zallet antes hace que se reinicie en bucle hasta que /ready sea verdadero.
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 sigue el mismo flujo con .env.testnet y ./scripts/check-zebra-readiness.sh 18080.
Las ediciones en config/<network>/ permanecen locales y sobreviven 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
Los puertos predeterminados de Grafana son 3000 (mainnet), 13000 (testnet), 23000 (regtest).
:latest. Actualice una fijación en un cambio revisado o establezca Z3_<SERVICE>_IMAGE.ZEBRA_NETWORK__EXTERNAL_ADDR en la dirección a la que los pares deben conectarse. Regtest no tiene pares.linux/amd64. En Apple Silicon se ejecuta mediante emulación, a menos que compile desde el código fuente. Zebra y Zallet son multiarquitectura.deploy.resources.limits en un archivo de sobrescritura si la máquina no está dedicada al nodo.Lista de comprobación y preguntas frecuentes orientadas a producción: docs/faq.md, docs/docker-architecture.md.
Buena opción
zcashd como nodo más billeteraNormalmente, la herramienta equivocada
| Redes en un host | Conflictos de puertos difíciles | De primera clase: z3-mainnet, z3-testnet, z3-regtest |