المنظومة والمستودعات

كل مستودع Rome عام، ما هو، وكيف تتكوّن معًا — الخريطة للتنقل في السطح.

الواجهة العامة لـ Rome هي مجموعة من المستودعات: بضعة الأساس حِزم تبني عليها، وأداة توليد هيكل، وتطبيقات مرجعية تتعلم منها، وخدمتان يستدعيهما تطبيقك. هذه الصفحة هي الخريطة — ما هو كل مستودع وكيف تتكامل معًا.

جاران يجيبان عن أسئلة مختلفة، وهذه الصفحة تربط إلى كليهما بدلًا من تكرارهما:

• المعمارية تشرح البروتوكول — كيف يعمل EVM داخل برنامج Solana.

• كل مستودع يضم ملف AGENTS.md (مثل rome-sdk-ts/AGENTS.md) الذي يوجّهك حسب ما الذي تبدأ منه (عقد Solidity، برنامج Solana، مشروع جديد بالكامل، من المنزل) إلى المثال الأقرب لحالتك.

هذه الصفحة هي المستوى الذي يقع بينهما: السطح الكامل وكيف ترتبط الأجزاء.

السطح في لمحة

الأساس — ابنِ على هذه

المستودع	ما هو	استخدمه عندما
rome-registry	@rome-protocol/registry — إسقاط مُولَّد للقراءة فقط لحقائق السلسلة الحية (المعرّفات، RPC، العناوين، mints الرموز، معرّفات البرامج، خلاصات oracle، ALTs).	تحتاج إلى حقيقة فعلية من السلسلة — لا تضعها ثابتة أبدًا.
rome-sdk-ts	@rome-protocol/sdk — مسار الكتابة في TypeScript: submitRomeTx + تحديد حجم الرسوم، وكلا المسارين، ومُرمِّزات PDA/ATA + CPI، وروابط precompile، وعميل /bridge client.	أنت تكتب كود التطبيق أو الواجهة الأمامية.
rome-solidity	واجهات precompile الخاصة بـ Solidity، وأغلفة SPL/ERC-20، ومهايئات oracle — مجموعة أدوات جهة العقود.	أنت تكتب العقود.

تطبيقات مرجعية — تعلّم بالمثال

المستودع	ما هو	استخدمه عندما
rome-dex	AMM ثنائي المسار — تجمع Solana أصلي مع موجّه EVM نحيف.	فتح المسار الآخر؛ مثال native-core .
aerarium	إقراض ثنائي المسار — نواة Comet مكتوبة بـ Solidity يصل إليها مستخدمو Solana عبر مرسل اصطناعي.	فتح المسار الآخر؛ مثال Solidity-core .
cardo	مستخدمو EVM يديرون تطبيقات Solana اللامركزية (swap/stake/lend/perps) عبر CPI.	مثال عملي لتطبيق من CPI إلى Solana للدراسة.
appia	تمويل لامركزي عبر VMs متعددة يركز على المراكز؛ يصل إليه المستخدمون من سلسلتهم الأصلية.	تطبيق من المنزل .
rome-aave-v3-demo	الإيداع/الاقتراض/السداد في Aave v3، منشور دون تغيير.	تطبيق EVM كامل يعمل كما هو.

تفريعات العقود — بروتوكولات معروفة، منشورة على Rome

المستودع	ما هو	استخدمه عندما
compound-on-rome-comet	سوق أموال Compound III (Comet).	تفريع بروتوكول EVM معروف.
rome-aave-v3	تفريعة عقود Aave v3.	تفريع بروتوكول EVM معروف.

الخدمات — يستدعيها تطبيقك

المستودع	ما هو	استخدمه عندما
rome-bridge-api	منسّق خارج السلسلة + ممول الرسوم للجسر على السلسلة. لا يحتفظ بأي مفاتيح.	تمويل محفظة، أو مسار من المنزل.
rome-oracle-gateway	خلاصات أسعار Solana (Pyth, Switchboard) معروضة لـ EVM عبر Chainlink AggregatorV3Interface.	تحتاج إلى خلاصة سعر.

القالب — ابدأ هنا

المستودع	ما هو	استخدمه عندما
create-rome-app	npx github:rome-protocol/create-rome-app — ينشئ قالب تطبيق ثنائي المسار موصولًا مسبقًا بالـ registry وSDK، مع فحص ممول لكلا المسارين.	بدء تطبيق جديد.

كيف تتكوّن معًا

العمود الفقري هو ثلاث ركائز أساسية وأداة توليد:

• rome-registry هو المصدر الوحيد للحقائق الحية. rome-sdk-ts هو مسار الكتابة — و /bridge المسار الفرعي الخاص به هو العميل الذي يستخدمه تطبيقك للتواصل مع rome-bridge-api. rome-solidity هو ما تستورده عقودك (والتفريعات)؛ مهايئات oracle التي rome-oracle-gateway تُنشر هناك أيضًا. الثلاثة مستقلون عن بعضهم — اختر ما يحتاجه تطبيقك.

• create-rome-app يربط الأولين معًا لتطبيق جديد، بحيث يبدأ المشروع الجديد بقراءة الـ registry والكتابة عبر SDK بالفعل.

التطبيقات المرجعية هي الاستثناء الذي يستحق أن تعرفه: فهي تسبق الحِزم المستخرجة. يستخدم cardo حزمة registry؛ ويحوّل appia الـ registry إلى JSON ثابت وقت البناء؛ وكلاهما يضمّن مسار الكتابة بدلًا من استيراد SDK. اقرأها لتتعلم الأنماط — لكن تطبيقًا جديدًا يجب أن يبدأ من create-rome-app + الحِزم، لا باستنساخ تطبيق.

