Oracle guidance
A guided market pulls its curve's price toward one feed by a fixed weight and never past a fixed cap, after checking the report on every price-sensitive instruction.
Updated Nov 11, 2026
A market can opt into one external price feed at creation. Its provider and feed cannot be replaced later. Its oracle policy names the feed and how far to trust it:
| Setting | What it does | Bounds |
|---|---|---|
| Source | Pyth, or a provider's normalized report, as one feed for the pair or as a base and a quote feed taken as a ratio | Fixed accounts and feed IDs |
| Oracle weight | How far the curve's price moves toward the feed | Above zero and below 100%; zero is native pricing |
| Adjustment cap | The furthest the feed can pull the price from the native curve, either way | Above 1×; 1.25× allows 25% higher or 20% lower |
| Maximum age | How old a report may be, in seconds and in slots | Above zero |
| Maximum confidence | The widest confidence band accepted, relative to the price | Below 100% |
| Maximum publish skew | How far apart the base and quote reports may be published | Ratio sources only |
The policy is an argument of initialize_market, and an invalid one fails creation with InvalidMarketConfig. The weight is stored in basis points, from 1 to 9,999. A Pyth source must be a fully verified PriceUpdateV2 account owned by the Pyth receiver program. A normalized report names its base and quote mints: a single feed must name the market's pair, and the two legs of a ratio must name the market's base and quote assets over one shared denomination, so no peg between the quote asset and that denomination is assumed.
Checks on every read
Every price-sensitive instruction reads the feed accounts itself, from its remaining accounts, and checks all of the following before it prices anything:
- Each configured account is present (
OracleAccountMissing), owned by the configured provider, not executable, in the configured layout with the configured feed ID, and for a normalized report naming the right mints (OracleAuthenticationFailed). - The report is usable: open status and a positive sequence for a normalized report, a Pyth exponent within ±18, and a positive price with a confidence below it (
OracleInvalidObservation). - It is not dated in the future, by timestamp or by slot (
OracleInvalidObservation), and it is no older than the maximum age in seconds and in slots (OracleStale). The two legs of a ratio must be published within the maximum skew of each other (OracleInvalidObservation). - The price is the base report over the quote report, . Its band runs from to , and the band's wider side, relative to the price, must be within the maximum confidence (
OracleInvalidObservation). - No sequence, publish time or slot may fall below the last report the market used, and a normalized report at an unchanged sequence must be identical (
OracleReplay).
For a ratio of a base report at 150 ± 0.15 and a quote report at 1 ± 0.001, the band runs from 149.7003 to 150.3003, a confidence of 20.02 bps: rejected under a 20 bps maximum and accepted under 25.
When an accepted price differs from the market's last one, the program treats the change as a price move. The curve revision advances, the move feeds the volatility signal and the sticky centre's average, and any stored centre target is dropped. The stored report is history for these replay checks and never authorizes a later instruction, which has to read the feed again.
The guided price
The guided marginal price is the native curve's price pulled toward the feed's price :
where is the oracle weight and the adjustment cap. Inside the cap that is a weighted geometric mean of the two prices, , the pricing rule of the OP-AMM paper, Oracle-Parametrized Constant Function Market Makers by Hamed Amini and Zachary Feinstein. Dusk applies the rule to its own curve, bands included, and adds the cap.
The cap binds once leaves the range to . With , and that range is 0.64 to 1.5625:
| Feed price | Guided price | Without the cap |
|---|---|---|
| 50 | 80.00 | 70.71 |
| 90 | 94.87 | 94.87 |
| 120 | 109.54 | 109.54 |
| 156.25 | 125.00 | 125.00 |
| 200 | 125.00 | 141.42 |
- Guided price
- The feed itself
- Adjustment cap
The weight also deepens the market. Inside the cap, the guided log-price moves times as fast as the native one as inventory changes, so where the feed agrees with the native price a small trade sees times the native depth, twice as much at . Once the cap binds, the slope is the native one again.
A guided trade pays the guided price at every point of its path, with the native shape fixing how depends on the reserve ratio. Its invariant is defined by its gradient, and . For an exact input the program proposes at most 12 candidate outputs and accepts one only when an outward-rounded interval bound proves the invariant did not fall, so any numerical uncertainty counts against the trader. An output it cannot certify fails with InsufficientOutputAmount. Refinement stops once the next correction is within one part in of the output reserve or within the numerical uncertainty, and rounding gains from settling ownership stay with LPs.
Swaps, the moving averages, borrow admission, collateral values and hLP valuation all run on the guided curve. The feed can move the curve's price only within the cap, and trades still pay price impact and fees along the curve's depth.
Emergency liquidation is the one exception. Its reference curve is the market's own curve at the symmetric moving-average price and smoothed depth, without the feed, because that average already follows the guided price. The settlement itself still trades on the guided curve.
A guided market's first deposit is priced at the feed, and no caller chooses its price. initialize_market rejects an imported launch price for it (InvalidMarketConfig), and add_liquidity treats both deposit amounts as caps at the feed price, rounding the base down and the quote up to whole atoms.
Lending reads a recognized depth on a guided market. A guided trade can leave the reserves on a different native curve, so lending counts the curve's depth only up to a recognized tail level and scales it down when the actual tail is larger. That level scales with the ordinary srLP supply outside the hLP vaults and falls at once with any loss. Fees that compound without new shares deepen the curve but leave the level where it was, so lending capacity can trail the market's real depth.
When the feed fails
When a report is stale or fails a check, every instruction that depends on price fails with it: swaps and their previews, borrows, srLP and hLP deposits and withdrawals, partial collateral withdrawals, leverage actions including added margin, liquidations, yield harvests, interest funding and junior seed compounding. Nothing switches to native pricing during an outage.
Repayments (repay and repay_leverage) and collateral top-ups (deposit_collateral and donate_collateral) use the feed when it is valid and otherwise proceed without taking a new price observation. Withdrawing everything from a position that owes nothing, with withdraw_all_collateral or withdraw_repaid_leverage, never reads it.
The provider and feed are creation-only. Operators cannot replace an unavailable source or use an oracle edit to bypass price checks, and executing an operator bundle on a guided market needs a fresh report too.