BookKeeper

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

The BookKeeper manages the state and operations related to collateral pools within Fathom FXD Protocol. It involves the management of stablecoin debt, collateral ratios, and various fees associated with positions held in these pools.

Structs

CollateralPool: Contains detailed metrics and settings for each collateral pool, including debt shares, rates, ceilings, and specific fees.

• totalDebtShare (uint256, [wad]): Total debt share of FXD stablecoin for this collateral pool.

• debtAccumulatedRate (uint256, [ray]): Rate at which debt accumulates, essentially the price of the internal token.

• priceWithSafetyMargin (uint256, [ray]): Adjusted price accounting for the collateralization safety margin.

• debtCeiling (uint256, [rad]): Maximum allowable debt for this pool.

• debtFloor (uint256, [rad]): Minimum debt amount for positions within this pool.

• priceFeed (address): Oracle address providing the price feed.

• liquidationRatio (uint256, [ray]): Required collateral ratio to avoid liquidation.

• stabilityFeeRate (uint256, [ray]): Fee rate applied to the debt for maintaining stability.

• lastAccumulationTime (uint256, [unix epoch time]): Timestamp of the last debt rate accumulation.

• adapter (address): Interface for integrating external functionalities.

• closeFactorBps (uint256): Basis points describing the percentage of debt that can be liquidated in one action.

• liquidatorIncentiveBps (uint256): Additional collateral percentage awarded to liquidators.

• treasuryFeesBps (uint256): Collateral percentage allocated to the treasury from liquidations.

• strategy (address): Address of the strategy used for managing liquidations.

• positionDebtCeiling (uint256, [rad]): Maximum debt that an individual position can hold.

CollateralPoolInfo: Simplified version focused on essential metrics like debt rate, total debt share, and debt ceilings.

• debtAccumulatedRate (uint256, [ray]): Current debt accumulation rate for the pool.

• totalDebtShare (uint256, [wad]): Total shared debt in the pool.

• debtCeiling (uint256, [rad]): Debt ceiling of the pool.

• priceWithSafetyMargin (uint256, [ray]): Price adjusted for safety margins.

• debtFloor (uint256, [rad]): Minimum threshold of debt for the pool.

• positionDebtCeiling (uint256, [rad]): Maximum debt allowed per position.

Position: Structure representing individual positions within the collateral pools, focused on collateral and debt metrics.

• lockedCollateral (uint256, [wad]): Amount of collateral currently locked within this position.

• debtShare (uint256, [wad]): Share of the FXD stablecoin debt attributed to this position.

State Variables

positions

• Description: Retrieves the position details for a given collateral pool and position address.

• Parameters:

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

  • _positionAddress (address): The address of the position.

• Returns: Position struct containing the locked collateral and debt share of the position.

collateralToken

• Description: Retrieves the amount of collateral token that has been deposited into the protocol for a given collateral pool and address.

• Parameters:

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

  • _address (address): The address for which to retrieve the collateral token amount.

• Returns: uint256 representing the amount of collateral token.

stablecoin

• Description: Retrieves the amount of stablecoin that has been deposited or has not been withdrawn from the protocol for a given address.

• Parameters:

  • _address (address): The address for which to retrieve the stablecoin amount.

• Returns: uint256 representing the amount of stablecoin.

systemBadDebt

• Description: Retrieves the amount of system bad debt, which arises from late liquidations for a given address.

• Parameters:

  • _address (address): The address for which to retrieve the bad debt amount.

• Returns: uint256 representing the amount of bad debt.

poolStablecoinIssued

• Description: Retrieves the amount of stablecoin issued per collateral pool.

• Parameters:

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

• Returns: uint256 representing the amount of stablecoin issued for the specified collateral pool.

positionWhitelist

• Description: Checks if a position address has been whitelisted to allow adjustments by another address.

• Parameters:

  • _positionAddress (address): The position address.

  • _delegateAddress (address): The address to check if it has allowance to adjust the position.

• Returns: uint256 (1 for allowed, 0 for not allowed).

Set Functions

These functions are used to set or update key parameters of the collateral pools:

setPriceWithSafetyMargin(bytes32 collateralPoolId, uint256 priceWithSafetyMargin)

• collateralPoolId (bytes32): The identifier for the collateral pool.

• priceWithSafetyMargin (uint256): The new price of the collateral, adjusted to include the safety margin.

setTotalDebtShare(bytes32 collateralPoolId, uint256 totalDebtShare)

• collateralPoolId (bytes32): The identifier for the collateral pool.

• totalDebtShare (uint256): The new total debt share for the collateral pool.

setDebtAccumulatedRate(bytes32 collateralPoolId, uint256 debtAccumulatedRate)

• collateralPoolId (bytes32): The identifier for the collateral pool.

• debtAccumulatedRate (uint256): The new accumulated rate of debt for the collateral pool.

setPositionDebtCeiling(bytes32 collateralPoolId, uint256 positionDebtCeiling)

• collateralPoolId (bytes32): The identifier for the collateral pool.

• positionDebtCeiling (uint256): The new debt ceiling for any individual position within the collateral pool.

Update Function

