OracleLib

Title: OracleLib

Library for common oracle validation patterns.

Provides reusable functions for sequencer checks, staleness validation, and price validation.

Functions

checkSequencer

Check if the L2 sequencer is up and grace period has passed.

Skips check if sequencerFeed is address(0) (e.g., on L1 or testnets).

function checkSequencer(
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod
) internal view;

Parameters

Name	Type	Description
`sequencerFeed`	`AggregatorV3Interface`	The Chainlink sequencer uptime feed.
`gracePeriod`	`uint256`	The grace period in seconds after sequencer comes back up.

checkStaleness

Check if the oracle price is stale.

function checkStaleness(
    uint256 updatedAt,
    uint256 timeout
) internal view;

Parameters

Name	Type	Description
`updatedAt`	`uint256`	The timestamp when the price was last updated.
`timeout`	`uint256`	The maximum age in seconds for a valid price.

checkStalenessAt

Check staleness relative to a specific reference timestamp instead of block.timestamp.

function checkStalenessAt(
    uint256 updatedAt,
    uint256 timeout,
    uint256 referenceTime
) internal pure;

Parameters

Name	Type	Description
`updatedAt`	`uint256`	The timestamp when the price was last updated.
`timeout`	`uint256`	The maximum age in seconds for a valid price.
`referenceTime`	`uint256`	The timestamp to measure staleness against.

verifyHistoricalPrice

Verifies a caller-provided hint round is the correct price at a target timestamp.

Avoids backward traversal that breaks on Chainlink phase boundaries.

function verifyHistoricalPrice(
    AggregatorV3Interface feed,
    uint256 targetTimestamp,
    uint80 hintRoundId
) internal view returns (int256 price, uint256 updatedAt);

Parameters

Name	Type	Description
`feed`	`AggregatorV3Interface`	The Chainlink price feed.
`targetTimestamp`	`uint256`	The timestamp to look up the price for.
`hintRoundId`	`uint80`	The round ID that the caller claims was active at targetTimestamp.

Returns

Name	Type	Description
`price`	`int256`	The price at the target timestamp.
`updatedAt`	`uint256`	The timestamp of the round found.

getValidatedPrice

Get a validated price from an oracle with staleness and sequencer checks.

Reverts on zero or negative prices to prevent operations during oracle failures.

function getValidatedPrice(
    AggregatorV3Interface oracle,
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod,
    uint256 timeout
) internal view returns (uint256 price);

Parameters

Name	Type	Description
`oracle`	`AggregatorV3Interface`	The price oracle.
`sequencerFeed`	`AggregatorV3Interface`	The sequencer uptime feed (can be address(0) to skip).
`gracePeriod`	`uint256`	The sequencer grace period in seconds.
`timeout`	`uint256`	The staleness timeout in seconds.

Returns

Name	Type	Description
`price`	`uint256`	The validated price.

tryGetValidatedPrice

Non-reverting variant of getValidatedPrice for best-effort oracle reads.

function tryGetValidatedPrice(
    AggregatorV3Interface oracle,
    AggregatorV3Interface sequencerFeed,
    uint256 gracePeriod,
    uint256 timeout
) internal view returns (bool success, uint256 price);

Returns

Name	Type	Description
`success`	`bool`	True if the price passed all validation checks.
`price`	`uint256`	The validated price (0 if success is false).

Errors

OracleLib__SequencerDown

error OracleLib__SequencerDown();

OracleLib__SequencerGracePeriod

error OracleLib__SequencerGracePeriod();

OracleLib__StalePrice

error OracleLib__StalePrice();

OracleLib__InvalidPrice

error OracleLib__InvalidPrice();

OracleLib__NoPriceAtExpiry

error OracleLib__NoPriceAtExpiry();

OracleLib__InsufficientGas

error OracleLib__InsufficientGas();

Keyboard shortcuts