Aggregated Price Oracle

When a market is created, the Market Manager admin must specify an oracle compliant with the SEP-40 standard. This allows markets to use existing Stellar-based solutions, such as Reflector, or Alula's own SEP-40 adapters for Chainlink, RedStone, and Soroswap price feeds, or Alula's aggregated oracle at deployment time (the oracle address is immutable and cannot be updated afterward).

For higher reliability, Alula provides an optional aggregated oracle that computes the median price across multiple SEP-40-compliant sources, checks every source for staleness and can be configured with circuit breakers.

Circuit Breaker

The aggregated oracle implements a per-asset circuit breaker that suppresses the price when a rapid, large deviation is detected. This protection operates at the oracle layer; when triggered, the oracle returns no price.

The breaker tracks two references per asset, both stamped with ledger time (not the source's signing time):

• anchor — the first accepted read of the current window.
• last — the most recently accepted read.

On every lastprice() call:

1. A new median is computed from all non-stale, positive source prices.
2. For each reference (anchor and last) still within the configured max_dev_consecutive_diff_secs window, the deviation is checked:

deviation_bps = |new_median - reference| / reference × 10,000

3. If deviation_bps exceeds the asset's max_dev_bps against either reference, the breaker trips: a PriceDeviationExceedsMax event is emitted and no price is returned.
4. If both checks pass, the median is returned. last is updated to the new read; anchor is kept while still in window, or reset to the new read once the window has elapsed.

Checking against both anchor and last prevents an attacker from walking the price in small per-tick steps while the anchor rolls over.

INFO

A reference older than max_dev_consecutive_diff_secs is skipped. If both references are out of window, no deviation check runs and the new median is accepted — preventing false positives after legitimate extended periods of inactivity.

Source Staleness

Each source is checked for freshness before it can contribute to the median. Sources fall into two types:

• Periodic sources (which publish on a fixed cadence) are allowed a short grace period on top of their resolution: a price is accepted while its age is within min(resolution + 70s, periodic_oracles_price_max_age).
• Heartbeat sources are accepted only within their declared resolution.

Stale, expired, or non-positive source prices are silently dropped, and the median is computed from whatever valid sources remain. If no source has a usable price, the oracle returns no price.

Price Manipulation Resistance

Comparing the new median against the last accepted valid median compounds the difficulty for an attacker:

• Outlier filtering: The median discards outliers; an attacker needs to control ⌈N/2⌉ sources to move the median.
• Per-tick caps: Even if the median shifts, an attacker must sustain manipulation across multiple consecutive ticks, moving at most max_dev_bps each time. A multi-minute update frequency for a source further increases the required manipulation window.

The following diagrams illustrate three attack scenarios against a three-source aggregated oracle:

Scenario 1: Single source manipulated. The median discards the outlier and a valid price is reported.

Scenario 2: Majority manipulated, within deviation window. The circuit breaker detects the deviation and no price is reported.

Scenario 3: Majority manipulated, after deviation window. The manipulated price can pass, but an attacker must control at least half the sources for an extended period to reach this state.

Per-asset Configuration

Each asset is registered with its own circuit breaker parameters via add_asset:

Parameter	Type	Description
max_dev_bps	u32	Maximum allowed deviation in basis points.
max_dev_consecutive_diff_secs	u64	Time window in seconds; deviation is only enforced when consecutive reads fall within this window.

This allows volatile assets to use wider bands than stablecoins, and the time window can be tuned to the expected oracle update frequency.

Effect on Market Operations

• Obligations without active borrows: Withdrawals can remain possible, allowing users to reduce exposure while prices are paused.
• Obligations with open borrows: Withdrawals and new borrows cannot proceed because the protocol cannot confirm collateralization without a price.
• Liquidations: Liquidations are also blocked because the protocol cannot evaluate the obligation's health factor without a current price.