hypercall_db/types/
liquidation.rs

1//! Liquidation state, history, and auction types.
2//!
3//! Covers the full lifecycle: Healthy -> PreLiquidation -> InLiquidation -> Liquidated,
4//! with auction records and bonus application results.
5
6use chrono::NaiveDateTime;
7use hypercall_types::WalletAddress;
8use rust_decimal::Decimal;
9use serde::{Deserialize, Serialize};
10
11/// Current liquidation state for a wallet. One row per wallet, upserted
12/// on every state transition.
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct LiquidationStateRecord {
15    pub wallet_address: WalletAddress,
16    /// Healthy, PreLiquidation, InLiquidation, or Liquidated.
17    pub state: String,
18    /// "standard" or "portfolio".
19    pub margin_mode: String,
20    pub equity: Decimal,
21    pub mm_required: Decimal,
22    pub maintenance_margin: Decimal,
23    /// "partial" or "full".
24    pub liquidation_mode: Option<String>,
25    pub target_equity: Option<Decimal>,
26    pub entered_pre_liq_at: Option<i64>,
27    pub mm_shortfall: Option<Decimal>,
28    pub escalation_deadline: Option<i64>,
29    pub last_reprice_at: Option<i64>,
30    pub partial_order_request_ids: Option<serde_json::Value>,
31    pub partial_order_client_ids: Option<serde_json::Value>,
32    pub partial_bonus_bps: Option<i32>,
33    pub auction_id: Option<String>,
34    pub request_id: Option<String>,
35    pub tx_hash: Option<String>,
36    pub auction_started_at: Option<i64>,
37    pub chain_start_time: Option<i64>,
38    pub margin_needed: Option<Decimal>,
39    pub stop_request_id: Option<String>,
40    pub stop_tx_hash: Option<String>,
41    pub liquidated_at: Option<i64>,
42    pub resolved_winner: Option<WalletAddress>,
43    pub resolved_bonus: Option<Decimal>,
44    pub resolution_tx_hash: Option<String>,
45    pub last_observed_block: Option<i64>,
46    pub updated_at_ms: Option<i64>,
47    pub created_at: Option<NaiveDateTime>,
48    pub updated_at: Option<NaiveDateTime>,
49}
50
51/// Audit trail entry for a liquidation state transition.
52#[derive(Debug, Clone, Serialize, Deserialize)]
53pub struct LiquidationHistoryRecord {
54    pub id: i64,
55    pub wallet_address: WalletAddress,
56    pub previous_state: String,
57    pub new_state: String,
58    pub liquidation_mode: Option<String>,
59    pub equity: Decimal,
60    pub mm_required: Decimal,
61    pub maintenance_margin: Decimal,
62    pub shortfall: Decimal,
63    pub auction_id: Option<String>,
64    pub request_id: Option<String>,
65    pub tx_hash: Option<String>,
66    pub margin_needed: Option<Decimal>,
67    pub winner_address: Option<WalletAddress>,
68    pub bonus: Option<Decimal>,
69    /// Full serialized `AccountLiquidationStatus` snapshot.
70    pub details: serde_json::Value,
71    pub timestamp: i64,
72    pub created_at: Option<NaiveDateTime>,
73}
74
75/// On-chain liquidation auction record.
76///
77/// Generates [`LiquidationAuctionUpdate`] via `#[derive(Changeset)]` for
78/// partial DB updates. `created_at`/`updated_at` auto-skipped.
79#[derive(Debug, Clone, Serialize, Deserialize, struct_convert::Changeset)]
80#[changeset_skip = "auction_id, wallet_address, positions, equity_at_start, mm_shortfall_at_start, target_equity, started_at"]
81#[changeset_name = "LiquidationAuctionUpdate"]
82pub struct LiquidationAuctionRecord {
83    pub auction_id: String,
84    pub wallet_address: WalletAddress,
85    /// "pending", "active", "completed", or "cancelled".
86    pub status: String,
87    pub positions: serde_json::Value,
88    pub equity_at_start: Decimal,
89    pub mm_shortfall_at_start: Decimal,
90    pub target_equity: Option<Decimal>,
91    pub request_id: Option<String>,
92    pub tx_hash: Option<String>,
93    pub started_at: i64,
94    pub chain_start_time: Option<i64>,
95    pub margin_needed: Option<Decimal>,
96    pub stop_request_id: Option<String>,
97    pub stop_tx_hash: Option<String>,
98    pub completed_at: Option<i64>,
99    pub liquidator_address: Option<WalletAddress>,
100    pub bonus: Option<Decimal>,
101    pub settlement_value: Option<Decimal>,
102    pub last_observed_block: Option<i64>,
103    pub created_at: Option<NaiveDateTime>,
104    pub updated_at: Option<NaiveDateTime>,
105}
106
107/// Result of applying a liquidation bonus to the winner's account.
108#[derive(Debug, Clone)]
109pub struct LiquidationBonusApplyResult {
110    pub ledger_event_id: Option<u64>,
111    pub newly_applied: bool,
112}
hypercall_db/types/liquidation.rs

hypercall_db/types/
liquidation.rs
