CollateralPoolConfig

https://github.com/Into-the-Fathom/fathom-stablecoin-smart-contracts/blob/master/contracts/main/stablecoin-core/config/CollateralPoolConfig.sol

The CollateralPoolConfig contract manages the configuration of different collateral pools within the Fathom protocol. It includes settings such as debt ceilings, liquidation ratios, and other important parameters that define the behavior and constraints of collateral pools.

Structs

CollateralPool

Defines the parameters and state of a collateral pool.

• totalDebtShare (uint256): The total debt share of the stablecoin issued against this collateral pool, denominated in wei.

• debtAccumulatedRate (uint256, ray): The accumulated rate which calculates the compounding stability fee over time. Initialized to 1 RAY (10^27).

• priceWithSafetyMargin (uint256, ray): The price of the collateral with a safety margin applied. This price accounts for the liquidation ratio.

• debtCeiling (uint256, rad): The maximum debt that can be issued against this collateral pool.

• debtFloor (uint256, rad): The minimum amount of debt required to open a position in this collateral pool.

• priceFeed (address): Address of the price feed contract which provides price updates for the collateral.

• liquidationRatio (uint256, ray): The minimum collateralization ratio required to avoid liquidation, expressed as a Ray.

• stabilityFeeRate (uint256, ray): The per-second stability fee rate, compounding to calculate the debt over time.

• lastAccumulationTime (uint256): The timestamp of the last update to the debtAccumulatedRate.

• adapter (address): The adapter address that handles token-specific logic for deposits and withdrawals.

• closeFactorBps (uint256): The percentage (in basis points) of debt that can be liquidated in one transaction.

• liquidatorIncentiveBps (uint256): Additional collateral percentage given to the liquidator as an incentive.

• treasuryFeesBps (uint256): The fee taken by the treasury on liquidations, expressed in basis points.

• strategy (address): Address of the liquidation strategy contract for this collateral pool.

• positionDebtCeiling (uint256, rad): The maximum debt that any single position can hold in this collateral pool.

CollateralPoolInfo

A simplified struct for returning basic information about a collateral pool.

• debtAccumulatedRate (uint256, ray): Current accumulated rate for stability fees.

• totalDebtShare (uint256): Total debt issued against this pool.

• debtCeiling (uint256, rad): Maximum debt allowed in this pool.

• priceWithSafetyMargin (uint256, ray): Price of collateral with safety margin considered.

• debtFloor (uint256, rad): Minimum debt per position.

• positionDebtCeiling (uint256, rad): Maximum debt per individual position.

Storage Variables

accessControlConfig

• Type: IAccessControlConfig

• Description: An instance of the IAccessControlConfig interface that provides functionalities for managing access control based on roles. This variable is crucial for enforcing role-based security within the contract, ensuring that only authorized roles can perform specific actions (e.g., updating pool configurations).

Set Functions

• setPriceWithSafetyMargin(bytes32 _collateralPoolId, uint256 _priceWithSafetyMargin): Sets the price with a safety margin for the specified pool. Only callable by the price oracle role.

• setDebtCeiling(bytes32 _collateralPoolId, uint256 _debtCeiling): Sets the debt ceiling for a pool. Only callable by the contract owner.

• setPositionDebtCeiling(bytes32 _collateralPoolId, uint256 _positionDebtCeiling): Sets the maximum debt that can be issued against a single position in the specified pool.

• setPriceFeed(bytes32 _poolId, address _priceFeed): Assigns a new price feed contract to a collateral pool.

• setLiquidationRatio(bytes32 _poolId, uint256 _liquidationRatio): Adjusts the liquidation ratio for a collateral pool.

• setStabilityFeeRate(bytes32 _collateralPoolId, uint256 _stabilityFeeRate): Sets the stability fee rate for a collateral pool.

• setDebtFloor(bytes32 _collateralPoolId, uint256 _debtFloor): Sets the minimum debt that can be created in a specific collateral pool, preventing under-collateralized positions.

• setAdapter(bytes32 _collateralPoolId, address _adapter): Updates the adapter address for a collateral pool, which handles specific token interactions for depositing and withdrawing collateral.

• setCloseFactorBps(bytes32 _collateralPoolId, uint256 _closeFactorBps): Sets the percentage (in basis points) of how much debt can be liquidated in a single transaction for a specific collateral pool.

• setLiquidatorIncentiveBps(bytes32 _collateralPoolId, uint256 _liquidatorIncentiveBps): Defines the incentive, in basis points, given to liquidators for performing liquidations in a specific pool.

• setTreasuryFeesBps(bytes32 _collateralPoolId, uint256 _treasuryFeesBps): Sets the treasury fees, in basis points, collected from liquidations in a specific collateral pool.

• setTotalDebtShare(bytes32 _collateralPoolId, uint256 _totalDebtShare): Updates the total debt share of the stablecoin issued against a specific collateral pool. Restricted to the bookkeeper role.

• setDebtAccumulatedRate(bytes32 _collateralPoolId, uint256 _debtAccumulatedRate): Updates the accumulated rate for calculating the compounding stability fee over time for a specific pool. Also restricted to the bookkeeper role.

• setStrategy(bytes32 _collateralPoolId, address _strategy): Assigns a new liquidation strategy contract to a collateral pool, which defines how liquidations should be handled.

• updateLastAccumulationTime(bytes32 _collateralPoolId): Updates the timestamp of the last accumulation of stability fees for a collateral pool. Restricted to the stability fee collector role.

View Functions

• collateralPools(bytes32 _collateralPoolId): Returns detailed information about a specific collateral pool.

• getTotalDebtShare(bytes32 _collateralPoolId): Retrieves the total debt share issued against a collateral pool.

