Market 1: feUSD CDP

For any questions, join the Felix Discord, and reach out to contributors.

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.

Parameter	Value
feUSD	0x02c6a2fa58cc01a18b8d9e00ea48d65e4df26c70
Collateral Registry	0x9de1e57049c475736289cb006212f3e1dce4711b
Hint Helpers	0xa32e89c658f7fdcc0bdb2717f253bacd99f864d4
WHYPE	0x5555555555555555555555555555555555555555

WHYPE Parameters

Parameter	Value
WHYPE Zapper (For Native Hype)	0xd389c600B302C05e619a25112B27eA07C62A6c8c
Active Pool	0x39ebba742b6917d49d4a9ac7cf5c70f84d34cc9e
Address Registry	0x7201fb5c3ba06f10a858819f62221ae2f473815d
Borrower Operations	0x5b271dc20ba7beb8eee276eb4f1644b6a217f0a3
Collateral Surplus Pool	0x9182e36bd7cceb71812c766c4464208ad9c122ca
Default Pool	0xa1e95e74d07fec324a82cd2ef19ebcb33907c605
Gas Pool	0x7560059081ede2ff6c6b980fd1ee9a53df4e9935
Price Feed	0x12a1868b89789900e413a6241ca9032dd1873a51
Sorted Troves	0xd1caa4218808eb94d36e1df7247f7406f43f2ef6
Stability Pool	0x576c9c501473e01ae23748de28415a74425efd6b
Trove Manager	0x3100f4e7bda2ed2452d9a57eb30260ab071bbe62
Trove NFT	0x5ad1512e7006fdbd0f3ebb8aa35c5e9234a03aa7

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.

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.

getFelixDebt() 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.

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.

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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