Oracle

Provides price and liquidity data useful for a wide variety of system designs

Instances of stored oracle data, "observations", are collected in the oracle array Every pool is initialized with an oracle array length of 1. Anyone can pay the SSTOREs to increase the maximum length of the oracle array. New slots will be added when the array is fully populated. Observations are overwritten when the full length of the oracle array is populated. The most recent observation is available, independent of the length of the oracle array, by passing 0 to observe()

Functions#

initialize#

  function initialize(
    struct Oracle.Observation[65535] self,
    uint32 time
  ) internal returns (uint16 cardinality, uint16 cardinalityNext)

Initialize the oracle array by writing the first slot. Called once for the lifecycle of the observations array

Parameters:#

Name	Type	Description
`self`	struct Oracle.Observation[65535]	The stored oracle array
`time`	uint32	The time of the oracle initialization, via block.timestamp truncated to uint32

Return Values:#

Name	Type	Description
`cardinality`	uint16	The number of populated elements in the oracle array
`cardinalityNext`	uint16	The new length of the oracle array, independent of population

write#

  function write(
    struct Oracle.Observation[65535] self,
    uint16 index,
    uint32 blockTimestamp,
    int24 tick,
    uint128 liquidity,
    uint16 cardinality,
    uint16 cardinalityNext
  ) internal returns (uint16 indexUpdated, uint16 cardinalityUpdated)

Writes an oracle observation to the array

Writable at most once per block. Index represents the most recently written element. cardinality and index must be tracked externally. If the index is at the end of the allowable array length (according to cardinality), and the next cardinality is greater than the current one, cardinality may be increased. This restriction is created to preserve ordering.

Parameters:#

Name	Type	Description
`self`	struct Oracle.Observation[65535]	The stored oracle array
`index`	uint16	The location of the most recently updated observation
`blockTimestamp`	uint32	The timestamp of the new observation
`tick`	int24	The active tick at the time of the new observation
`liquidity`	uint128	The total in-range liquidity at the time of the new observation
`cardinality`	uint16	The number of populated elements in the oracle array
`cardinalityNext`	uint16	The new length of the oracle array, independent of population

Return Values:#

Name	Type	Description
`indexUpdated`	uint16	The new index of the most recently written element in the oracle array
`cardinalityUpdated`	uint16	The new cardinality of the oracle array

grow#

  function grow(
    struct Oracle.Observation[65535] self,
    uint16 current,
    uint16 next
  ) internal returns (uint16)

Prepares the oracle array to store up to next observations

Parameters:#

Name	Type	Description
`self`	struct Oracle.Observation[65535]	The stored oracle array
`current`	uint16	The current next cardinality of the oracle array
`next`	uint16	The proposed next cardinality which will be populated in the oracle array

Return Values:#

Name	Type	Description
`next`	uint16	The next cardinality which will be populated in the oracle array

observe#

  function observe(
    struct Oracle.Observation[65535] self,
    uint32 time,
    uint32[] secondsAgos,
    int24 tick,
    uint16 index,
    uint128 liquidity,
    uint16 cardinality
  ) internal view returns (int56[] tickCumulatives, uint160[] liquidityCumulatives)

Returns the accumulator values as of each time seconds ago from the given time in the array of secondsAgos

Reverts if secondsAgos > oldest observation

Parameters:#

Name	Type	Description
`self`	struct Oracle.Observation[65535]	The stored oracle array
`time`	uint32	The current block.timestamp
`secondsAgos`	uint32[]	Each amount of time to look back, in seconds, at which point to return an observation
`tick`	int24	The current tick
`index`	uint16	The location of a given observation within the oracle array
`liquidity`	uint128	The current in-range pool liquidity
`cardinality`	uint16	The number of populated elements in the oracle array

Return Values:#

Name	Type	Description
`tickCumulatives`	int56[]	The tick * time elapsed since the pool was first initialized, as of each `secondsAgo`
`liquidityCumulatives`	uint160[]	The liquidity * time elapsed since the pool was first initialized, as of each `secondsAgo`