Edit this page on GitHub (opens in a new tab)
Z3 Stack — это пакетная платформа узлов Zcash Foundation: Zebra (полный узел) + Zallet (кошелёк полного узла), с дополнительным индексатором Zaino. Она предназначена для замены отдельного процесса zcashd, который объединял консенсус и кошелёк в одном бинарном файле и достиг конца жизненного цикла 18 июля 2026 года.
Эталонная реализация — проект Docker Compose по адресу github.com/ZcashFoundation/z3.
zcashd: Zebra проверяет цепочку, Zallet хранит ключи и предоставляет RPC кошелька, а Zaino (опционально) использует протокол gRPC lightwalletd.zcashd объединял узел и кошелёк. Z3 разделяет эти роли. Биржи, майнинговые пулы и другие операторы кошельков полного узла переходят на эту комбинацию, а не только на Zebra.На протяжении большей части существования Zcash, zcashd был одновременно эталонным полным узлом и единственным промышленным кошельком полного узла. Именно с этой архитектурой интегрировались биржи, пулы и кастодианы.
zcashd выведен из эксплуатации. Консенсус перешёл в (а теперь также в ). Встроенный кошелёк переместился в Zallet. Обслуживание лёгких кошельков переносится с на .
Эти три компонента находятся в отдельных репозиториях, имеют отдельные циклы выпуска и отдельные конфигурации. Z3 — это связующее звено: закреплённые образы, проверки работоспособности, которые не дают кошельку запуститься до синхронизации узла, порты и тома для каждой сети, а также документированный путь для оператора.
Название является неформальным сокращением в экосистеме — Zebra, Zaino, Zallet — хотя файл Compose по умолчанию запускает только Zebra и Zallet. Zaino — это профиль Compose, а не обязательный третий процесс.
┌──────────────────────── 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
| Компонент | Роль в Z3 | Обязателен? |
|---|---|---|
| Zebra | Синхронизирует и проверяет цепочку, gossip, JSON-RPC, конечная точка проверки работоспособности | Да |
| Zallet | Кошелёк полного узла. Встраивает библиотеки Zaino. Подключается напрямую к JSON-RPC Zebra. Не вызывает отдельный контейнер Zaino | Да |
| Zaino | Отдельный индексатор. Совместимый с lightwalletd gRPC для внешних лёгких клиентов, а также прокси JSON-RPC для обозревателей и кранов | Нет — --profile indexer |
Z3 закрепляет версии образов в docker-compose.yml. При необходимости другого тега переопределите их с помощью Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE или Z3_ZALLET_IMAGE.
| zcashd | Z3 | |
|---|---|---|
| Язык | C++ (форк Bitcoin) | Сервисы Rust, оркестрируемые Docker Compose |
| Модель процессов | Один бинарный файл: узел + кошелёк | Отдельные контейнеры узла и кошелька |
| Консенсус | Выведен из эксплуатации (EOL 18 июля 2026 года) | Zebra (или другой совместимый узел) |
| Кошелёк | Встроенный wallet.dat | Zallet, каталог данных, зашифрованный age |
| Лёгкие клиенты | Обычно отдельный lightwalletd | Опциональный профиль Zaino |
| Конфигурация | zcash.conf | Файлы для каждой сети в config/<network>/ плюс файлы окружения Compose |
Если у вас всё ещё есть кошелёк zcashd, используйте руководство по миграции ZecHub и команду migrate-zcashd-wallet от Zallet вместо копирования wallet.dat в том Z3.
Z3 состоит из трёх независимых проектов Compose. Они не используют общие порты или тома.
| Сеть | Имя проекта | Использование | Первая синхронизация | Реальные средства |
|---|---|---|---|---|
| mainnet | z3-mainnet | Рабочая среда | 24–72 часа | Да |
| testnet | z3-testnet | Тестирование в публичной тестовой сети | 2–12 часов | Нет (тестовые ZEC) |
| regtest | z3-regtest | Локальная практика: мгновенные блоки, без пиров | Секунды | Нет |
Новым операторам следует начать с regtest, проверить потоки RPC и кошелька, затем перейти на testnet или mainnet.
Все три сети рассчитаны на одновременную работу на одной машине. Приведённые ниже значения являются опубликованными значениями по умолчанию; каждое можно переопределить через соответствующую переменную окружения Z3_*. Каноническая матрица: z3-contract.yaml.
| Сервис | Mainnet | Testnet | Regtest |
|---|---|---|---|
| JSON-RPC Zebra | 8232 | 18232 | 29232 |
| P2P Zebra | 8233 | 18233 | (не опубликован) |
Проверка работоспособности Zebra (/ready) | 8080 | 18080 | 28080 |
| gRPC Zaino (профиль индексатора) | 8137 | 18137 | 28137 |
| JSON-RPC Zaino (профиль индексатора) | 8237 | 18237 | 28237 |
| RPC Zallet | 28232 | 40232 | 50232 |
Внутри сети Compose сервисы разрешаются по именам (zebra, zaino, zallet).
| Том | Что содержит | Создавать резервную копию? |
|---|---|---|
z3-<network>-chain | Состояние цепочки Zebra (~300 ГБ в mainnet) | Опционально — можно синхронизировать заново |
z3-<network>-zallet | Зашифрованная база данных кошелька и идентификатор age, который её разблокирует | Да — это единственный том, для которого необходимо создавать резервную копию |
z3-<network>-zaino | Состояние индексатора (только с профилем индексатора) | Опционально — можно перестроить |
z3-<network>-cookie | Cookie RPC Zebra | Нет — создаётся заново |
Чтобы разместить состояние цепочки на другом диске перед первым запуском:
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 останавливает стек и сохраняет тома. Добавление -v удаляет их и принудительно запускает полную повторную синхронизацию. Добавьте --profile "*", чтобы сервисы, ограниченные профилем (индексатор, мониторинг), действительно были остановлены.
Требования: Docker Engine, Docker Compose v2.24.4+, Git. openssl требуется только для regtest.
git clone https://github.com/ZcashFoundation/z3 && cd z3
./scripts/regtest-init.sh
docker compose --env-file .env.regtest up -d
Команды для тестирования приведены в docs/regtest.md.
Zebra должен завершить синхронизацию, прежде чем Zallet станет полезен. Ранний запуск Zallet заставляет его перезапускаться в цикле, пока условие /ready не станет истинным.
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 используется тот же процесс с .env.testnet и ./scripts/check-zebra-readiness.sh 18080.
Изменения в config/<network>/ остаются локальными и сохраняются после 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
Стандартные порты Grafana: 3000 (mainnet), 13000 (testnet), 23000 (regtest).
:latest. Обновите закреплённую версию в проверенном изменении либо задайте Z3_<SERVICE>_IMAGE.ZEBRA_NETWORK__EXTERNAL_ADDR как адрес, который должны набирать пиры. В regtest пиров нет.linux/amd64. На Apple Silicon он работает через эмуляцию, если только вы не соберёте его из исходного кода. Zebra и Zallet поддерживают несколько архитектур.deploy.resources.limits в файл переопределения, если машина не выделена исключительно для узла.Контрольный список для рабочей среды и FAQ: docs/faq.md, docs/docker-architecture.md.
Подходит
zcashd как узел с кошелькомОбычно это неподходящий инструмент
| Сети на одном хосте |
| Неудобные конфликты портов |
Поддерживается напрямую: z3-mainnet, z3-testnet, z3-regtest |