Oracles

The price aggregator resolves external observations into USD prices for account valuation. The controller consumes these prices; the pool does not value assets in USD. A failed price check prevents valuation-dependent transactions from proceeding.

Configuration keys

An oracle is keyed by token or intermediate reference, rather than by hub or spoke:

enum PriceKey {
    Token(Address),
    Ref(Symbol),
}

Each key maps to an AssetOracle:

Field	Meaning and constraint
`sources`	One or two `PriceSource` entries; any other count returns `#231 SourceCountOutOfRange`.
`tolerance`	`OracleTolerance { upper_ratio_bps, lower_ratio_bps }` for two-source agreement.
`independence`	`RequireDisjoint`, or `AllowShared(Vec<Address>)` declaring permitted shared provider contracts.
`max_price_stale_seconds`	Maximum resolved-price age, from 60 through 93,600 seconds.
`asset_decimals`	Token amount decimals: 0 through 18 for `Token`, exactly 0 for `Ref`. Returned prices always use WAD. A replacement must preserve the stored decimals.
`min_sanity_price_wad`, `max_sanity_price_wad`	Accepted range for the final price.

Price sources

Variant	Valuation
`Feed(FeedSource)`	Reads a provider feed directly.
`Scaled(ScaledSource)`	Multiplies a factor feed by the resolved price of another `PriceKey`. The factor must remain within `min_factor_wad` and `max_factor_wad`, or the read fails with `#230`.
`AquariusLp(...)`	Calculates constant-product LP share fair value from the pool’s two reserves.
`AquariusStableLp(...)`	Calculates stable-swap LP share fair value.

An LP source must be the only source on its key. Nested Scaled.quote and LP leg references are bounded by MAX_RESOLUTION_DEPTH = 3; exceeding the bound returns #229. A reference cycle returns #225 OracleCycleDetected.

Feed providers

FeedSource contains provider, decimals, and max_stale_seconds:

Provider	Read options
`Reflector(ReflectorFeedRef)`	`Spot` or `Twap(records)`. Configuration requires 3 through `MAX_TWAP_RECORDS = 12` TWAP records.
`RedStone(MultiFeedRef)`	Feed-id read with `FeedNature::Market` or `Fundamental`.
`Xoxno(MultiFeedRef)`	The same reference shape as RedStone, with a separate provider kind.

Reflector asset references accept Stellar(Address) or Symbol(Symbol); a String reference returns #204. A direct Reflector feed must be USD-quoted. A Reflector factor in Scaled must instead quote the Stellar token named by Scaled.quote = Token(address). A USD-quoted factor or Ref quote fails with #220. FeedNature distinguishes market observations from fundamental valuations. It affects staleness handling and the leg-age comparison described below.

At least one complete non-LP source composition must have no unsmoothed market dependency, or configuration fails with #38 SpotOnlyNotProductionSafe. A direct Reflector TWAP feed or direct fundamental feed meets this requirement. A fundamental factor does not make an unsmoothed market quote dependency safe.

The XOXNO oracle aggregates authenticated signer submissions into a median under a configured quorum. The quorum applies across stored submissions; each submit call authenticates one registered signer. Submission age and relative skew control eligibility. See XOXNO oracle ABI for submission, aggregation persistence, and administration. A configured feed id does not prove that an observation is available or establish its upstream pricing method. Match the provider address and feed id to the oracle configuration and read a usable quote before integrating an asset.

Composition and tolerance

A two-source oracle requires both legs to pass resolution and freshness checks. It serves their midpoint, (a + b) / 2, only when they agree within tolerance. One readable leg is incomplete and fails with #205 UnsafePriceNotAllowed; there is no single-leg fallback. Agreement compares the larger price to the smaller, expressed as a BPS ratio, against upper_ratio_bps. The configured upper bound must be between 10_150 and 12_500. Governance expresses this as excess tolerance above BPS = 10_000, from 150 through 2,500 bps. Invalid tolerance returns #208. At configuration, lower_ratio_bps must equal half_up(BPS * BPS / upper_ratio_bps). The price-time comparison uses the upper ratio; comparing larger to smaller covers either direction of deviation. A single-source oracle serves its accepted leg directly. It still checks freshness, positivity, and sanity, and requires a tighter sanity band: MAX_SINGLE_SOURCE_SANITY_BAND_BPS = 1000. Two sources with identical provider trust sets also receive this cap. LP oracles use MAX_LP_SANITY_BAND_BPS = 8182. An overly wide single-source band returns #226. For two-source independence, RequireDisjoint forbids shared provider contracts. AllowShared requires the declared shared set to match the actual set exactly, or configuration fails with #232 IndependenceNotDeclared.

