مقدمة
Stellar Trade Contracts هي مساحة عمل لعقود Soroban خاصة بـ Stellar Trade، وهو نموذج أولي مفتوح المصدر لسوق التوقعات مبني على Stellar. كتنظّم العقود كيفاش كيدخل XLM لمجمّع السوق، وكيفاش كيقلّصو المشاركين المراكز ديالهم، وكيفاش كتتوزّع الدفوعات والاسترجاعات فالسوق اللي تحسمات ولا تلغات.
المستودع مهيّأ للمطورين اللي خاصهم يبنيو أو يختابرو أو يراجعو أو ينشرو العقود اللي ورا التطبيق. فيه عقد السوق، وزايد عليه حزم token وreferral وleaderboard واختبارات التكامل.
فهم مساحة العمل
المستودع منظّم فخمسة حزم رئيسية، وكل وحدة عندها مسؤولية محددة:
prediction_market: كينشئ الأسواق، كيقبل المراكز، كيقلّص المراكز، كيتعامل مع إجراءات الحسم، كيحسب المطالبات النسبية، كيعالج استرجاعات الإلغاء، كيسجّل الرسوم، وكيْدعم النزاعات والحكامة.stellar_trade_token: كيوفّر رمز المكافآت مع تحكّمات المسؤولين، وجهات سكّ مصادق عليها، وتحكّمات الإيقاف المؤقت، وسقف اختياري للعرض. عمليات النشر الجديدة كتستعمل الاسمStellar TradeوالرمزSTRD.referral_registry: كيسجّل الإحالات، كيحدّ من عمق سلسلة الإحالة، وكيْوزّع رسوم الإحالة.leaderboard: كيتبّع نقط المشاركين وسجلات الربح والخسارة، كيطبّق تراجع النقاط، وكيْدعم سكّ المكافآت المصرّح به.cross_contract_invariants: كيختابر المحاسبة والسلوك عبر عقود السوق والإحالة ولوحة الصدارة والرمز.
إعداد مساحة عمل Rust
المشروع كيثبّت Rust 1.91.0 والهدف wasm32v1-none عبر rust-toolchain.toml. ثبّت سلسلة الأدوات والهدف المحددين فالمستودع قبل ما تشغّل الفحوصات من جذر المستودع.
منين تكون البيئة واجدة، شغّل مجموعة اختبارات مساحة العمل كاملة:
cargo test --workspace --all-featuresفحوصات التنسيق كتتأكد باللي المصدر تابع لقواعد التنسيق ديال المشروع:
cargo fmt --all -- --checkشغّل Clippy مع اعتبار التحذيرات أخطاء باش تلقى مشاكل جودة الكود والصحة:
cargo clippy --workspace --all-features -- -D warningsبنِ عقد سوق التوقعات لـ WebAssembly باستعمال إعداد الإصدار:
cargo build --release --target wasm32v1-none -p prediction_marketهاد الأوامر كتمثّل الفحوصات المستعملة فمسار GitHub Actions ديال المستودع. المسار كيبني حتى ملفات WASM وكيشغّل اختبارات الثوابت عبر العقود بالنسبة للتغييرات فالفرع الافتراضي وطلبات السحب.
تتبّع دورة حياة السوق
1. إنشاء سوق
منشئ مصادق عليه كينشر سؤال السوق والفئة ووقت الإغلاق. إنشاء السوق مقيّد بالصلاحيات، وبالتالي خاص المستدعي يستوفي قواعد التفويض المهيّأة فالعقد.
2. وضع مركز
المشارك كيستدعي place_bet باش يراهن بـ XLM على جهة YES ولا NO. العقد كيطبّق الرسوم المهيّأة وكيقيّد الجهة اللي اختارها المشارك بالمركز الناتج.
آلية تقليص المركز ماشي بيع من نظير لنظير، وماشي دفتر أوامر، وماشي مركز بيع على المكشوف. هي عملية على الحصة المسجّلة من قبل للمشارك.
3. تقليص مركز قبل الإغلاق
قبل ما يسالي السوق، يقدر المشارك يستدعي reduce_position باش ينقص من مركز موجود. العقد كيستعمل الجهة المسجّلة فمركز المشارك وكيحسب المبلغ المرجوع انطلاقاً من الحصة المنقوصة وقواعد الرسوم المحتفظ بها.
حيت العقد كيختار الجهة من المركز الموجود ديال المشارك، خاص المستدعين ما يعتبروا هاد العملية تبديل للجهة ولا تداول مع مشارك آخر.
4. حسم السوق
مُحكِّم مصادق عليه كيقدّم النتيجة من بعد ما يسالي السوق. من بعد عقد السوق كيحسب الدفوعات النسبية للمراكز الرابحة.
الحسم مقيّد بالصلاحيات. مساحة العمل هادي ما كتوفّرش أوراكل آلي. البيانات الخارجية ديال الأسعار ولا الشبكة ما تقدرش تحسم السوق إلا استعملها مُحكِّم مصادق عليه وقدّم النتيجة.
5. المطالبة بالأرباح أو استلام استرجاع الإلغاء
المشاركون كيطالبو بالدفوعات النسبية عبر العقد من بعد حسم السوق. الأسواق الملغاة كتتبع مسار استرجاع مستقل عوض مسار الدفعة العادية للمراكز الرابحة.
اختيار المُحكِّم، ومعايير الحسم، والأدلة، والتعامل مع النزاعات كلها افتراضات مهمة مرتبطة بالثقة. راجع هاد المساطر قبل ما تعتمد على سوق منشور.
مراجعة خصائص المحاسبة والسلامة
قبل ما تبدّل سلوك العقد، قرا مصفوفة الثوابت. كتربط قواعد المحاسبة المهمة بالاختبارات اللي كتحميها.
المصفوفة كتغطّي مجالات منها:
- الحفاظ على الرسوم وعزل الرسوم على مستوى السوق.
- الحدود ديال الدفوعات النسبية.
- سلوك الإلغاء.
- محاسبة الإحالات.
- تتبّع عرض المكافآت.
- التعامل مع مدة صلاحية التخزين.
- مسارات الإيقاف الطارئ.
إلى بدّلتي الرسوم أو المكافآت أو صيغ الدفعات أو مدد التخزين، حدّث اختبارات التراجع والثوابت المعنية فنفس الوقت. حزمة cross_contract_invariants مفيدة خصوصاً ملي كيأثر التغيير على أكثر من عقد واحد.
استعمال تقارير المشاكل التاريخية بالشكل الصحيح
المجلد issues/ فيه تقارير تاريخية على الأمان والصحة. قرا issues/README.md باش تفهم السياق ديالها.
هاد التقارير كتوثّق مخاطر فالتصميم كانت من قبل. ما خاصّهاش تتعتبر دليل بلي العقود دازو من التدقيق، ولا تأكيد بلي كل مشكل مذكور مازال قائم دابا. استعملوها كمدخل للمراجعة مع الكود المصدري الحالي، والاختبارات، ومصفوفة الثوابت.
وجد للنشر
عمليات النشر فشبكة الاختبار كتحافظ على معرّفات العقود التاريخية وبيانات الرموز. النشر الجديد كينشئ عناوين جديدة وكيهيّأ STRD؛ وما كينقلش المالكين الحاليين ولا الأرصدة.
قبل النشر، تأكد من هاد الأمور كاملين:
- الشبكة المستهدفة.
- معرّفات العقود.
- هوية المسؤول.
- إعدادات الرسوم.
- إعدادات الـ Resolver.
عمرَك تدفع مفاتيح سرية، عبارات استرجاع المحفظة، .deploy.env، مخرجات النشر، ولا ملفات الهوية المحلية للمستودع.
بالنسبة لتطوير الواجهة الأمامية محلياً وتعليمات نشر التطبيق، راجع README ديال التطبيق.
نصائح متقدمة فالتطوير
اختبر السلوك بين العقود
تغيير كيبان محصور فعقد واحد يقدر يأثر على الإحالات، والمكافآت، وسجلات لوحة الصدارة، ولا العرض ديال الرموز. شغّل مجموعة الاختبارات الكاملة ديال مساحة العمل واختبارات الثوابت بين العقود، وما تعتمدش غير على اختبارات الوحدة ديال عقد واحد.
خلي حدود الصلاحيات واضحة
إنشاء الأسواق، وتسوية النتائج، وإدارة الرموز، وإصدارها، وإجراءات حساسة أخرى كتستعمل ضوابط التفويض. ملي كتراجع عقد ولا كتوسّعو، تأكد شكون من الهويات مسموح ليه ينفذ كل عملية، وكيفاش كتأثر ضوابط الإيقاف على سلوك الطوارئ.
راجع تغييرات مدة التخزين
التعامل مع TTL ديال التخزين جزء من نموذج السلامة ديال المشروع. أي تغيير فأنماط الوصول للتخزين ولا فمدد الصلاحية ديالو خاصّو يتراجع مقابل مصفوفة الثوابت ويتغطّى باختبارات الانحدار.
تحقق من مخرجات الإصدار
شغّل التنسيق، وClippy، والاختبارات، وبناء WASM ديال الإصدار قبل نشر التغييرات ولا إطلاقها. اعتبر نجاح البناء محلياً شرطاً مسبقاً للتطوير، وما تعتبرهش بديلاً عن مراجعة الإعدادات وهويات النشر.
الخلاصة
Stellar Trade Contracts كيوفّر منطق Soroban لإنشاء أسواق التوقعات، وتسجيل مراكز YES وNO، وتقليص الرهانات، وتسوية النتائج، وتوزيع المطالبات بشكل نسبي، وردّ الأموال فالأسواق الملغاة. وكريات الدعم ديالو كتزيد وظائف الرموز المكافِئة، والإحالات، ولوحة الصدارة، والتكامل.
باش تخدم بأمان مع المستودع، بدا ببيئة Rust المثبّتة، وشغّل جميع فحوصات مساحة العمل، ودرس دورة حياة السوق، وراجع مصفوفة الثوابت قبل ما تغيّر سلوك المحاسبة ولا التخزين. أثناء النشر، تحقق من كل إعدادات الصلاحيات والشبكة، وخلي جميع الأسرار خارج التحكم فالإصدارات.