Oracles

Every FX rate on Windrose comes through IFxOracle: units of a currency per 1 USD in 1e18 fixed point, with a publish time and a freshness flag. The registry, the factory and the router use whichever adapter the registry points at; each vault keeps the adapter it was created with. Today that adapter is KeeperFxOracle on every chain. Source: contracts/src/interfaces/IFxOracle.sol, contracts/src/oracle/FxOracleBase.sol, KeeperFxOracle.sol, PythFxOracle.sol, ChainlinkFxOracle.sol.

Interface

interface IFxOracle {
    function rate(bytes32 code) external view returns (uint256 rate_, uint256 publishTime, bool fresh); // reverts StalePrice past the stale limit
    function peekRate(bytes32 code) external view returns (uint256 rate_, uint256 publishTime);        // no age check
    function update(bytes[] calldata priceUpdate) external payable;                                   // push price data; excess value refunded
    function updateFee(bytes[] calldata priceUpdate) external view returns (uint256);                  // native fee `update` needs
    function isSupported(bytes32 code) external view returns (bool);
}

rate is what vaults use for every mint, redeem, deposit and withdrawal. peekRate is only for uses that cannot be manipulated by an old price: the factory sizes a new curve with it, so launches can be created while the FX market is closed. USD always returns 1e18, the current timestamp and fresh = true.

Shared rules: `FxOracleBase`

uint256 public maxAgeFresh;   // age at or below which a price is fresh
uint256 public maxAgeStale;   // age above which rate() reverts StalePrice
function setLimits(uint256 maxAgeFresh_, uint256 maxAgeStale_) external onlyOwner; // f != 0 and s >= f, else BadLimits

Three windows apply to every adapter, with age = block.timestamp - publishTime:

Window	Condition	Vault behaviour
Fresh	`age <= maxAgeFresh`	normal fees; underwriter deposits and withdrawals allowed
Stale	`maxAgeFresh < age <= maxAgeStale`	mint and redeem at `staleFeeBps`; deposits and withdrawals revert `NotFresh`
Rejected	`age > maxAgeStale`	`rate()` reverts `StalePrice(code, age)`: mint, redeem, deposit, withdraw, `status()` and the previews all revert

The stale window exists because FX markets close from Friday evening to Sunday evening (New York time), so a weekend must not stop trading. Deployed limits: keeper oracle 2 hours fresh, 5 days stale; Pyth adapter 60 seconds fresh, 5 days stale. Errors shared by every adapter: UnsupportedCurrency(code), StalePrice(code, age), InvalidPrice(code), RefundFailed(), BadLimits(). The base update refunds any value and updateFee returns 0; push adapters inherit both.

`KeeperFxOracle` (live on every chain)

struct Entry { uint128 rate; uint64 publishTime; bool enabled; }
mapping(bytes32 => Entry) public entries;
mapping(address => bool) public keepers;
uint256 public maxMoveBps;

function post(bytes32[] calldata codes, uint256[] calldata rates, uint256 publishTime) external; // keepers only
function forcePost(bytes32 code, uint256 rate_) external onlyOwner;
function setKeeper(address keeper, bool allowed) external onlyOwner;
function setCurrency(bytes32 code, bool enabled) external onlyOwner;   // UsdIsFixed for "USD"
function setMaxMoveBps(uint256 bps) external onlyOwner;                 // 0 disables the move check
function isSupported(bytes32 code) external view returns (bool);

post checks, in order: NotKeeper; LengthMismatch; FuturePublishTime when publishTime > block.timestamp; then per code: UnsupportedCurrency if not enabled, InvalidPrice if the rate is zero or above uint128, and MoveTooLarge(code) if a previous rate exists, maxMoveBps is non-zero and the change exceeds maxMoveBps of the previous rate. A code whose stored publishTime is newer than the posted one is skipped silently (rates never go backwards). Each accepted code emits RatePosted(code, rate, publishTime). forcePost lets the owner recover from a bad post: it bypasses the move limit, stamps block.timestamp and emits RatePosted. Deployed with maxAgeFresh = 2 hours, maxAgeStale = 5 days, maxMoveBps = 1500 (15% per post), EUR plus the sixty synthetic codes enabled, and the deployment’s KEEPER address (the VPS hot key on Robinhood Chain) allow-listed. The keeper bot posts every 10 minutes and re-posts unchanged rates hourly so nothing crosses the fresh window; if it stops, minting, redeeming and underwriting degrade to the stale fee after 2 hours and stop after 5 days, while curve trading in the quote asset continues unaffected. Events: KeeperSet, CurrencySet(code, enabled), RatePosted, MaxMoveSet, LimitsSet. Errors: NotKeeper, MoveTooLarge, UsdIsFixed, LengthMismatch, FuturePublishTime plus the shared ones.

