hypercall_db/traits/
liquidation.rs

1//! Liquidation persistence traits (async).
2//!
3//! Async because callers (liquidator, chain observer, API handlers) are
4//! in async contexts.
5
6use anyhow::Result;
7use async_trait::async_trait;
8use hypercall_types::WalletAddress;
9use rust_decimal::Decimal;
10
11use crate::{
12    LiquidationAuctionRecord, LiquidationAuctionUpdate, LiquidationBonusApplyResult,
13    LiquidationHistoryRecord, LiquidationStateRecord,
14};
15
16/// Read-only liquidation queries.
17#[async_trait]
18pub trait LiquidationReader: Send + Sync {
19    /// Current liquidation state for a wallet (or None if healthy and never tracked).
20    async fn get_liquidation_state(
21        &self,
22        wallet: &WalletAddress,
23    ) -> Result<Option<LiquidationStateRecord>>;
24
25    /// All liquidation states across all wallets.
26    async fn get_all_liquidation_states(&self) -> Result<Vec<LiquidationStateRecord>>;
27
28    /// Paginated liquidation history for a wallet. Returns (rows, total_count).
29    async fn get_liquidation_history(
30        &self,
31        wallet: &WalletAddress,
32        limit: i64,
33        offset: i64,
34    ) -> Result<(Vec<LiquidationHistoryRecord>, i64)>;
35
36    /// Most recent liquidation history entries across all wallets.
37    async fn get_recent_liquidation_history(
38        &self,
39        limit: i64,
40    ) -> Result<Vec<LiquidationHistoryRecord>>;
41
42    /// Load a single auction by ID.
43    async fn get_liquidation_auction(
44        &self,
45        auction_id: &str,
46    ) -> Result<Option<LiquidationAuctionRecord>>;
47
48    /// Highest `last_observed_block` across all auction rows.
49    async fn get_max_liquidation_observed_block(&self) -> Result<Option<u64>>;
50
51    #[cfg(any(test, feature = "test-utils"))]
52    async fn get_active_auctions_for_wallet(
53        &self,
54        wallet: &WalletAddress,
55    ) -> Result<Vec<LiquidationAuctionRecord>>;
56}
57
58/// Liquidation mutations.
59#[async_trait]
60pub trait LiquidationWriter: LiquidationReader {
61    /// Upsert liquidation state for a wallet.
62    async fn save_liquidation_state(&self, state: &LiquidationStateRecord) -> Result<()>;
63
64    #[cfg(any(test, feature = "test-utils"))]
65    async fn delete_liquidation_state(&self, wallet: &WalletAddress) -> Result<()>;
66
67    /// Insert a liquidation history audit trail entry. Returns the new row ID.
68    async fn insert_liquidation_history(&self, entry: &LiquidationHistoryRecord) -> Result<i64>;
69
70    /// Create a new liquidation auction record.
71    async fn create_liquidation_auction(&self, auction: &LiquidationAuctionRecord) -> Result<()>;
72
73    /// Update fields on an existing auction (status, timestamps, winner, etc).
74    async fn update_liquidation_auction(
75        &self,
76        auction_id: &str,
77        updates: &LiquidationAuctionUpdate,
78    ) -> Result<()>;
79
80    /// Claim and apply a liquidation bonus to the winner's account.
81    async fn claim_and_apply_liquidation_bonus(
82        &self,
83        winner: &WalletAddress,
84        liquidated_wallet: &WalletAddress,
85        auction_id: &str,
86        resolution_tx_hash: &str,
87        bonus: Decimal,
88        event_ts_ms: i64,
89    ) -> Result<LiquidationBonusApplyResult>;
90}
hypercall_db/traits/liquidation.rs

hypercall_db/traits/
liquidation.rs
