مستندات اوراکل

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: ۱ OPEN، ۲ CLOSED (آخرین قیمت رسمی، مثلاً در آخر هفته)، ۳ HALTED.
• spreadBps: اسپرد خرید و فروش بر حسب واحد پایه؛ با چند کارگزار، فاصله آن‌ها از هم را هم نشان می‌دهد.

پاسخ API شامل report (کدگذاری‌شده ABI) و signature (۶۵ بایت) است: دقیقاً دو آرگومان submit.

5. توابع قرارداد

• submit(PriceReport r, bytes sig) returns (bool): تأیید و ذخیره؛ اگر قیمتی برابر یا جدیدتر ذخیره شده باشد نادیده گرفته می‌شود.
• submitBatch(PriceReport[] rs, bytes[] sigs): چند فید در یک تراکنش؛ ورودی‌های نامعتبر رد می‌شوند.
• getPrice(bytes32 feedId): آخرین قیمت ذخیره‌شده و زمان آن؛ تا وقتی فید هنوز قیمتی ندارد revert می‌کند.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): revert می‌کند مگر بازار 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): سرویس امضا کوتاه‌مدت در دسترس نیست؛ با تأخیر فزاینده دوباره تلاش کنید.
• revertهای روی زنجیره: InvalidSignature (امضاکننده، زنجیره یا قرارداد اشتباه)، ReportExpired، FutureTimestamp، InvalidPrice، InvalidStatus، NoPrice (فید هنوز قیمتی ندارد)، FeedTripped (مدارشکن)، MarketNotOpen و PriceTooOld (از getPriceNoOlderThan)، IsPaused.

9. بهترین شیوه‌ها

• درست پیش از ارسال تراکنش گزارش را بگیرید؛ گزارش‌ها پس از حدود یک دقیقه منقضی می‌شوند.
• همیشه با getPriceNoOlderThan و حداکثر عمری متناسب با محصولتان بخوانید.
• بازارهای CLOSED (آخر هفته‌ها، تعطیلات) را صریحاً مدیریت کنید، مثلاً تسویه در باز شدن بعدی.
• ابتدا روی تست‌نت آزمایش کنید، سپس فقط نشانی قرارداد و شناسه زنجیره را تغییر دهید.
• کلیدهای API را روی سرور خودتان نگه دارید، هرگز در صفحه وب.