# 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.zestprotocol.com/start/stacks-market-v2-smart-contracts-overview/v2-contracts/egroup.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.