البنية المعمارية

Kora هو مساحة عمل Rust (workspace) تتألف من ثلاث حزم (crates):

• تحتوي kora-lib على المنطق الأساسي وخادم RPC،
• وتبني kora-cli الملف التنفيذي kora الذي يشغّله المشغّلون،
• أما kora-deploy فهي أداة متخصصة لنشر البرامج، ولها إصدارات مستقلة. كل ما يرد أدناه يوجد في crates/lib/src ما لم يُذكر خلاف ذلك.

دورة حياة الطلب

يوضح المخطط أدناه المسار العام لمعاملة ما عبر Kora. يُعد فهم مسار الاستدعاء أمرًا مهمًا لإعداد عقدة Kora وإضافة ميزات جديدة.

أين توجد كل مرحلة

هناك ملفان آخران يجدر الإلمام بهما: يحدد config.rs مخطط kora.toml بالكامل، بينما يحتفظ state.rs بالإعدادات بعد فك تسلسلها ضمن حالة عامة على مستوى العملية.

قراءة خادم RPC

يُعد rpc.rs طبقة توجيه رقيقة، بطريقة واحدة لكل نقطة نهاية JSON-RPC، وهو أسرع وسيلة للاطلاع على واجهة API بأكملها. ويوجد منطق كل طريقة في ملف خاص بها ضمن rpc_server/method/. اقرأ sign_transaction.rs من البداية إلى النهاية؛ فطرق التوقيع الأخرى ما هي إلا تنويعات عليه.

قراءة وحدة التحقق

يحتوي transaction_validator.rs وtransaction/instruction_util.rs على منطق التحقق من المعاملات والتعليمات. بالإضافة إلى ذلك، توجد اختبارات خصائص أمان سياسة دافع الرسوم (fee-payer-policy)، وهي مخصصة بملف واحد لكل برنامج خاضع للضبط ضمن validator/transaction_validator/fee_payer_policy_props/.

أعراف يجدر معرفتها

التحقق الافتراضي. جميع الخيارات ضمن [validation.fee_payer_policy] قيمتها الافتراضية false، كما أن هياكل السياسة تحمل #[serde(default)]. وهذا الاقتران مقصود: فإضافة تعليمة جديدة خاضعة للضبط يجب ألا تكسر إعدادات مشغّل قائم، ويجب أن تُعامل كحالة رفض لا كسماح عرضي. حافظ على الأمرين معًا عند إضافة خيار جديد.

تحقق من المعاملة بعد حل عناوينها، وليس من المعاملة الخام أبدًا. تكشف VersionedTransaction الخام المفاتيح الثابتة للحسابات فقط، ولذلك فإن التحقق من معاملة V0 أو تسعيرها انطلاقًا منها يتجاهل بصمت حسابات جداول البحث (lookup tables) ويؤدي إلى تحصيل رسوم أقل من اللازم. تقوم VersionedTransactionResolved::from_transaction بحل تلك العناوين مسبقًا، ولهذا تقبل كل مرحلة لاحقة النوع بعد الحل.

إضافة إضافة معاملات (plugin)

تنفّذ الإضافات السمة TransactionPlugin الموجودة في plugin/mod.rs. ولها دالتان: تعمل validate لكل معاملة أثناء مسارات التوقيع، بينما تعمل validate_config مرة واحدة عند بدء التشغيل وتعيد الأخطاء والتحذيرات إلى المشغّل. ويُعلم PluginExecutionContext الإضافةَ بأي من طرق التوقيع الأربع استدعاها.

تقوم TransactionPluginRunner::from_config بالمطابقة على TransactionPluginType، المعرَّف في config.rs. وإضافة مدمجة جديدة تعني متغيرًا (variant) جديدًا هناك مع فرع مطابقة (match arm) جديد في المشغّل. والإضافتان المتوفرتان حاليًا هما gas_swap و deploy_authority.

الاختبار

يحتفظ Kora بالإعدادات في حالة عامة على مستوى العملية، ولذلك يعلن tests/ عن هدف [[test]] واحد لكل مرحلة، ويقوم كل هدف بتشغيل surfnet مضمّن خاص به مع عقدة Kora، ويُهيَّأ من الصفر. إعداد واحد لكل ملف تنفيذي: فالمرحلة الجديدة تحتاج إلى هدف جديد، لا إلى وحدة جديدة داخل هدف قائم.

cargo test -p tests --test <target>

كل شيء آخر مرتبط عبر justfile. اقرأ ذلك الملف بدلًا من إعادة بناء الأوامر يدويًا.