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

Fields returned by lookup

---

get-popbucket

Get population bucket metadata (number of buckets).Parameters

• (none)

Returns

• uint — Population bucket count

Population = number of bits set in mask. Used for efficient egroup lookup.

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

Searches population bucket matching mask's bit count for efficient lookup.

find

Find egroup containing target asset.

Parameters

• target — uint — Target asset ID

Returns

• (response uint uint) — Egroup ID or error

Searches for egroup where target bit is set in mask.

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

DAO executor only

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

DAO executor only

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