IChainlinkOracle

Git Source

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Interface for the Quantillon Chainlink-based oracle

Exposes read methods for prices and health, plus admin/emergency controls

Note: security-contact: team@quantillon.money

Functions

initialize

Initializes the oracle with admin and feed addresses

Sets up the oracle with initial configuration and assigns roles to admin

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function initialize(address admin, address _eurUsdPriceFeed, address _usdcUsdPriceFeed, address _treasury) external;

Parameters

Name	Type	Description
`admin`	`address`	Address that receives admin and manager roles
`_eurUsdPriceFeed`	`address`	Chainlink EUR/USD feed address
`_usdcUsdPriceFeed`	`address`	Chainlink USDC/USD feed address
`_treasury`	`address`	Treasury address

getEurUsdPrice

Gets the current EUR/USD price with validation

Retrieves and validates EUR/USD price from Chainlink feed with freshness checks

Notes:

security: Validates timestamp freshness, circuit breaker status, price bounds
validation: Checks price > 0, timestamp < 1 hour old, within min/max bounds
state-changes: No state changes - view function only
events: No events emitted
errors: No errors thrown - returns fallback price if invalid
reentrancy: Not applicable - view function
access: Public - no access restrictions
oracle: Requires fresh Chainlink EUR/USD price feed data

function getEurUsdPrice() external returns (uint256 price, bool isValid);

Returns

Name	Type	Description
`price`	`uint256`	EUR/USD price in 18 decimals
`isValid`	`bool`	True if fresh and within acceptable bounds

getUsdcUsdPrice

Gets the current USDC/USD price with validation

Retrieves and validates USDC/USD price from Chainlink feed with tolerance checks

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function getUsdcUsdPrice() external view returns (uint256 price, bool isValid);

Returns

Name	Type	Description
`price`	`uint256`	USDC/USD price in 18 decimals (should be ~1e18)
`isValid`	`bool`	True if fresh and within tolerance

getOracleHealth

Returns overall oracle health signals

Checks the health status of both price feeds and overall oracle state

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function getOracleHealth() external returns (bool isHealthy, bool eurUsdFresh, bool usdcUsdFresh);

Returns

Name	Type	Description
`isHealthy`	`bool`	True if both feeds are fresh, circuit breaker is off, and not paused
`eurUsdFresh`	`bool`	True if EUR/USD feed is fresh
`usdcUsdFresh`	`bool`	True if USDC/USD feed is fresh

getEurUsdDetails

Detailed information about the EUR/USD price

Provides comprehensive EUR/USD price information including validation status

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function getEurUsdDetails()
    external
    returns (uint256 currentPrice, uint256 lastValidPrice, uint256 lastUpdate, bool isStale, bool withinBounds);

Returns

Name	Type	Description
`currentPrice`	`uint256`	Current price (may be fallback)
`lastValidPrice`	`uint256`	Last validated price stored
`lastUpdate`	`uint256`	Timestamp of last successful update
`isStale`	`bool`	True if the feed data is stale
`withinBounds`	`bool`	True if within configured min/max bounds

getOracleConfig

Current configuration and circuit breaker state

Returns current oracle configuration parameters and circuit breaker status

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function getOracleConfig()
    external
    view
    returns (
        uint256 minPrice,
        uint256 maxPrice,
        uint256 maxStaleness,
        uint256 usdcTolerance,
        bool circuitBreakerActive
    );

Returns

Name	Type	Description
`minPrice`	`uint256`	Minimum accepted EUR/USD price
`maxPrice`	`uint256`	Maximum accepted EUR/USD price
`maxStaleness`	`uint256`	Maximum allowed staleness in seconds
`usdcTolerance`	`uint256`	USDC tolerance in basis points
`circuitBreakerActive`	`bool`	True if circuit breaker is triggered

getPriceFeedAddresses

Addresses and decimals of the underlying feeds

Returns the addresses and decimal precision of both Chainlink price feeds

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function getPriceFeedAddresses()
    external
    view
    returns (address eurUsdFeedAddress, address usdcUsdFeedAddress, uint8 eurUsdDecimals, uint8 usdcUsdDecimals);

Returns

Name	Type	Description
`eurUsdFeedAddress`	`address`	EUR/USD feed address
`usdcUsdFeedAddress`	`address`	USDC/USD feed address
`eurUsdDecimals`	`uint8`	EUR/USD feed decimals
`usdcUsdDecimals`	`uint8`	USDC/USD feed decimals

checkPriceFeedConnectivity

Connectivity check for both feeds

Tests connectivity to both Chainlink price feeds and returns latest round information

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function checkPriceFeedConnectivity()
    external
    view
    returns (bool eurUsdConnected, bool usdcUsdConnected, uint80 eurUsdLatestRound, uint80 usdcUsdLatestRound);

Returns

Name	Type	Description
`eurUsdConnected`	`bool`	True if EUR/USD feed responds
`usdcUsdConnected`	`bool`	True if USDC/USD feed responds
`eurUsdLatestRound`	`uint80`	Latest round ID for EUR/USD
`usdcUsdLatestRound`	`uint80`	Latest round ID for USDC/USD

updatePriceBounds

Updates EUR/USD min and max acceptable prices

Updates the price bounds for EUR/USD validation with security checks

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function updatePriceBounds(uint256 _minPrice, uint256 _maxPrice) external;

Parameters

Name	Type	Description
`_minPrice`	`uint256`	New minimum price (18 decimals)
`_maxPrice`	`uint256`	New maximum price (18 decimals)

updateUsdcTolerance

Updates the allowed USDC deviation from $1.00 in basis points

Updates the USDC price tolerance for validation with security checks

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function updateUsdcTolerance(uint256 newToleranceBps) external;

Parameters

Name	Type	Description
`newToleranceBps`	`uint256`	New tolerance (e.g., 200 = 2%)

updatePriceFeeds

Updates Chainlink feed addresses

Updates the addresses of both Chainlink price feeds with validation

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function updatePriceFeeds(address _eurUsdFeed, address _usdcUsdFeed) external;

Parameters

Name	Type	Description
`_eurUsdFeed`	`address`	New EUR/USD feed
`_usdcUsdFeed`	`address`	New USDC/USD feed

resetCircuitBreaker

Clears circuit breaker and attempts to resume live prices

Resets the circuit breaker state to allow normal price operations

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function resetCircuitBreaker() external;

triggerCircuitBreaker

Manually triggers circuit breaker to use fallback prices

Activates circuit breaker to switch to fallback price mode for safety

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function triggerCircuitBreaker() external;

pause

Pauses all oracle operations

Pauses the oracle contract to halt all price operations

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function pause() external;

unpause

Unpauses oracle operations

Resumes oracle operations after being paused

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function unpause() external;

recoverToken

Recovers ERC20 tokens sent to the oracle contract by mistake

Allows recovery of ERC20 tokens accidentally sent to the oracle contract

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function recoverToken(address token, uint256 amount) external;

Parameters

Name	Type	Description
`token`	`address`	Token address to recover
`amount`	`uint256`	Amount to transfer

recoverETH

Recovers ETH sent to the oracle contract by mistake

Allows recovery of ETH accidentally sent to the oracle contract

Notes:

security: Validates input parameters and enforces security checks
validation: Validates input parameters and business logic constraints
state-changes: Updates contract state variables
events: Emits relevant events for state changes
errors: Throws custom errors for invalid conditions
reentrancy: Protected by reentrancy guard
access: Restricted to authorized roles
oracle: Requires fresh oracle price data

function recoverETH() external;

Keyboard shortcuts