> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/ar/albda-1/ecosystem.md).

# النظام البيئي والمستودعات

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

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

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

* [المعمارية](https://docs.rome.builders/ar/albda-1/architecture.md) تشرح **البروتوكول** — كيف يعمل EVM داخل برنامج Solana.
* يأتي مع كل مستودع **`AGENTS.md`** (مثل [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)) الذي يوجّه حسب **ما تبدأ منه** (عقد Solidity، أو برنامج Solana، أو من الصفر، أو من المنزل) إلى المثال الأقرب إلى حالتك.

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

## الواجهة في لمحة

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

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

الأسماء `@rome-protocol/…` أعلاه هي أسماء حِزم، لكن هذه الحِزم غير منشورة على npm. ثبّتها من GitHub (الأوامر موجودة في كل قسم تحت [طبقة الأساس عن قرب](#the-foundation-layer-up-close))؛ وتبقى مسارات الاستيراد في كودك كما هي.

### تجميعات Rome ZK EVM

| المستودع                                                        | ما هو                                               | استخدمه عندما                               |
| --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------- |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | برامج تجميع ZK، ووثائق العقدة، والمُثبِت، والمشغّل. | أنت تشغّل سلسلة EVM تُسوّى على Solana.      |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | مصدر الضيف الدُفعي المبني لبدء كل سلسلة (genesis).  | أنت تبني ضيفًا وتطلب مفتاح التحقق الخاص به. |

### Ostia (ZK EVM على Canton)

| المستودع                                                                              | ما هو                                                                                                    | استخدمه عندما                                                                                                                                                                                |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Ostia، وهو ZK EVM على Canton: يتم تسجيل كل كتلة EVM مُثبتة مع إجراءات Canton الخاصة بها في معاملة واحدة. | أنت تبني على Ostia DevNet ([المستكشف](https://ostia.devnet.romeprotocol.xyz/)) أو تشغّل Ostia الخاصة بك. راجع [Canton ZK EVM](https://docs.rome.builders/ar/canton-zk-evm/canton-zk-evm.md). |

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

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

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

| المستودع                                                                          | ما هو                           | استخدمه عندما             |
| --------------------------------------------------------------------------------- | ------------------------------- | ------------------------- |
| [compound-on-rome-comet](https://github.com/rome-protocol/compound-on-rome-comet) | سوق المال Compound III (Comet). | تفرّع بروتوكول EVM معروف. |
| [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3)                     | تفرّع عقود Aave v3.             | تفرّع بروتوكول EVM معروف. |

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

| المستودع                                                                    | ما هو                                                                                        | استخدمه عندما                            |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api)         | منسّق خارج السلسلة + راعي الرسوم للجسر على السلسلة. لا يحتفظ بأي مفاتيح.                     | تمويل محفظة، أو مسار من السلسلة الأصلية. |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | تغذيات أسعار Solana (Pyth, Switchboard) مُتاحة لـ EVM عبر Chainlink `AggregatorV3Interface`. | تحتاج إلى تغذية سعرية.                   |

### الهيكل الأولي — ابدأ هنا

| المستودع                                                            | ما هو                                                                                                                             | استخدمه عندما   |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — ينشئ هيكل تطبيق ثنائي المسار موصولًا مسبقًا بالسجل + SDK، مع فحص ممول لكلا المسارين. | بدء تطبيق جديد. |

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

```mermaid
flowchart TD
    REG["rome-registry — حقائق السلسلة الحية"]
    SDK["rome-sdk-ts — الكتابة، CPI، وعميل الجسر"]
    SOL["rome-solidity — واجهات precompile، وغلافات SPL، ومحوّلات الأوراكل"]
    CRA["create-rome-app — أداة توليد الهيكل"]
    APP["تطبيقك — الواجهة الأمامية + العقود"]
    BAPI["rome-bridge-api — منسّق خارج السلسلة، لا يحتفظ بأي مفاتيح"]
    OG["rome-oracle-gateway — تغذيات أسعار Solana"]

    CRA -->|ينشئ الهيكل، موصول مسبقًا| APP
    REG -->|حقائق، لا تُضمّن ثابتة أبدًا| APP
    SDK -->|مسار الكتابة وCPI| APP
    SOL -->|تستورده عقودك| APP
    APP -->|عميل SDK /bridge| BAPI
    APP -->|يقرأ عبر AggregatorV3Interface| OG
    OG -.->|المحوّلات موجودة في| SOL
    CRA -.->|يوصل| REG
    CRA -.->|يوصل| SDK
```

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

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) هو المصدر الوحيد للحقائق الحية. [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) هو مسار الكتابة — و `/bridge` المسار الفرعي هو العميل الذي يستخدمه تطبيقك للتخاطب مع `rome-bridge-api`. [**rome-solidity**](https://github.com/rome-protocol/rome-solidity) هو ما تستورده عقودك (والتفرعات)؛ ومحوّلات الأوراكل التي `rome-oracle-gateway` تُنشر هناك أيضًا. الثلاثة مستقلة عن بعضها — فاختر ما يحتاجه تطبيقك.
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) يربط الأولين معًا لتطبيق جديد، بحيث يبدأ المشروع الجديد وهو يقرأ السجل ويكتب عبر SDK.

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

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

* **حقيقة حية من السلسلة** (المعرّف، العنوان، mint، معرّف البرنامج) → [rome-registry](https://github.com/rome-protocol/rome-registry). لا تُضمّنه ثابتًا أبدًا.
* **كتابة كود التطبيق** (كتابة، أو استدعاء CPI، أو جسر) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)؛ راجع في [Rome SDK](https://docs.rome.builders/ar/almntjat/rome-sdk.md).
* **كتابة العقود** → [rome-solidity](https://github.com/rome-protocol/rome-solidity)؛ راجع [نشر عقود Solidity](https://docs.rome.builders/ar/adlh-almtw-ryn/deploy-solidity.md).
* **استدعاء برنامج Solana من عقد Solidity** → الـ CPI precompile في [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) هو مثال عملي.
* **مثال عملي** لتطبيق AMM أو إقراض أو CPI أو تطبيق من السلسلة الأصلية → التطبيقات المرجعية أعلاه؛ و `AGENTS.md` يوجّه بحسب نقطة البداية.
* **إنشاء هيكل تطبيق جديد** → [create-rome-app](https://github.com/rome-protocol/create-rome-app).
* **تغذية سعرية** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) (راجع [بوابة Oracle Gateway](https://docs.rome.builders/ar/alttbyqat-ala-rome/oracle-gateway.md)).
* **مستخدمون على سلسلة أخرى** → [من السلسلة الأصلية](https://docs.rome.builders/ar/adlh-almtw-ryn/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **تحديد أي جانب يحتوي منطقك** → [اختر النواة المناسبة](https://docs.rome.builders/ar/almfahym-alasasyh/choose-your-core.md).

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

### rome-registry — حقائق حيّة، عامة بحكم التصميم

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

ثبّته من GitHub، مثبتًا على وسم إصدار: `npm install github:rome-protocol/rome-registry#v0.2.0`. تقرؤه عبر دوال getter — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`، و `getPrograms(network)` (معرّفات البرامج مفهرسة بحسب الشبكة، لا بحسب معرّف السلسلة). الحزمة عبارة عن ESM عادي (ولا تتضمن أنواع TypeScript مدمجة حاليًا).

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

* **`getTokens()` لا تُرجع `assetRef`.** للعثور على غلاف رمز، طابِق على **mint** (`mintId`) — مثلًا، غلاف رمز الغاز هو الإدخال الذي يشاركها الـ mint.
* **يقرأ JSON من القرص (`node:fs`) — وهو غير آمن للاستخدام في المتصفح.** في تطبيق ويب، اسقِط القيم التي تحتاجها إلى ملف JSON ثابت وقت البناء واستورده في العميل. (وهذا بالضبط ما يفعله `create-rome-app` و appia.)

تعود عناوين العقود على شكل قائمة إصدارات لكل عقد؛ اختر الإصدار الذي يكون `حالته` هو `نشطًا`. [قراءة قائمة العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md#reading-the-contracts-list) يوضح كيف. كما تظهر الحقائق التي لا يقرأها تطبيقك مباشرةً في [عناوين العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md) المرجع.

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

ثبّته من GitHub: `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`.

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

* **`submitRomeTx`** — مسار الكتابة في مسار EVM: يحدد الغاز اعتمادًا على `eth_estimateGas` (بعد الحشو، مع سقف احتياطي عندما يفشل التقدير) ويزوّد برسوم EIP-1559.
* **`submitRomeTxV1`** — الشيء نفسه، ولكن لمحفظة **Solana** التي تشغّل تطبيق EVM الخاص بك: معاملة Solana v1 واحدة لكل استدعاء، ومطالبتا محفظة. المرسل الاصطناعي لا يحتفظ بأي شيء في حالة السكون؛ `buildFundLeg`/`buildSweepLeg` نقل القيمة إلى الداخل والخارج بصفتها ERC-20 (`wUSDC`), **وليس** الأصلي `msg.value`؛ أما تعليمات Solana العادية المحيطة باستدعاء (مسار التمويل، وإنشاء حساب الرمز في المحفظة قبل عملية sweep) فتُمرَّر عبر `submitSolanaInstructionsV1` كمعاملات v1 أيضًا. `submitRomeTxSolanaLane` هو المسار الأقدم، الذي يبني معاملة Solana قديمة في العميل ويُجهّز تلقائيًا مرسلًا اصطناعيًا جديدًا (`create_pda`) عند الاستخدام الأول.
* **اشتقاق PDA/ATA، وCPI `invoke`/`invoke_signed` المشفّرات، وروابط precompile**، و **`/bridge`** مسار فرعي (`@rome-protocol/sdk/bridge`) — عميل الجسر الذي يعتمد على التسعير أولًا.

واجهة API الكاملة + أمثلة: [Rome SDK](https://docs.rome.builders/ar/almntjat/rome-sdk.md)، وأدلة [استدعِ Solana من EVM](https://docs.rome.builders/ar/adlh-almtw-ryn/call-solana-from-evm.md), [استدعِ EVM من Solana](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md)، و [أنشئ تطبيقًا ثنائي المسار](https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md).

### rome-solidity — مجموعة الأدوات على جانب العقود

ثبّته من GitHub، وليس npm. مع npm أو Hardhat: `npm install github:rome-protocol/rome-solidity`. مع Foundry: `forge install rome-protocol/rome-solidity`، ثم أضف إعادة التعيين `@rome-protocol/rome-solidity/=lib/rome-solidity/` إلى `foundry.toml` (تحت `[profile.default]`، كـ `remappings = [...]`) حتى يتمكّن `@rome-protocol/rome-solidity/contracts/interface.sol` من الحل. اسم الحزمة في `package.json` هو `@rome-protocol/rome-solidity`، لذا يعمل مسار الاستيراد نفسه مع كليهما.

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

* **`contracts/interface.sol`** — واجهات precompile المربوطة بعناوينها: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **المساعد** `IHelperProgram` (`0xFF…09`، وإنشاء ATA/PDA، وتحويلات SPL، والغاز↔lamports)، **السحب** `IWithdraw` (`0x42…16`)، و **النظام** (`0xFF…07`). توجد هنا أيضًا عائلة محسّنة للغاز من نوع **المخزّنة** ؛ ويستخدم العقد مسارًا واحدًا باستمرار. جدول العناوين الكامل: [عناوين العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md).
* **غلافات SPL/ERC-20** — `SPL_ERC20` (المعتمدة على CPI) و `SPL_ERC20_cached` (المسار المخزّن، المستخدم على devnet)؛ وأي mint في SPL يصبح بالفعل ERC-20 عبر هذه.
* **محوّلات الأوراكل** (`contracts/oracle/`) — محوّلات Pyth/Switchboard `rome-oracle-gateway` المنشورة، تُقرأ عبر `IAggregatorV3Interface`.
* أمثلة عملية في `contracts/examples/`.

قسم Solidity SDK في [Rome SDK](https://docs.rome.builders/ar/almntjat/rome-sdk.md) يوضح أنماط الاستيراد وروابط precompile في الكود.

## ما التالي

* [اختر النواة المناسبة](https://docs.rome.builders/ar/almfahym-alasasyh/choose-your-core.md) — أي جانب يحتوي منطقك.
* [البدء السريع](https://docs.rome.builders/ar/albda-1/quickstart.md) — انشر أول عقد لك.
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) — أنشئ هيكل تطبيق ثنائي المسار.
* كل مستودع `AGENTS.md` — المسار حسب نقطة البداية إلى أقرب مثال.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/ar/albda-1/ecosystem.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
