# Market 1: feUSD CDP

## Overview

The feUSD CDP is a a decentralized borrowing and stablecoin Market that builds on Liquity V2.

* **Borrowers** deposit HYPE or other assets as collateral and borrow feUSD with user-set interest rates.
* **Stability Pool Depositers** deposit feUSD to earn borrower interest & liquidation rewards.

#### Protocol Parameters

These parameters are common to all the collateral branches in the protocol. Each branch is independent to each other and they don't share any state.

<table><thead><tr><th width="303">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>feUSD</td><td>0x02c6a2fa58cc01a18b8d9e00ea48d65e4df26c70</td></tr><tr><td>Collateral Registry</td><td>0x9de1e57049c475736289cb006212f3e1dce4711b</td></tr><tr><td>Hint Helpers</td><td>0xa32e89c658f7fdcc0bdb2717f253bacd99f864d4</td></tr><tr><td>WHYPE</td><td>0x5555555555555555555555555555555555555555</td></tr></tbody></table>

#### WHYPE Parameters

<table><thead><tr><th width="303">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>WHYPE Zapper</td><td>0x999876BC29Bc2251539C900a1bCfC6C934991F49</td></tr><tr><td>WHYPE Zapper (Deprecated)</td><td>0xd389c600B302C05e619a25112B27eA07C62A6c8c</td></tr><tr><td>Active Pool</td><td>0x39ebba742b6917d49d4a9ac7cf5c70f84d34cc9e</td></tr><tr><td>Address Registry</td><td>0x7201fb5c3ba06f10a858819f62221ae2f473815d</td></tr><tr><td>Borrower Operations</td><td>0x5b271dc20ba7beb8eee276eb4f1644b6a217f0a3</td></tr><tr><td>Collateral Surplus Pool</td><td>0x9182e36bd7cceb71812c766c4464208ad9c122ca</td></tr><tr><td>Default Pool</td><td>0xa1e95e74d07fec324a82cd2ef19ebcb33907c605</td></tr><tr><td>Gas Pool</td><td>0x7560059081ede2ff6c6b980fd1ee9a53df4e9935</td></tr><tr><td>Price Feed</td><td>0x12a1868b89789900e413a6241ca9032dd1873a51</td></tr><tr><td>Sorted Troves</td><td>0xd1caa4218808eb94d36e1df7247f7406f43f2ef6</td></tr><tr><td>Stability Pool</td><td>0x576c9c501473e01ae23748de28415a74425efd6b</td></tr><tr><td>Trove Manager</td><td>0x3100f4e7bda2ed2452d9a57eb30260ab071bbe62</td></tr><tr><td>Trove NFT</td><td>0x5ad1512e7006fdbd0f3ebb8aa35c5e9234a03aa7</td></tr></tbody></table>

#### UBTC Parameters

<table><thead><tr><th width="322">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>UBTC</td><td>0x9fdbda0a5e284c32744d2f17ee5c74b284993463</td></tr><tr><td>feUBTC (Felix UBTC Wrapper for Decimals)</td><td>0xefbd9cfe88235f0e648aefb52c8e8dc152a9ad6f</td></tr><tr><td>Active Pool</td><td>0x8d99575ebbbda038a626ca769561c16fdd7a5939</td></tr><tr><td>Address Registry</td><td>0xfc4e20bd9f0e4f8782bea92a7bd8002367882407</td></tr><tr><td>Borrower Operations</td><td>0x36b7bd65276eda7cdc5f730da5cdb7ee7736672e</td></tr><tr><td>Collateral Surplus Pool</td><td>0xe7aba857f8e2c95462e69b93c7ea78ac19aafe38</td></tr><tr><td>Default Pool</td><td>0x50743a84c68a9d14d93364ed31afa4012183df1c</td></tr><tr><td>Gas Pool</td><td>0x8b71c92edf02dff693042e4e808d0568ccf0a137</td></tr><tr><td>Price Feed</td><td>0xf59f338424062dd1d44a9b4dd2721128a45358ab</td></tr><tr><td>Sorted Troves</td><td>0x642d979341eaac9c10623f5a58283aa72f6e2fa9</td></tr><tr><td>Stability Pool</td><td>0xabf0369530205ae56dd4c49629474c65d1168924</td></tr><tr><td>Trove Manager</td><td>0xbbe5f227275f24b64bd290a91f55723a00214885</td></tr><tr><td>Trove NFT</td><td>0xad8a43ac8da98990efa4d5ec7b91135965d5846b</td></tr></tbody></table>

#### kHYPE Parameters

