Oracles

How the protocol turns external price feeds into a single USD price, and why it refuses to act when those feeds are stale or disagree. There is no guarantee of oracle correctness. Prices live in a dedicated price aggregator contract. The controller reads it; the pool never sees a price. Read first: System architecture.

The shape of a configuration

Configuration is keyed by PriceKey, not by market:

enum PriceKey {
  Token(Address),   // a token contract
  Ref(Symbol),      // a synthetic reference used as an intermediate quote
}

Every key maps to one AssetOracle:

Field	Meaning
`sources`	One or two `PriceSource` entries. Zero or three or more is `#231 SourceCountOutOfRange`.
`tolerance`	`OracleTolerance { upper_ratio_bps, lower_ratio_bps }` — the agreement band between two sources.
`independence`	`RequireDisjoint`, or `AllowShared(Vec<Address>)` naming exactly which provider contracts the two sources may share.
`max_price_stale_seconds`	Maximum age the blended price may have. Range `60`..`93_600` seconds.
`asset_decimals`	Decimal scale of the price this oracle returns, `1`..`18`.
`min_sanity_price_wad` / `max_sanity_price_wad`	Bounds the resolved price must fall within.

PriceSource is one of four variants:

Variant	What it reads
`Feed(FeedSource)`	A direct provider feed.
`Scaled(ScaledSource)`	A factor feed multiplied by the price resolved for another `PriceKey`, with the factor bounded by `min_factor_wad`..`max_factor_wad` (`#230` outside).
`AquariusLp(...)`	Constant-product LP share fair value from the pool’s two reserves.
`AquariusStableLp(...)`	Stable-swap LP share fair value.

