توثيق الأوراكل

1. كيف يعمل

1. تطلب الواجهة الخلفية لديك تقريرًا موقّعًا: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (مفتاح API بنطاق read:oracle؛ يُحتسب لكل تقرير موقّع).
2. تمرّر معاملتك التقرير والتوقيع إلى عقد التحقق، الذي يتحقق من توقيع EIP-712 وانتهاء الصلاحية والسلسلة وقاطع الدارة الخاص به، ثم يخزّن السعر.
3. في المعاملة نفسها يقرأ عقدك السعر مع شرط الحداثة. يستخدم نمط السحب هذا السعر الحالي دائمًا.

تُدفع الأسعار المطلوبة عبر الـ API أيضًا إلى السلسلة تلقائيًا من حين لآخر، لكن لا تعتمد أبدًا على سعر مخزَّن دون فحص حداثته.

2. الشبكات والعقود

عنوان المُوقِّع: 0x83fa2d8836525251FAd214A78A72038D0864f877. شبكات الاختبار مخصصة للاختبار المجاني دون ضمانات للخدمة.

3. المصادر

لكل مصدر معرّف دائم: feedId = keccak256(symbol). وتستخدم الأسعار 8 منازل عشرية.

4. التقرير الموقّع

نطاق EIP-712: الاسم MarketAPI Oracle، والإصدار 2، ومعرّف السلسلة، وعنوان عقد التحقق. النوع:

PriceReport(bytes32 feedId,int256 price,uint64 timestamp,uint64 validUntil,uint8 marketStatus,uint32 spreadBps)

• price: السعر الأوسط بـ 8 منازل عشرية.
• timestamp: وقت السعر (بثواني UTC)؛ validUntil: تنتهي صلاحية التقرير بعد نحو دقيقة.
• marketStatus: 1 OPEN، 2 CLOSED (السعر الرسمي الأخير، مثلًا في عطلات نهاية الأسبوع)، 3 HALTED.
• spreadBps: فارق العرض والطلب بنقاط الأساس؛ ومع عدة وسطاء يعكس أيضًا مدى تباعدهم.

يحتوي رد الـ API على report (مرمَّز بـ ABI) وsignature (65 بايت): وهما بالضبط وسيطا submit.

5. دوال العقد

• submit(PriceReport r, bytes sig) returns (bool): تحقّق وخزّن؛ ويُتجاهَل إن كان هناك سعر مساوٍ أو أحدث مخزَّن.
• submitBatch(PriceReport[] rs, bytes[] sigs): عدة مصادر في معاملة واحدة؛ وتُتخطّى الإدخالات غير الصالحة.
• getPrice(bytes32 feedId): آخر سعر مخزَّن وطابعه الزمني؛ يُرجع (revert) ما دام المصدر بلا سعر بعد.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): يُرجع ما لم يكن السوق OPEN والسعر حديثًا بما يكفي. استخدمها لإجراءات التداول.

لكل مصدر قاطع دارة: القفزة الأكبر من حدّه توقف المصدر حتى تتم مراجعته.

6. مثال Solidity (نمط السحب)

interface IMarketApiOracle {
    struct PriceReport { bytes32 feedId; int256 price; uint64 timestamp; uint64 validUntil; uint8 marketStatus; uint32 spreadBps; }
    function submit(PriceReport calldata r, bytes calldata sig) external returns (bool);
    function getPriceNoOlderThan(bytes32 feedId, uint256 maxAge) external view returns (int256 price, uint64 timestamp);
}

contract GoldVault {
    IMarketApiOracle immutable oracle;
    bytes32 constant XAUUSD = keccak256("XAUUSD");
    constructor(IMarketApiOracle o) { oracle = o; }

    function settle(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);
        (int256 price, ) = oracle.getPriceNoOlderThan(XAUUSD, 60);   // reverts unless OPEN and at most 60 s old
        // ... use price (8 decimals)
    }
}

7. مثال JavaScript (ethers v6)

const res = await fetch("https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10",
  { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
const { data, refused } = await res.json();
if (!data.length) throw new Error(refused[0]?.reason);            // e.g. market closed or stale
const r = data[0];
const report = ethers.AbiCoder.defaultAbiCoder().decode(
  ["tuple(bytes32,int256,uint64,uint64,uint8,uint32)"], r.report)[0];
await vault.settle(report, r.signature);                          // your contract calls oracle.submit(...)

8. حالات الرفض والأخطاء

• تسرد إدخالات refused الرموز التي لم تُوقَّع مع السبب، مثل لا سعر موثوق الآن (STALE) أو سوق مغلق. ولا تُحتسب عليها رسوم.
• oracle_unavailable (503): خدمة التوقيع غير متاحة لفترة وجيزة؛ أعد المحاولة مع تأخير متزايد.
• حالات الإرجاع على السلسلة: InvalidSignature (مُوقِّع أو سلسلة أو عقد خاطئ)، وReportExpired، وFutureTimestamp، وInvalidPrice، وInvalidStatus، وNoPrice (لا سعر للمصدر بعد)، وFeedTripped (قاطع الدارة)، وMarketNotOpen وPriceTooOld (من getPriceNoOlderThan)، وIsPaused.

9. أفضل الممارسات

• اجلب التقرير قبيل إرسال المعاملة مباشرة؛ تنتهي صلاحية التقارير بعد نحو دقيقة.
• اقرأ دائمًا عبر getPriceNoOlderThan وبحد أقصى للعمر يناسب منتجك.
• تعامل صراحةً مع الأسواق المغلقة CLOSED (عطلات نهاية الأسبوع والعطل الرسمية)، مثلًا بالتسوية عند الافتتاح التالي.
• اختبر على شبكة الاختبار أولًا، ثم غيّر عنوان العقد ومعرّف السلسلة فقط.
• احتفظ بمفاتيح الـ API على خادمك، ولا تضعها أبدًا في صفحة ويب.