<table><thead><tr><th width="319.43359375">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>kHYPE</td><td>0xfd739d4e423301ce9385c1fb8850539d657c296d</td></tr><tr><td>Active Pool</td><td>0xbfd0b103a49faf426f36864d19f5d871bf411a5a</td></tr><tr><td>Address Registry</td><td>0x382d2fe4eed8e35a5855321e62fd45ad60ca589f</td></tr><tr><td>Borrower Operations</td><td>0x3a2a181ab6e4ffb77c87ee201041a0806dadc397</td></tr><tr><td>Collateral Surplus Pool</td><td>0x246aceb6b121fe2cb7ec76fcf8e667fb8096f7b0</td></tr><tr><td>Default Pool</td><td>0xee6d1804feb4817d6db77f6f31b86673d7fc195f</td></tr><tr><td>Gas Pool</td><td>0xea5d5a859be7c96aa0481ed35170af8e277a9f8e</td></tr><tr><td>Price Feed</td><td>0x0a04e685f12e47b22b03c3763add63f1dd73265c</td></tr><tr><td>Sorted Troves</td><td>0x6bc81472c10ec526c14c8b0e8faa282f9368f86f</td></tr><tr><td>Stability Pool</td><td>0x56a346e0730cb209a93964c41cd36098030779ab</td></tr><tr><td>Trove Manager</td><td>0x7c07bb77b1cf9a5b40d92f805c10d90c90957e4a</td></tr><tr><td>Trove NFT</td><td>0x9d08780deec2270b8296f520b3fb28346abf6036</td></tr></tbody></table>

#### wstHYPE Parameters (coming soon)

<table><thead><tr><th width="324.61328125">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>wstHYPE</td><td>0x94e8396e0869c9f2200760af0621afd240e1cf38</td></tr><tr><td>Active Pool</td><td>0x7abca40474d6b5f000f801d7fe7e0df4c89425ff</td></tr><tr><td>Address Registry</td><td>0x6a1ce00901c3deb2683a6c63fcd158cc3adc2740</td></tr><tr><td>Borrower Operations</td><td>0x389c03c1f77981d158fbe286e7cafac2bb2fe83e</td></tr><tr><td>Collateral Surplus Pool</td><td>0x339d10ba20f3575ec9b44275f978dd38386f0f32</td></tr><tr><td>Default Pool</td><td>0x535a9ff6bfd0d9f1b64fe03f185b0af8ddeb7bd1</td></tr><tr><td>Gas Pool</td><td>0x5db69b925c35b85905255f0b9443bfefda97fce0</td></tr><tr><td>Price Feed</td><td>0x067e69ad6bdb8ee95cac31b34626f48eb6f169a2</td></tr><tr><td>Sorted Troves</td><td>0xa82c325553baee63bd97604e10a7cc40482008a1</td></tr><tr><td>Stability Pool</td><td>0xadfba621a75beced7dd1727b2067047b7eeedc8b</td></tr><tr><td>Trove Manager</td><td>0x58446c58caa8a6f6cc8be343f812ebf0b997c001</td></tr><tr><td>Trove NFT</td><td>0x7d29515fc4eaef2a01c46218b4cb8d2d8ae437e4</td></tr></tbody></table>

## Read Functions

### Total Collateral Balance

* **Contract**: Active Pool Contract
* **Purpose**: Returns the total collateral balance currently held in the Active Pool for a given collateral branch.
* **Parameters**: None
* **Return Values**:
  * `collBalance`: A `uint256` representing the total amount of collateral stored in the Active Pool.

```solidity
getCollBalance() external view returns (uint256 collBalance)
```

### Total feUSD Debt

* **Contract**: Active Pool Contract
* **Purpose**: Returns the total outstanding debt in the Active Pool contract for a given collateral branch, including recorded debt, pending interest, and batch management fees.
* **Parameters**: None
* **Return Values**:
  * `totalDebt`: A `uint256` representing the sum of:
    * `aggRecordedDebt`: The total recorded debt in the system.
    * `calcPendingAggInterest()`: The calculated pending interest on the aggregate debt.
    * `aggBatchManagementFees`: The total accumulated batch management fees.
    * `calcPendingAggBatchManagementFee()`: The calculated pending batch management fees.

```solidity
getfeUSDDebt() external view returns (uint256 totalDebt)
```

### Latest Trove Data

