Best practices

Validation patterns, health status API, staleness checks, and an integration checklist for safely consuming Chiliz Chain price feeds.

Always Validate Before Using a Price

latestRoundData() reverts with NoDataAvailable() if no rounds exist, but does not enforce staleness or pause checks: it returns stored values as-is. Before consuming any price value, always perform these three checks:

1. Pause check: call paused() and reject if the feed is paused.

2. Positive answer: require answer > 0.

3. Staleness check: gate on getHealthStatus().isHealthy.

The getSafePrice() example in Reading Prices implements all three.

Health Status API

Each PriceFeed exposes a getHealthStatus() view that aggregates freshness information in a single call:

function getHealthStatus()
    external view
    returns (
        uint256 lastUpdateTimestamp,
        uint256 totalRounds,
        uint256 timeSinceLastUpdate,
        bool isHealthy
    );

Field	Description
lastUpdateTimestamp	updatedAt of the most recent round
totalRounds	Total number of rounds written
timeSinceLastUpdate	block.timestamp - lastUpdateTimestamp (or block.timestamp if no data)
isHealthy	true if timeSinceLastUpdate <= updateInterval × healthFactor

The health factor is initialised to 2 by default but is configurable per feed by the oracle admin via setHealthFactor(). Do not hardcode 2. Read it directly from the contract:

uint80 factor = priceFeed.healthFactor(); // per-feed; do NOT assume the default of 2 (live feeds use 720)

The health window is updateInterval × healthFactor, both configured per feed. updateInterval is a small on-chain minimum spacing, not the heartbeat. It varies per feed: CHZ/USDC uses 5s × 720 = 1-hour window, PEPPER/CHZ uses 10s × 720 = 2-hour window, while the off-chain pipeline pushes on a ~1-hour heartbeat. Never use updateInterval alone as a staleness baseline; gate on isHealthy. See getSafePrice() in Reading Prices for the full pattern.

Use getAllOracleHealthStatus() on the OracleFactoryReader to monitor every feed in the system at once (useful for off-chain dashboards and alerting).

Cache decimals()

Each pair has its own decimal precision: always call decimals() to confirm before interpreting a price value. Decimals are set at deployment and never change, so read them once at contract initialisation rather than on every price read:

uint8 public immutable feedDecimals;

constructor(address _feed) {
    priceFeed = IChilizPriceFeed(_feed);
    feedDecimals = priceFeed.decimals();
}

Handle the Paused State Gracefully

In an emergency, the oracle manager can pause a feed. Handle the resulting revert cleanly rather than silently consuming a bad value:

require(!priceFeed.paused(), "Feed paused");

Use the Tracker During Development

The Price Oracle Tracker lets you compare on-chain prices against CoinMarketCap and CoinGecko in real time, making it easy to validate feed accuracy during integration. It also shows live health status, heartbeat parameters, and individual contract addresses for every pair.

Integration Checklist

• Obtain the PriceFeed address via the tracker, pairToOracle(), or getActiveOracles()

• Confirm the pair description and decimals using description() and decimals()

• Cache decimals() at contract initialisation

• Read prices via latestRoundData() (reverts with NoDataAvailable() if no rounds exist yet)

• Check paused() before consuming a price

• Validate answer > 0

• Gate on getHealthStatus().isHealthy for staleness (do not derive your own threshold from updateInterval alone)

• Normalise the price to your internal precision (e.g. 18 decimals) if needed

• Test on Spicy Testnet before deploying to Mainnet