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 المفاتيح وتوفّر wallet 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 | مفهرس مستقل. gRPC متوافق مع lightwalletd للعملاء الخفيفين الخارجيين، بالإضافة إلى وكيل JSON-RPC للمستكشفات والصنابير | لا — --profile indexer |
يثبّت Z3 إصدارات الصور في docker-compose.yml. تجاوزها باستخدام Z3_ZEBRA_IMAGE أو Z3_ZAINO_IMAGE أو Z3_ZALLET_IMAGE إذا احتجت إلى وسم مختلف.
| zcashd | Z3 | |
|---|---|---|
| اللغة | C++ (تفرع من Bitcoin) | خدمات Rust، منظّمة باستخدام Docker Compose |
| نموذج العملية | ملف ثنائي واحد: عقدة + محفظة | حاويات منفصلة للعقدة والمحفظة |
| التوافق | متوقّف (انتهى عمره التشغيلي في 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 GB لـmainnet) | اختياري — قابلة لإعادة المزامنة |
z3-<network>-zallet | قاعدة بيانات المحفظة المشفرة وهوية age التي تفتحها | نعم — هذه وحدة التخزين الوحيدة التي يجب نسخها احتياطيًا |
z3-<network>-zaino | حالة المفهرس (فقط مع ملف تعريف المفهرس) | اختياري — قابل لإعادة البناء |
z3-<network>-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 في ملف تجاوز إذا لم يكن الجهاز مخصصًا للعقدة.قائمة التحقق المهيأة للإنتاج والأسئلة الشائعة: docs/faq.md، docs/docker-architecture.md.
مناسب جيدًا
zcashd كعقدة إضافةً إلى محفظةعادةً الأداة الخاطئة
| الشبكات على مضيف واحد |
| تعارضات منافذ مرهقة |
دعم أساسي: z3-mainnet، z3-testnet، z3-regtest |