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

Kora هي مساحة عمل Rust تضم ثلاث حزم (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 أو تسعيرها انطلاقًا منها يتجاهل بصمت حسابات جداول البحث ويؤدي إلى تحصيل أقل من اللازم. تقوم VersionedTransactionResolved::from_transaction بحل تلك العناوين مسبقًا، ولهذا تستقبل كل مرحلة لاحقة النوع المحلول.

إضافة إضافة معاملات

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

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

الاختبار

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

cargo test -p tests --test <target>

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