> For the complete documentation index, see [llms.txt](https://docs.hann.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hann.finance/mechanics/deep-dives/redemptions.md). # Redemptions Redemption allocation, interest-rate ordering, fee calculations, and changes to collateral ratios A normal redemption burns USDHN and reduces the selected Troves’ debt. The redeemer receives collateral after a fee; the fee remains in those Troves. CollateralRegistry allocates the amount across branches, and each branch’s TroveManager selects positions. ## Branch allocation A branch participates when it is active, has not shut down, and its total collateral ratio (`TCR`) is at least its shutdown collateral ratio (`SCR`). For an eligible branch `j`, define: $$ u\_j = \max(\text{BranchDebt}\_j - \text{SPDeposits}\_j, 0) $$ This is debt that exceeds the branch’s Stability Pool deposits. The debt remains backed by Trove collateral. If the sum of `u_j` is positive, the requested redemption is capped at that sum and allocated in proportion to `u_j`. If every eligible branch has `u_j = 0`, allocation uses total branch debt instead. Ignoring integer division for this proportional expression: $$ A\_j = A \times \frac{w\_j}{\sum\_k w\_k} $$ Here `A` is the amount after the cap, and `w_j` is either `u_j` or the branch debt in the fallback case. The contract processes branches in registry order and recalculates the remaining amount and weights after each allocation, distributing the integer remainder through later allocations. ![A 25 USDHN redemption is split 40%, 20%, and 40% across branches by their debt above Stability Pool deposits.](https://2221521122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8nyFCptMbCTgKUyVYlHX%2Fuploads%2Fgit-blob-c76ae11934e4c8dd8b85cd68b5a0578c161b7499%2Fredemption-allocation.png?alt=media) Blue stacks represent branch debt; lime stacks represent USDHN deposited in the Stability Pool. The dashed portion is the debt above those deposits. **Example: 25 USDHN.** Before redemption, the three branches have debt of 150, 100, and 170 USDHN and Stability Pool deposits of 50, 50, and 70 USDHN. Their outside-debt weights are 100, 50, and 100. The redemption splits into 10, 5, and 10 USDHN. Stability Pool deposits stay unchanged, and the redeemer receives collateral after the fee. ## Trove order within each branch The normal redemption path: 1. Checks `lastZombieTroveId`, the recorded Trove with a small amount of debt left from an earlier redemption. 2. Starts at `SortedTroves.getLast()` and follows `getPrev()`, moving from the **lowest annual interest rate upward**. 3. Skips a Trove whose current collateral ratio is below 100% at the normal oracle price. 4. Applies accrued interest and redistribution before calculating the redeemable debt. 5. Uses the smaller of the remaining allocated USDHN and that Trove’s debt. ![Redeeming 250,000 USDHN reduces the 4% Trove's debt from 200,000 to zero and the 4.3% Trove's debt from 60,000 to 10,000. The 4.4% Trove keeps its 450,000 USDHN debt.](https://2221521122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8nyFCptMbCTgKUyVYlHX%2Fuploads%2Fgit-blob-94e1fd32c780e1f11c95531502de50ddc7eb4cb4%2Fredemption-order.png?alt=media) **Example: 250,000 USDHN allocated to one branch.** The 4% Trove contributes all 200,000 USDHN of its debt. The next Trove, at 4.3%, contributes 50,000 of its 60,000 USDHN debt. The allocation is then complete, leaving 10,000 USDHN in that Trove and the 4.4% Trove untouched. The optional iteration limit counts traversed Troves, including skipped ones. A limit of `0` removes that cap. The loop also stops when the allocation has been redeemed or no more Troves remain. Borrowers set their rate directly or use a configured interest-rate manager. Raising the rate moves a position later in the normal order and increases interest costs. Troves sharing a manager use the batch’s rate. ## Redemption fee The fee rate combines a floor and a base rate. Using fractions rather than 18-decimal raw integers: * `b`: stored base rate. * `m`: whole minutes since the last fee operation. * `A`: attempted amount after the branch cap. * `S`: USDHN token supply at the start of the transaction. * `λ = 0.998076443575628800`: per-minute decay factor. * `β = 1`: redemption increase divisor. * `f₀ = 0.005`: the 0.5% fee floor. $$ b\_{decayed} = b\lambda^m $$ $$ b\_{quote} = \min\left(1, b\_{decayed} + \frac{A}{\beta S}\right) $$ $$ f = \min(1, f\_0 + b\_{quote}) $$ The decay factor has a six-hour half-life. The base rate starts at 100% when the registry is deployed and decays with time. Integer fixed-point arithmetic is used on-chain. The transaction checks `f` against the caller’s maximum fee before redeeming. After execution, the stored base rate is updated using the **amount actually redeemed**. An iteration-limited partial redemption can therefore pay a fee quoted for a larger attempted amount. The registry exposes `getRedemptionRateWithDecay()`, `getRedemptionRateForRedeemedAmount(amount)`, and `getEffectiveRedemptionFeeInUSDHN(amount)`. These quotes depend on the current supply, rate, time, and amount. ## Collateral received and fee retained Let: * `r` be the USDHN redeemed against one Trove. * `pᵣ` be the branch’s redemption price per collateral token. * `f` be the redemption fee fraction. In normalized token units: $$ \text{CorrespondingCollateral} = \frac{r}{p\_r} $$ $$ \text{CollateralFee} = \frac{r}{p\_r}f $$ $$ \text{CollateralSent} = \frac{r}{p\_r}(1-f) $$ The Trove’s debt decreases by `r`. Its collateral decreases by `CollateralSent`; `CollateralFee` stays in the Trove. The contract uses `fetchPrice()` for the 100% eligibility check and `fetchRedemptionPrice()` for the output calculation. For a normal price `p`, collateral value `V`, and debt `D`, the new ratio is: $$ CR' = \frac{V-r(1-f)p/p\_r}{D-r} $$ This formula requires `r < D`. At full debt redemption, the debt becomes zero and the remaining collateral stays in the Trove. ## Collateral-ratio examples The following examples hold the collateral price constant and set fees and interest to zero. Collateral value and debt therefore decrease by the same amount `r`: $$ CR' = \frac{V-r}{D-r} $$ For `V > D` and `0 < r < D`: $$ CR' - CR = \frac{r(V-D)}{D(D-r)} > 0 $$ The position has less collateral and less debt, with a higher collateral ratio. ### Example 1: one redemption Start with `V = $200` and `D = 100` USDHN. The collateral ratio is `200 / 100 = 200%`. Redeeming 20 USDHN changes the position to `V′ = $180` and `D′ = 80` USDHN: $$ CR' = \frac{180}{80} = 225% $$ The collateral buffer increases while the collateral position becomes smaller. With a fee and equal normal/redemption prices, the fee retained in the Trove leaves additional collateral above this fee-free result. ### Example 2: borrowing after redemption Start from `V = $180`, `D = 80` USDHN, and `CR = 225%`. Borrow another 40 USDHN without adding collateral. Debt rises to 120 USDHN: $$ CR = \frac{180}{120} = 150% $$ Additional borrowing uses the collateral-ratio buffer created by the redemption. ### Example 3: a price drop after redemption Start again from `V = $180` and `D = 80` USDHN. A 40% collateral-price drop reduces the value to `180 × 0.6 = $108`: $$ CR = \frac{108}{80} = 135% $$ A branch with `MCR > 135%` can liquidate this position. At `MCR = 135%`, a further decline takes it below the threshold. Redemption reduces debt while collateral-price exposure remains. ## Small or fully redeemed debt When normal redemption leaves less than `MIN_DEBT`, the Trove becomes `zombie` and is removed from SortedTroves. A nonzero remainder can be recorded in `lastZombieTroveId` for the next redemption. Fully redeemed debt becomes zero; remaining collateral stays attached to the borrower’s Trove. Closing the Trove releases that collateral. A position with remaining small debt can be returned to active status through an eligible borrower adjustment. ## Helper and shutdown paths `RedemptionHelper` transfers USDHN from the caller, calls the registry, checks each collateral minimum in `_minCollRedeemed`, forwards collateral, and refunds unused USDHN. It requires a USDHN allowance. The app uses the direct registry route, which burns from the caller without consuming an allowance. A shut-down branch supports `TroveManager.urgentRedemption(amount, troveIds, minCollateral)`. The caller supplies Trove IDs rather than following normal interest-rate order. The current contract applies a 2% collateral bonus, capped by the Trove’s available collateral, with no normal redemption fee. The transaction enforces the supplied minimum collateral output. [Redemptions & Risk](/protocol/redemptions-and-risk.md) contains the app steps. [CDP Safety](/mechanics/deep-dives/cdp-safety.md) covers collateral ratios and [Risk Disclosure](/security/risk-disclosure.md) covers market, liquidity, and oracle risks. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.hann.finance/mechanics/deep-dives/redemptions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.