* **Contract**: Trove Manager Contract
* **Purpose**: Returns the most recent state of a specified Trove, including collateral, debt, and other relevant data.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove to be fetched.
* **Return Values**:
  * `trove`: A `LatestTroveData` struct containing the most recent state of the specified Trove, including:
    * `entireColl`: Total collateral held by the Trove.
    * `entireDebt`: Total debt of the Trove, including interest and fees.
    * `redistCollGain`: Collateral gains from redistribution.
    * `redistFelixDebtGain`: Debt gains from redistribution.
    * `annualInterestRate`: The annual interest rate currently applied to the Trove's debt.
    * `lastInterestRateAdjTime`: Timestamp of the last interest rate adjustment.

```solidity
getLatestTroveData(uint256 _troveId) external view returns (LatestTroveData memory trove)
```

### Total Stability Pool feUSD Deposits

* **Contract:** Stability Pool Contract
* **Purpose**: Returns the total amount of feUSD deposits currently held in the Stability Pool.
* **Parameters**: None
* **Return Values**:
  * `totalDeposits`: A `uint256` representing the cumulative sum of all feUSD deposits in the Stability Pool.

```solidity
getTotalFelixDeposits() external view returns (uint256 totalDeposits)
```

### Depositor Yield Gain with Pending

* **Contract**: Stability Pool Contract
* **Purpose**: Returns the total yield gain for a specific depositor, including both realized and pending yield from the Stability Pool.
* **Parameters**:
  * `_depositor`: The address of the user whose yield gain is being queried.
* **Return Values**:
  * `yieldGain`: A `uint256` representing the total yield gain of the depositor, including pending yield gains from the current epoch and scale.

```solidity
getDepositorYieldGainWithPending(address _depositor) external view returns (uint256 yieldGain)
```

### Compounded feUSD Deposit

* **Contract**: Stability Pool Contract
* **Purpose**: Returns the compounded value of a user's feUSD deposit in the Stability Pool, accounting for yield gains since the last update.
* **Parameters**:
  * `_depositor`: The address of the user whose compounded deposit is being queried.
* **Return Values**:
  * `compoundedDeposit`: A `uint256` representing the current value of the user's feUSD deposit after compounding yield gains and losses.

```solidity
getCompoundedFelixDeposit(address _depositor) public view returns (uint256 compoundedDeposit)
```

## Write Functions

### Open Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Opens a new Trove with the specified collateral and debt amount, setting the owner's position and initializing the interest rate and fee parameters.
* **Parameters**:
  * `_owner`: The address of the user opening the Trove.
  * `_ownerIndex`: Index to track the owner's position in the Trove list.
  * `_collAmount`: The amount of collateral (in the native token) to be deposited.
  * `_felixAmount`: The amount of feUSD stablecoin to be borrowed against the collateral.
  * `_upperHint`: ID of the Trove above the new Trove in the sorted list (for gas optimization).
  * `_lowerHint`: ID of the Trove below the new Trove in the sorted list (for gas optimization).
  * `_annualInterestRate`: The annual interest rate applied to the borrowed amount.
  * `_maxUpfrontFee`: The maximum allowable upfront fee for borrowing.
  * `_addManager`: Address authorized to add collateral to the Trove.
  * `_removeManager`: Address authorized to remove collateral from the Trove.
  * `_receiver`: Address receiving the borrowed feUSD stablecoin.
* **Return Values**:
  * `troveId`: A `uint256` representing the unique identifier of the newly opened Trove.

```solidity
openTrove(
    address _owner,
    uint256 _ownerIndex,
    uint256 _collAmount,
    uint256 _felixAmount,
    uint256 _upperHint,
    uint256 _lowerHint,
    uint256 _annualInterestRate,
    uint256 _maxUpfrontFee,
    address _addManager,
    address _removeManager,
    address _receiver
) external returns (uint256 troveId)
```

### Add Collateral to Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Increases the collateral balance of an existing Trove, enhancing its collateralization ratio and reducing liquidation risk.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove to which collateral is being added.
  * `_collAmount`: The amount of collateral (in the native token) to be added to the Trove.
* **Return Values**: None

```solidity
addColl(uint256 _troveId, uint256 _collAmount) external
```

### Withdraw Collateral from Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Decreases the collateral balance of an existing Trove, allowing the owner to withdraw collateral while maintaining the required collateralization ratio.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove from which collateral is being withdrawn.
  * `_collWithdrawal`: The amount of collateral to be withdrawn from the Trove.
* **Return Values**: None

```solidity
withdrawColl(uint256 _troveId, uint256 _collWithdrawal) external
```

### Borrow more feUSD from Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Increases the debt of an existing Trove, allowing the owner to withdraw additional feUSD stablecoin against the collateral while maintaining the required collateralization ratio.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove from which feUSD is being withdrawn.
  * `_felixAmount`: The amount of feUSD stablecoin to be withdrawn from the Trove.
  * `_maxUpfrontFee`: The maximum allowable upfront fee for the debt increase.
