fintech-algorithms

Collateral-Health Factor

Install and import

bash
npm install fintech-algorithms
ts
import { healthFactor } from "fintech-algorithms/digital-assets-and-on-chain-finance/liquidity-and-liquidation/collateral-health-factor";

Signature

healthFactor(data, config)

The ratio of weighted collateral to debt in a lending position. Below 1 the position is liquidatable, which makes it the single number a borrower has to watch.

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
{
  "collateral_price_multiplier": 1,
  "debt_price_multiplier": 1
}

Call

healthFactor(data, config)

Returns

object with 10 fields: total_collateral_value, threshold_adjusted_collateral_value, total_debt_value, weighted_average_liquidation_threshold, health_factor, buffer_value, state, collateral_ledger, …

{
  "total_collateral_value": 4000,
  "threshold_adjusted_collateral_value": 3200,
  "total_debt_value": 2500,
  "weighted_average_liquidation_threshold": 0.8,
  "health_factor": 1.28,
  "buffer_value": 700,
  "state": "above-threshold",
  "collateral_ledger": [
    {
      "asset": "WETH",
      "value": 4000,
      "threshold": 0.8,
      "eligible": true,
      "adjusted_contribution": 3200
    }
  ],
  "debt_ledger": [
    {
      "asset": "USDC",
      "value": 2500
    }
  ],
  "trace": [
    {
      "collateral_price_multiplier": 0.4,
      "health_factor": 0.512,
      "adjusted_collateral_value": 1280
    },
    {
      "collateral_price_multiplier": 0.4041666667,
      "health_factor": 0.5173333333,
      "adjusted_collateral_value": 1293.3333333333
    },
    {
      "collateral_price_multiplier": 0.4083333333,
      "health_factor": 0.5226666667,
      "adjusted_collateral_value": 1306.6666666667
    }
  ]
}

Other exports

This module also exports impermanentLoss, feeApr, liquidationPrice, 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

Collateral-Health Factor — boundary audit
Collateral-Health Factor — calculation map
Collateral-Health Factor — diagnostic deep dive
Collateral-Health Factor — family handoff
Collateral-Health Factor — parameter sensitivity
Collateral-Health Factor — 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