feat(hypercore): add HIP-3 builder dex perps support

- Fan out perpetual API calls across active builder dexes via `for_each_dex` helper
- Add `PerpDex` model and `perpDexs` RPC endpoint
- Map HIP-3 asset indices with offset encoding (100k + dex_index * 10k + meta_index)
- Format display names as `SYMBOL (dex)` for builder dex assets
- Add `only_isolated` to `Perpetual` and `margin_type` to `PerpetualConfirmData`
- Use margin type from confirm data in signer instead of hardcoded cross margin
- Merge positions, portfolios, and account summaries across dexes
- Extract HIP-3 specific logic into `hip3_mapper` module
- Extract `with_dex` helper to deduplicate RPC client dex injection
- Add `UniverseAsset::mock()` and `AssetMetadata::mock()` to testkit
- Make `ReferrerState.data` optional for `needToCreateCode` stage

Author: 0xh3rman

crates/gem_hypercore/src/models/mod.rs

@@ -3,6 +3,7 @@ pub mod balance;
 pub mod candlestick;
 pub mod metadata;
 pub mod order;
+pub mod perp_dex;
 pub mod portfolio;
 pub mod position;
 pub mod referral;

crates/gem_hypercore/src/models/perp_dex.rs

@@ -0,0 +1,8 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PerpDex {
+    pub name: String,
+    pub is_active: Option<bool>,
+}

crates/gem_hypercore/src/provider/fee_calculator.rs

@@ -16,13 +16,7 @@ pub fn calculate_perpetual_fee_amount(fiat_value: f64, fee_rate: i64) -> BigInt
     BigInt::from(result as i64)
 }
 
