Egroup

Purpose: Efficiency groups defining risk parameters (LTV, liquidation curves) per asset combination. Enforces superset invariant: broader collateral masks have lower/equal LTV.

List of Core Functions

Queries:

• get-nonce
• lookup
• get-popbucket
• get-bucket
• get-reverse
• serialize-and-validate-input
• resolve
• find

Admin:

• insert
• update

Function Details

get-nonce

Get total number of registered efficiency groups.Parameters

• (none)

Returns

• (response uint uint) — Egroup count

lookup

Get egroup details by ID.Parameters

• id — uint — Egroup ID

Returns

• {...} — Egroup configuration

get-popbucket

Get population bucket metadata (number of buckets).Parameters

• (none)

Returns

• uint — Population bucket count

get-bucket

Get list of egroup IDs in specific population bucket.

Parameters

• pop-b1 — (buff 1) — Population bucket ID

Returns

• (optional (list 128 uint)) — List of egroup IDs or none

get-reverse

Get egroup ID by mask (exact match).

Parameters

• mask — uint — Asset combination mask

Returns

• (optional uint) — Egroup ID or none if not found

serialize-and-validate-input

Validate and serialize egroup parameters before insertion/update.

Parameters

• ltv-params — { borrow: uint, liq-partial: uint, liq-full: uint } — LTV parameters (BPS)
• liq-params — { exp: uint, penalty-min: uint, penalty-max: uint, factor-mul: uint, factor-denom: uint } — Liquidation curve parameters

Returns

• (response {...} uint) — Serialized parameters or error

Validations

• LTV-borrow ≤ LTV-liq-partial ≤ LTV-liq-full
• All LTV values ≤ 10000 BPS
• Liquidation curve params within bounds

resolve

Find egroup for given collateral/debt mask. Returns egroup with smallest matching mask.

Parameters

• mask — uint — Collateral + debt mask (bits 0-63 = collateral, 64-127 = debt)

Returns

• (response uint uint) — Egroup ID or error

find

Find egroup containing target asset.

Parameters

• target — uint — Target asset ID

Returns

• (response uint uint) — Egroup ID or error

insert

Create new efficiency group with risk parameters.

Parameters

• mask — uint — Asset combination mask (collateral + debt)
• ltv-params — { borrow: uint, liq-partial: uint, liq-full: uint } — LTV thresholds (BPS: 10000 = 100%)
• liq-params — { exp: uint, penalty-min: uint, penalty-max: uint, factor-mul: uint, factor-denom: uint } — Liquidation curve parameters (BPS)

Returns

• (response uint uint) — New egroup ID or error

Authorization

Constraints

• Mask not already registered
• Superset invariant: if new mask is superset of existing, LTVs must be ≤ existing
• LTV-borrow ≤ LTV-liq-partial ≤ LTV-liq-full
• All parameters within valid ranges

LTV Parameters

• borrow: Max LTV for new borrows (e.g., 8000 = 80%)
• liq-partial: LTV threshold where partial liquidation allowed (e.g., 8500 = 85%)
• liq-full: LTV threshold where full liquidation allowed (e.g., 9000 = 90%)

Liquidation Curve Parameters

• exp: Exponent for liquidation penalty curve (BPS)
• penalty-min: Minimum liquidation bonus (BPS, e.g., 500 = 5%)
• penalty-max: Maximum liquidation bonus (BPS, e.g., 1500 = 15%)
• factor-mul: Multiplier for liquidation amount (BPS, max 5000 = 50% position)
• factor-denom: Denominator for liquidation amount (BPS, min 40000 = 2.5%)

update

Update existing egroup parameters.

Parameters

• id — uint — Egroup ID to update
• mask — uint — New asset combination mask
• ltv-params — { borrow: uint, liq-partial: uint, liq-full: uint } — New LTV thresholds (BPS)
• liq-params — { exp: uint, penalty-min: uint, penalty-max: uint, factor-mul: uint, factor-denom: uint } — New liquidation curve parameters

Returns

• (response bool uint) — Success or error

Authorization

Constraints

• Same as insert, plus superset invariant validated against ALL existing egroups except self
• Mask can be changed if new mask not already registered and invariant holds