تنقّل حسب ما تحتاجه

• حقيقة حيّة من السلسلة (id، address، mint، program id) → rome-registry. لا تثبته يدويًا أبدًا.

• كتابة كود التطبيق (كتابة، استدعاء CPI، جسر) → rome-sdk-ts؛ المرجع في Rome SDK.

• كتابة العقود → rome-solidity؛ راجع نشر عقود Solidity.

• استدعاء برنامج Solana من عقد Solidity → precompile الخاص بـ CPI في rome-solidity (interface.sol); cardo هو مثال عملي.

• مثال يعمل فعليًا على AMM أو الإقراض أو CPI أو تطبيق من المنزل → التطبيقات المرجعية أعلاه؛ و AGENTS.md لكل مستودع

• يوجّهك حسب نقطة البداية. → create-rome-app.

• خلاصة سعر → rome-oracle-gateway (انظر بوابة Oracle Gateway).

• المستخدمون على سلسلة أخرى → من المنزل + rome-bridge-api.

• تحديد أي جانب يحمل منطقك → اختر نواتك.

طبقة الأساس، عن قرب

rome-registry — حقائق حيّة، عامة بطبيعتها

الـ registry هو مولَّد من المصدر الداخلي لـ Rome: قائمة سماح تُصدِر فقط ما يُفترض أن يكون عامًا، تستبدل نقاط النهاية الداخلية بنظيراتها العامة، و ترفض افتراضيًا كل شيء آخر — لذا فهو آمن للنشر العام بطبيعته. ينشر، لكل سلسلة، chain.json / tokens.json / contracts.json / oracle.json / bridge.json / alts.json، بالإضافة إلى برامج Solana و عمليات نشر التطبيقات لكل بروتوكول.

تقرأه عبر دوال getter — getChain, getTokens, getContracts, getOracle, getBridge, getAlts، و getPrograms(network) (معرّفات البرامج مفهرسة حسب الشبكة، لا حسب chain id). الحزمة ESM عادية (ولا تتضمن أنواع TypeScript مضمّنة اليوم).

شيئان يجب معرفتهما قبل دمجها:

• getTokens() لا تُرجع assetRef. للعثور على غلاف رمز ما، طابِق على mint (mintId) — مثلًا، غلاف رمز الغاز هو الإدخال الذي يشارك نفس mint.

• تقرأ JSON من القرص (node:fs) — لذا فهي ليست آمنة للمتصفح. في تطبيق ويب، اسقِط القيم التي تحتاجها إلى ملف JSON ثابت وقت البناء واستورد ذلك في العميل. (وهذا بالضبط ما يفعله create-rome-app وappia.)

الحقائق التي لا يقرأها تطبيقك مباشرة تظهر أيضًا في مرجع عناوين العقود .

rome-sdk-ts — مسار الكتابة، كلا المسارين

@rome-protocol/sdk (v0.2.1) يغلّف كل ما تحتاجه كتابة Rome حتى لا تبني calldata أو الرسوم يدويًا:

• submitRomeTx — مسار الكتابة في جانب EVM: يحسب الغاز من eth_estimateGas ‏(مع حشو، ومع حدٍّ احتياطي عندما يفشل التقدير) ويزوّد رسوم EIP-1559.

• submitRomeTxSolanaLane — الشيء نفسه، مع Phantom/Solana المحفظة التي تقود تطبيق EVM الخاص بك. المرسل الاصطناعي لا يحتفظ بأي شيء في حالة السكون؛ buildFundLeg/buildSweepLeg ينقل القيمة إلى الداخل والخارج كـ ERC-20 (wUSDC), وليس الأصلي msg.value، ويتم توفير مُرسِل اصطناعي جديد تلقائيًا (create_pda) عند أول استخدام.

• اشتقاق PDA/ATA، ومُرمِّزات CPI invoke/invoke_signed ، وروابط precompile، و /bridge مسار فرعي (@rome-protocol/sdk/bridge) — عميل الجسر المعتمد على التسعير أولًا.

واجهة API الكاملة + أمثلة: Rome SDK، والأدلّة استدعِ Solana من EVM, استدعِ EVM من Solana، و ابنِ تطبيقًا ثنائي المسار.

rome-solidity — مجموعة أدوات جهة العقود

ما تستورده عقودك:

• contracts/interface.sol — واجهات precompile المرتبطة بعناوينها: CPI ICrossProgramInvocation (0xFF…08), Helper IHelperProgram (0xFF…09، وإنشاء ATA/PDA، وتحويلات SPL، و gas↔lamports)، Withdraw IWithdraw (0x42…16، و System (0xFF…07). توجد هنا أيضًا عائلة المخزنة مؤقتًا المُحسَّنة للغاز؛ ويستخدم العقد track واحدًا باستمرار. جدول العناوين الكامل: عناوين العقود.

• أغلفة SPL/ERC-20 — SPL_ERC20 (معتمد على CPI) و SPL_ERC20_cached (المسار المخزن مؤقتًا، المستخدم على devnet)؛ أي mint من SPL هو بالفعل ERC-20 عبر هذه.

• مهايئات Oracle (contracts/oracle/) — مهايئات Pyth/Switchboard rome-oracle-gateway تُنشر، وتُقرأ عبر IAggregatorV3Interface.

• أمثلة عملية في contracts/examples/.

قسم Solidity SDK في Rome SDK يعرض أنماط الاستيراد وروابط precompile في الكود.

ما التالي

• اختر نواتك — أي جانب يحمل منطقك.

• البداية السريعة — انشر أول عقد لك.

• create-rome-app — أنشئ قالب تطبيق ثنائي المسار.

• لكل مستودع AGENTS.md — المسار حسب نقطة البداية إلى المثال الأقرب.