البناء من المصدر
يرشدك هذا الدليل خلال بناء الملف الثنائي qorechaind المجتمعي من المصدر العام، ويوضح ما الغرض من هذا الملف الثنائي وما ليس الغرض منه.
يحتوي المستودع العام على واجهات الوحدات مع Keepers بديلة (stub)؛ أما تطبيقات Keeper الحاسمة للإجماع والموقِّع ما بعد الكمي فليست في شجرة المصدر العامة. ولا يمكن للملف الثنائي المبني منها إعادة إنتاج حالة الإجماع للشبكات، ولا يمكنه إنشاء التوقيع الهجين ما بعد الكمي الذي تتطلبه كل معاملة في مسار Cosmos. ومنذ v3.2.3 يرفض البدء أيضًا على qorechain-vladi أو qorechain-diana (يتعرّف عليهما من معرّف السلسلة ووقت التكوين الأولي؛ ولا تتأثر شبكة تطوير محلية تعيد استخدام معرّف سلسلة عام مع تكوين أولي خاص بها). يتجاوز الأمر qorechaind start --community-unenforced-pqc هذا الرفض لأغراض التجارب؛ وعندها لا تتحقق العقدة من أي توقيعات ما بعد كمية وقد تنحرف عن الشبكة دون أي تحذير، لذا لا تستخدمه أبدًا لعقدة تعتمد عليها. لتشغيل عقدة أو مدقّق على الشبكة الرئيسية أو شبكة الاختبار، ثبّت الملف الثنائي الرسمي للإصدار المذكور في البيان الحي (https://download.qore.host/mainnet/latest.json أو .../testnet/latest.json)؛ راجع تشغيل عقدة وتشغيل مدقّق.
المتطلبات الأساسية
| الاعتمادية | الحد الأدنى للإصدار | ملاحظات |
|---|---|---|
| Go | 1.26+ | مطلوب لجميع أنواع البناء |
| CGO | مفعّل (CGO_ENABLED=1) | مطلوب لجسور FFI الخاصة بـ PQC وSVM |
| Make | 3.81+ | أتمتة البناء |
| Git | 2.x | سحب المصدر |
تحقّق من بيئتك:
go version # go1.26.x or later
echo $CGO_ENABLED # must be 1
يجب أن يحمل كل استدعاء لـ go build وgo test وgo run القيمة CGO_ENABLED=1. تربط العقدة مكتبات أصلية (بيئة تشغيل QoreChain Native، وفي بناء الإصدار مكتبتا PQC وSVM) عبر cgo.
المكتبات الأصلية (Native Libraries)
libqorepqc وlibqoresvm
تُبنى مكتبتا ما بعد الكمي (libqorepqc) وSVM (libqoresvm) من مصادر Rust ليست جزءًا من المستودع العام (لا يوجد مجلد rust/ في qorechain-core). ولا يحتاج بناء المجتمع إليهما. تضم أرشيفات الإصدار للشبكات المكتبات المصرَّفة (libqorepqc.so وlibqoresvm.so وlibwasmvm.x86_64.so ومنذ v3.2.8 أيضاً libwasmvmqore_v1.x86_64.so). انسخ مجلد lib/ بأكمله لا ملفات منفردة في مجلد lib/ بجوار qorechaind؛ ضعها في lib/{os}_{arch}/ أو وجّه المحمِّل إليها كما هو موضح أدناه.
تحديد مسار المكتبة
عند استخدام الملف الثنائي الرسمي للإصدار، يجب أن تكون مكتباته المشتركة قابلة للاكتشاف وقت التشغيل. عيّن متغير البيئة المناسب لمنصتك:
macOS:
export DYLD_LIBRARY_PATH=$(pwd)/lib/darwin_arm64:$DYLD_LIBRARY_PATH
Linux:
export LD_LIBRARY_PATH=$(pwd)/lib/linux_amd64:$LD_LIBRARY_PATH
نصيحة: أضِف الأمر export إلى ملف تهيئة الصدفة الخاص بك (~/.bashrc، ~/.zshrc) ليبقى نافذًا عبر الجلسات.
بنية Open-Core
تتبع QoreChain نموذج open-core:
- بناء المجتمع — يحتوي على الواجهات الكاملة للوحدات، وأوامر CLI، وتعريفات protobuf، وأنواع الرسائل لكل وحدة من وحدات QoreChain (x/pqc، x/ai، x/reputation، x/qca، x/svm، x/crossvm، إلخ). تستخدم Keepers الخاصة بالوحدات الخاصة (proprietary) تطبيقات بديلة (stub) تُعيد قيمًا افتراضية آمنة أو استجابات بلا تأثير (no-op). هذا يسمح لأدوات الطرف الثالث والمحافظ والفهارس (indexers) بالتكامل مع جميع واجهات QoreChain البرمجية دون الحاجة إلى الكود الخاص.
- البناء الكامل — يحتوي على تطبيقات Keeper الكاملة (منطق الوحدات الحقيقي الحاسم للإجماع والموقِّع ما بعد الكمي). يُوزَّع على هيئة الملفات الثنائية الرسمية للإصدار المنشورة في download.qore.host؛ ولا يُبنى من شجرة المصدر العامة.
الوسم v3.2.6 في github.com/qorechain/qorechain-core هو أحدث وسم عام للمصدر المفتوح (open-core)؛ وتشغّل الشبكة الرئيسية v3.2.7 منذ 12 نوفمبر 2026 ولا يوجد وسم عام v3.2.7 بعد. وتشغّل شبكة الاختبار v3.2.8 منذ 12 نوفمبر 2026؛ ولا يوجد وسم عام v3.2.8 بعد. يستخدم البناء العام Keepers بديلة (stub) ولا يمكنه إعادة إنتاج حالة الإجماع، لذا يجب على العقدة استخدام حزمة الإصدار المذكورة في البيان (latest.json في download.qore.host)، وليس ملفًا ثنائيًا مبنيًا من هذا الوسم.
ينتج كلا البناءين نفس اسم الملف الثنائي qorechaind ويعرضان نفس أوامر CLI. الفرق يكمن في السلوك وقت التشغيل لمنطق Keeper خلف تلك الواجهات.
بناء المجتمع
CGO_ENABLED=1 go build -o qorechaind ./cmd/qorechaind/
يقوم هذا بتصريف جميع واجهات الوحدات العامة مع Keepers بديلة (stub) للميزات الخاصة. الملف الثنائي الناتج مخصّص لـ:
- التطوير والاختبار المحليين (مثل شبكة تطوير بعقدة واحدة)
- الاستعلام عن شبكة (تعمل أوامر
query ...مقابل أي عقدة) - بناء تكاملات وأدوات الطرف الثالث على واجهات الوحدات
وليس وسيلة للانضمام إلى الشبكة الرئيسية أو شبكة الاختبار كمدقّق أو لإجراء المعاملات هناك: فهو لا يملك موقِّعًا ما بعد كمي (يُرجع tx pqc gen-key وtx pqc cosign خطأً) ولا تعيد Keepers البديلة (stub) الخاصة به إنتاج قواعد الإجماع للشبكات.
البناء الكامل (الملف الثنائي الرسمي للإصدار)
تطبيقات Keeper الكاملة، والموقِّع الكامن وراء tx pqc gen-key وtx pqc cosign، ليست في شجرة المصدر العامة، ولذلك لا يمكن بناؤها منها. الملفات الثنائية المنشورة في download.qore.host هي البناء الكامل؛ استخدمها للشبكة الرئيسية وشبكة الاختبار.
تشغيل الاختبارات
CGO_ENABLED=1 go test ./... -count=1
تعطّل الراية -count=1 التخزين المؤقت للاختبارات، مما يضمن تشغيلاً نظيفًا في كل مرة. يمكن تشغيل اختبارات الحزم الفردية بواسطة:
CGO_ENABLED=1 go test ./x/pqc/... -count=1 -v
CGO_ENABLED=1 go test ./x/svm/... -count=1 -v
الاختبارات التي تستخدم المكتبات الأصلية أو Keepers الخاصة (proprietary) تُصرَّف في البناء الكامل فقط وليست جزءًا من المجموعة العامة.
التحقق من البناء
بعد نجاح البناء، تحقّق من الملف الثنائي:
./qorechaind version # may print nothing: release binaries do not report a version string
./qorechaind init test-node --chain-id qorechain-diana
يجب أن يُنشئ أمر init ملف تكوين أولي (genesis) وإعدادات عقدة في ~/.qorechaind/ دون أخطاء. يُهيّئ المثال أعلاه الشبكة التجريبية qorechain-diana — أما للشبكة الرئيسية، استبدل بـ --chain-id qorechain-vladi، الشبكة الحية (إصدار العقدة v3.2.4 وقت كتابة هذا النص؛ وتشغّل شبكة الاختبار v3.2.6).
البناء عبر Docker
يتوفر ملف Dockerfile في جذر المستودع:
docker build -t qorechaind:community .
يبني الملف الثنائي المجتمعي (يقرأ تعليقه الخاص "Public build — no PQC library")، ولذلك فإن الصورة مخصّصة للتطوير المحلي والأدوات، لا لمتابعة الشبكة الرئيسية أو شبكة الاختبار. لتشغيل عقدة شبكة في Docker، غلّف الملف الثنائي الرسمي للإصدار بدلًا من ذلك؛ راجع تشغيل عقدة.
استكشاف الأخطاء وإصلاحها
cgo: C compiler not found
ثبّت أدوات Xcode CLI (على macOS) أو build-essential (على Linux)
cannot find -lqorepqc
أنت تربط بناءً يتوقع وجود المكتبات الأصلية. استخدم بناء المجتمع (فهو لا يحتاج إليها) أو أرشيف الإصدار الذي يضمّها، وعيّن LD_LIBRARY_PATH / DYLD_LIBRARY_PATH على مجلد lib/ الخاص به
undefined: sonic.*
تأكد من تحديث go.sum: go mod tidy
signal: killed during build
زِد الذاكرة المتاحة (شائع في Docker عند وجود حدود منخفضة)
PQC tests fail with size mismatch
أحجام ML-DSA-87 هي: المفتاح العام 2,592 بايت، والمفتاح الخاص 4,896 بايت، والتوقيع 4,627 بايت. أي حجم آخر يعني خوارزمية مختلفة أو قيمة مبتورة.