The trust assumption is the keeper key and the reference-rate API behind it (open.er-api.com, with frankfurter.app as fallback: free daily reference rates, not tradeable quotes). Within the 15% band a compromised keeper can post wrong prices, and the owner can post any price with forcePost. The contract’s own comment says it: never use this as the sole oracle for a mainnet vault holding real money. Today it is the sole oracle everywhere, because no decentralised FX feed covers most of the sixty currencies on the chains Windrose runs on. See Security model.

`PythFxOracle` (deployed on Arc testnet, not in use)

struct Feed { bytes32 id; bool invert; bool enabled; }
IPyth public immutable pyth;
mapping(bytes32 => Feed) public feeds;
uint256 public maxConfBps;

function setFeed(bytes32 code, bytes32 id, bool invert, bool enabled) external onlyOwner;
function setMaxConfBps(uint256 bps) external onlyOwner;
function update(bytes[] calldata priceUpdate) external payable;               // forwards pyth.getUpdateFee to updatePriceFeeds; empty payload is a no-op
function updateFee(bytes[] calldata priceUpdate) external view returns (uint256); // 0 for an empty payload

A pull adapter: callers fetch Hermes update data for the feed id and attach it as priceUpdate; the fee is paid in native value (18-decimal USDC on Arc) and any excess is refunded. _read uses getPriceUnsafe, rejects non-positive prices, zero publish times and a confidence interval wider than maxConfBps of the price (InvalidPrice), normalises price * 10^expo to 1e18 (ExponentOutOfRange beyond 40 digits) and inverts (1e36 / v) for feeds quoted as USD per XXX. Deployed on Arc testnet at the address in Addresses with 60 s fresh, 5 days stale, maxConfBps = 100, and the 30 feeds in contracts/script/PythFeeds.sol (AUD, EUR, GBP and NZD inverted). Pyth is not on Arc mainnet or Robinhood Chain, and Hermes FX data needs a paid key since August 2026. Errors specific to it: InsufficientFee(required, provided), UsdIsFixed, ExponentOutOfRange.

`ChainlinkFxOracle` (implemented, not deployed)

struct Feed { AggregatorV3Interface aggregator; uint8 decimals; bool invert; bool enabled; }
function setFeed(bytes32 code, AggregatorV3Interface aggregator, bool invert, bool enabled) external onlyOwner;

A push adapter reading latestRoundData (free): rejects non-positive answers and zero updatedAt, scales by the feed’s decimals and inverts when the feed is XXX/USD (the usual case). The deploy script does not deploy it. Arc mainnet has seven free FX feeds (EUR, JPY, CAD, AUD, MXN, BRL, KRW); Robinhood Chain has none.

How the rest of the protocol uses the oracle

Reader	Call	Purpose
`LaunchFactory.createLaunch`	`registry.oracle().update` + `peekRate(code)`	size `virtualQuote` at creation; no age check
`Router` dollar paths	`registry.oracle().updateFee(priceUpdate)`	how much value to forward to the vault
`FxVault` (own immutable oracle)	`update` + `rate(code)`	every mint, redeem, deposit, withdrawal, preview and `status()`
Keeper bot	`entries`, `keepers`, `post`	posts and heartbeats
Indexer	`RatePosted`	`rate` history and `currency.lastRate`, which price every launch’s `priceUsd`

Switching the registry to another adapter changes the first two rows only; vaults keep reading the keeper oracle. The router computes the fee from the registry’s oracle but the vault forwards it to its own, so a mismatch between the two would make buyWithUSDC / sellForUSDC revert with the vault’s InsufficientFee or leave the fee unrefunded. Keep the registry oracle and the vault oracle the same contract, or leave the registry on the keeper oracle. contracts/test/Oracles.t.sol covers Pyth normalisation and inversion, the fresh-to-stale transitions, the confidence check, fee refunds and rejection, the empty-update no-op, the fixed USD rate, Chainlink inversion and the keeper’s rules (test_keeper_rules).

Overview

Contracts

Integrate

Interface

Shared rules: `FxOracleBase`

`KeeperFxOracle` (live on every chain)

`PythFxOracle` (deployed on Arc testnet, not in use)

`ChainlinkFxOracle` (implemented, not deployed)

How the rest of the protocol uses the oracle

​Interface

​Shared rules: FxOracleBase

​KeeperFxOracle (live on every chain)

​PythFxOracle (deployed on Arc testnet, not in use)

​ChainlinkFxOracle (implemented, not deployed)

​How the rest of the protocol uses the oracle

Interface

Shared rules: `FxOracleBase`

`KeeperFxOracle` (live on every chain)

`PythFxOracle` (deployed on Arc testnet, not in use)

`ChainlinkFxOracle` (implemented, not deployed)

How the rest of the protocol uses the oracle