• getDebtAccumulatedRate(bytes32 _collateralPoolId): Retrieves the current debt accumulated rate for a collateral pool.

• getPriceWithSafetyMargin(bytes32 _collateralPoolId): Retrieves the current price of the collateral in the pool, adjusted for the safety margin.

• getDebtCeiling(bytes32 _collateralPoolId): Retrieves the debt ceiling for a specific collateral pool.

• getPositionDebtCeiling(bytes32 _collateralPoolId): Gets the maximum amount of debt that can be taken out in a single position for a specified collateral pool.

• getDebtFloor(bytes32 _collateralPoolId): Retrieves the minimum debt amount that must be maintained in a position within a specific collateral pool.

• getPriceFeed(bytes32 _collateralPoolId): Returns the address of the price feed contract associated with a collateral pool.

• getLiquidationRatio(bytes32 _collateralPoolId): Retrieves the liquidation ratio for a collateral pool, determining the minimum required collateralization.

• getStabilityFeeRate(bytes32 _collateralPoolId): Retrieves the stability fee rate for a specific collateral pool.

• getLastAccumulationTime(bytes32 _collateralPoolId): Retrieves the timestamp of the last stability fee accumulation for a collateral pool.

• getAdapter(bytes32 _collateralPoolId): Returns the address of the token adapter associated with a collateral pool.

• getCloseFactorBps(bytes32 _collateralPoolId): Retrieves the close factor, in basis points, for a specific collateral pool.

• getLiquidatorIncentiveBps(bytes32 _collateralPoolId): Retrieves the liquidator incentive, in basis points, for a specific collateral pool.

• getTreasuryFeesBps(bytes32 _collateralPoolId): Retrieves the percentage of fees collected for the treasury from liquidations in a specific collateral pool.

• getStrategy(bytes32 _collateralPoolId): Returns the address of the liquidation strategy contract for a collateral pool.

• getCollateralPoolInfo(bytes32 _collateralPoolId): Provides a snapshot of current settings and state for a specific collateral pool.

Events

LogSetPriceWithSafetyMargin

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _priceWithSafetyMargin (uint256): The updated price of the collateral with the safety margin applied.

• Description: This event is emitted when the price with safety margin for a specific collateral pool is updated. The safety margin is a buffer that helps protect the protocol against rapid price fluctuations leading to under-collateralized loans.

LogSetDebtCeiling

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _debtCeiling (uint256): The updated debt ceiling of the pool.

• Description: This event is fired when the debt ceiling of a collateral pool is set. The debt ceiling is the maximum amount of debt that can be issued against the collateral in the pool.

LogSetDebtFloor

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _debtFloor (uint256): The updated debt floor of the pool.

• Description: Emitted when the debt floor of a collateral pool is updated. The debt floor is the minimum debt that must be maintained in any position within this pool, ensuring that very small positions do not disproportionately consume resources.

LogSetPriceFeed

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _poolId (bytes32): The identifier of the collateral pool.

  • _priceFeed (address): The address of the new price feed contract.

• Description: This event is emitted when the price feed for a collateral pool is changed. The price feed is a critical component that supplies the market price of the collateral, which is used to manage all economic activities related to the pool.

LogSetLiquidationRatio

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _poolId (bytes32): The identifier of the collateral pool.

  • _data (uint256): The updated liquidation ratio.

• Description: Emitted when the liquidation ratio of a collateral pool is updated. This ratio determines the threshold below which positions become subject to liquidation.

LogSetStabilityFeeRate

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _poolId (bytes32): The identifier of the collateral pool.

  • _data (uint256): The updated stability fee rate.

• Description: Fired when the stability fee rate for a collateral pool is set. This fee rate affects how quickly debt accrues on borrowed amounts.

LogSetAdapter

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _adapter (address): The address of the adapter contract.

• Description: Emitted when the adapter for a collateral pool is changed. Adapters handle the specific mechanics of interacting with different types of collateral.

LogSetCloseFactorBps

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _closeFactorBps (uint256): The updated close factor in basis points.

• Description: This event is emitted when the close factor for a collateral pool is updated. The close factor determines the percentage of a position that can be liquidated in a single transaction.

LogSetLiquidatorIncentiveBps

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _liquidatorIncentiveBps (uint256): The updated liquidator incentive in basis points.

• Description: Emitted when the liquidator incentive for a collateral pool is updated. This incentive is given to liquidators as a reward for executing liquidations.

LogSetTreasuryFeesBps

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _treasuryFeeBps (uint256): The updated treasury fees in basis points.

• Description: Fired when the treasury fees for a collateral pool are set. These fees are transferred to the treasury upon liquidations and contribute to the overall economic stability of the protocol.

LogSetTotalDebtShare

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _totalDebtShare (uint256): The updated total debt share.

• Description: This event is emitted when the total debt share for a collateral pool is updated. This represents the total amount of debt issued against the collateral in the pool.

LogSetDebtAccumulatedRate

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _debtAccumulatedRate (uint256): The updated accumulated rate for debt.

• Description: Emitted when the debt accumulated rate for a collateral pool is updated. This rate determines how stability fees compound over time.

LogSetStrategy

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _strategy (address): The address of the liquidation strategy contract.

• Description: Fired when the liquidation strategy for a collateral pool is updated. This strategy defines how liquidations should be conducted for the specific type of collateral.

LogPositionDebtCeiling

• Parameters:

  • _caller (address): The address of the user who called the function.

  • _collateralPoolId (bytes32): The identifier of the collateral pool.

  • _positionDebtCeiling (uint256): The updated maximum debt that can be taken out in a single position for the specified collateral pool.

• Description: This event is emitted when the position debt ceiling of a collateral pool is updated. This ceiling limits the maximum debt that any single position can hold within the pool.