Struct SpotMarginLiquidation 

pub struct SpotMarginLiquidation(/* private fields */);

When the simulated venue liquidates a spot margin account, what it charges for it, and whether it warns first. Set by SpotMarginConfig::with_liquidation.

When

The venue checks the account’s margin level after each of its inputs, a market tick or a move of its clock, since those are what change it: prices move, and interest falls due. The level is the value of everything the account holds over the value of what it owes, loans plus interest, both valued as the leverage limit values them (see SpotMarginConfig’s # How much it lends): at the mid of a spot instrument pairing each asset with the valuation asset, else its last price. What it holds of an asset beyond what it owes of it counts at the asset’s liquidation_collateral_ratio, one by default (see SpotMarginConfig’s # Collateral ratios). There is no index price, so a market’s own mid stands in for the one a venue liquidates on. An asset the venue cannot value counts for nothing, which can bring a liquidation forward but never put one off. While it cannot value a debt it does not check, and warns once.

At or below level it liquidates.

How

It sends an AccountNotice of NoticeKind::Liquidation, then closes every debt:

1. It cancels every open order, resting or held, releasing what each held.
2. It repays each debt from the asset’s own free balance, interest first.
3. It repays what is still owed of the valuation asset with the proceeds of selling the account’s other assets, each on a spot instrument pairing it with the valuation asset, in name order, as much of each as is needed.
4. It buys back what is still owed of each other asset, in name order, on a spot instrument pairing it with the valuation asset, selling other assets for the valuation asset first as in step 3 when the account holds too little of it. What a buy delivers repays the debt.
5. It charges the fee: fee_rate times the value of the debt this repaid, in the valuation asset, raised as in step 3 if the account holds too little of it.

Each forced trade fills as a market order would on arrival, as a taker: priced by the venue’s fill model at its current market, slipped, limited by the depth on offer, and charged the venue’s fee. It is reported as [balance.., trade], the Trade carrying TradeOrigin::Liquidation, no client order id and an unknown strategy, with no order snapshot, since no client placed it. It is never held for a bar or a fresh market. Once priced it has drawn from the venue’s slippage stream, even if it then trades nothing, so a liquidation that runs over several inputs draws on each. The fee is reported as [balance, cash flow], a CashFlowKind::LiquidationFee with no instrument.

When it cannot close every debt

A debt can outlast an input when the depth on offer is too thin, when an asset has no market to trade on, or when the account holds too little to repay it. The venue then warns once, and leaves the rest owed: it has no insurance fund, and nothing floors the account’s balances.

The liquidation continues on each later input until no debt is left, without another notice: each input cancels whatever the account has since placed, repays what it can, and charges the fee on what it repaid.

Each pass’s fee is charged out of the account’s remaining assets after that pass’s repayments, selling for it as in step 3, as a venue takes its fee out of the proceeds of the liquidation’s trades. So a debt a pass leaves owed has that much less to be repaid from on the next pass. A fee the account cannot pay takes the valuation asset’s free balance below zero.

While the liquidation is under way the venue lends nothing. An order that would need a loan is rejected as unaffordable, its reason showing nothing borrowable, and so is the fill of a held order that would need one. One the account can pay for from its own balance is accepted, and cancelled by the next input if it is still open. A debt the venue cannot trade out of, for want of a market or of anything left to sell, keeps lending off until the account repays it.

Margin call

Off by default. With with_margin_call, the venue sends NoticeKind::MarginCall when the margin level falls to or below that level, and NoticeKind::MarginRestored when it rises back above it or the account no longer owes anything, once per crossing. A liquidation ends a margin call without a notice.

Each notice carries the margin level that caused it, None for an account that owes nothing, and its kind’s name as its status.

Not liquidated

A CFD position: its margin is posted from the quote asset, outside the spot margin account.

Serialised form

level, fee_rate and margin_call_level are decimal strings, and margin_call_level is left out when off. Deserialising refuses what the constructors refuse.

Implementations

impl SpotMarginLiquidation

pub fn new( level: Decimal, fee_rate: Decimal, ) -> Result<Self, SpotMarginConfigError>

Liquidation at a margin level of level or below, charging fee_rate of the debt it repays, with no margin call.

For example, a level of 1.1 and a fee rate of 0.02 liquidate an account whose holdings are worth 1.1 times its debt or less, and charge 2 % of what it repays.

Errors

SpotMarginConfigError::LiquidationLevelBelowOne for a level below one, and SpotMarginConfigError::LiquidationFeeOutOfRange for a fee_rate below zero or not below one.

pub fn with_margin_call( self, margin_call_level: Decimal, ) -> Result<Self, SpotMarginConfigError>

This liquidation, with a margin call at margin_call_level. See # Margin call.

Errors

SpotMarginConfigError::MarginCallNotAboveLiquidation if margin_call_level is not above the liquidation level.

pub fn level(&self) -> Decimal

The margin level at or below which the venue liquidates.

pub fn fee_rate(&self) -> Decimal

The fee, as a fraction of the value of the debt a liquidation repays.

pub fn margin_call_level(&self) -> Option<Decimal>

The margin level at or below which the venue sends a margin call, or None for none.

Trait Implementations

impl Clone for SpotMarginLiquidation

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SpotMarginLiquidation

impl Debug for SpotMarginLiquidation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SpotMarginLiquidation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SpotMarginLiquidation

impl Hash for SpotMarginLiquidation

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SpotMarginLiquidation

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for SpotMarginLiquidation

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for SpotMarginLiquidation

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for SpotMarginLiquidation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SpotMarginLiquidation