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

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

## المشكلة

تتوقع DeFi على Ethereum من واجهة 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 بثماني منازل عشرية (مثلًا 15000000000 = 150.00 دولار)
```

## استهلك خلاصة في ثلاث خطوات

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

```ts
import { getOracle } from "@rome-protocol/registry";
const solUsd = getOracle(200010).feeds["SOL/USD"].address;
// Hadrian، إصدار السجل 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، إصدار السجل 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` عقد. يحتفظ الدفتر بأسعار جميع خلاصاته المسجَّلة ويُحدَّث على دفعات (والتحديث غير مقيَّد بالإذن)؛ ولا يحتفظ محوّل كل خلاصة بأي ذاكرة تخزين مؤقتة خاصة به. ويؤدي إدخال متوقف إلى revert فورًا مع `AdapterPaused`، بدلًا من الانتظار حتى يصبح قديمًا.

تُنشَر المحوّلات على شكل نسخ minimal-proxy وفق EIP-1167: يقوم `OracleAdapterFactory` 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` أرجعت خلاصةها حالة قديمة. وكل `-CACHED` و `-CACHEDPYTH` خلاصة أرجعت `UninitializedPriceFeed` (لم يُحدّثها شيء)، و `SOL/USD-SB` أرجعت `StalePriceFeed`. على Hadrian، يُفضَّل `-BOOK` الخلاصة، وشغّل `latestRoundData()` على الخلاصة التي تختارها قبل أن تعتمد عليها.
* **Rubicon.** لا يدرج السجل خلاصات الأوركل الخاصة بـ Rubicon، لذا لا تغطيها هذه الصفحة. المصنع منشور هناك (انظر [العناوين المنشورة](#deployed-addresses)) وتستجيب محوّلاته الأولى، لكن ابحث عن عناوين الخلاصات من المصنع (`adapterCount()` و `allAdapters(i)`) بدلًا من السجل.

إرجاع revert هنا هو السلوك المقصود: فشل الخلاصة القديمة أو غير المهيأة بصوت عالٍ بدلًا من إرجاع سعر قديم. تعامل مع ذلك داخل عقدك.

## الحداثة — keeper الخاص بالأوركل

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

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

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

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

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

العناوين المعيارية لكل سلسلة (المصانع، تطبيقات المحوّل، والخلاصات الحية) موجودة في [السجل](https://github.com/rome-protocol/rome-registry/tree/main/chains). أما المصانع الرئيسية، فمن `نشطًا` إدخالات registry v0.2.0 (الإصدار 5.0.0 على Hadrian؛ وعناوين Rubicon هي تلك الموجودة على [عناوين العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md) الصفحة)؛ انظر [قراءة قائمة العقود](https://docs.rome.builders/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](https://docs.rome.builders/ar/alttbyqat-ala-rome/oracle-gateway.md) — سجّل الخلاصات، وعيّن المستهلكين
* [عناوين العقود](https://docs.rome.builders/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.
