Meilleures pratiques

Schémas de validation, API health status, vérifications d'obsolescence et checklist d'intégration pour consommer les flux de prix Chiliz Chain en toute sécurité.

Toujours valider avant d'utiliser un prix

latestRoundData() génère un revert avec NoDataAvailable() si aucun round n'existe, mais n'applique pas de vérifications d'obsolescence ou de pause — il retourne les valeurs stockées telles quelles. Avant de consommer une valeur de prix, effectuez toujours ces trois vérifications :

1. Vérification de pause : appelez paused() et rejetez si le flux est en pause.

2. Réponse positive : exigez answer > 0.

3. Vérification d'obsolescence : conditionnez à getHealthStatus().isHealthy.

L'exemple getSafePrice() dans Lecture des prix implémente les trois.

API Health Status

Chaque PriceFeed expose une vue getHealthStatus() qui agrège les informations de fraîcheur en un seul appel :

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

Champ	Description
lastUpdateTimestamp	updatedAt du round le plus récent
totalRounds	Nombre total de rounds écrits
timeSinceLastUpdate	block.timestamp - lastUpdateTimestamp (ou block.timestamp si aucune donnée)
isHealthy	true si timeSinceLastUpdate <= updateInterval × healthFactor

Le health factor est initialisé à 2 par défaut mais est configurable par flux par l'admin oracle via setHealthFactor(). Ne codez pas 2 en dur — lisez-le directement depuis le contrat :

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

La fenêtre de santé est updateInterval × healthFactor, tous deux configurés par flux — updateInterval est un espacement minimum on-chain minimal, pas le heartbeat. Il varie selon le flux : CHZ/USDC utilise 5s × 720 = fenêtre d'1 heure, PEPPER/CHZ utilise 10s × 720 = fenêtre de 2 heures, tandis que le pipeline off-chain publie selon un heartbeat d'environ 1 heure. N'utilisez jamais updateInterval seul comme référence d'obsolescence — conditionnez à isHealthy — consultez getSafePrice() dans Lecture des prix pour le schéma complet.

Utilisez getAllOracleHealthStatus() sur l'OracleFactoryReader pour surveiller chaque flux du système en même temps — utile pour les tableaux de bord off-chain et les alertes.

Mettre en cache decimals()

Chaque paire a sa propre précision décimale — appelez toujours decimals() pour confirmer avant d'interpréter une valeur de prix. Les décimales sont définies au déploiement et ne changent jamais, lisez-les donc une fois à l'initialisation du contrat plutôt qu'à chaque lecture de prix :

uint8 public immutable feedDecimals;

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

Gérer l'état en pause gracieusement

En cas d'urgence, le gestionnaire d'oracle peut mettre un flux en pause. Gérez le revert résultant proprement plutôt que de consommer silencieusement une mauvaise valeur :

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

Utiliser le Tracker pendant le développement

Le Price Oracle Tracker vous permet de comparer les prix on-chain avec CoinMarketCap et CoinGecko en temps réel, ce qui facilite la validation de la précision du flux lors de l'intégration. Il affiche également l'état de santé en direct, les paramètres de heartbeat et les adresses de contrat individuelles pour chaque paire.

Checklist d'intégration

• Obtenir l'adresse du PriceFeed via le tracker, pairToOracle(), ou getActiveOracles()

• Confirmer la description et les décimales de la paire avec description() et decimals()

• Mettre en cache decimals() à l'initialisation du contrat

• Lire les prix via latestRoundData() (génère un revert avec NoDataAvailable() si aucun round n'existe encore)

• Vérifier paused() avant de consommer un prix

• Valider answer > 0

• Conditionner à getHealthStatus().isHealthy pour l'obsolescence (ne pas dériver votre propre seuil depuis updateInterval seul)

• Normaliser le prix à votre précision interne (p. ex. 18 décimales) si nécessaire

• Tester sur le Spicy Testnet avant de déployer sur le Mainnet