hypercall/shared/
traits.rs

1use crate::types::{Account, MarginDetails};
2use async_trait::async_trait;
3use hypercall_types::WalletAddress;
4pub use hypercall_vol_oracle::PollingVolOracle;
5
6pub type H256 = [u8; 32];
7pub type TxHash = String;
8pub type AccountId = WalletAddress;
9pub type PriceVector = Vec<(String, f64)>; // (symbol, price)
10
11#[derive(Debug, Clone)]
12pub struct AccountState {
13    pub account: Account,
14}
15
16#[derive(Debug)]
17pub struct MarginLeaf {
18    pub account_id: WalletAddress,
19    pub margin_details: MarginDetails,
20}
21
22/// Mark price oracle for determining underlying asset prices.
23///
24/// This trait provides methods for:
25/// - Getting current spot prices from the oracle
26/// - Computing forward/mark prices for a given expiry
27/// - Registering and retrieving settlement prices via TWAP
28/// - Committing price roots on-chain
29#[async_trait]
30pub trait MarkPriceOracle: Send + Sync {
31    /// Get the current cached spot/oracle price.
32    async fn get_spot_price(&self) -> Option<f64>;
33
34    /// Get the previous day's price (from Hyperliquid perp context).
35    async fn get_prev_day_price(&self) -> Option<f64> {
36        None
37    }
38
39    /// Compute the mark/forward price for a given expiry timestamp.
40    ///
41    /// Formula: `spot * e^(r * time_to_maturity)`
42    /// where r is the risk-free rate and time_to_maturity is in years.
43    ///
44    /// Returns an error if no spot price is available or expiry is in the past.
45    async fn get_mark_price(&self, expiry_timestamp: i64) -> anyhow::Result<f64>;
46
47    /// Register a settlement window for TWAP computation.
48    ///
49    /// The oracle will begin collecting price samples when:
50    /// `current_time >= expiry_timestamp - twap_seconds`
51    ///
52    /// After the expiry, the TWAP settlement price will be computed and stored.
53    async fn register_settlement(&self, expiry_timestamp: i64, twap_seconds: u32);
54
55    /// Get the finalized settlement price for a given expiry.
56    ///
57    /// Returns None if:
58    /// - No settlement was registered for this expiry
59    /// - The TWAP computation has not yet completed
60    async fn get_settlement_price(&self, expiry_timestamp: i64) -> Option<f64>;
61
62    /// Commit a merkle root of prices on-chain for L1 anchoring.
63    ///
64    /// Returns the transaction hash on success.
65    async fn commit_price(&self, root: H256) -> anyhow::Result<TxHash>;
66
67    /// Get the current price sequence number.
68    ///
69    /// This is a monotonically increasing counter that increments with each price update.
70    async fn get_price_seq(&self) -> u64;
71}
hypercall/shared/traits.rs

hypercall/shared/
traits.rs