* **Return Values**: None

```solidity
withdrawFelix(uint256 _troveId, uint256 _felixAmount, uint256 _maxUpfrontFee) external
```

### Repay feUSD Debt in Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Decreases the debt of an existing Trove, allowing the owner to repay feUSD stablecoin and reduce the outstanding debt while increasing the collateralization ratio.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove whose debt is being repaid.
  * `_felixAmount`: The amount of feUSD stablecoin to be repaid towards the Trove's debt.
* **Return Values**: None

```solidity
repayFelix(uint256 _troveId, uint256 _felixAmount) external
```

### Adjust Trove Interest Rate

* **Contract**: Trove Manager Contract
* **Purpose**: Adjusts the annual interest rate of an existing Trove, recalculating the debt and updating the Trove's position in the sorted list accordingly. An upfront fee applies.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove whose interest rate is being adjusted.
  * `_newAnnualInterestRate`: The new annual interest rate to be applied to the Trove's debt.
  * `_upperHint`: Address of the Trove above the adjusted Trove in the sorted list (for gas optimization).
  * `_lowerHint`: Address of the Trove below the adjusted Trove in the sorted list (for gas optimization).
  * `_maxUpfrontFee`: The maximum allowable upfront fee for making the interest rate adjustment.
* **Return Values**: None

```solidity
adjustTroveInterestRate(
    uint256 _troveId,
    uint256 _newAnnualInterestRate,
    uint256 _upperHint,
    uint256 _lowerHint,
    uint256 _maxUpfrontFee
) external
```

### Close Trove

* **Contract**: Trove Manager Contract
* **Purpose**: Closes an existing Trove by repaying the entire debt, including accrued interest, batch fees, and redistribution gains. It returns the collateral to the owner and updates the protocol's state accordingly.
* **Parameters**:
  * `_troveId`: The unique identifier of the Trove to be closed.
* **Return Values**: None

```solidity
closeTrove(uint256 _troveId) external
```

### Provide to Stability Pool

* **Contract**: Stability Pool Contract
* **Purpose**: Deposits feUSD stablecoin into the Stability Pool, earning yield and collateral gains from liquidations. Optionally allows the user to claim accumulated yield during the deposit operation.
* **Parameters**:
  * `_topUp`: The amount of feUSD stablecoin to be added to the user's Stability Pool deposit.
  * `_doClaim`: A boolean indicating whether to claim accumulated yield gains during this operation.
* **Return Values**: None

```solidity
provideToSP(uint256 _topUp, bool _doClaim) external
```

### Withdraw from Stability Pool

* **Contract**: Stability Pool Contract
* **Purpose**: Withdraws feUSD stablecoin from the user's deposit in the Stability Pool. Optionally allows the user to claim accumulated yield and collateral gains during the withdrawal.
* **Parameters**:
  * `_amount`: The amount of feUSD stablecoin to withdraw from the Stability Pool.
  * `_doClaim`: A boolean indicating whether to claim accumulated yield and collateral gains during this operation.
* **Return Values**: None

```solidity
solidityCopyEditwithdrawFromSP(uint256 _amount, bool _doClaim) external
```

### **Batch Liquidate Troves**

* **Contract:** Trove Manager Contract
* **Purpose:** Executes the liquidation of multiple troves that are under the MCR threshold in a single transaction. This function is typically used to efficiently clear risky positions when the protocol detects unhealthy collateral ratios.
* **Parameters:**
  * `_troveArray`: An array of `uint256` values, each representing the ID of a trove to be liquidated.
* **Return Values:** None

```solidity
batchLiquidateTroves(uint256[] memory _troveArray) public
```

### **Redeem Collateral**

* **Contract:** Collateral Registry Contract
* **Purpose:** Enables users to redeem system collateral by burning a specified amount of feUSD. The redemption is performed against troves, starting from the trove with the lowest interest rate, and proceeding up to a maximum number of iterations.
* **Parameters:**
  * `_feUSDAmount`: The amount of feUSD stablecoin to redeem in exchange for collateral.
  * `_maxIterationsPerCollateral`: The maximum number of troves to process for each collateral type during redemption. Used to bound gas usage.
  * `_maxFeePercentage`: The maximum acceptable fee (as a percentage, scaled by 1e18) the user is willing to pay for the redemption. If the actual fee exceeds this value, the transaction will revert.
* **Return Values:** None

```solidity
redeemCollateral(
    uint256 _feUSDAmount,
    uint256 _maxIterationsPerCollateral,
    uint256 _maxFeePercentage
) external
```