Najlepsze praktyki

Wzorce walidacji, API stanu zdrowia, sprawdzanie nieaktualności oraz lista kontrolna integracji dla bezpiecznego korzystania z feedów cenowych Chiliz Chain.

Zawsze waliduj przed użyciem ceny

latestRoundData() revertuje z NoDataAvailable(), jeśli nie istnieją żadne rundy, ale nie wymusza sprawdzenia nieaktualności ani pauzy — zwraca przechowywane wartości bez zmian. Przed skonsumowaniem jakiejkolwiek wartości cenowej zawsze wykonuj te trzy sprawdzenia:

1. Sprawdzenie pauzy: wywołaj paused() i odrzuć, jeśli feed jest wstrzymany.

2. Dodatnia wartość: wymagaj answer > 0.

3. Sprawdzenie nieaktualności: warunkuj na getHealthStatus().isHealthy.

Przykład getSafePrice() w Odczytywanie cen implementuje wszystkie trzy.

API stanu zdrowia

Każdy PriceFeed udostępnia widok getHealthStatus(), który agreguje informacje o świeżości danych jednym wywołaniem:

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

Pole	Opis
lastUpdateTimestamp	updatedAt ostatniej rundy
totalRounds	Łączna liczba zapisanych rund
timeSinceLastUpdate	block.timestamp - lastUpdateTimestamp (lub block.timestamp, jeśli brak danych)
isHealthy	true, jeśli timeSinceLastUpdate <= updateInterval × healthFactor

Współczynnik zdrowia (health factor) jest domyślnie inicjalizowany na 2, ale jest konfigurowalny per feed przez administratora oracle za pomocą setHealthFactor(). Nie wpisuj na stałe 2 — odczytaj go bezpośrednio z kontraktu:

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

Okno zdrowia to updateInterval × healthFactor, oba skonfigurowane per feed — updateInterval to małe on-chain minimalne odstępy, a nie heartbeat. Różni się per feed: CHZ/USDC używa 5s × 720 = 1 godzina okna, PEPPER/CHZ używa 10s × 720 = 2 godziny okna, podczas gdy potok off-chain wysyła z częstotliwością ~1 godziny heartbeat. Nigdy nie używaj samego updateInterval jako podstawy nieaktualności — warunkuj na isHealthy — patrz getSafePrice() w Odczytywanie cen po pełny wzorzec.

Użyj getAllOracleHealthStatus() na OracleFactoryReader, aby monitorować każdy feed w systemie jednocześnie — przydatne dla dashboardów off-chain i alertowania.

Buforuj decimals()

Każda para ma własną precyzję dziesiętną — zawsze wywołuj decimals(), aby potwierdzić przed interpretacją wartości cenowej. Decimals są ustawiane przy wdrożeniu i nigdy się nie zmieniają, więc odczytaj je raz przy inicjalizacji kontraktu zamiast przy każdym odczycie ceny:

uint8 public immutable feedDecimals;

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

Obsługuj stan pauzy w sposób elegancki

W sytuacji awaryjnej menedżer oracle może wstrzymać feed. Obsługuj wynikający z tego revert w sposób przejrzysty, zamiast po cichu konsumować błędną wartość:

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

Używaj Trackera podczas developmentu

Price Oracle Tracker pozwala porównywać ceny on-chain z CoinMarketCap i CoinGecko w czasie rzeczywistym, ułatwiając weryfikację dokładności feedu podczas integracji. Pokazuje też na żywo stan zdrowia, parametry heartbeat oraz indywidualne adresy kontraktów dla każdej pary.

Lista kontrolna integracji

• Uzyskaj adres PriceFeed przez tracker, pairToOracle() lub getActiveOracles()

• Potwierdź opis pary i decimals używając description() i decimals()

• Buforuj decimals() przy inicjalizacji kontraktu

• Odczytuj ceny przez latestRoundData() (revertuje z NoDataAvailable(), jeśli rundy jeszcze nie istnieją)

• Sprawdź paused() przed skonsumowaniem ceny

• Zwaliduj answer > 0

• Warunkuj na getHealthStatus().isHealthy w kwestii nieaktualności (nie wywodź własnego progu z samego updateInterval)

• Normalizuj cenę do wewnętrznej precyzji (np. 18 decimals), jeśli potrzeba

• Przetestuj na Spicy Testnet przed wdrożeniem na Mainnet