Skip to main content
Version: V3

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:

NameTypeDescription
selfstruct Oracle.Observation[65535]The stored oracle array
timeuint32The time of the oracle initialization, via block.timestamp truncated to uint32

Return Values:

NameTypeDescription
cardinalityuint16The number of populated elements in the oracle array
cardinalityNextuint16The 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:

NameTypeDescription
selfstruct Oracle.Observation[65535]The stored oracle array
indexuint16The location of the most recently updated observation
blockTimestampuint32The timestamp of the new observation
tickint24The active tick at the time of the new observation
liquidityuint128The total in-range liquidity at the time of the new observation
cardinalityuint16The number of populated elements in the oracle array
cardinalityNextuint16The new length of the oracle array, independent of population

Return Values:

NameTypeDescription
indexUpdateduint16The new index of the most recently written element in the oracle array
cardinalityUpdateduint16The 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:

NameTypeDescription
selfstruct Oracle.Observation[65535]The stored oracle array
currentuint16The current next cardinality of the oracle array
nextuint16The proposed next cardinality which will be populated in the oracle array

Return Values:

NameTypeDescription
nextuint16The 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:

NameTypeDescription
selfstruct Oracle.Observation[65535]The stored oracle array
timeuint32The current block.timestamp
secondsAgosuint32[]Each amount of time to look back, in seconds, at which point to return an observation
tickint24The current tick
indexuint16The location of a given observation within the oracle array
liquidityuint128The current in-range pool liquidity
cardinalityuint16The number of populated elements in the oracle array

Return Values:

NameTypeDescription
tickCumulativesint56[]The tick * time elapsed since the pool was first initialized, as of each secondsAgo
liquidityCumulativesuint160[]The liquidity * time elapsed since the pool was first initialized, as of each secondsAgo