🔮Oracles & Settlement

Oracles

Oracles are the core of each market within Perennial. Each market pulls in one or more prices from oracles to be used in the payoff function.

While a simple market will just use a single price feed (ex. ETH), more complex market could use payoffs with multiple price feeds (ex. ETH / BTC).

Perennial's modular design supports custom oracles. Currently, Perennial markets use an implementation of Pyth's low latency oracles, allowing for fast & efficient price updates.

Settlement

Since the market payoff is computed directly from the oracle price, a lag needs to introduced into the settlement system so that entering and exiting positions cannot be timed to arbitrage the market.

Time in Perennial markets is split into units called oracle versions. Settlement only occurs on the transition of one oracle version to another. When a user requests to open or close a new position, that position delta sits in a pending state until the next oracle version update, after which it takes effect.

Settlement Flow:

In this example: the user calls open(10) at during oracle version 1, and close(10) during oracle version 3. The user's position opens at the start of version 2 and closes at the start of version 4, meaning they are exposed to the price difference between versions 2 and 4.

Oracle Version	User Action	Pending	Oracle Price	Position (Profit/loss)
1	Open 1 ETH	Opening: 10 Closing: 0	$1000	- (0)
2		Opening: 0 Closing: 0	$1025	1 ETH (0)
3	Close 1 ETH	Opening: 0 Closing: 10	$1075	1 ETH (+$50)
4		Opening: 0 Closing: 0	$1050	- (+$25)

Developer Note: The settlement flow happens entirely on-chain, giving strong guarantees for projects building on top of Perennial.

Perennial smart contracts store the current version for position adjustments, allowing for the positions opening price & PnL to be retroactively calculated at the next on-chain settlement period (when the contracts are interacted with again), avoiding the need for a second interaction during opens/closing (or the need for a keeper).