-pub fn calculate_spot_fee_amount(
-    swap_data: &SwapData,
-    from_asset: &Asset,
-    to_asset: &Asset,
-    fee_rate: i64,
-    builder_fee_bps: u32,
-) -> Result<BigInt, Box<dyn Error + Send + Sync>> {
+pub fn calculate_spot_fee_amount(swap_data: &SwapData, from_asset: &Asset, to_asset: &Asset, fee_rate: i64, builder_fee_bps: u32) -> Result<BigInt, Box<dyn Error + Send + Sync>> {
     let fiat_value = calculate_spot_usdc_value(swap_data, from_asset, to_asset, builder_fee_bps)?;
     let usdc_decimals = spot_usdc_decimals(from_asset, to_asset)?;
     let trade_fee = calculate_perpetual_fee_amount(fiat_value * decimal_scale(usdc_decimals - HYPERCORE_PERPETUAL_USDC_DECIMALS), fee_rate);
@@ -31,12 +25,7 @@ pub fn calculate_spot_fee_amount(
     Ok(trade_fee + builder_fee)
 }
 
-fn calculate_spot_usdc_value(
-    swap_data: &SwapData,
-    from_asset: &Asset,
-    to_asset: &Asset,
-    builder_fee_bps: u32,
-) -> Result<f64, Box<dyn Error + Send + Sync>> {
+fn calculate_spot_usdc_value(swap_data: &SwapData, from_asset: &Asset, to_asset: &Asset, builder_fee_bps: u32) -> Result<f64, Box<dyn Error + Send + Sync>> {
     let usdc_from = from_asset.id == *HYPERCORE_SPOT_USDC_ASSET_ID;
     let usdc_to = to_asset.id == *HYPERCORE_SPOT_USDC_ASSET_ID;
 

crates/gem_hypercore/src/provider/hip3_mapper.rs

@@ -0,0 +1,199 @@
+use std::collections::BTreeMap;
+
+use primitives::{
+    chart::ChartDateValue,
+    perpetual::{PerpetualBalance, PerpetualPositionsSummary},
+    portfolio::{PerpetualAccountSummary, PerpetualPortfolio, PerpetualPortfolioTimeframeData},
+};
+
+use crate::models::position::AssetPositions;
+
+const HIP3_PERP_ASSET_OFFSET: u32 = 100_000;
+const HIP3_PERP_ASSET_STRIDE: u32 = 10_000;
+
+pub fn perp_asset_index(perp_dex_index: u32, meta_index: u32) -> u32 {
+    if perp_dex_index == 0 {
+        meta_index
+    } else {
+        HIP3_PERP_ASSET_OFFSET + perp_dex_index * HIP3_PERP_ASSET_STRIDE + meta_index
+    }
+}
+
+pub fn format_display_name(name: &str) -> String {
+    match name.split_once(':') {
+        Some((dex, symbol)) => format!("{symbol} ({dex})"),
+        None => name.to_string(),
+    }
+}
+
+pub fn map_account_summary_aggregate(positions: &[AssetPositions]) -> PerpetualAccountSummary {
+    let account_value: f64 = positions.iter().map(|p| p.margin_summary.account_value.parse().unwrap_or(0.0)).sum();
+    let total_ntl_pos: f64 = positions.iter().map(|p| p.margin_summary.total_ntl_pos.parse().unwrap_or(0.0)).sum();
+    let total_margin_used: f64 = positions.iter().map(|p| p.margin_summary.total_margin_used.parse().unwrap_or(0.0)).sum();
+    let unrealized_pnl: f64 = positions
+        .iter()
+        .flat_map(|p| &p.asset_positions)
+        .map(|p| p.position.unrealized_pnl.parse().unwrap_or(0.0))
+        .sum();
+
+    let account_leverage = if account_value > 0.0 { total_ntl_pos / account_value } else { 0.0 };
+    let margin_usage = if account_value > 0.0 { total_margin_used / account_value } else { 0.0 };
+
+    PerpetualAccountSummary {
+        account_value,
+        account_leverage,
+        margin_usage,
+        unrealized_pnl,
+    }
+}
+
+pub fn merge_positions_summaries(summaries: Vec<PerpetualPositionsSummary>) -> PerpetualPositionsSummary {
+    let (positions, balance) = summaries.into_iter().fold(
+        (Vec::new(), PerpetualBalance { available: 0.0, reserved: 0.0, withdrawable: 0.0 }),
+        |(mut acc_pos, mut acc_bal), summary| {
+            acc_pos.extend(summary.positions);
+            acc_bal.available += summary.balance.available;
+            acc_bal.reserved += summary.balance.reserved;
+            acc_bal.withdrawable += summary.balance.withdrawable;
+            (acc_pos, acc_bal)
+        },
+    );
+    PerpetualPositionsSummary { positions, balance }
+}
+
+pub fn merge_perpetual_portfolios(portfolios: Vec<PerpetualPortfolio>, account_summary: Option<PerpetualAccountSummary>) -> PerpetualPortfolio {
+    let mut day = Vec::new();
+    let mut week = Vec::new();
+    let mut month = Vec::new();
+    let mut all_time = Vec::new();
+
+    for portfolio in portfolios {
+        day.extend(portfolio.day);
+        week.extend(portfolio.week);
+        month.extend(portfolio.month);
+        all_time.extend(portfolio.all_time);
+    }
+
+    PerpetualPortfolio {
+        day: merge_portfolio_timeframes(day),
+        week: merge_portfolio_timeframes(week),
+        month: merge_portfolio_timeframes(month),
+        all_time: merge_portfolio_timeframes(all_time),
+        account_summary,
+    }
+}
+
+fn merge_portfolio_timeframes(values: Vec<PerpetualPortfolioTimeframeData>) -> Option<PerpetualPortfolioTimeframeData> {
+    if values.is_empty() {
+        return None;
+    }
+
+    let mut account_value_histories = Vec::new();
+    let mut pnl_histories = Vec::new();
+    let mut volume = 0.0;
+
+    for value in values {
+        account_value_histories.push(value.account_value_history);
+        pnl_histories.push(value.pnl_history);
+        volume += value.volume;
+    }
+
+    Some(PerpetualPortfolioTimeframeData {
+        account_value_history: merge_chart_histories(account_value_histories),
+        pnl_history: merge_chart_histories(pnl_histories),
+        volume,
+    })
+}
+
+fn merge_chart_histories(values: Vec<Vec<ChartDateValue>>) -> Vec<ChartDateValue> {
+    let mut grouped = BTreeMap::new();
+    for history in values {
+        for point in history {
+            let entry = grouped.entry(point.date).or_insert(0.0);
+            *entry += point.value;
+        }
+    }
+
+    grouped.into_iter().map(|(date, value)| ChartDateValue { date, value }).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use primitives::portfolio::PerpetualAccountSummary;
+
+    #[test]
+    fn test_perp_asset_index() {
+        assert_eq!(perp_asset_index(0, 0), 0);
+        assert_eq!(perp_asset_index(0, 5), 5);
+        assert_eq!(perp_asset_index(1, 0), 110_000);
+        assert_eq!(perp_asset_index(1, 3), 110_003);
+        assert_eq!(perp_asset_index(2, 0), 120_000);
+        assert_eq!(perp_asset_index(2, 7), 120_007);
+    }
+
+    #[test]
+    fn test_format_display_name() {
+        assert_eq!(format_display_name("xyz:GOLD"), "GOLD (xyz)");
+        assert_eq!(format_display_name("BTC"), "BTC");
+    }
+
+    #[test]
+    fn test_map_account_summary_aggregate() {
+        let positions = vec![AssetPositions::mock(), AssetPositions::mock()];
+        let summary = map_account_summary_aggregate(&positions);
+
+        assert_eq!(summary.account_value, 20000.0);
+        assert_eq!(summary.account_leverage, 0.5);
+        assert_eq!(summary.margin_usage, 0.2);
+        assert_eq!(summary.unrealized_pnl, 0.0);
+    }
+
+    #[test]
+    fn test_merge_chart_histories() {
+        use chrono::{TimeZone, Utc};
+
+        let d1 = Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap();
+        let d2 = Utc.with_ymd_and_hms(2024, 1, 2, 0, 0, 0).unwrap();
+        let d3 = Utc.with_ymd_and_hms(2024, 1, 3, 0, 0, 0).unwrap();
+
+        let histories = vec![
+            vec![ChartDateValue { date: d1, value: 100.0 }, ChartDateValue { date: d2, value: 200.0 }],
+            vec![ChartDateValue { date: d1, value: 50.0 }, ChartDateValue { date: d3, value: 300.0 }],
+        ];
+
+        let merged = merge_chart_histories(histories);
+        assert_eq!(merged.len(), 3);
+        assert_eq!(merged[0].value, 150.0);
+        assert_eq!(merged[1].value, 200.0);
+        assert_eq!(merged[2].value, 300.0);
+    }
+
+    #[test]
+    fn test_merge_perpetual_portfolios() {
+        use chrono::{TimeZone, Utc};
+
+        let d1 = Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap();
+        let portfolios = vec![
+            PerpetualPortfolio::mock_with_day(d1, 100.0, 10.0, 500.0),
+            PerpetualPortfolio::mock_with_day(d1, 200.0, 20.0, 300.0),
+        ];
+        let summary = PerpetualAccountSummary { account_value: 1000.0, account_leverage: 2.0, margin_usage: 0.5, unrealized_pnl: 30.0 };
+
+        let merged = merge_perpetual_portfolios(portfolios, Some(summary));
+
+        let day = merged.day.unwrap();
+        assert_eq!(day.volume, 800.0);
+        assert_eq!(day.account_value_history.len(), 1);
+        assert_eq!(day.account_value_history[0].value, 300.0);
+        assert_eq!(day.pnl_history[0].value, 30.0);
+        assert!(merged.week.is_none());
+        assert_eq!(merged.account_summary.unwrap().account_value, 1000.0);
+    }
+
+    #[test]
+    fn test_merge_portfolio_timeframes_empty() {
+        let result = merge_portfolio_timeframes(vec![]);
+        assert!(result.is_none());
+    }
+}

crates/gem_hypercore/src/provider/mod.rs

@@ -5,6 +5,7 @@ use gem_client::Client;
 pub mod balances;
 pub mod balances_mapper;
 pub mod fee_calculator;
+pub mod hip3_mapper;
 pub mod perpetual;
 pub mod perpetual_mapper;
 pub mod preload;