updateLastAccumulationTime(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool for which the last accumulation time will be updated.

Retrieval Functions

These functions provide read-only access to various parameters and states within the collateral pools:

collateralPools(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the CollateralPool struct with detailed information.

getTotalDebtShare(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the total debt share as uint256.

getDebtAccumulatedRate(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the debt accumulated rate as uint256.

getPriceWithSafetyMargin(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the price adjusted for safety margin as uint256.

getDebtCeiling(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the debt ceiling as uint256.

getDebtFloor(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the debt floor as uint256.

getPositionDebtCeiling(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the position debt ceiling as uint256.

getPriceFeed(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the address of the price feed.

getLiquidationRatio(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the liquidation ratio as uint256.

getStabilityFeeRate(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the stability fee rate as uint256.

getLastAccumulationTime(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the last accumulation time as uint256.

getAdapter(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool. Returns the address of the adapter.

getCloseFactorBps(bytes32 collateralPoolId)

• collateralPoolId (bytes32): The identifier for the collateral pool

Events

LogSetTotalDebtCeiling

• Emitted when: The total debt ceiling of the system is updated.

• Parameters:

  • _caller (address indexed): The address of the user who initiated the update.

  • _totalDebtCeiling (uint256): The new total debt ceiling set for the system.

LogSetAccessControlConfig

• Emitted when: The access control configuration is updated.

• Parameters:

  • _caller (address indexed): The address of the user who initiated the update.

  • _accessControlConfig (address): The new address of the access control configuration.

LogSetCollateralPoolConfig

• Emitted when: The collateral pool configuration is updated.

• Parameters:

  • _caller (address indexed): The address of the user who initiated the update.

  • _collateralPoolConfig (address): The new address of the collateral pool configuration.

LogAdjustPosition

• Emitted when: A position is adjusted (collateral or debt share is changed).

• Parameters:

  • _caller (address indexed): The address of the user who made the adjustment.

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

  • _positionAddress (address indexed): The address of the position being adjusted.

  • _lockedCollateral (uint256): The amount of collateral locked.

  • _debtShare (uint256): The debt share associated with the position.

  • _positionDebtValue (uint256): The total debt value of the position.

  • _addCollateral (int256): The amount of collateral added or removed.

  • _addDebtShare (int256): The amount of debt share added or removed.

LogAddCollateral

• Emitted when: Collateral is added to a position.

• Parameters:

  • _caller (address indexed): The address of the user who added the collateral.

  • _usr (address indexed): The address of the position where collateral is added.

  • _amount (int256): The amount of collateral added.

LogMoveCollateral

• Emitted when: Collateral is moved from one position to another.

• Parameters:

  • _caller (address indexed): The address of the user who initiated the move.

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

  • _src (address): The source address from which collateral is moved.

  • _dst (address indexed): The destination address to which collateral is moved.

  • _amount (uint256): The amount of collateral moved.

LogMoveStablecoin

• Emitted when: Stablecoin is moved from one account to another.

• Parameters:

  • _caller (address indexed): The address of the user who initiated the move.

  • _src (address): The source address from which stablecoin is moved.

  • _dst (address indexed): The destination address to which stablecoin is moved.

  • _amount (uint256): The amount of stablecoin moved.

StablecoinIssuedAmount

• Emitted when: Stablecoin issuance data is recorded.

• Parameters:

  • _totalStablecoinIssued (uint256): Total stablecoin issued to date.

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

  • _poolStablecoinIssued (uint256): Amount of stablecoin issued for the specified collateral pool.

Role Management

These functions manage access control for different roles within the protocol, such as granting and revoking roles, and checking role assignments.

The BookKeeper serves as a comprehensive system for managing collateral pools, their configurations, and associated roles, ensuring robust control over the protocol's functionalities related to stablecoin issuance and collateral management.

Includes functions like grantRole, revokeRole, and hasRole, managing access and permissions within the protocol.

Events

RoleAdminChanged: Emitted when there is a change in the administration of a role within the system.

• role (bytes32 indexed): The role affected.

• previousAdminRole (bytes32 indexed): The previous administrator of the role.

• newAdminRole (bytes32 indexed): The new administrator of the role.

RoleGranted: Indicates that a role has been granted to an account.

• role (bytes32 indexed): The role that has been granted.

• account (address indexed): The account to which the role has been granted.

• sender (address indexed): The account that performed the role grant.

RoleRevoked: Signals that a role has been revoked from an account.

• role (bytes32 indexed): The role that has been revoked.

• account (address indexed): The account from which the role has been removed.

• sender (address indexed): The account that performed the role revocation.

Functions

hasRole(bytes32 role, address account)

• Checks if a specific account has been granted a specified role.

• Arguments:

  • role (bytes32): The identifier of the role to check.

  • account (address): The address of the account to check for the role.

• Returns: bool indicating whether the account has the specified role.

getRoleAdmin(bytes32 role)

• Retrieves the administrator role for a given role. The administrator role is capable of managing the permissions for the specified role, including granting and revoking it.

• Arguments:

  • role (bytes32): The role identifier for which the admin role is requested.

• Returns: bytes32 representing the admin role that manages the specified role.

grantRole(bytes32 role, address account)

• Grants a role to an account. This function can only be called by an account that has the admin role for the role being granted.

• Arguments:

  • role (bytes32): The role to be granted.

  • account (address): The address of the account to which the role will be granted.

• Emits: A RoleGranted event indicating that the role has been granted.

revokeRole(bytes32 role, address account)

• Revokes a role from an account. This function can only be called by an account that has the admin role for the role being revoked.

• Arguments:

  • role (bytes32): The role to be revoked.

  • account (address): The address of the account from which the role will be revoked.

• Emits: A RoleRevoked event indicating that the role has been revoked.

renounceRole(bytes32 role, address account)

• Allows an account to renounce a role it currently holds. This function is designed to be used in cases where an account needs to voluntarily give up its privileges, such as when the security of the account is compromised.

• Arguments:

  • role (bytes32): The role to be renounced.

  • account (address): The address of the account that is renouncing the role.

• Emits: A RoleRevoked event indicating that the role has been renounced by the account.