1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
//! Represent closed positions.
use shared::prelude::*;
use std::fmt;
use std::fmt::{Display, Formatter};
use super::{LiquidationMargin, Position, PositionId, PositionQueryResponse};
/// Information on a closed position
#[cw_serde]
pub struct ClosedPosition {
/// Owner at the time the position closed
pub owner: Addr,
/// ID of the position
pub id: PositionId,
/// Direction (to base) of the position
pub direction_to_base: DirectionToBase,
/// Timestamp the position was created, block time.
pub created_at: Timestamp,
/// Timestamp of the price point used for creating this position.
pub price_point_created_at: Option<Timestamp>,
/// Timestamp of the last liquifunding
pub liquifunded_at: Timestamp,
/// The one-time fee paid when opening or updating a position
///
/// this value is the current balance, including all updates
pub trading_fee_collateral: Collateral,
/// Cumulative trading fees expressed in USD
pub trading_fee_usd: Usd,
/// The ongoing fee paid (and earned!) between positions
/// to incentivize keeping longs and shorts in balance
/// which in turn reduces risk for LPs
///
/// This value is the current balance, not a historical record of each payment
pub funding_fee_collateral: Signed<Collateral>,
/// Cumulative funding fee in USD
pub funding_fee_usd: Signed<Usd>,
/// The ongoing fee paid to LPs to lock up their deposit
/// as counter-size collateral in this position
///
/// This value is the current balance, not a historical record of each payment
pub borrow_fee_collateral: Collateral,
/// Cumulative borrow fee in USD
pub borrow_fee_usd: Usd,
/// Cumulative amount of crank fees paid by the position
pub crank_fee_collateral: Collateral,
/// Cumulative crank fees in USD
pub crank_fee_usd: Usd,
/// Cumulative amount of delta neutrality fees paid by (or received by) the position.
///
/// Positive == outgoing, negative == incoming, like funding_fee.
pub delta_neutrality_fee_collateral: Signed<Collateral>,
/// Cumulative delta neutrality fee in USD
pub delta_neutrality_fee_usd: Signed<Usd>,
/// Deposit collateral for the position.
///
/// This includes any updates from collateral being added or removed.
pub deposit_collateral: Signed<Collateral>,
/// Deposit collateral in USD, using cost basis analysis.
#[serde(default)]
pub deposit_collateral_usd: Signed<Usd>,
/// Final active collateral, the amount sent back to the trader on close
pub active_collateral: Collateral,
/// Profit or loss of the position in terms of collateral.
///
/// This is the final collateral send to the trader minus all deposits (including updates).
pub pnl_collateral: Signed<Collateral>,
/// Profit or loss, in USD
///
/// This is not simply the PnL in collateral converted to USD. It converts
/// each individual event to a USD representation using the historical
/// timestamp. This can be viewed as a _cost basis_ view of PnL.
pub pnl_usd: Signed<Usd>,
/// The notional size of the position at close.
pub notional_size: Signed<Notional>,
/// Entry price
pub entry_price_base: PriceBaseInQuote,
/// the time at which the position is actually closed
///
/// This will always be the block time when the crank closed the position,
/// whether via liquidation, deferred execution of a ClosePosition call, or
/// liquifunding.
pub close_time: Timestamp,
/// needed for calculating final settlement amounts
/// if by user: same as close time
/// if by liquidation: first time position became liquidatable
pub settlement_time: Timestamp,
/// the reason the position is closed
pub reason: PositionCloseReason,
/// liquidation margin at the time of close
/// Optional for the sake of backwards-compatibility
pub liquidation_margin: Option<LiquidationMargin>,
}
/// Reason the position was closed
#[cw_serde]
#[derive(Eq, Copy)]
pub enum PositionCloseReason {
/// Some kind of automated price trigger
Liquidated(LiquidationReason),
/// The trader directly chose to close the position
Direct,
}
impl Display for PositionCloseReason {
fn fmt(&self, f: &mut Formatter) -> fmt::Result {
match self {
PositionCloseReason::Liquidated(reason) => write!(f, "{reason}"),
PositionCloseReason::Direct => f.write_str("Manual close"),
}
}
}
/// Reason why a position was liquidated
#[cw_serde]
#[derive(Eq, Copy)]
pub enum LiquidationReason {
/// True liquidation: insufficient funds in active collateral.
Liquidated,
/// Maximum gains were achieved.
MaxGains,
/// Stop loss price override was triggered.
StopLoss,
/// Specifically take profit override, not max gains.
TakeProfit,
}
impl Display for LiquidationReason {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
let str = match self {
LiquidationReason::Liquidated => "liquidated",
LiquidationReason::MaxGains => "max-gains",
LiquidationReason::StopLoss => "stop-loss",
LiquidationReason::TakeProfit => "take-profit",
};
write!(f, "{}", str)
}
}
/// Instructions to close a position.
///
/// Closing a position can occur for multiple reasons: explicit action by the
/// trader, settling price exposure (meaning: you hit a liquidation or take
/// profit), insufficient margin... the point of this data structure is to
/// capture all the information needed by the close position actions to do final
/// settlement on a position and move it to the closed position data structures.
#[derive(Clone, Debug)]
pub struct ClosePositionInstructions {
/// The position in its current state
pub pos: Position,
/// The capped exposure amount after taking liquidation margin into account.
///
/// Positive value means a transfer from counter collateral to active
/// collateral. Negative means active to counter collateral. This is not
/// reflected in the position itself, since Position requires non-zero
/// active and counter collateral, and it's entirely possible we will
/// consume the entirety of one of those fields.
pub capped_exposure: Signed<Collateral>,
/// Additional losses that the trader experienced that cut into liquidation margin.
///
/// If the trader
/// experienced max gains, then this value is 0. In the case where the trader
/// experienced a liquidation event and capped_exposure did not fully represent
/// losses due to liquidation margin, this value contains additional losses we would
/// like to take away from the trader after paying all pending fees.
pub additional_losses: Collateral,
/// The price point used for settling this position.
pub settlement_price: PricePoint,
/// See [ClosedPosition::reason]
pub reason: PositionCloseReason,
/// Did this occur because the position was closed during liquifunding?
pub closed_during_liquifunding: bool,
}
/// Outcome of operations which might require closing a position.
///
/// This can apply to liquifunding, settling price exposure, etc.
#[must_use]
#[derive(Debug)]
#[allow(clippy::large_enum_variant)]
pub enum MaybeClosedPosition {
/// The position stayed open, here's the current status
Open(Position),
/// We need to close the position
Close(ClosePositionInstructions),
}
impl From<MaybeClosedPosition> for Position {
fn from(maybe_closed: MaybeClosedPosition) -> Self {
match maybe_closed {
MaybeClosedPosition::Open(pos) => pos,
MaybeClosedPosition::Close(instructions) => instructions.pos,
}
}
}
/// Query response intermediate value on a position.
///
/// Positions which are open but need to be liquidated cannot be represented in
/// a [PositionQueryResponse], since many of the calculated fields will be
/// invalid. We use this data type to represent query responses for open
/// positions.
pub enum PositionOrPendingClose {
/// Position which should remain open.
Open(Box<PositionQueryResponse>),
/// The value stored here may change after actual close occurs due to pending payments.
PendingClose(Box<ClosedPosition>),
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ser_de_position_close_reason() {
for value in [
PositionCloseReason::Direct,
PositionCloseReason::Liquidated(LiquidationReason::Liquidated),
PositionCloseReason::Liquidated(LiquidationReason::MaxGains),
PositionCloseReason::Liquidated(LiquidationReason::StopLoss),
PositionCloseReason::Liquidated(LiquidationReason::TakeProfit),
] {
let json = serde_json::to_string(&value).unwrap();
let parsed = serde_json::from_str(&json).unwrap();
assert_eq!(value, parsed);
}
}
}