fintech-algorithms

Liquidation-Price Calculation

Install and import

bash
npm install fintech-algorithms
ts
import { liquidationPrice } from "fintech-algorithms/digital-assets-and-on-chain-finance/liquidity-and-liquidation/liquidation-price-calculation";

Signature

liquidationPrice(data, config)

The collateral price at which a position becomes liquidatable. The number a borrower actually needs — a health factor is abstract, a price is something you can set an alert on.

Parameters

NameTypeNotes
dataPositionInputPosition state — balances, prices, and the protocol parameters the calculation depends on.
configProtocolConfigProtocol-specific thresholds and factors. These differ per protocol and per asset, so a figure computed under the wrong config is confidently wrong.

Returns

{ status, value, components, diagnostics }

The result with every component, so a position's state can be reconciled against the protocol's own interface.

Errors

  • When a required protocol parameter is missing — reported as a status rather than thrown

Complexity: time O(assets), space O(assets).

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

data
{
  "collateral": [
    {
      "asset": "WETH",
      "quantity": 2,
      "price": 2000,
      "liquidation_threshold": 0.8,
      "eligible": true
    }
  ],
  "debts": [
    {
      "asset": "USDC",
      "quantity": 2500,
      "price": 1
    }
  ],
  "selected_asset": "WETH"
}
config
{
  "debt_multiplier": 1,
  "threshold_shift": 0
}

Call

liquidationPrice(data, config)

Returns

object with 11 fields: selected_asset, selected_quantity, current_selected_price, effective_selected_liquidation_threshold, total_debt_value, other_adjusted_collateral_value, liquidation_price, distance_to_liquidation_fraction, …

{
  "selected_asset": "WETH",
  "selected_quantity": 2,
  "current_selected_price": 2000,
  "effective_selected_liquidation_threshold": 0.8,
  "total_debt_value": 2500,
  "other_adjusted_collateral_value": 0,
  "liquidation_price": 1562.5,
  "distance_to_liquidation_fraction": 0.21875,
  "current_health_factor": 1.28,
  "reason": "finite break-even price",
  "trace": [
    {
      "price_multiplier": 0.4,
      "selected_price": 800,
      "health_factor": 0.512
    },
    {
      "price_multiplier": 0.4041666667,
      "selected_price": 808.3333333333,
      "health_factor": 0.5173333333
    },
    {
      "price_multiplier": 0.4083333333,
      "selected_price": 816.6666666667,
      "health_factor": 0.5226666667
    }
  ]
}

Other exports

This module also exports impermanentLoss, feeApr, healthFactor, liquidationWaterfall, runTopic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams

Liquidation-Price Calculation — boundary audit
Liquidation-Price Calculation — calculation map
Liquidation-Price Calculation — diagnostic deep dive
Liquidation-Price Calculation — family handoff
Liquidation-Price Calculation — parameter sensitivity
Liquidation-Price Calculation — scenario suite

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References