> For the complete documentation index, see [llms.txt](https://docs.kwenta.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kwenta.io/using-kwenta/perennial-isolated-margin/perennial-intro/oracles.md).

# 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](https://pyth.network/) low latency oracles, allowing for fast & efficient price updates.

### Settlement <a href="#settlement" id="settlement"></a>

Since the [market payoff](https://docs.perennial.finance/protocol-design/payoff-and-positions) 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  | <p>Opening: 10</p><p>Closing: 0</p> | $1000        | - (0)                  |
| 2              |             | <p>Opening: 0</p><p>Closing: 0</p>  | $1025        | 1 ETH (0)              |
| 3              | Close 1 ETH | <p>Opening: 0</p><p>Closing: 10</p> | $1075        | 1 ETH (+$50)           |
| 4              |             | <p>Opening: 0</p><p>Closing: 0</p>  | $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).