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:

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):

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.