الخطافات والوحدات المرجعية

الوحدات عروض توضيحية، وليست المعيار

العلاقة بين A-REX Core ووحداتها هي العلاقة نفسها بين ERC-3643 ووحدات الامتثال في T-REX: الواجهة التي تتصل بها الوحدات موحَّدة؛ أما الوحدات فليست كذلك. والرمز المطابق الذي لا خطاف له رمز A-REX صالح. والخطاف الذي يكتبه أي شخص متوافق مع كل رمز مطابق. وهذا ما يجعل المنظومة تنمو دون أن يتغير المعيار.

graph LR
    T["ARexToken<br/>رمز مطابق"] -->|"check / onExecuted / canSend / canReceive"| H1[EligibilityHook]
    T --> H2[ExpiryHook]
    T --> H3[AttestationHook]
    T --> H4["خطافك الخاص"]
    H3 --> A[ARexAttestations]

عقد الخطاف

تكون op واحدة من OP_MINT (1) وOP_TRANSFER (2) وOP_BURN (3) وOP_FORCED_TRANSFER (4) وOP_TRANSFORM (5). وفي التحويل التصنيعي تصل المدخلات بـ to == 0 والمخرجات بـ from == 0. وdata هي بيانات تحويل ERC-1155، وهي abi.encode(processRef) في عمليات التحويل التصنيعي، وفارغة في التحويلات القسرية.

الرمز المستدعي هو msg.sender. والخطاف الذي يحتاج إلى الدفعة يقرأ IARexBatch(msg.sender).batchOf(id).

الخطافات المرجعية

EligibilityHook — السماح والحظر والعقوبات

يوضّح HOOK_ELIGIBILITY. ويحتفظ بقائمة سماح اختيارية وقائمة حظر وقائمة عقوبات؛ وتُرجع canSend/canReceive اقترانهما المنطقي؛ وتُرجع check القيمة SANCTIONED أو SENDER_INELIGIBLE أو RECEIVER_INELIGIBLE كي تتمكن واجهات المستخدم من تفسير الرفض. والتحويلات القسرية مسموحة دائمًا: فحجز السلع من حساب خاضع للعقوبات هو جوهر الإنفاذ. وفي بيئة الإنتاج تُغذَّى القوائم من سجل هوية (ONCHAINID أو EAS أو بيانات الاعتماد القابلة للتحقق) أو من أوراكل عقوبات؛ ولا يهتم الخطاف بأيهما.

ExpiryHook — قابلية التلف دون وحدة

بلا حالة. يقرأ expiresAt وproducedAt من الدفعة. يمنع سك الدفعات المنتهية الصلاحية وتحويلها (BATCH_EXPIRED) لكنه لا يمنع الحرق (الشطب) ولا التحويلات القسرية (الإنفاذ). ويمنع اختياريًا تحويل الدفعات التي لم تُنتَج بعد (BATCH_NOT_PRODUCED) — فالمنصة التي تموّل ما قبل الحصاد تضبط العلم للسماح بها؛ والسوق الفورية تضبطه لمنعها. ويغطي هذا الخطاف وحده جزء المنع من قابلية التلف؛ أما منحنيات التدهور فتصبح دالة عرض مساعدة أو تقييمًا خارج السلسلة.

AttestationHook — تقييد تنظيمي لكل سلعة

يربط كود السلعة بموضوع إفادة مطلوب. وقبل التحويل يقرأ الدفعة، ويبحث عن المتطلب، ويسأل سجل الإفادات isAttested، ويُرجع ATTESTATION_MISSING في غير ذلك. فعبارات "يحتاج البن إلى مرجع عناية واجبة وفق EUDR"، و"تحتاج الدفعات الموسومة بأنها عضوية إلى شهادة عضوية سارية"، و"تحتاج الماشية إلى شهادة صحية" يتحقق كل منها باستدعاء واحد إلى setRequirement.

PerishabilityHook — نماذج التدهور

ضبط التدهور لكل كود سلعة مع تجاوز لكل دفعة؛ والنماذج NONE وLINEAR (حتى حد أدنى عند انتهاء الصلاحية) وEXPONENTIAL (عمر النصف) وSTEP (انخفاض كل فترة زمنية). دوال العرض: valueBps وsecondsRemaining وisExpired. ويمنع سك الدفعات المنتهية الصلاحية وتحويلها (BATCH_EXPIRED) وتحويل الدفعات التي تساوي قيمتها المتبقية صفرًا (PERISH:NO_VALUE)؛ ولا يمنع الحرق ولا الإنفاذ أبدًا.

SeasonalHook — نوافذ الحصاد والتداول