An Aquarius LP source must be the only source on its key. Composition through Scaled.quote and LP leg keys is bounded at MAX_RESOLUTION_DEPTH = 3 (#229), and a cycle is rejected with #225 OracleCycleDetected.

Providers

FeedSource { provider, decimals, max_stale_seconds }, where provider is:

Variant	Role	Read mode
`Reflector(ReflectorFeedRef)`	Primary for liquid majors	`OracleReadMode::Spot`, or `Twap(records)` with up to `MAX_TWAP_RECORDS = 12` records
`RedStone(MultiFeedRef)`	Anchor or primary	Feed-id read, carries a `FeedNature`
`Xoxno(MultiFeedRef)`	Primary for RWA / custom feeds	Same wire shape as RedStone, distinct provider kind

Reflector references identify their asset with OracleAssetRef::Stellar(Address) or Symbol(Symbol); a String reference is rejected with #204. A Reflector feed must be USD-quoted at listing (#220). RedStone and Xoxno references carry a FeedNature of Market or Fundamental. That choice changes how staleness is judged and whether the leg-age spread bound applies — see the oracle disruption runbook.

Unsmoothed spot everywhere is rejected. If every configured source reads an unsmoothed market feed — including a single-source oracle whose only leg is one — set_oracle reverts with #38 SpotOnlyNotProductionSafe. Add a TWAP-read Reflector leg, or a Fundamental-nature feed.

XOXNO oracle (RWA)

The XOXNO oracle is a self-hosted multi-signer oracle. Registered bot wallets submit prices; the contract stores the latest per signer per feed and recomputes a median aggregate under an N-of-M threshold, keeping reads O(1). Writes are threshold-signed and verify signer-set membership, submission age, and relative skew. Reads are open and Reflector-compatible. Its full callable surface — submitting prices, the Reflector-compatible reads, and the admin knobs — is on XOXNO oracle ABI. Use it when Reflector and RedStone have no suitable Stellar feed — especially tokenized RWA listings. A listing does not imply issuer endorsement, regulatory compliance, or user eligibility.

Knob	Purpose
`max_submission_age_seconds`	Absolute age for inclusion in the median
`max_relative_skew_seconds`	Drop lagging peers vs the freshest submission
`max_stale_seconds`	How long a cached aggregate may be served

Keep submission age at or below the consuming oracle’s max_price_stale_seconds. Below threshold, aggregates clear and reads fail closed with adapter error 7 NoDataForFeed.

set_threshold, set_max_submission_age_seconds, and set_max_relative_skew_seconds store the new bound only; they do not re-derive aggregates that already exist. Follow a change with recompute_feeds(feed_ids) in batches small enough to stay inside the transaction footprint limit (roughly one ledger entry per signer plus three, per feed). feeds() enumerates the registered ids.

Mainnet RWA feeds

Feed ids must match the lending bot job pairs that submit prices.

Feed id	Issuer / product	Pricing note
`SPIKOEUTBL`	Spiko EUTBL	Chainlink EUTBL NAV (EUR) × EUR/USD
`SPIKOUSTBL`	Spiko USTBL	Chainlink USTBL NAV (USD)
`SPIKOUKTBL`	Spiko UKTBL	Spiko public NAV (GBP) × GBP/USD
`SPIKOSAFO` / `SPIKOEURSAFO` / `SPIKOGBPSAFO`	Spiko SAFO share classes	Spiko public NAV (+ FX when needed)
`SPIKOSPKCC` / `SPIKOEURSPKCC`	Spiko Cash & Carry	Chainlink (+ FX for EUR class)
`DEJTRSY` / `DEJAAA`	Centrifuge	Chronicle ChainlinkAdapter + CoinGecko
`USDY`	Ondo USDY	CoinGecko (USD)

Composition and tolerance

A two-source price is the midpoint of its two legs, or it fails. There is no band-by-band fallback, no “use the primary inside the first band”, and no degrading to a single leg. One readable leg is an incomplete observation, not a fallback price.

For a dual-source oracle:

Both legs must be readable and fresh. Only one leg producing a reading is #205 UnsafePriceNotAllowed.
within_tolerance_band divides the larger leg by the smaller and compares that ratio to upper_ratio_bps. Beyond it, #205.
The served value is (a + b) / 2.

The band is stored as a pair of reciprocal ratios. At configuration time the contract checks that lower_ratio_bps equals BPS × BPS / upper_ratio_bps, rounded half up. At price time only upper_ratio_bps is read. Dividing the larger leg by the smaller already gives a ratio above 1 either way, so one bound covers both directions. upper_ratio_bps must be between MIN_TOLERANCE = 150 and MAX_TOLERANCE = 2500 bps, else #208. A single-source oracle serves its one leg directly, still subject to staleness, positivity, and sanity checks — and is admitted only with a tighter sanity band (MAX_SINGLE_SOURCE_SANITY_BAND_BPS = 1000, versus MAX_LP_SANITY_BAND_BPS = 8182 for LP oracles). Exceeding it is #226 SanityBandTooWideForSingleSource. independence governs whether the two legs may depend on the same provider contract. RequireDisjoint forbids it; AllowShared requires the declared set to match the actual one exactly, else #232 IndependenceNotDeclared.

Staleness and sanity

Staleness: a leg older than its own max_stale_seconds, or a blend older than the oracle’s max_price_stale_seconds, is #206 PriceFeedStale. Both bounds are clamped to [60, 93_600] seconds.
Future-dated observations do not raise #206. They are dropped outright, so the read fails as #210 NoLastPrice or #205 instead.
Leg-age spread: when both legs are Market nature, they must be within MAX_LEG_AGE_SPREAD_SECONDS = 3600 of each other, because the blend weights them equally. A Fundamental leg is exempt.
Sanity bounds: the final WAD price must sit in [min_sanity_price_wad, max_sanity_price_wad], else #223. The band is a pass/fail check on the already-blended value, never a clamp. It must be at least MIN_SANITY_BAND_BPS = 50 wide and at most MAX_REASONABLE_PRICE_WAD = $1e9 per whole token.

Fail-closed

Every valuation-dependent mutation consumes a complete price snapshot. Source failure, staleness, disagreement, or a failed sanity rule reverts the operation — the protocol halts risk-taking rather than acting on a questionable price. There is no permissive mode, no per-flow policy table, and no TWAP-to-spot fallback. Two read surfaces behave differently by design:

Call	On an unusable price
`prices(keys)`, `price_spread(key)`	Panics. So does every controller entrypoint that values an account.
`quotes(keys)`	Never panics. Returns a `PriceStatus` with `valid: false` and an `error_code`.

get_market_indexes_detailed on the controller surfaces the same per-leg detail for UIs: price_wad, primary_price_wad, anchor_price_wad, stale, deviation, valid, and error_code.

A resolution error — a nested reference leg going stale, for example — zeroes every other field, including stale and deviation. So stale: false does not mean the staleness check passed. It may mean resolution failed before that check ran.An error_code field that reports the reason directly is written but not yet released; it is on an unmerged branch. Until it ships, treat valid: false as “unusable, reason unknown” rather than inferring a cause from the other flags.

Callable surface

Everything the price aggregator exposes. Reads are open; the three mutators are governance-routed.

Reads

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>

Call	Behaviour on an unusable price
`prices`	Panics. Use it when you want the operation to fail rather than proceed.
`quotes`	Never panics. Returns a `PriceStatus` with `valid: false`.
`price_spread`	Panics, same as `prices`.
`oracle`	Cannot fail on price — it reads stored config, not a feed. Returns `None` if no oracle is registered.

PriceFeedRaw is { price_wad: i128, asset_decimals: u32, timestamp: u64 }. PriceStatus is { final_wad, primary_wad, secondary_wad, price_timestamp, stale, deviation, valid } — the blended price, both legs, the timestamp of the older leg, and three flags.

price_spread is not a band around the blend. It returns the two source legs sorted: (min(first, second), max(first, second)). On a single-source oracle both entries come from the same leg. Use it to see how far your two sources actually diverge, not as a confidence interval.

Pick between prices and quotes by what you want on failure. A liquidation bot sizing a position wants prices, so a bad feed aborts before it commits. A dashboard wants quotes, so one broken market does not blank the whole page.

Operator controls

The price aggregator exposes three configuration mutators, all governance-routed:

Call	Effect
`set_oracle(key, oracle)`	Replaces the whole configuration: sources, tolerance, independence, staleness, decimals, sanity band. Runs full admission validation and re-probes dependents.
`set_sanity_band(key, min_wad, max_wad)`	Adjusts bounds only. Has a guardian fast path through governance, but that path may only tighten — widening is `#227 SanityBandMustTighten` and must go through the timelocked `ConfigureAssetOracle` operation.
`set_tolerance(key, tolerance)`	Adjusts the dual-source agreement band.

All three publish UpdateAssetOracleEvent (["config", "asset_oracle"]) with the full post-change configuration. Read the current configuration with oracle(key).

Oracle disruption runbook

Triage, feed nature, blast radius, and repair when an asset stops pricing.

Markets

Listing lifecycle and hub-asset rows.

Spokes

Spiko and Centrifuge risk modules.

Security model

Fail-closed posture in the trust model.

Start here

Concepts

Integration guides

Reference

Operations

The shape of a configuration

Providers

XOXNO oracle (RWA)

Mainnet RWA feeds

Composition and tolerance

Staleness and sanity

Fail-closed

Callable surface

Reads

Operator controls

Next

Oracle disruption runbook

Markets

Spokes

Security model

​The shape of a configuration

​Providers

​XOXNO oracle (RWA)

​Mainnet RWA feeds

​Composition and tolerance

​Staleness and sanity

​Fail-closed

​Callable surface

​Reads

​Operator controls

​Next

Oracle disruption runbook

Markets

Spokes

Security model

The shape of a configuration

Providers

XOXNO oracle (RWA)

Mainnet RWA feeds

Composition and tolerance

Staleness and sanity

Fail-closed

Callable surface

Reads

Operator controls

Next