> 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/almntjat/oracle-gateway.md).

# بوابة الأوركل

خلاصات أسعار Pyth وSwitchboard خلف واجهة AggregatorV3Interface الخاصة بـ Chainlink.

تُعرِض Oracle Gateway موجزات الأسعار الأصلية لـSolana (Pyth وSwitchboard V3) عبر `AggregatorV3Interface`، لذا تحتفظ بروتوكولات Ethereum المنقولة إلى Rome بكود دمج الأوراكل الحالي لديها. **تم نشر Oracle Gateway V2 على Hadrian وRubicon**، رغم أن السجل يسرد عناوين الموجزات لـHadrian فقط، وتتكفّل بوابة العملاء بعملية التسجيل. ويقوم keeper يعمل على Rome بتحديث الموجزات المخبأة وموجزات الـbook، لكن ليست كل موجزات محدثة في كل لحظة — [أيُّ الموجزات تستجيب اليوم](#which-feeds-answer-today) موضَّحة أدناه. وتُغطّى نماذج المُكيّفات والـfactory والـkeeper في [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) المستودع.

> **معاينة.** لم يتم تدقيق Oracle Gateway. وتقول البوابة الشيء نفسه: لا تستخدمه في تدفقات القيمة الإنتاجية.

## المشكلة

يتوقع Ethereum DeFi واجهة Chainlink الخاصة بـ `AggregatorV3Interface`:

```solidity
(, int256 price,,,) = priceFeed.latestRoundData();
```

لدى مزودي الأوراكل في Solana (Pyth وSwitchboard) صيغ بيانات مختلفة. ومن دون تكييف، سيحتاج كل بروتوكول منقول إلى كود أوراكل مخصص.

## الحل

ينشر Oracle Gateway V2 عقود مُكيّف خفيفة الوزن تقوم بما يلي:

1. قراءة بيانات الأسعار مباشرةً من حسابات Pyth أو Switchboard على Solana (قراءات عبر الحالة، وليس CPI)
2. تحليل البيانات الموجودة على السلسلة
3. توحيد الأسعار إلى 8 منازل عشرية
4. توفير واجهة Chainlink القياسية `AggregatorV3Interface`

```solidity
import {IAggregatorV3Interface} from "@rome-protocol/rome-solidity/contracts/oracle/IAggregatorV3Interface.sol";

// الواجهة نفسها التي يستخدمها Chainlink على Ethereum
(, int256 price,,,) = IAggregatorV3Interface(ADAPTER).latestRoundData();
// السعر = SOL/USD عند 8 منازل عشرية (مثلًا 15000000000 = ‏$150.00)
```

## استهلك موجزًا في ثلاث خطوات

1. **استخرج عنوان المُكيّف من السجل** — لا تُضمِّنه في الشيفرة أبدًا:

```ts
import { getOracle } from "@rome-protocol/registry";
const solUsd = getOracle(200010).feeds["SOL/USD"].address;
// Hadrian، registry v0.2.0: 0x567384ee000ca0418c386A73eC2b7466f9f99D6b
```

يُثبَّت السجل من GitHub (`npm install github:rome-protocol/rome-registry#v0.2.0`). تحمل مفاتيح الموجز لاحقة توضّح نوع المُكيّف الموجود خلفها؛ راجع [مفاتيح الموجز في السجل](#feed-keys-in-the-registry) قبل أن تختار أحدها.

2. **اقرأه** بالواجهة التي يستخدمها بروتوكولك بالفعل — `IAggregatorV3Interface(solUsd).latestRoundData()`. الموجز المتأخر أو غير المُهيَّأ **يفشل** بدلًا من تقديم سعر متجمّد.
3. **عدة موجزات دفعة واحدة؟** `BatchReader.getLatestPrices(adapters[])` (Hadrian، registry v0.2.0: `0x2869f0a96572e7fb15036656e9a32fd17346499b`) — و `getFeedHealth(adapters[])` قبل أن تعتمد عليها. وتجعل المُكيّفات المخبأة كل مستهلك يقرأ `SLOAD`بسيطًا، لذا تبقى معاملات عدة موجزات (اقتراض متعدد الضمانات، عرض محفظة) رخيصة.

[cardo](https://github.com/rome-protocol/cardo) يقرأ هذه الموجزات على Hadrian. ولأن الواجهة هي تمامًا `AggregatorV3Interface`، يمكن لبروتوكولات فئة Compound وAave استخدام هذه الموجزات دون تغييرات في كود الأوراكل — فقط وجّه إعدادات موجز الأسعار إلى عناوين المُكيّفات.

## أنواع المُكيّفات

* **PythPullAdapter** — يقرأ حسابات أسعار Pyth (السعر، الثقة، EMA، وقت النشر).
* **SwitchboardV3Adapter** — يقرأ حسابات المجمّع في Switchboard (السعر، الطابع الزمني؛ لا يوجد EMA).
* **مُكيّفات CachedPyth / CachedFeed** — نسخ مُخبّأة للقراءة بكفاءة في استهلاك وحدات الحوسبة (CU).
* **BookFeedAdapter** — عرض للقراءة فقط متوافق مع Chainlink فوق إدخال واحد من `PriceBook` العقد. يحتفظ الـbook بأسعار جميع الموجزات المسجَّلة فيه ويُحدَّث على دفعات (والتحديث غير مقيَّد بالصلاحيات)؛ ولا يحتفظ مُكيّف كل موجز بأي ذاكرة تخزين مؤقت خاصة به. ويؤدي الإدخال الموقوف إلى revert فورًا مع `AdapterPaused`، بدلًا من انتظار أن يصبح متأخرًا.

تُنشر المُكيّفات كنسخ minimal-proxy وفق EIP-1167: إن `OracleAdapterFactory` تستنسخ مُكيّفات Pyth وSwitchboard والمُكيّفات المُخبّأة، وكل `PriceBook` تستنسخ نسختها الخاصة من `BookFeedAdapter` عند تسجيل موجز. وتوفّر واجهة موسّعة إلى جانب `AggregatorV3Interface` (`latestPriceData`, `maxStaleness`, `oracleType`، و `metadata()` الواجهة المستخدمة لفحوصات السلامة).

## مفاتيح الموجز في السجل

`getOracle(chainId).feeds` يحتوي على عدة مفاتيح لكل أصل. واللاحقة في اسم المفتاح تحدد نوع المُكيّف:

| المفتاح              | نوع المُكيّف                         | طريقة القراءة                                                                        |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `SOL/USD`            | Pyth مباشر (`PythPullAdapter`)       | يحلّل حساب Pyth في كل استدعاء.                                                       |
| `SOL/USD-BOOK`       | `BookFeedAdapter`                    | يقرأ `PriceBook` إدخالًا يقوم الـkeeper بتحديثه.                                     |
| `SOL/USD-CACHED`     | مُخبّأ (يلف موجزًا آخر)              | يقرأ سعرًا مخزَّنًا يقوم الـkeeper بتحديثه.                                          |
| `SOL/USD-CACHEDPYTH` | Pyth مُخبّأ (`CachedPythAdapter`)    | يقرأ سعرًا مخزَّنًا يقوم الـkeeper بتحديثه.                                          |
| `SOL/USD-SB`         | Switchboard (`SwitchboardV3Adapter`) | يحلّل حساب Switchboard في كل استدعاء. ويضع السجل علامة على هذه الإدخالات `مُتقاعدة`. |

يعتمد أيٌّ منها ستستخدمه على السلسلة. راجع القسم التالي أولًا.

### أيُّ الموجزات تستجيب اليوم

هذه نتائج لاستدعاءات للقراءة فقط `latestRoundData()` على الموجزات المدرجة في registry v0.2.0، أُجريت أثناء كتابة هذه الصفحة. تتغيّر حداثة الموجز من دقيقة إلى أخرى على devnet، لذا تعامل معها على أنها لقطة ثابتة وشغّل الاستدعاء نفسه على الموجز الذي تنوي استخدامه.

* **Hadrian.** غالبًا ما تكون الموجزات المباشرة متأخرة: ففي عمليات التحقق المتكررة، أرجع معظمها (BONK وBTC وETH وJITOSOL وJTO وJUP وMSOL وUSDC وUSDT) الخطأ `StalePriceFeed` في كل مرة، و `SOL/USD` أجاب بعضها في بعض الاستدعاءات ولم يجب في أخرى. أما `-BOOK` فكانت الموجزات هي الأكثر موثوقية وأجابت في كل استدعاء لكل أصل باستثناء JTO، الذي كان `-BOOK` موجزه يُعيد revert بوصفه متأخرًا. وكل `-CACHED` و `-CACHEDPYTH` موجز أعاد revert مع `UninitializedPriceFeed` (لم يُحدِّثها شيء)، و `SOL/USD-SB` أعاد revert مع `StalePriceFeed`. على Hadrian، فضّل `-BOOK` موجز، وشغّل `latestRoundData()` على الموجز الذي تختاره قبل أن تعتمد عليه.
* **Rubicon.** لا يسرد السجل موجزات الأوراكل لـRubicon، لذا لا تغطي هذه الصفحة تلك الموجزات. وقد نُشرت factory هناك (انظر [العناوين المنشورة](#deployed-addresses)) وتستجيب مُكيّفاته الأولى، لكن ابحث عن عناوين الموجز من الـfactory (`adapterCount()` و `allAdapters(i)`) بدلًا من السجل.

الـrevert هنا هو السلوك المقصود: فالموجز المتأخر أو غير المُهيَّأ يفشل بوضوح بدلًا من إرجاع سعر قديم. تعامل معه داخل عقدك.

## الحداثة — oracle-keeper

تفرض المُكيّفات `maxStaleness` نافذة: إذا `block.timestamp - publishTime > maxStaleness`، فإن القراءات تُعيد revert. على الشبكة الرئيسية لـSolana، يشغّل Pyth keepers للإنتاج. أمّا على devnet في Solana (حيث يوجد Hadrian)، فمرسلو Pyth يعملون بأفضل جهد ممكن، لذا يشغّل Rome **oracle-keeper** خدمة جانبية للحفاظ على حداثة حسابات Pyth الأساسية ولتحديث الموجزات المخبأة وموجزات الـbook. ولا يغطي keeper كل موجز على كل سلسلة في كل لحظة (راجع [أيُّ الموجزات تستجيب اليوم](#which-feeds-answer-today)).

تحقق من صحة الموجز باستخدام `BatchReader.getFeedHealth` (الذي يقرأ `metadata()`الخاص بكل مُكيّف)، وليس فقط `latestRoundData` — فقد يكون الموجز قابلاً للوصول لكنه متأخرًا.

## بوابة العملاء

سجّل الموجزات واضبط المستهلكين لكل سلسلة عبر [بوابة Oracle Gateway](https://oracle.testnet.romeprotocol.xyz/). راجع [صفحة البوابة](/ar/alttbyqat-ala-rome/oracle-gateway.md) للاطلاع على ما تغطيه.

## العناوين المنشورة

العناوين المعيارية لكل سلسلة (factorys، وتنفيذات المُكيّفات، والموجزات الحية) موجودة في [السجل](https://github.com/rome-protocol/rome-registry/tree/main/chains). أما العناوين الرئيسية للـfactorys، فمن `نشطًا` إدخالات registry v0.2.0 (الإصدار 5.0.0 على Hadrian؛ أما عناوين Rubicon فهي تلك الموجودة على [عناوين العقود](/ar/almrja/contract-addresses.md) الصفحة)؛ راجع [قراءة قائمة العقود](/ar/almrja/contract-addresses.md#reading-the-contracts-list):

| العقد                | هادريان                                      | روبيكون                                      |
| -------------------- | -------------------------------------------- | -------------------------------------------- |
| OracleAdapterFactory | `0x52b008771fc95b4674a4f3533570b3d223f27f68` | `0x6a1340dd86c3951b6f13d9001b3951d56a2fe581` |
| BatchReader          | `0x2869f0a96572e7fb15036656e9a32fd17346499b` | `0x580dc0ecb226530ee8a90b57e0f0cd2555fb4f0f` |

## القيود

* **لا توجد بيانات دورات تاريخية** — `getRoundData(roundId)` يؤدي إلى revert؛ ولا يُدعَم سوى `latestRoundData()` مدعوم.
* **EMA الخاص بـSwitchboard غير مدعوم** — بيانات EMA خاصة بـPyth فقط.
* **حدّ التأخر لكل سلسلة** — `maxStaleness` يُضبط لكل بيئة عند التشغيل: المكيّفات المباشرة (التي تقرأ Pyth) تضبط افتراضيًا على نحو 60 ثانية؛ أما المُكيّفات المخبأة فافتراضيها 3600 ثانية (وعندما يقوم keeper بتحديثها، فإنه يفعل ذلك بوتيرة أعلى بكثير من ذلك).
* **إزاحات المحلل** تُتحقق من صحتها مقابل التخطيطات الحالية لـPyth/Switchboard؛ وتتطلب تغييرات التخطيط إعادة التحقق.

## ما التالي

* [بوابة Oracle Gateway](/ar/alttbyqat-ala-rome/oracle-gateway.md) — سجّل الموجزات، واضبط المستهلكين
* [عناوين العقود](/ar/almrja/contract-addresses.md) — precompiles والعناوين الخاصة بكل سلسلة


---

# 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/almntjat/oracle-gateway.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.