ITWAPOracle

Title: ITWAPOracle

Author: Modified from Uniswap V2 (https://github.com/Uniswap/v2-periphery/blob/master/contracts/examples/ExampleSlidingWindowOracle.sol)

Interface for the TWAPOracle Diamond facet.

Implements a Uniswap V2-style time-weighted average price oracle. Any address can call recordObservation to push a new snapshot; consult then computes the TWAP over the requested window from the stored history.

Functions

getPair

Returns the address of the Uniswap V2 pair registered under key.

function getPair(bytes32 key) external view returns (address pair);

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.

Returns

Name	Type	Description
pair	`address`

getLatestObservation

Returns the most recently recorded observation for a pair.

function getLatestObservation(bytes32 key) external view returns (Observation memory);

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.

Returns

Name	Type	Description
<none>	`Observation`

consult

Computes the TWAP over the last windowSeconds for a registered pair.

Selects the oldest observation that is at least windowSeconds old and computes (cumulativeNow - cumulativeOld) / (timestampNow - timestampOld).

function consult(bytes32 key, uint32 windowSeconds) external view returns (uint256 price0Twap, uint256 price1Twap);

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.
windowSeconds	`uint32`	The desired TWAP window in seconds.

Returns

Name	Type	Description
price0Twap	`uint256`	TWAP of token0 over the window (UQ112x112 fixed-point).
price1Twap	`uint256`	TWAP of token1 over the window (UQ112x112 fixed-point).

registerPair

Registers a Uniswap V2 pair under the given key and records an initial observation.

Caller must hold DEFAULT_ADMIN_ROLE. Re-registering an existing key discards its stored observations and starts a fresh history.

function registerPair(bytes32 key, address pair) external;

Parameters

Name	Type	Description
key	`bytes32`	Arbitrary identifier for this pair.
pair	`address`	Address of the IUniswapV2Pair contract.

unregisterPair

Removes a registered pair and all its stored observations.

Caller must hold DEFAULT_ADMIN_ROLE.

function unregisterPair(bytes32 key) external;

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier to remove.

recordObservation

Records a new cumulative price observation for the pair.

Open to any caller to allow permissionless oracle maintenance.

function recordObservation(bytes32 key) external;

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.

Events

PairRegistered

Emitted when a Uniswap V2 pair is registered.

event PairRegistered(bytes32 indexed key, address pair);

Parameters

Name	Type	Description
key	`bytes32`	Arbitrary identifier for this pair.
pair	`address`	Address of the IUniswapV2Pair contract.

PairUnregistered

Emitted when a pair is unregistered.

event PairUnregistered(bytes32 indexed key);

Parameters

Name	Type	Description
key	`bytes32`	The identifier of the removed pair.

ObservationRecorded

Emitted when a new cumulative price observation is recorded.

event ObservationRecorded(
        bytes32 indexed key, uint32 timestamp, uint256 price0Cumulative, uint256 price1Cumulative
    );

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.
timestamp	`uint32`	Block timestamp of the observation.
price0Cumulative	`uint256`	Cumulative price of token0 at this timestamp.
price1Cumulative	`uint256`	Cumulative price of token1 at this timestamp.

Errors

TWAPZeroPair

registerPair was called with the zero address as the pair.

error TWAPZeroPair();

TWAPPairNotRegistered

No pair is registered under the given key.

error TWAPPairNotRegistered(bytes32 key);

Parameters

Name	Type	Description
key	`bytes32`

TWAPInsufficientHistory

Fewer than two observations have been recorded; cannot compute TWAP.

error TWAPInsufficientHistory(bytes32 key);

Parameters

Name	Type	Description
key	`bytes32`

TWAPWindowTooLarge

The requested TWAP window is larger than the oldest available observation.

error TWAPWindowTooLarge(uint32 requested, uint32 oldest);

Parameters

Name	Type	Description
requested	`uint32`	The requested window in seconds.
oldest	`uint32`	The age (seconds ago) of the oldest stored observation.

TWAPZeroWindow

consult was called with windowSeconds == 0.

A zero window would divide by elapsed time which may itself be zero, producing a division-by-zero panic.

error TWAPZeroWindow();

TWAPStaleObservation

The newest stored observation is too old to satisfy the request.

Guards against returning a confidently-priced but stale TWAP when recording stopped long ago. consult reverts when block.timestamp - newestTimestamp > windowSeconds, i.e. the freshest data point does not even fall within the requested window.

error TWAPStaleObservation(uint32 newestTimestamp, uint32 currentTimestamp);

Parameters

Name	Type	Description
newestTimestamp	`uint32`	Timestamp of the most recent observation.
currentTimestamp	`uint32`	The current block timestamp.

TWAPElapsedZero

The usable time span between the selected observations is zero.

Prevents a division-by-zero panic (0x12) when the newest and the base observation share a timestamp (e.g. the oldest and newest observations carry the same timestamp). Reverts with a clear error instead.

error TWAPElapsedZero(bytes32 key);

Parameters

Name	Type	Description
key	`bytes32`	The pair identifier.

Structs

Observation

A single cumulative price snapshot.

struct Observation {
        /// @notice Block timestamp when this snapshot was taken (mod 2**32).
        uint32 timestamp;
        /// @notice Cumulative price of token0 at `timestamp`.
        uint256 price0Cumulative;
        /// @notice Cumulative price of token1 at `timestamp`.
        uint256 price1Cumulative;
    }

Properties

Name	Type	Description
timestamp	`uint32`
price0Cumulative	`uint256`
price1Cumulative	`uint256`