Oracle

Oracles are applications that produce data feeds that make off-chain data sources available to the blockchain for smart contracts. You can find a detailed overview of the concept of an oracle here.

Oracles on SpookySwap V3

All SpookySwap V3 pools serve as oracles, providing access to historical price and liquidity data, which opens up various on-chain use cases.

Historical data is organized as an array of observations. Initially, each pool tracks only a single observation, replacing it as new blocks are added. This limitation restricts users' access to historical data. However, any participant willing to cover the transaction fees can increase the number of tracked observations (up to a maximum of 65,535), thereby extending the availability of data to approximately nine days or more.

By storing price and liquidity history directly within the pool contract, the risk of logical errors from the calling contract is significantly minimized, and integration costs are reduced since there’s no need to maintain separate historical records. Moreover, the extensive maximum length of the V3 oracle makes it much harder to manipulate prices, allowing the calling contract to easily construct a time-weighted average over any chosen range, whether it fits within or fully spans the length of the oracle array.

Observations

Observations take the following form:

struct Observation {
    // the block timestamp of the observation
    uint32 blockTimestamp;
    // the tick accumulator, i.e. tick * time elapsed since the pool was first initialized
    int56 tickCumulative;
    // the seconds per liquidity, i.e. seconds elapsed / max(1, liquidity) since the pool was first initialized
    uint160 secondsPerLiquidityCumulativeX128;
    // whether or not the observation is initialized
    bool initialized;
}

Observations may be retrieved via the observations method on V3 pools. However, this is not the recommended way to consume oracle data. Instead, prefer observe:

function observe(uint32[] calldata secondsAgos)
    external
    view
    returns (int56[] memory tickCumulatives, uint160[] memory secondsPerLiquidityCumulativeX128s);

Each time observe is called, the caller must specify an array containing any number of seconds ago, denoting the times to return observations from. Note that each of the given times must be more recent (or as old as) the oldest stored observation. Note: If the times don't correspond exactly to a block in which an observation was written, a counterfactual observation will be constructed, removing the need for the caller to interpolate manually. This is one of the primary reasons to use observe over observations.

Keep in mind that because the oracle is only updated at most once every block, calling observe with a secondsAgo value of 0 will return the most recently written observation, which can only be as recent as the beginning of the current block (or older).

Tick Accumulator

The tick accumulator stores the cumulative sum of the active tick at the time of the observation. The tick accumulator value increases monotonically and grows by the value of the current tick per second.

To derive the arithmetic mean tick over an interval, the caller needs to retrieve two observations, one after the other, take the delta of the two values, and divide by the time elapsed between them. Calculating a TWAP from the tick accumulator is also covered in the whitepaper. Note that using an arithmetic mean tick to derive a price corresponds to a geometric mean price.

See Oracle Library for an example of how to use the tick accumulator.

Liquidity Accumulator

The liquidity accumulator stores the value of seconds / in-range liquidity at the time of the observation. The liquidity accumulator value increases monotonically and grows by the value of seconds / in-range liquidity - per second.

To derive the harmonic mean liquidity over an interval, the caller needs to retrieve two observations, one after the other, take the delta of the two values, then divide the time elapsed by this value. Calculating TWAL is addressed in finer detail in the whitepaper.

Advanced Oracles

SpookySwap V2 introduced time-weighted average price (TWAP) oracles, which have become a vital component of decentralized finance (DeFi) infrastructure. These oracles have been integrated into numerous projects, such as Compound and Reflexer.

In V2, oracles function by storing cumulative sums of SpookySwap pair prices on a per-second basis. By checking these price sums at the beginning and end of a specified period, users can accurately calculate the TWAP for that time frame.

SpookySwap V3 significantly enhances the TWAP oracle functionality, enabling the calculation of any recent TWAP from the past approximately nine days with a single on-chain call. This improvement is made possible by storing an array of cumulative sums instead of a single value.

This array of historical price accumulators facilitates the creation of more sophisticated oracles, allowing for the inclusion of features such as simple moving averages (SMA), exponential moving averages (EMA), and outlier filtering, among others.

Notably, the gas costs for SpookySwap traders to maintain these oracles have been reduced by around 50% compared to V2. Additionally, the expenses associated with calculating TWAPs in external smart contracts have also become significantly more affordable.