Smart Contract Integration

Integrating ORCAFI is designed to be plug-and-play compatible with standard Solidity patterns. Currently, we support BNB Chain (Mainnet and Testnet).

1. The Consumer Interface

To consume price data, your contract should reference the IOrcafiRouter interface. This provides a standardized way to fetch the latest round data.

IOrcafiRouter.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

interface IOrcafiRouter {
    struct PriceData {
        uint256 price;      // Price with 18 decimals
        uint256 conf;       // Confidence interval
        uint256 expo;       // Exponent (usually -18)
        uint256 timestamp;  // Unix timestamp of the update
    }

    /**
     * @notice Returns the latest price data for a given feed ID
     * @param feedId The unique identifier string (e.g., "ETH/USD")
     */
    function getLatestPrice(string calldata feedId) external view returns (PriceData memory);
}

2. System Architecture

The on-chain system consists of three core contracts working in tandem:

SourceRegistry: Manages approved data sources. Tracks metadata including Source Type (CEX/DEX), Reliability Score, and Active Status.
Aggregator: Validates submissions, enforces time-checks, and prevents replay attacks.
RiskOracle: The final output contract that consumers interact with. Stores price, confidence score, and risk classification.

3. Example Implementation

Below is a production-ready example of a user contract securely fetching the ETH/USD price.

MyDefiProtocol.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "./interfaces/IOrcafiRouter.sol";

contract MyDefiProtocol {
    IOrcafiRouter public immutable oracleRouter;
    
    // Safety: Max allowed time since last update (e.g., 1 hour)
    uint256 public constant MAX_STALE_TIME = 3600; 

    constructor(address _router) {
        oracleRouter = IOrcafiRouter(_router);
    }

    function getSafeEthPrice() public view returns (uint256) {
        // 1. Fetch data
        IOrcafiRouter.PriceData memory data = oracleRouter.getLatestPrice("ETH/USD");

        // 2. Freshness Check (CRITICAL)
        require(block.timestamp - data.timestamp < MAX_STALE_TIME, "Oracle: Stale price");

        // 3. Confidence Check (Optional but recommended)
        // If the spread/uncertainty is too high, pause operations
        require(data.conf < (data.price * 5 / 1000), "Oracle: Low confidence"); // 0.5% tolerance

        return data.price;
    }
}

4. Advanced Patterns

Gas Optimization

The getLatestPrice function is a view function and costs 0 gas when called externally. However, when called inside a state-changing transaction, it costs approximately 4,500 gas reading from storage.

Handling Decimals

All price feeds return values with 18 decimals standard (Wad), regardless of the asset's underlying decimals. This simplifies arithmetic operations in Solidity.

1 ETH = 3,000.00 USD ➔ 3000 * 10^18

5. Address Registry (Mainnet)

Use the following Router addresses for your deployments. These proxies are persistent and upgradable.

Network	Router Address
BNB Chain (Mainnet)	0x... (Pending Audit)
BNB Chain (Testnet)	0x... (Deployment Pending)

⚠️ Warning: Never hardcode the Router address in production if you plan to deploy on multiple chains. Pass it as a constructor argument.