Melhores práticas

Padrões de validação, API de status de saúde, verificações de desatualização e um checklist de integração para consumir feeds de preço da Chiliz Chain com segurança.

Sempre Valide Antes de Usar um Preço

latestRoundData() reverte com NoDataAvailable() se não existirem rounds, mas não impõe verificações de desatualização ou pausa — retorna os valores armazenados como estão. Antes de consumir qualquer valor de preço, sempre realize estas três verificações:

1. Verificação de pausa: chame paused() e rejeite se o feed estiver pausado.

2. Resposta positiva: exija que answer > 0.

3. Verificação de desatualização: condicione à getHealthStatus().isHealthy.

O exemplo getSafePrice() em Lendo Preços implementa todas as três.

API de Status de Saúde

Cada PriceFeed expõe uma view getHealthStatus() que agrega informações de atualidade em uma única chamada:

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

Campo	Descrição
lastUpdateTimestamp	updatedAt do round mais recente
totalRounds	Número total de rounds gravados
timeSinceLastUpdate	block.timestamp - lastUpdateTimestamp (ou block.timestamp se não houver dados)
isHealthy	true se timeSinceLastUpdate <= updateInterval × healthFactor

O health factor é inicializado em 2 por padrão, mas é configurável por feed pelo administrador do oracle via setHealthFactor(). Não fixe 2 no código — leia diretamente do contrato:

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

A janela de saúde é updateInterval × healthFactor, ambos configurados por feed — updateInterval é um espaçamento mínimo on-chain pequeno, não o heartbeat. Ele varia por feed: CHZ/USDC usa 5s × 720 = janela de 1 hora, PEPPER/CHZ usa 10s × 720 = janela de 2 horas, enquanto o pipeline off-chain envia em um heartbeat de ~1 hora. Nunca use updateInterval isoladamente como base para desatualização — condicione à isHealthy — veja getSafePrice() em Lendo Preços para o padrão completo.

Use getAllOracleHealthStatus() no OracleFactoryReader para monitorar todos os feeds do sistema de uma vez — útil para dashboards off-chain e alertas.

Faça Cache de decimals()

Cada par tem sua própria precisão decimal — sempre chame decimals() para confirmar antes de interpretar um valor de preço. Os decimais são definidos na implantação e nunca mudam, portanto, leia-os uma vez na inicialização do contrato em vez de a cada leitura de preço:

uint8 public immutable feedDecimals;

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

Trate o Estado de Pausa com Elegância

Em uma emergência, o administrador do oracle pode pausar um feed. Trate o revert resultante de forma limpa em vez de consumir silenciosamente um valor incorreto:

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

Use o Tracker Durante o Desenvolvimento

O Price Oracle Tracker permite comparar preços on-chain com o CoinMarketCap e o CoinGecko em tempo real, facilitando a validação da precisão do feed durante a integração. Ele também exibe o status de saúde ao vivo, parâmetros de heartbeat e endereços individuais dos contratos para todos os pares.

Checklist de Integração

• Obtenha o endereço do PriceFeed via tracker, pairToOracle() ou getActiveOracles()

• Confirme a descrição e os decimais do par usando description() e decimals()

• Faça cache de decimals() na inicialização do contrato

• Leia os preços via latestRoundData() (reverte com NoDataAvailable() se ainda não existirem rounds)

• Verifique paused() antes de consumir um preço

• Valide answer > 0

• Condicione à getHealthStatus().isHealthy para desatualização (não derive seu próprio limite apenas de updateInterval)

• Normalize o preço para a precisão interna do seu protocolo (ex.: 18 decimais) se necessário

• Teste no Spicy Testnet antes de implantar no Mainnet