> For the complete documentation index, see [llms.txt](https://docs.napier.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.napier.finance/learn/protocols/markets-napier-amm/oracles/deterministic-oracles.md).

# 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.