> For the complete documentation index, see [llms.txt](https://docs.linxlabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.linxlabs.org/lending-technical-documentation/oracles.md).

# Oracles

#### **What is the oracle role**

Lending protocols operate on a fundamental question: "How much can I safely lend against this collateral?" Answering this requires knowing the relative value between two assets - and blockchains don't have this information natively.

This is where oracles come in. An oracle is a smart contract that provides external price data to on-chain applications. For Linx Lending, oracles answer questions like:

* "What is 1 ALPH worth in USDT right now?"
* "How many USDC equals 1 BTC?"

Without accurate pricing, the protocol cannot:

* Determine if a borrower has sufficient collateral
* Calculate how much can be safely borrowed
* Identify when positions should be liquidated
* Maintain protocol solvency

#### **Oracle-Agnostic Architecture**

Linx takes a flexible approach to pricing: each market creator chooses their preferred oracle implementation. There is no single "official" oracle - instead, Linx provides a standard interface that any pricing mechanism can implement.

This design enables:

* **Asset-specific solutions**: Use the best pricing source for each token pair
* **Innovation**: New oracle designs can be deployed without protocol upgrades
* **Diversification**: Different markets can use different pricing approaches
* **Long-tail support**: Exotic assets can use specialized oracles

#### **The Oracle Interface**

All Linx-compatible oracles implement a standardized interface in Ralph:

```ralph
pub fn price() -> U256
```

This function returns the price of one unit of collateral denominated in the loan token, properly scaled to account for token decimal differences.

#### **Oracle Categories**

Different asset types require different pricing approaches:

**Price Feed Oracles** Consume external data from off-chain sources and publish on-chain prices. Common providers include Chainlink, Pyth, DIA, API3.

*Best for:* Liquid assets with established markets (BTC, ETH, ALPH, major tokens)

**Exchange Rate Oracles** Calculate deterministic rates between related assets, like wrapped or staked versions of tokens.

*Best for:* Derivative tokens (wrapped tokens, liquid staking tokens, yield-bearing tokens)

*Example:* An oracle for sALPH/ALPH could query the staking contract directly for the exchange rate.

**Fixed Rate Oracles** Return constant exchange rates for assets with known pegs.

*Best for:* Stablecoin pairs (USDT/USDC), same-asset markets

*Example:* A USDT/USDC oracle might always return 1.0 (with proper scaling)

**Composite Oracles** Combine multiple price sources through routing or aggregation.

*Best for:* Assets without direct price feeds, requiring multiple hops

*Example:* Pricing TokenA/USDT when only TokenA/ALPH and ALPH/USDT feeds exist

#### **Oracle Selection & Market Creation**

When creating a Linx Market, the creator specifies the oracle contract address as one of the five immutable parameters:

```
CollateralToken/LoanToken (LLTV%, OracleContract, IRM)
```

This choice is permanent. The oracle cannot be changed after market deployment, making selection critical to market safety and functionality.

**Market creators should consider:**

* Price source reliability and manipulation resistance
* Update frequency and staleness protection
* Decimal handling and scaling accuracy

#### **Due Diligence for Users**

The immutable nature of Linx Markets means oracle choice defines permanent risk characteristics. Before supplying or borrowing:

1. **Verify the oracle contract address** in the market parameters
2. **Review the oracle's source code** and implementation logic
3. **Understand the pricing methodology** being used
4. **Check for audits or security reviews** of the oracle
5. **Consider historical reliability** if the oracle has been deployed before

Remember: Market creators, not the Linx Lending protocol, are responsible for oracle selection. Each market's safety depends on its oracle quality.