> For the complete documentation index, see [llms.txt](https://docs.zestprotocol.com/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zestprotocol.com/start/stacks-market-smart-contracts/v2-contracts/egroup.md).
# 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
{% hint style="info" %}
Population = number of bits set in mask. Used for efficient egroup lookup.
{% endhint %}
### 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
{% hint style="info" %}
Searches population bucket matching mask's bit count for efficient lookup.
{% endhint %}
### find
Find egroup containing target asset.
Parameters
* `target` — uint — Target asset ID
Returns
* `(response uint uint)` — Egroup ID or error
{% hint style="info" %}
Searches for egroup where target bit is set in mask.
{% endhint %}
### 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
{% hint style="warning" %}
DAO executor only
{% endhint %}
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
{% hint style="warning" %}
DAO executor only
{% endhint %}
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