نوافذ مطلقة [start, end] لكل سلعة وعملية (16 نافذة كحد أقصى لكل مفتاح). والسلعة/العملية التي لا نوافذ لها غير مقيّدة. الاستخدام المعتاد: تقييد OP_MINT بنافذة الحصاد، وOP_TRANSFER بنافذة التداول؛ وSEASON_CLOSED في غير ذلك.

DeliveryHook — الحيازة والتسوية

يجدول المُرسِل تسليم كمية amount إلى مستلم عبر ناقل؛ وتُقفل الكمية (بعدّاد O(1)، فلا تمرّ check على التاريخ أبدًا). ويسجّل الناقل والمستشعرات الاستلام والعبور وقراءات درجة الحرارة (مع علم المخالفة)؛ ويؤكد المستلم التسليم؛ وتُحال النزاعات إلى محكّم. والتسوية هي تحويل ERC-1155 نفسه: من المُرسِل إلى المستلم، بالمقدار الدقيق، مع data = abi.encode(deliveryId)؛ ولا تسمح به check إلا حين يكون التسليم DELIVERED، وتضع onExecuted علامة SETTLED عليه وتفتح القفل. وتظل الكمية الحرة (غير المقفلة) قابلة للحركة.

TraceabilityHook — سجل أحداث بصيغة EPCIS

يراقب كل عملية على الرمز ويصنّفها وفق خطوات الأعمال في CBV (commissioning وshipping وdestroying وtransforming) وحالات التصرف (active وin_transit وdestroyed وseized)؛ ويسجّل RECORDER_ROLE أحداث التتبع الحرجة غير المتعلقة بالرمز (التبريد، والتعبئة، والاستلام) مع readPoint وbizLocation. وله وضعان: الإصدار فقط (نحو +17 k غاز لكل تحويل؛ ويعيد المفهرس بناء السجل) أو الحفظ (نحو +184 k؛ وتجيب getEvents على السلسلة، مع ترقيم الصفحات).

الامتدادات المرافقة

ثلاثة جوانب لم تكن تحتاج قط إلى أن تكون قواعد تحويل؛ فهي عقود عادية تقرأ الإفادات أو تكتبها:

كتابة خطافك الخاص

يبقى المثال contracts/examples/SeasonHook.sol في المستودع. ويختبره test/standard/ImplementationGuide.test.js للقرّاء الذين لديهم وصول. وSeasonalHook هو الوحدة المرجعية لعدة نوافذ لكل سلعة ولكل عملية.

قواعد عملية:

1. الرمزان OK وOP_FORCED_TRANSFER معرّفان في النص المعياري.
2. سلوك الحرق معرّف في النص المعياري.
3. الاستدعاء check معرّف في النص المعياري.
4. أسماء الأكواد مثل ARexCodes.code("MYNS", "NAME") معرّفة في النص المعياري.
5. قيم الأعلام معرّفة في النص المعياري.
6. الاستدعاءان onExecuted وcheck معرّفان في النص المعياري.

التسجيل والترتيب

ضع القواعد الرخيصة ذات معدل الرفض المرتفع أولًا. وينبغي أن يوضع HOOK_ADMIN_ROLE خلف توقيع متعدد أو تأخير زمني: فمن يتحكم في المسار يتحكم في التحويلات الممكنة.

الاختبار

ينشر test/standard/helpers.js الحزمة المرجعية. ويسجّل RecordingHook كل استدعاء ويمكن توجيهه إلى الرفض بأي كود؛ ويحاول ReentrantHook إعادة دخول الرمز من onExecuted ويثبت فعالية القفل. ويغطي DomainHooks.test.js وExtensions.test.js الخطافات والمرافقات المنقولة؛ ويشغّل Invariants.test.js تسلسلًا عشوائيًا ببذرة محددة من العمليات ويتحقق من حفظ المعروض والحالة النهائية ومن أن canTransfer تتنبأ بكل نتيجة.

التشغيل البيني مع امتثال ERC-3643

تكشف وحدة امتثال ERC-3643 الدالة moduleCheck(from, to, value, compliance). والخطاف الذي يستدعيها للعملية OP_TRANSFER ويحوّل false إلى كود يجعل قيود الدول وسقوف الأرصدة والأقفال الزمنية المكتوبة لرموز الأوراق المالية قابلة لإعادة الاستخدام على رموز الدفعات. والعكس — أي إتاحة خطاف A-REX لرمز ERC-3643 — آلي بالقدر نفسه. ويتكامل Automated Compliance Engine من Chainlink عبر النمط نفسه: فيصبح محرك سياساته خطافًا واحدًا.