Struct HyperliquidMarkPriceOracle 

pub struct HyperliquidMarkPriceOracle {
    config: HyperliquidOracleConfig,
    client: Client,
    state: Arc<RwLock<OracleState>>,
    sync_status: Arc<SyncStatus>,
    hydromancer_client: Option<Arc<HydromancerClient>>,
    fallback_cache: Arc<RwLock<HashMap<(String, i64), CachedFallbackResult>>>,
}

The main Hyperliquid Mark Price Oracle.

This oracle fetches oracle/index prices from Hyperliquid and computes forward prices for options settlement.

Fields

config: HyperliquidOracleConfig

client: Client

state: Arc<RwLock<OracleState>>

sync_status: Arc<SyncStatus>

Sync status for readiness tracking

hydromancer_client: Option<Arc<HydromancerClient>>

Hydromancer fallback client (None if not configured)

fallback_cache: Arc<RwLock<HashMap<(String, i64), CachedFallbackResult>>>

Cache of Hydromancer fallback results keyed by (symbol, expiry_timestamp)

Implementations

impl HyperliquidMarkPriceOracle

pub fn new(config: HyperliquidOracleConfig) -> Result<Self>

Create a new oracle with the given configuration.

Returns an error if the configuration is invalid (e.g., missing symbol).

pub fn risk_free_rate(&self) -> f64

Risk-free rate used by this oracle when converting spot to forward.

pub async fn new_with_init(config: HyperliquidOracleConfig) -> Result<Self>

Create with async initialization (fetches initial price).

If a WebSocket feed is configured, waits for it to deliver a price first. Falls back to HTTP if WS doesn’t deliver within a few seconds. Sets sync status to Ready after successful initial price fetch.

pub fn sync_status(&self) -> Arc<SyncStatus>

Get the sync status for readiness checks.

pub fn config(&self) -> &HyperliquidOracleConfig

Get the oracle configuration.

pub async fn is_healthy(&self) -> bool

Check if the oracle is healthy (receiving updates).

pub async fn get_last_fetch_timestamp_ms(&self) -> Option<i64>

Get the last fetch timestamp in milliseconds (if any). Returns None if no price has been fetched yet.

pub async fn get_staleness_seconds(&self) -> Option<f64>

Get the staleness of the price in seconds. Returns None if no price has been fetched yet.

pub async fn fetch_oracle_price(&self) -> Result<OracleFetchResult>

Fetch oracle price (and prev day price) from Hyperliquid metaAndAssetCtxs endpoint.

pub fn start_polling(self: &Arc<Self>) -> JoinHandle<()>

Start the background polling task (legacy, no shutdown support).

Returns a JoinHandle that can be awaited or aborted. For graceful shutdown support, use start_polling_with_shutdown instead.

pub fn start_polling_with_shutdown( self: &Arc<Self>, shutdown_rx: Receiver<()>, ) -> JoinHandle<()>

Start the background polling task with shutdown support.

Reads prices exclusively from the WebSocket feed. If the WS price is stale or unavailable (during reconnect), marks the oracle unhealthy and skips the tick — the WS feed’s own reconnect loop handles recovery. Returns a JoinHandle that can be awaited or added to a TaskGroup.

async fn process_settlement_samples( &self, state: &mut OracleState, price: f64, now_ms: i64, now_secs: i64, )

Process settlement samples for active windows.

pub fn compute_forward_price( spot: f64, expiry_timestamp: i64, risk_free_rate: f64, ) -> Result<f64>

Compute forward price: spot * e^(r * t).

• spot: Current spot/oracle price
• expiry_timestamp: Unix timestamp (seconds) of expiry
• risk_free_rate: Annual risk-free rate (e.g., 0.05 for 5%)

Returns error if expiry is in the past.

pub fn compute_twap_median_of_means( samples: &[PriceSample], trim_pct: f64, ) -> f64

Compute TWAP using median-of-means with trimming.

Algorithm:

1. Sort all samples by price
2. Trim trim_pct from each tail (removes outliers/manipulation)
3. Divide remaining samples into sqrt(n) buckets
4. Compute mean of each bucket
5. Return median of bucket means

This is more robust than simple mean for manipulation resistance.

fn persist_samples_via_writer( writer: &dyn OracleWriter, symbol: &str, expiry_timestamp: i64, samples: &[PriceSample], ) -> Result<()>

Persist price samples to database via the OracleWriter trait.

pub fn set_hydromancer_client(&mut self, client: Arc<HydromancerClient>)

Set the Hydromancer fallback client.

fn persist_hydromancer_settlement_via_writer( writer: &dyn OracleWriter, symbol: &str, expiry_timestamp: i64, settlement_price: f64, sample_count: usize, window_start: i64, window_end: i64, ) -> Result<()>

Persist a Hydromancer-computed settlement price via the OracleWriter trait.

pub async fn attempt_hydromancer_fallback( &self, expiry_timestamp: i64, ) -> Option<f64>

Attempt to settle an expiry using Hydromancer as a fallback oracle source.

Returns Some(price) on success, None if Hydromancer cannot provide sufficient data. Results are cached to avoid repeated API calls.

pub async fn set_spot_price_for_testing(&self, price: f64)

Set spot price directly (for testing only).

This allows tests to inject spot prices without making network requests. ONLY use this in test environments.

Trait Implementations

impl MarkPriceOracle for HyperliquidMarkPriceOracle

fn get_spot_price<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<f64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the current cached spot/oracle price.

fn get_prev_day_price<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<f64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the previous day’s price (from Hyperliquid perp context).

fn get_mark_price<'life0, 'async_trait>( &'life0 self, expiry_timestamp: i64, ) -> Pin<Box<dyn Future<Output = Result<f64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Compute the mark/forward price for a given expiry timestamp.

fn register_settlement<'life0, 'async_trait>( &'life0 self, expiry_timestamp: i64, twap_seconds: u32, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Register a settlement window for TWAP computation.

fn get_settlement_price<'life0, 'async_trait>( &'life0 self, expiry_timestamp: i64, ) -> Pin<Box<dyn Future<Output = Option<f64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the finalized settlement price for a given expiry.

fn commit_price<'life0, 'async_trait>( &'life0 self, root: H256, ) -> Pin<Box<dyn Future<Output = Result<TxHash>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Commit a merkle root of prices on-chain for L1 anchoring.

fn get_price_seq<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = u64> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the current price sequence number.