Freshness and sanity

Check	Rule
Source age	Each leg must fit its own `max_stale_seconds`; staleness returns `#206 PriceFeedStale`.
Resolved-price age	The price must fit `max_price_stale_seconds`. Both source and outer bounds are 60 through 93,600 seconds, and each source envelope must fit the outer bound.
Future observations	Up to 60 seconds ahead of ledger time is allowed. Observations beyond that allowance are excluded.
Leg-age spread	Two `Market` legs must be within 3,600 seconds of one another. A `Fundamental` leg is exempt.
Sanity bounds	Final price must be in `[min_sanity_price_wad, max_sanity_price_wad]`; a failure returns `#223`.

If future-dated observations leave no readable leg, resolution returns #210 NoLastPrice. In a dual-source oracle, one remaining fresh leg gives #205, while a stale remaining leg gives #206. The sanity band must be at least MIN_SANITY_BAND_BPS = 50 wide and stay within MAX_REASONABLE_PRICE_WAD, equal to $1 billion per whole token. Sanity is a pass/fail check on the resolved price; it never clamps an out-of-range value.

Failure behavior

Every valuation-dependent mutation needs a complete price snapshot. Provider failure, stale observations, disagreement, or invalid sanity checks revert the operation. This also applies to risk-decreasing actions when they need valuation. There is no per-flow permissive mode or TWAP-to-spot fallback. Choose the read method by its failure behavior:

Method	Result and failure behavior
`prices(keys)`	Returns validated `PriceFeedRaw` values; unusable prices revert.
`quotes(keys)`	Returns `PriceStatus` diagnostics, with `valid: false` and an error code for resolution failures.
`price_spread(key)`	Returns accepted source legs sorted as `(min, max)`; unusable prices revert. Single-source results contain the same value twice.
`oracle(key)`	Reads stored configuration; returns `None` for an unconfigured key without reading a feed.

price_spread reports source divergence, not a confidence interval around the midpoint. Dashboards can use quotes to report an individual market failure. Transaction logic must require a valid price before using it. PriceFeedRaw contains price_wad, asset_decimals, and timestamp. PriceStatus contains final_wad, primary_wad, secondary_wad, price_timestamp, stale, deviation, valid, and error_code: Option<u32>. The price timestamp uses the older accepted leg. The controller’s get_market_indexes_detailed includes equivalent diagnostics under price_wad, primary_price_wad, anchor_price_wad, stale, deviation, valid, and error_code.

A resolution failure can zero other diagnostic fields, including stale and deviation. Their being false does not prove those checks passed. Require valid: true; use error_code to explain a failure. None supplies no error reason and does not make an invalid quote usable.

Price-aggregator interface

Read signatures are:

prices(keys: Vec<PriceKey>) -> Map<PriceKey, PriceFeedRaw>
quotes(keys: Vec<PriceKey>) -> Map<PriceKey, PriceStatus>
price_spread(key: PriceKey) -> (i128, i128)
oracle(key: PriceKey) -> Option<AssetOracle>
get_owner() -> Option<Address>

Governance routes the configuration and upgrade calls:

Method	Effect
`set_oracle(key, oracle)`	Replaces and validates sources, tolerance, independence, age limits, decimals, and sanity bounds. Attests providers, probes the key, and structurally revalidates dependents.
`set_sanity_band(key, min_wad, max_wad)`	Changes bounds. The governance `ORACLE` fast path permits narrowing only; widening returns `#227 SanityBandMustTighten` and requires timelocked `ConfigureAssetOracle`.
`set_tolerance(key, tolerance)`	Changes the two-source agreement band.
`upgrade(new_wasm_hash: BytesN<32>)`	Replaces contract code through timelocked `UpgradePriceAggregator`.

A non-LP configuration probe rejects configuration failures but may accept a stale, deviating, or out-of-band observation. LP admission requires a usable price. Dependent keys receive structural validation, so a successful configuration change does not establish that dependent prices are usable. The three configuration methods emit UpdateAssetOracleEvent on ["config", "asset_oracle"] with the full resulting configuration. Use the Oracle disruption runbook for diagnosis and repair, and Governance for scheduling changes.

Start here

Core concepts

Lending actions

Strategies and integrations

System behavior

Reference

Operations

Configuration keys

Price sources

Feed providers

Composition and tolerance

Freshness and sanity

Failure behavior

Price-aggregator interface

​Configuration keys

​Price sources

​Feed providers

​Composition and tolerance

​Freshness and sanity

​Failure behavior

​Price-aggregator interface

Configuration keys

Price sources

Feed providers

Composition and tolerance

Freshness and sanity

Failure behavior

Price-aggregator interface