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

يكشف Oracle Gateway موجّهات الأسعار الأصلية لـ Solana (Pyth Network، Switchboard V3) عبر `AggregatorV3Interface` الخاصة بـ Chainlink. يمكن للبروتوكولات على Ethereum التي تنتقل إلى Rome استخدام كود تكامل أوراكلها الحالي دون تغيير.

## المشكلة

تتوقع بروتوكولات Ethereum DeFi واجهة Chainlink `AggregatorV3Interface`:

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

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

## الحل

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

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

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

// نفس الواجهة كما في Chainlink على Ethereum
IAggregatorV3 priceFeed = IAggregatorV3(ORACLE_ADAPTER_ADDRESS);
(, int256 price,,,) = priceFeed.latestRoundData();
// السعر = SOL/USD بدقة 8 منازل عشرية (مثلًا، 15000000000 = ‎$150.00)
```

## البنية المعمارية

### OracleAdapterFactory

تنشر وتدير محوّلات الأوراكل:

```solidity
OracleAdapterFactory factory = OracleAdapterFactory(0xa4647955a16b72d15f13b51b5277036755d297be);

// نشر محوّل تغذية سعر Pyth
address adapter = factory.createPythFeed(
    pythAccountPubkey,    // حساب سعر Pyth على Solana
    "SOL/USD",            // الوصف
    60                    // أقصى حدّ لقدم البيانات بالثواني
);

// نشر محوّل تغذية سعر Switchboard
address adapter = factory.createSwitchboardFeed(
    sbAccountPubkey,      // مجمّع Switchboard على Solana
    "SOL/USD",
    60
);
```

يتحقق المصنع من أن الحساب مملوك فعليًا لبرنامج Pyth/Switchboard قبل النشر.

### أنواع المحوّلات

**PythPullAdapter** — يقرأ Pyth `PriceUpdateV2` الحسابات. يدعم السعر، ونطاق الثقة، وسعر EMA، ووقت النشر.

**SwitchboardV3Adapter** — يقرأ Switchboard `AggregatorAccountData` الحسابات. يدعم السعر والطابع الزمني. EMA غير متاح.

كلا المحوّلين يستخدمان **نسخًا بديلة مصغّرة وفق EIP-1167** للنشر بكفاءة في استهلاك الغاز.

## الواجهات

### واجهة Chainlink القياسية

```solidity
interface IAggregatorV3Interface {
    function decimals() external view returns (uint8);          // دائمًا 8
    function description() external view returns (string memory);
    function version() external view returns (uint256);
    function latestRoundData() external view returns (
        uint80 roundId,
        int256 answer,        // السعر موحّد إلى 8 منازل عشرية
        uint256 startedAt,
        uint256 updatedAt,
        uint80 answeredInRound
    );
}
```

### واجهة موسّعة

```solidity
interface IExtendedOracleAdapter {
    function latestPriceData() external view returns (
        int64 price, uint64 conf, int32 expo, uint64 publishTime
    );
    function latestEMAData() external view returns (        // Pyth فقط
        int64 emaPrice, uint64 emaConf, int32 expo, uint64 publishTime
    );
    function priceStatus() external view returns (uint8);   // 0=تداول، 1=قديم، 2=متوقف
    function maxStaleness() external view returns (uint256);
    function oracleType() external view returns (uint8);    // 0=PythPull، 1=Switchboard
}
```

### قارئ الدُفعات

اقرأ عدة موجّهات في استدعاء واحد:

```solidity
BatchReader reader = BatchReader(0x70da375e5680f84032f5b15d35ba0e6f9871d3fd);

address[] memory adapters = new address[](3);
adapters[0] = solUsdAdapter;
adapters[1] = btcUsdAdapter;
adapters[2] = ethUsdAdapter;

// يعيد مصفوفة من (adapter, answer, updatedAt, success)
// موجّه قديم واحد لا يؤدي إلى فشل الدُفعة كلها
reader.getLatestPrices(adapters);
```

## الحماية من التقادم

يفرض المحوّلان معلمة `maxStaleness` . إذا كان `block.timestamp - publishTime > maxStaleness`، فسيؤدي الاستدعاء إلى فشل مع `StalePriceFeed()`. القيمة الافتراضية: 60 ثانية.

يمكن لمالك المصنع تعديل حدّ التقادم لكل محوّل أو على مستوى عام:

```solidity
factory.setDefaultMaxStaleness(120); // دقيقتان
```

## العناوين المنشورة (Devnet)

| العقد                       | العنوان                                      |
| --------------------------- | -------------------------------------------- |
| OracleAdapterFactory        | `0xa4647955a16b72d15f13b51b5277036755d297be` |
| PythPullAdapter (impl)      | `0x4fd11aed44ee5f71df22fb804cfcbb4c50535db9` |
| SwitchboardV3Adapter (impl) | `0xb57e3589b880aa3f6b66ce2df6aa42cd9c36925e` |
| BatchReader                 | `0x70da375e5680f84032f5b15d35ba0e6f9871d3fd` |
| SOL/USD (Switchboard)       | `0xF0864572019c295407CF2ed46e6FD3615e10E19d` |

انظر [عناوين العقود](/ar/almrja/contract-addresses.md) للاطلاع على القائمة الكاملة.

## القيود

* **لا توجد بيانات تاريخية للجولات** — `getRoundData(roundId)` يفشل مع `HistoricalRoundsNotSupported()`
* **EMA الخاص بـ Switchboard غير مدعوم** — `latestEMAData()` يفشل على محوّلات Switchboard
* **تم التحقق تجريبيًا من إزاحات المحلّل** — يجب إعادة التحقق باستخدام نصوص التحقق قبل إعادة النشر مقابل إصدارات Pyth/Switchboard الجديدة
* **تطبيع الأسعار** — تُطبَّع أسعار Pyth على أنها `price * 10^(expo - (-8))`؛ وSwitchboard على أنها `(mantissa * 10^8) / 10^scale`

## الحالة

**تم إطلاق V1** (2026-04-01) — الإصدار V2 قيد التنفيذ مع حماية من التقادم، وقراءة دفعات، ومحوّل Switchboard، ونسخ EIP-1167 البديلة.

## ما التالي

* [عناوين العقود](/ar/almrja/contract-addresses.md) — جميع عناوين الأوراكل المنشورة
* [نشر Solidity](/ar/adlh-almtwryn/deploy-solidity.md) — نشر عقود تستخدم موجّهات الأوراكل


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rome.builders/ar/almntjat/oracle-gateway.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.