# Deterministic Oracles

### Overview

A **Deterministic Oracle** is a predictable lower-bound evaluation mechanism that always returns the same output for the same input.\
In Napier, it serves two main purposes:

* **PT Lower-Bound Pricing:**\
  Provides a time-based function that converges to 1 (face value) at maturity, offering a conservative reference for collateral valuation and liquidation logic.
* **LP Lower-Bound Pricing:**\
  A conservative time-consistent model for LP value estimation (the **LP Linear Discount** model).

### Supported Variants

* **PT Variant**\
  Uses the annual slope parameter `rateBps` (basis points) to apply a **linear time-based discount** on PT valuation.\
  The discount rate increases linearly as maturity approaches, and the price is **clipped at 1.0** upon maturity.
* **LP Variant**\
  Extends the PT linear discount logic to LPs, providing a **conservative, time-consistent valuation** of LP tokens. The LP price is also **clipped at 1.0** as an upper bound to prevent overvaluation.

### Argument Specification

The encoded arguments used when initializing the oracle are as follows:

```solidity
bytes memory args = abi.encode(
  address(pool),          
  address(principalToken),
  address(base),          
  uint16 rateBps          
);
```

| Parameter        | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `pool`           | The pool or market being evaluated                                                |
| `principalToken` | The target PT (Principal Token)                                                   |
| `base`           | The reference asset used for price expression (either SY or the underlying asset) |
| `rateBps`        | The annual linear slope in basis points (`bps`), where `10000 = 100% per year`    |

### Formula

```
SECONDS_PER_YEAR = 365 * 24 * 60 * 60
t: current timestamp (unix seconds)
maturity: maturity timestamp (unix seconds)
rateWad = rateBps * 1e14
```

**Discount factor** (in WAD, where `1e18 = 1.0`):

```solidity
discountWad = min(
  1e18,
  1e18 - ((maturity - t) * rateWad) / SECONDS_PER_YEAR
);
```

* When `t >= maturity`, `discountWad = 1e18`
* **Lower-bound PT price (assuming face value = 1):**\
  `pricePT_lower = discountWad`

### Design Considerations

* **Conservative Valuation:**\
  The model always produces a value that may be lower than the market price — it serves as a **lower-bound guide**.
* **Parameter Responsibility:**\
  Setting `rateBps` too high results in overly conservative (strict) valuations.
* **Boundary Conditions:**\
  Handle maturity crossover correctly, maintain consistency in seconds-to-year conversion, and unify WAD/decimal precision.
* **Intended Usage:**\
  In production, this oracle should be used **in conjunction with TWAP-based rate or price oracles** and **risk-control mechanisms**, serving as a **sanity boundary** rather than a standalone pricing source.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.napier.finance/learn/protocols/markets-napier-amm/oracles/deterministic-oracles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.