How pegging works

When the price of FXD on some market (DEX or CEX) is less than $1, the arbitrageurs are looking for an incentive to arbitrage it with the market, which has a price closer to or more than $1. The below images show how the FXD price is pegged from time 0 to time 2.

When the market price of FXD is greater than $1, it provides an incentive to sell FXD in the market. The below images show how the FXD price is pegged from time 0 to time 2.

StableSwapModule (SSM) is the special mechanism developed by the Fathom team to provide an additional incentive for arbitrageurs.

What is the Fathom Protocol?

The Fathom Protocol is a pioneering decentralized finance platform. Its primary aim is to bolster the liquidity by positioning FXD, an over-collateralized and soft-pegged stablecoin. The other parts of the Fathom ecosystem are built around FXD: Vaults, Lending, DEX and Oracles. Fathom is operated in the DAO framework..

Key Highlights of the Fathom Protocol

1. Fathom's FXD: The Over-Collateralized, Soft-Pegged Stablecoin: FXD stands as a cornerstone of the Fathom Protocol, being soft-pegged to the US dollar. This approach provides a stable and reliable digital currency, aiming to minimize cryptocurrency's inherent volatility.

2. Fathom's Vaults: Platform designed for astute investors seeking to enhance their digital asset portfolio. Vaults offer a secure and dynamic way to grow cryptocurrency investments through robust yield strategies.

3. Fathom's Lending: Decentralized non-custodial liquidity market where users can participate as suppliers or borrowers. Suppliers provide liquidity to the market to earn a passive income, while borrowers can borrow in an over-collateralized (perpetually) or under-collateralized (one-block liquidity) fashion.

4. Fathom's Decentralized Exchange (DEX): As the central trading hub within the Fathom ecosystem, the DEX enhances the liquidity of both XDC and FXD. It's a key platform for facilitating secure and efficient trading activities.

5. Fathom's Oracles: Decentralized oracle network powered by Fathom's FXD with high availability, reliability, and data accuracy.

6. Governance through Fathom DAO: The Fathom protocol is driven by the Decentralized Autonomous Organization (DAO), which integrates the FTHM token, governance, and staking. This framework empowers FTHM token holders with voting rights and a say in the protocol's governance and future direction.

Vision for DeFi Evolution: The Fathom Protocol is uniquely positioned to contribute significantly to the evolution of DeFi. Its focus on providing a stable digital currency and a fluid trading environment underscores its commitment to advancing decentralized finance.

The complete explanation of the Fixed Spread Liquidation Strategy can be found in https://docs.fathom.fi/whitepaper/version-1.0#id-3.1.3-fxd-fixed-spread-liquidation-strategy.

The images below depict the functional flows for opening and closing positions.

The emergency shutdown process for Fathom's FXD is a comprehensive mechanism designed to safeguard both the protocol and its users in a significant crisis. This process is crucial for maintaining stability in decentralized finance (DeFi) systems. The emergency shutdown facilitates the return of excess collateral from safe positions. It allows for the return of collateral to those who give back FXD to the protocol, using a specific FXD to Collateral conversion ratio determined during the emergency shutdown. Here's a detailed explanation of the Fathom protocol's emergency shutdown procedure:

1. Initiating Emergency Shutdown

• Caging the Protocol: The shutdown process starts with the protocol owner calling the cage function in the ShowStopper contract. This action halts most activities within the protocol and is irreversible. The _cageCooldown period is the time allotted for calling the accumulateBadDebt function before the finalizeDebt function is executed.

function cage(uint256 _cageCoolDown) external;

• Caging Specific Collateral Pools: The cagePool function is then called to initiate the shutdown for a particular collateral pool type, marking a point of no return for that pool.

function cagePool(bytes32 _collateralPoolId) external;

• Accumulating Bad Debt: The accumulateBadDebt function, is called for all positions, leaving each with a certain amount of excess collateral. All positions within the protocol must undergo this process. If any positions have not been processed by users using accumulateBadDebt, the protocol administrator must ensure that all remaining positions are appropriately managed.

function accumulateBadDebt(bytes32 _collateralPoolId, address _positionAddress) external;

• Redeeming Locked Collateral: Position owners can then use the redeemLockedCollateral function to transfer this excess collateral to a specified receiver. The receiver's collateral balance is recorded in the BookKeeper.

function redeemLockedCollateral(
    bytes32 _collateralPoolId,
    address _positionAddress,
    address _collateralReceiver,
    bytes calldata /* _data */
) external;

3. Returning FXD and Retrieving Collateral

• Finalizing Debt and Price: After dealing with bad debt by calling accumulateBadDebt function for all the positions, the finalizeDebt function is called to fix the debt amount, followed by the finalizeCashPrice function to set a conversion ratio from FXD to collateral. finalizeDebt function will revert if there will be remaining systemSurplus.

function finalizeDebt() external;

• Depositing FXD: FXD Owners deposit their FXD into the system using the stablecoinAdapterDeposit function in the FathomStablecoinProxyActions contract. Since the FathomStablecoinProxyActions contract serves as a library for the ProxyWallet contract, calls to the stablecoinAdapterDeposit function need to be well-encoded and executed using the execute function of the ProxyWallet, owned by the FXD owner. When encoding the function call, the _positionAddress argument must match the address of the FXD Owner depositing FXD into the protocol.

function stablecoinAdapterDeposit(
    address _adapter,
    address _positionAddress,
    uint256 _stablecoinAmount, // [wad]
    bytes calldata _data
) public;

function execute(bytes memory _data) public payable returns (bytes memory _response);

• Whitelisting and Accumulating Stablecoin: FXD owners must whitelist the ShowStopper contract in the BookKeeper contract to allow FXD/Collateral manipulation. They then call accumulateStablecoin to move the FXD accounting from the BookKeeper to the ShowStopper’s stablecoinAccumulator.

function accumulateStablecoin(uint256 _amount) external;

• Redeeming Stablecoin for Collateral: FXD owners use redeemStablecoin to transfer collateral from the ShowStopper to their account (EOA) within the BookKeeper.

function redeemStablecoin(bytes32 _collateralPoolId, uint256 _amount) external;

4. Final Withdrawal of Collateral

• Caging the CollateralTokenAdapter: This action signifies the end of the process for depositing FXD and retrieving collateral. The owner of the protocol does the caging.

• Emergency Withdrawal: Finally, users can call the emergency withdrawal function to withdraw their collateral.

function emergencyWithdraw(address _to) external;

5. Responsibility of Users

• Adhering to Process: Users are advised to follow the steps specified to reduce confusion and ensure a smooth process.

• Bearing Consequences of Deviation: If a user deviates from the prescribed process and incurs a loss, they bear the responsibility for their actions.

6. Responsibility of the protocol

• Providing instruction: In times of emergency, the Fathom protocol team should provide user-friendly interfaces to ensure that users do not have to deal with overly technical tasks, such as encoding a function call and directly calling the smart contracts.

• Skimming all the positions: The protocol administrator must ensure that all positions are processed using the accumulateBadDebt function before the coolDownPeriod ends to ensure the correct execution of the emergency shutdown process.

• Settling systemBadDebt and withdrawing systemSurplus: The protocol administrator must ensure that the systemBadDebt is settled using the systemSurplus, and all the surplus (if any is left) is withdrawn before the finalizeDebt function is called.

Summary of the Fathom's FXD Emergency Shutdown

The emergency shutdown of Fathom's FXD is an intricate, irreversible, multi-step process crucial for preserving the stability and security of the decentralized finance (DeFi) system during significant crises. This procedure involves several key stages:

1. Initiating Emergency Shutdown: The process begins with halting most protocol activities through the cage function in the ShowStopper contract, marking a no-return point. The cooldown period following this action allows for the necessary processing of positions.

2. Handling Excess Collateral from Positions: The accumulateBadDebt function, essential for managing excess collateral, must be applied to all positions. This responsibility falls to the protocol administrator if not completed by users. Subsequently, position owners can transfer excess collateral using the redeemLockedCollateral function.

3. Returning FXD and Retrieving Collateral: After handling bad debt, the finalizeDebt function is called to solidify the debt amount, followed by the finalizeCashPrice function for setting the FXD to collateral conversion ratio. FXD owners must deposit their tokens using the stablecoinAdapterDeposit function, which requires precise encoding and execution. They also need to whitelist the ShowStopper contract for FXD/Collateral manipulation, followed by using redeemStablecoin to transfer collateral.

4. Final Withdrawal of Collateral: The process concludes with caging the CollateralTokenAdapter and the final step of emergencyWithdraw by users to reclaim their collateral.

5. User and Protocol Responsibilities: Users must adhere to the specified process sequence to minimize confusion and prevent losses. Any deviation leading to losses falls under the user's responsibility. On the protocol's end, providing user-friendly interfaces during emergencies and ensuring all positions are skimmed within the cooldown period is critical for smooth shutdown execution. The protocol administrator is also responsible for settling system bad debt and withdrawing any remaining system surplus before calling finalizeDebt.

Minting Mechanism with LTV Ratio Consideration

1. Collateralization and LTV Ratio: In the Fathom Protocol, users provide collateral to borrow FXD. The Loan-to-Value (LTV) ratio determines the maximum loan amount. This ratio specifies the maximum proportion of the borrowed value relative to the collateral's value.

2. Example of LTV-Based Minting: For instance, if a user collateralizes $100 worth of collateral asset and the LTV ratio is 65%, the user can borrow up to $65 worth of FXD. This system ensures that the minting of FXD is always in alignment with the value of the collateral based on the predetermined LTV ratio.

3. Ensuring Balanced Issuance: The LTV ratio is a crucial parameter in smart contracts, ensuring that the issuance of FXD is balanced and proportionate to the underlying collateral. This prevents over-minting and maintains the protocol’s financial stability.

Burning Mechanism and Liquidation Process

1. Position Closure and FXD Return: When users close their positions, they return the borrowed FXD to the protocol. The smart contracts immediately burn this returned FXD, removing it from circulation.

2. Liquidation Trigger and Process: If the market value of the collateralized asset falls such that the LTV ratio is breached (i.e., the value of the borrowed FXD exceeds the adjusted permissible limit), a liquidation process may be initiated. This process involves the sale of the collateralized asset to liquidators in exchange for FXD.

3. FXD Burning Post-Liquidation: The FXD acquired by the liquidator in exchange for the asset is then burned. This step is crucial for offsetting the outstanding debt and maintaining the financial equilibrium of the Fathom Protocol.

The FathomStablecoinProxyActions contract enables complex operations such as opening, managing, and interacting with positions (vaults) that hold collateral and issue stablecoins. It handles tasks like depositing collateral, drawing stablecoins against it, paying back debt, and unlocking collateral.

The address for this interface should be the address of the particular ProxyWallet.

Functions:

Admin Functions:

• whitelist(address _bookKeeper, address _usr):

  • Arguments:

    • _bookKeeper: The address of the bookkeeper contract.

    • _usr: The address to be whitelisted.

• blacklist(address _bookKeeper, address _usr):

  • Arguments:

    • _bookKeeper: The address of the bookkeeper contract.

    • _usr: The address to be blacklisted.

Position Management Functions:

• allowManagePosition(address _manager, uint256 _positionId, address _user, uint256 _ok):

  • Arguments:

    • _manager: Address of the position management contract.

    • _positionId: Numeric ID of the position.

    • _user: Address of the user to be allowed or disallowed.

    • _ok: Permission flag (typically 0 or 1).

• allowMigratePosition(address _manager, address _user, uint256 _ok):

  • Arguments:

    • _manager: Address of the position management contract.

    • _user: Address of the user whose migration permissions are being set.

    • _ok: Permission flag (typically 0 or 1).

• exportPosition(address _manager, uint256 _positionId, address _destination):

  • Arguments:

    • _manager: Address of the position management contract.

    • _positionId: Numeric ID of the position.

    • _destination: Address where the position should be exported.

• importPosition(address _manager, address _source, uint256 _positionId):

  • Arguments:

    • _manager: Address of the position management contract.

    • _source: Address from which the position is imported.

    • _positionId: Numeric ID of the position.

• movePosition(address _manager, uint256 _source, uint256 _destination):

  • Arguments:

    • _manager: Address of the position management contract.

    • _source: Numeric ID of the source position.

    • _destination: Numeric ID of the destination position.

Collateral and Stablecoin Management Functions:

• safeLockXDC(address _manager, address _xdcAdapter, uint256 _positionId, address _owner, bytes calldata _data):

  • Arguments:

    • _manager: Address of the manager contract.

    • _xdcAdapter: Address of the XDC adapter contract.

    • _positionId: Numeric ID of the position.

    • _owner: Address of the owner of the position.

    • _data: Additional data passed in call.

• draw(address _manager, address _stabilityFeeCollector, address _stablecoinAdapter, uint256 _positionId, uint256 _amount, bytes calldata _data):

  • Arguments:

    • _manager: Address of the manager contract.

    • _stabilityFeeCollector: Address of the stability fee collector.

    • _stablecoinAdapter: Address of the stablecoin adapter.

    • _positionId: Numeric ID of the position.

    • _amount: Amount of stablecoins to draw.

    • _data: Additional data passed in call.

Events:

• LogBorrowedAmount(address _positionAddress, uint256 _FXDBorrowAmount):

  • Arguments:

    • _positionAddress: Address of the position from which stablecoins were borrowed.

    • _FXDBorrowAmount: Amount of stablecoins borrowed.

• LogPaidAmount(address _positionAddress, uint256 _FXDPaidAmount):

  • Arguments:

    • _positionAddress: Address of the position to which stablecoins were repaid.

    • _FXDPaidAmount: Amount of stablecoins repaid.

totalStablecoinIssued

The formula mentioned above is used in all the functions that manipulate the totalStablecoinIssued and poolStablecoinIssued variables. If the value on the right-hand side of the equation changes, the value on the left side must be changed exactly the same way.

Now, let's delve deeper into the functions that manipulate the poolStablecoinIssued and totalStablecoinIssued variables. We will see how the above mentioned equation affects each function, starting with poolStablecoinIssued.

poolStablecoinIssued

The variable poolStablecoinIssued is stored in the BookKeeper contract. Three functions manipulate poolStablecoinIssued.

fn adjustPosition

This function manipulates both poolStablecoinIssued and totalStablecoinIssued.

The adjustPosition function changes the lockedCollateral and debtShare values mapped to each position. When the debtShare in a position decreases, poolStablecoinIssued also decreases. Conversely, when the debtShare in a position increases, the value of poolStablecoinIssued increases. It calculates the amount by which the debt value in a position has increased or decreased and adjusts the poolStablecoinIssued value accordingly. The adjustPosition function also manipulates the totalStablecoinIssued variable.

For example:

If debtShare in position, which is of collateral XYZ, decreases by 10, then

• poolStablecoinissued[XYZ] decreases by 10*debtAccumulatedRate

• totalStablecoinIssued decreases by 10*debtAccumulatedRate

fn confiscatePosition

This function manipulates both poolStablecoinIssued and totalUnbackedStablecoin but not totalStablecoinIssued.

The confiscatePosition function removes collateral and debt from a position and transfers them to addresses specified in the function arguments. During this process, the pool-specific balance is deducted. The amount of debt deducted from poolStablecoinIssued results in an increase in both the systemBadDebt[_stablecoinDebtor] and totalUnbackedStablecoin.

However, the totalStablecoinIssued is unaffected because it is the sum of all poolStablecoinIssued values and totalUnbackedStablecoin. The confiscatePosition function essentially transfers values from poolStablecoinIssued to totalUnbackedStablecoin, ensuring that the totalStablecoinIssued remains unchanged.

What the confiscatePosition function does is transition from equation A to equation B.

Equation A

Equation B

When α represents the amount of debt transferred from poolStablecoinIssued tot unbackedStablecoin by confiscatePosition function.

fn accrueStabilityFee

This function manipulates both poolStablecoinIssued and totalStablecoinIssued variables.

The accrueStabilityFee function increases the value of poolStablecoinIssued[_collateralPoolId]. This action of accruing stability fees involves recalculating the total amount of debt issued from a specific collateral type. Due to the increase in poolStablecoinIssued[_collateralPoolId], the totalStablecoinIssued value also increases.

Where β represents the amount by which the debtValue increases as the inflated value of _debtAccumulatedRate is reflected in the debtVault when the accrueStabilityFee function is called.

totalStablecoinIssued

totalStablecoinIssued is the variable stored in the BookKeeper contract. Four functions manipulate totalStablecoinIssued.

fn adjustPosition

The adjustPosition function adjusts the values of totalStablecoinIssued and poolStablecoinIssued based on the changes made to a position. For more details, please refer to the fn adjustPosition section under poolStablecoinIssued.

If a position's debt increases because a user borrows (more) FXD,

If a position's debt decreases as a user pays back FXD,

fn settleSystemBadDebt

The settleSystemBadDebt function utilizes the internal balance of stablecoin in the SystemDebtEngine within the bookKeeper to settle the bad debt. When the bad debt is settled, the value of totalUnbackedStablecoin decreases, and so does the value of totalStablecoinIssued.

fn mintUnbackedStablecoin

The mintUnbackedStablecoin function increases the amount of totalUnbackedStablecoin and totalStablecoinIssued.

fn accrueStabilityFee

Where β represents the amount by which the debtValue increases as the inflated value of _debtAccummulatedRate is reflected in the debtValue when the accrueStabilityFee function is called.

For a more detailed explanation, please refer to the previous section on accrueStabilityFee.

For a position to be considered safe, the below should hold true.

where

RawPrice is the price of collateral from PriceFeed and LTV is Loan to Ratio.

If a position's value of lockedCollateral(lockedCollateralAmount * PriceWithSafetyMargin) goes below the debtValue(DebtShare * debtAccumulatedRate), the position is considered unsafe/underwater and will be subject to liquidation process. The liquidator bot monitors the health of each position in the Fathom protocol.

Once a position is underwater and spotted by the liquidator bot, the bot can call the liquidate function in the LiquidationEngine contract.

Or the bot can call the batchLiquidate function if it spots multiple underwater positions.

If a bot calls liquidate or batchLiquidate functions to LiquidationEngine without using the _data param, the liquidator bot needs to have enough balance of FXD token available and should have approved FixedSpreadLiquidationStrategy as a spender. This is because the process of depositing FXD to liquidate and receive collateral is done in the execute function in FixedSpreadLiquidationStrategy.

_liquidate function first goes through some checks in the function args and checks whether the position targeted for liquidation is safe.

Once the position is underwater, the liquidation task is tossed to FixedSpeadLiquidationStrategy execute function.

The function then validates the input parameters, such as the debt share, collateral amount, and position address. It checks for zero values and valid price feeds to ensure the integrity of the liquidation data.

Then, it calculates the liquidation information based on the current market price, debt share, and collateral amount. This step involves determining the actual debt value to be liquidated, the collateral amount that will be seized, and any applicable treasury fees.

The function then calls confiscatePosition on the BookKeeper, adjusting the collateral and debt share of the position in question.

Treasury fees are moved from the liquidation contract to the SystemDebtEngine if any treasury fees are due.

If flash lending is enabled and valid, the contract facilitates flash lending calls. This step is optional and based on the encoded data provided.

Without flash lending, the contract withdraws the collateral to the liquidator and transfers the required FXD amount to cover the debt. The FXD is then deposited in the BookKeeper to clear the debt.

Finally, an event LogFixedSpreadLiquidate is emitted to record the details of the liquidation transaction.

After the execute function of the FixedSpreadLiquidationStrategy completes, the remaining liquidation process in the LiquidationEngine is verification of successful liquidation and recording of systemBadDebt if needed.

First, updated position data is retrieved:

Then, the decrease of position debt Share is validated, ensuring effective liquidation:

Once the liquidation validation is good with debtShare, receipt of the expected stablecoin amount by the SystemDebtEngine is checked:

In case the collateral is fully liquidated with remaining debt, the function records this as systemBadDebt:

For a position to be considered safe, below should hold true.

where

When RawPrice is the price of collateral from PriceFeed and LTV is Loan To Ratio.

In other words

And debtAccumulatedRate is calculated as

since debtAccumulatedRate is a second pounding interestRate.

Position safety calculation model

Please refer to below position safety calculation model.

Liquidation Risks

Risk:

Your position is at risk of liquidation if the market value of your collateral falls, causing your Safety Buffer to deplete entirely (Debt Ratio equals the Collateral Factor).

Mitigation:

• Fathom utilizes improved Fixed Spread Liquidation, with batch liquidations and a gentle Close Factor. Governance decides on the Close Factor value, but even for very volatile assets, it is possible to set it to 25% of a position's Debt Value. For Gold and other less volatile assets, this value is lower. This reduces the costs for the liquidators and the risk for FXD borrowers to lose capital, at the same time preventing the risk of bad debt.

• The user can mitigate the risk by increasing the Safety Buffer to protect against potential collateral price movements. It is recommended that the market be monitored and the Safety Buffer adjusted accordingly. Fathom is building AI agents to help users to understand the market conditions.

• Fathom FXD is moving towards employing a dual-threshold liquidation process designed to reduce the frequency and impact of liquidations. This approach includes a 'soft' threshold where AI agents assess market conditions. If the price drop is deemed temporary with an expected quick recovery, actions like liquidation can be postponed to avoid unnecessary cascades. The 'hard' threshold represents a more critical point where liquidation occurs to preserve system stability.

Price Stability

Risk:

Though fully backed by assets, FXD’s market price can fluctuate above or below its $1 peg temporarily due to real-time supply and demand dynamics.

Mitigation:

• Stability Fees can be adjusted to influence market behavior, encouraging repayment of loans with FXD during high supply phases, thus bolstering demand.

• FXD includes mechanisms like a debt ceiling to regulate FXD supply in accordance with market demand.

• The Stability Swap Module in Fathom ecosystem facilitates efficient arbitrage opportunities, stabilizing the FXD price around its peg.

Undercollateralization

Risk:

There is a potential for FXD to become undercollateralized if the market value of the backing assets drops significantly.

Mitigation:

• Liquidations are supposed to occur before collateralization value drops to 100%

• A conservative approach to the collateral factor limits the maximum FXD issuance per collateral unit. This factor is continuously adjusted based on asset volatility and comparative data from other lending protocols, ensuring a sufficient buffer against market downturns.

• Interest accrued on loans contributes to a surplus reserve, fortifying our capacity to manage and cover bad debts effectively.

• FXD is using the diverse basket of various assets, lowering the risk of total collateral value drop.

Smart Contract Vulnerabilities

Risk:

Despite thorough audits, our smart contracts and those of integrated platforms might contain vulnerabilities.

Mitigation:

We engage multiple reputable third-party auditing firms to scrutinize our contracts, significantly mitigating potential risks. Comprehensive audit reports are accessible for transparency.

The list of the audits:

Where is a position's collateral recorded?

How is a position's collateral recorded?

Three functions are directly involved in lockedCollateral accounting.

Described in https://docs.fathom.fi/whitepaper/version-1.0#id-5-fathom-sources-of-revenue.

Overview

The FXD token adheres to the ERC-20 standard and includes additional functionalities tailored to the Fathom protocol's needs.

ERC-20 Standard Functions

name

• Description: Returns the name of the token.

• Returns: string representing the token's name.

symbol

• Description: Returns the token symbol.

• Returns: string representing the token's symbol.

decimals

• Description: Returns the number of decimals the token uses.

• Returns: uint8 representing the number of decimal places the token uses. This affects the granularity of the token.

totalSupply

• Description: Returns the total amount of FXD tokens currently in circulation.

• Returns: uint256 representing the total supply of tokens.

balanceOf

• Parameters:

  • account (address): The address of the token holder.

• Description: Provides the balance of FXD tokens held by a specific account.

• Returns: uint256 representing the number of tokens held by the specified account.

transfer

• Parameters:

  • to (address): The address of the recipient.

  • amount (uint256): The amount of FXD tokens to transfer.

• Description: Transfers a specified amount of FXD tokens from the caller's account to another address.

• Returns: bool indicating whether the transfer was successful.

• Emits: Transfer event.

allowance

• Parameters:

  • owner (address): The address of the token owner.

  • spender (address): The address of the spender.

• Description: Returns the remaining number of tokens that the spender is allowed to spend on behalf of the owner.

• Returns: uint256 representing the remaining amount of tokens allowed to be spent.

approve

• Parameters:

  • spender (address): The address of the spender.

  • amount (uint256): The amount of FXD tokens the spender is allowed to use.

• Description: Approves a spender to withdraw tokens from the owner's account multiple times, up to the specified amount.

• Returns: bool indicating whether the approval was successful.

• Emits: Approval event.

transferFrom

• Parameters:

  • from (address): The address of the sender.

  • to (address): The address of the recipient.

  • amount (uint256): The amount of tokens to transfer.

• Description: Transfers tokens from one account to another, using an allowance mechanism.

• Returns: bool indicating whether the transfer was successful.

• Emits: Transfer event.

Additional Functions

mint

• Parameters:

  • to (address): The address that will receive the created tokens.

  • amount (uint256): The amount of tokens to create.

• Description: Mints new FXD tokens and assigns them to the specified address, increasing the total supply. Can be called only by the StablecoinAdapter in the process of taking the loan.

burn

• Parameters:

  • from (address): The address from which tokens will be burned.

  • amount (uint256): The amount of tokens to burn.

• Description: Burns a specified amount of FXD tokens from a given account, reducing the total supply. Can be called only by the StablecoinAdapter in the process of repaying the loan.

increaseAllowance

• Parameters:

  • spender (address): The address of the spender.

  • addedValue (uint256): The additional amount of tokens that the spender is allowed to spend.

• Description: Increases the allowance that a spender has to use the caller’s tokens.

• Returns: bool indicating whether the operation was successful.

decreaseAllowance

• Parameters:

  • spender (address): The address of the spender.

  • subtractedValue (uint256): The amount by which to decrease the spender's allowance.

• Description: Decreases the allowance that a spender has to use the caller’s tokens.

• Returns: bool indicating whether the operation was successful.

Events

Transfer

• Emitted when: Tokens are moved from one account to another.

• Parameters:

  • from (address indexed): The address of the sender.

  • to (address indexed): The address of the receiver.

  • value (uint256): The amount of tokens transferred.

Approval

• Emitted when: A spender is approved to use tokens from another account.

• Parameters:

  • owner (address indexed): The address of the token owner.

  • spender (address indexed): The address of the spender who is granted permission.

  • value (uint256): The amount of tokens the spender is allowed to use.

The ProxyWalletRegistry manages the creation and administration of proxy wallets. This contract serves as a registry to associate owners with their respective proxy wallets and includes features to manage access and operational states.

Events

• LogAddToWhitelist:

  • Emitted when an address is added to the whitelist. Only in centralized mode.

  • Parameters:

    • _user (address indexed): The address added to the whitelist.

• LogRemoveFromWhitelist:

  • Emitted when an address is removed from the whitelist. Only in centralized mode.

  • Parameters:

    • _user (address indexed): The address removed from the whitelist.

• LogSetDecentralizedMode:

  • Emitted when the decentralized mode is toggled.

  • Parameters:

    • newValue (bool): The new state of the decentralized mode (true for enabled, false for disabled).

• LogProxyWalletCreation:

  • Emitted when a new proxy wallet is created and associated with an owner.

  • Parameters:

    • owner (address): The owner of the new proxy wallet.

    • proxyWallet (address): The address of the newly created proxy wallet.

State Variables

• proxies (mapping(address => ProxyWallet)):

  • Maps an owner's address to their corresponding proxy wallet.

• factory (ProxyWalletFactory):

  • The factory contract used for creating new proxy wallets.

• whitelisted (mapping(address => bool)):

  • Tracks whether addresses are whitelisted, which influences their ability to create proxy wallets. Only in centralized mode.

• bookKeeper (IBookKeeper):

  • Reference to the BookKeeper contract used for managing financial interactions within the system.

• isDecentralizedMode (bool):

  • A flag indicating whether the system is operating in a decentralized mode, affecting proxy wallet creation permissions.

Functions

Public/External Functions

• initialize:

  • Initializes the ProxyWalletRegistry with necessary contract references.

  • Parameters:

    • _factory (address): Address of the ProxyWalletFactory contract.

    • _bookKeeper (address): Address of the BookKeeper contract.

• addToWhitelist:

  • Adds an address to the whitelist. Only in centralized mode.

  • Parameters:

    • _usr (address): The address to add to the whitelist.

• removeFromWhitelist:

  • Removes an address from the whitelist. Only in centralized mode.

  • Parameters:

    • _usr (address): The address to remove from the whitelist.

• setDecentralizedMode:

  • Toggles the decentralized mode of the registry.

  • Parameters:

    • isOn (bool): Boolean to enable or disable decentralized mode.

• pause and unpause:

  • Controls the paused state of the contract, restricting or enabling function execution based on the contract's operational state.

• build0:

  • Convenience function that allows an owner to create a proxy wallet for themselves without specifying an owner explicitly.

• build:

  • Creates a new proxy wallet for a specified owner if they are whitelisted or if the contract is in decentralized mode.

  • Parameters:

    • _owner (address): The intended owner of the new proxy wallet.

• setOwner:

  • Changes the owner of a specific proxy wallet.

  • Parameters:

    • _newOwner (address): The new owner to set.

The liquidation process in the Fathom protocol involves several key components and steps outlined in detail in the LiquidationEngine and FixedSpreadLiquidationStrategy contracts. The liquidation mechanism maintains the system's stability by handling under-collateralized positions. Here is an overview of the process:

Components Involved:

1. Liquidation Engine (LiquidationEngine): Manages the overall liquidation process.

2. Fixed Spread Liquidation Strategy (FixedSpreadLiquidationStrategy): Implements a specific strategy for liquidation.

3. Collateral Pool Config (CollateralPoolConfig): Provides configuration for collateral pools, including parameters like liquidation ratio, close factor, and liquidator incentives.

4. BookKeeper (BookKeeper): Records positions, stablecoin balances and collateral.

5. System Debt Engine (SystemDebtEngine): Manages the system's overall debt and surpluses, including systemBadDebt and systemSurpluses.

6. Price Oracle (PriceOracle): Provides price feeds for collateral assets.

Liquidation Process:

1. Triggering Liquidation:

• A position becomes eligible for liquidation when its collateral value falls below a predefined threshold (defined by the liquidation ratio in CollateralPoolConfig). The liquidation Ratio is the same as ( 1 / Loan to Value Ratio).

• The PriceOracle plays a crucial role in determining the health of positions by providing the latest available prices for collateral assets.

1. Liquidation Execution:

• The liquidation process is initiated by a liquidator (which, at the moment, is a role only available to whitelisted addresses) who identifies an under-collateralized position and calls the liquidate function in LiquidationEngine.

• The liquidate function checks various conditions, such as the liquidator's whitelist status, the system's operational status (live), and the health of the price feed.

• If the conditions are met, LiquidationEngine interacts with the FixedSpreadLiquidationStrategy to execute the liquidation.

1. Fixed Spread Liquidation Strategy:

• This strategy determines the specifics of the liquidation, such as the amount of debt to be repaid and the amount of collateral to be seized.

• It calculates the required parameters based on current prices, debt accumulated rates, and other factors defined in CollateralPoolConfig.

1. Financial Adjustments:

• Upon successful liquidation, the BookKeeper updates the financial state of the system, including adjusting the debt and collateral amounts for the liquidated position.

• The SystemDebtEngine may also handle any resultant bad debt from the liquidation process.

1. Distribution of Assets:

• The liquidator typically receives a portion of the seized collateral as an incentive, with the rest used to repay the debt.

• Parameters like liquidator incentives and treasury fees govern the distribution of assets.

1. Edge Cases and Safeguards:

• The system includes various safeguards and checks to prevent unauthorized access and ensure the integrity of the liquidation process.

• For instance, roles and permissions are enforced using access control mechanisms.

The following subsection guides you through the liquidation process in detail.

The LiquidationEngine contract manages all liquidations within the protocol, providing interfaces for liquidators to initiate the liquidation process for positions that are under-collateralized.

Functions

• liquidate(bytes32 _collateralPoolId, address _positionAddress, uint256 _debtShareToBeLiquidated, uint256 _maxDebtShareToBeLiquidated, address _collateralRecipient, bytes calldata _data): Allows a whitelisted liquidator to initiate the liquidation of a position. It requires the ID of the collateral pool, the address of the position, the amount of debt to be liquidated, a maximum allowable debt amount for liquidation to manage slippage, the recipient of the collateral, and additional data for the liquidation process.

• batchLiquidate(bytes32[] calldata _collateralPoolIds, address[] calldata _positionAddresses, uint256[] calldata _debtShareToBeLiquidateds, uint256[] calldata _maxDebtShareToBeLiquidateds, address[] calldata _collateralRecipients, bytes[] calldata datas): Facilitates the batch liquidation of multiple positions in a single transaction. This method enhances efficiency in handling liquidations at scale.

Events

• LiquidationFail(bytes32 _collateralPoolId, address _positionAddress, address _liquidator, string reason): Emitted when a liquidation attempt fails. It provides details about the failed operation, including the collateral pool ID, position address, liquidator, and reason for failure.

Overview

The ProxyWallet serves as a flexible, owner-controlled wallet that can execute arbitrary transactions. It uses a ProxyActionsStorage to manage state and actions and leverages comprehensive access control via FathomAuth.

Events

• LogSetAuthority (from FathomAuthEvents):

  • Emitted when the authority for this contract is set.

  • Parameters:

    • _authority (address indexed): The address of the new authority.

• LogSetOwner (from FathomAuthEvents):

  • Emitted when the owner of the contract is changed.

  • Parameters:

    • _owner (address indexed): The address of the new owner.

• LogNote (from FathomNote):

  • Emitted for each transaction executed through the proxy wallet, providing details of the operation.

  • Parameters:

    • sig (bytes4 indexed): The signature of the function called.

    • guy (address indexed): The address initiating the call.

    • foo (bytes32 indexed): Part of the call data.

    • bar (bytes32 indexed): Part of the call data.

    • wad (uint256): The value involved in the transaction.

    • fax (bytes): Full call data.

State Variables

• proxyActionsStorage (ProxyActionsStorage):

  • The storage contract used for managing proxy actions and settings.

• authority (IAuthority from FathomAuth):

  • The authority contract that checks permissions for actions.

• owner (address from FathomAuth):

  • The owner of the contract, who has elevated privileges.

Functions

• execute:

  • Executes a transaction via the proxy, allowing the wallet to interact with other contracts.

  • Parameters:

    • _data (bytes memory): The calldata or transaction data to be executed.

  • Returns:

    • _response (bytes memory): The return data from the executed call.

• receive:

  • A fallback function to allow the contract to receive Ether directly.

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.

The StabilityFeeCollector is a contract responsible for collecting stability fees from various collateral pools within a FXD system. These fees are used to manage the stability of FXD by compensating for volatility in the collateral's value and ensuring the system's solvency. The contract provides functionality to calculate and accrue stability fees over time, ensuring they are consistently applied and collected.

Storage Variables

• bookKeeper: Reference to the IBookKeeper contract, managing the accounting of collateral and debts within the system.

• systemDebtEngine: Address of the contract responsible for handling system debts and stability fees accumulation.

Functions

• pause(): Pauses fee collection, preventing new fees from being accumulated.

• unpause(): Resumes fee collection, allowing fees to be accumulated again.

• setSystemDebtEngine(address _systemDebtEngine): Updates the address of the system debt engine used for fee collection.

• collect(bytes32 _collateralPool): Public function that anyone can call to trigger the collection of stability fees for a specific collateral pool. It updates the accumulated rate of fees for the pool.

• _collect(bytes32 _collateralPoolId): Internal function that performs the actual calculation and collection of fees, updating the necessary state in the bookKeeper and collateral pool configuration.

Events

• LogSetSystemDebtEngine(address indexed _caller, address _data): Emitted when the system debt engine address is updated.

The ShowStopper contract manages the emergency shutdown of a system. It allows authorized users to trigger a shutdown to stop all essential financial operations, calculate and settle debts, and enable the redemption of collateral by users. The shutdown process ensures that the system can be gracefully wound down while protecting user assets.

Storage Variables

• bookKeeper: Reference to the IBookKeeper contract which handles all accounting-related operations.

• liquidationEngine: Reference to the ILiquidationEngine contract, responsible for handling the liquidation process during normal operations.

• systemDebtEngine: Reference to the ISystemDebtEngine, which manages the system's debts and surpluses.

• priceOracle: Reference to the IPriceOracle contract, providing updated asset prices.

• live: Boolean flag indicating if the system is active (1) or in shutdown mode (0).

• cagedTimestamp: Timestamp when the emergency shutdown was triggered.

• cageCoolDown: Cool-down period post-shutdown during which operations remain paused.

• debt: Total system debt recorded post-shutdown.

• cagePrice: Mapping of collateral types to their fixed prices set at the time of shutdown.

• badDebtAccumulator: Mapping tracking accumulated bad debts per collateral type.

• totalDebtShare: Mapping of total debt per collateral type.

• finalCashPrice: Final settled cash price per collateral type for redeeming stablecoins.

• stablecoinAccumulator: Tracks the total stablecoins deposited by users post-shutdown for later collateral redemption.

• redeemedStablecoinAmount: Mapping of redeemed stablecoin amounts per user per collateral type.

Functions

• cage(uint256 _cageCoolDown): Triggers the emergency shutdown and sets the cool-down period.

• cagePool(bytes32 _collateralPoolId): Locks the price of a specific collateral type at the time of shutdown.

• accumulateBadDebt(bytes32 _collateralPoolId, address _positionAddress): Calculates and accumulates bad debt for a given collateral type and position.

• finalizeDebt(): Finalizes the total system debt after processing all positions.

• finalizeCashPrice(bytes32 _collateralPoolId): Finalizes the cash price for a collateral type, determining the redemption value for stablecoins.

• accumulateStablecoin(uint256 _amount): Accumulates stablecoins deposited by a user for later redemption.

• redeemStablecoin(bytes32 _collateralPoolId, uint256 _amount): Allows users to redeem stablecoins for collateral based on the final cash price.

• redeemLockedCollateral(bytes32 _collateralPoolId, address _positionAddress, address _collateralReceiver): Redeems the locked collateral for a position, transferring it to the specified receiver.

Events

• LogCage(uint256 _cageCoolDown): Emitted when the emergency shutdown is triggered.

• LogCageCollateralPool(bytes32 indexed collateralPoolId): Emitted when a collateral pool is locked at its cage price.

• LogAccumulateBadDebt(bytes32 indexed collateralPoolId, address indexed positionAddress, uint256 amount, uint256 debtShare): Emitted when bad debt is accumulated for a position.

• LogRedeemLockedCollateral(bytes32 indexed collateralPoolId, address indexed positionAddress, uint256 lockedCollateral): Emitted when locked collateral is redeemed post-shutdown.

• LogFinalizeDebt(): Emitted when the final system debt is calculated.

• LogFinalizeCashPrice(bytes32 indexed collateralPoolId): Emitted when the final cash price for a collateral type is set.

• LogAccumulateStablecoin(address indexed ownerAddress, uint256 amount): Emitted when a user's stablecoins are accumulated for redemption.

• LogRedeemStablecoin(bytes32 indexed collateralPoolId, address indexed ownerAddress, uint256 amount): Emitted when stablecoins are redeemed for collateral.

The FlashMintModule contract facilitates the issuance of flash loans within the protocol. This contract allows borrowing a specified amount of stablecoins, executing arbitrary operations, and repaying the loan within a single transaction. It adheres to the ERC-3156 standard for flash loans.

Storage Variables

• bookKeeper (IBookKeeper):

  • This variable stores the address of the BookKeeper contract, which is used for managing accounting and collateral within the system. It interacts with the bookkeeping functionalities to record transactions related to flash loans.

• stablecoinAdapter (IStablecoinAdapter):

  • This variable holds the address of the StablecoinAdapter contract. The adapter is used to interact with the stablecoin in a manner consistent with the internal accounting system, such as depositing or withdrawing stablecoin for flash loans.

• stablecoin (IStablecoin):

  • This variable represents the ERC20 stablecoin used for flash loans. It facilitates operations such as minting, transferring, and burning the stablecoin.

• systemDebtEngine (address):

  • A crucial contract address for managing the system’s overall debt and fee accrual. It is used primarily to settle fees or bad debt that accrues through flash loan operations.

• max (uint256):

  • This variable sets the maximum amount of stablecoin that can be borrowed through a single flash loan. It is important for managing liquidity and risk.

• feeRate (uint256):

  • The fee rate charged for taking out a flash loan. It is expressed as a percentage and calculated over the amount of the loan to generate revenue from flash loan operations.

• locked (uint256):

  • A reentrancy guard used to prevent reentry into critical functions such as flash loan issuance. This helps protect against certain types of exploits where recursive calls can lead to unintended consequences.

• flashMintWhitelist (mapping(address => bool)):

  • A whitelist of addresses that are permitted to initiate flash loans. This control mechanism ensures that only approved contracts or addresses can utilize flash loan functionality, which can be essential for maintaining system security.

• isDecentralizedState (bool):

  • Indicates whether the contract is operating in a decentralized mode. In a decentralized state, the contract might allow a broader set of interactions than when it is in a more controlled state.

Flash Loan Functions

• flashLoan(IERC3156FlashBorrower _receiver, address _token, uint256 _amount, bytes calldata _data): Executes a flash loan. The _receiver must implement the IERC3156FlashBorrower interface. This function checks the token type, enforces the maximum loan amount, calculates the fee, mints the required stablecoin, sends it to the receiver, and expects repayment within the same transaction.

• bookKeeperFlashLoan(IBookKeeperFlashBorrower _receiver, uint256 _amount, bytes calldata _data): Similar to flashLoan but interacts with receivers that handle bookkeeping entries directly. It is meant for more integrated system operations, managing loans in terms of the bookkeeping system's RAD units.

Administrative Functions

• setMax(uint256 _data) and setFeeRate(uint256 _data): Set the maximum loanable amount and the fee rate for loans. The maximum is set in stablecoin units, and the fee rate is a percentage that applies to the borrowed amount.

• setDecentralizedStatesStatus(bool _status): Toggle the operational mode between a more decentralized setting (where whitelist control might be relaxed) and a more controlled setting.

• addToWhitelist(address _toBeWhitelisted) and removeFromWhitelist(address _usr): Manage addresses that are allowed to initiate flash loans. This is particularly relevant in a more centralized operational mode to ensure only vetted contracts or addresses can initiate loans.

• pause() and unpause(): Enable or disable the flash loan operations. This can be critical in situations where the protocol needs to be paused for upgrades or security issues.

Utility Functions

• convert() and accrue(): Handle internal conversions and accounting adjustments. convert() can be used to convert balance discrepancies into the bookkeeping system, while accrue() moves accrued fees to the system debt engine.

• refreshApproval(): Refresh the approval of the stablecoin to the maximum value for the stablecoin adapter, ensuring that the contract can always interact with the stablecoin as expected.

Events

• LogSetMax(uint256 _data), LogSetFeeRate(uint256 _data), and LogFlashLoan(address indexed _receiver, address indexed _token, uint256 _amount, uint256 _fee): Log significant actions and state changes within the contract, providing transparency over flash loan parameters and administrative adjustments.

• LogDecentralizedStateStatus(bool _oldDecentralizedStateStatus, bool _newDecentralizedStateStatus): Tracks changes in the operational mode of the contract, signaling shifts between centralized and decentralized control.

• LogAddToWhitelist(address indexed _user) and LogRemoveFromWhitelist(address indexed _user): Document changes to the list of addresses authorized to initiate flash loans.

The SystemDebtEngine contract is responsible for managing the system's surplus and bad debt. It acts as the central financial manager within a FXD system, specifically designed to handle scenarios where debts become unmanageable or when excess funds are accumulated beyond what is required for the system's stability.

Storage Variables

• bookKeeper: Reference to the IBookKeeper contract, which handles the ledger of all financial operations within the system.

• surplusBuffer: The minimum amount of surplus (in RAD, 10^45) that should always be maintained in the system to cover unexpected liabilities.

• live: A flag indicating whether the system is active (1) or has been shut down (0).

Functions

• withdrawCollateralSurplus(bytes32 _collateralPoolId, address _to, uint256 _amount): Allows the owner to withdraw surplus collateral from a specific collateral pool.

• withdrawStablecoinSurplus(address _to, uint256 _value): Allows the owner to withdraw surplus stablecoins from the system, provided there is no outstanding bad debt and the withdrawal does not drop the balance below the surplus buffer.

• setSurplusBuffer(uint256 _data): Sets the minimum surplus buffer required in the system.

• settleSystemBadDebt(uint256 _value): Allows anyone to settle bad debt using the surplus funds available in the system.

• cage(): Can be called by the owner or a designated emergency role to shut down the system in case of a significant issue. It settles as much bad debt as possible with available funds during the shutdown.

• pause(): Pauses all critical functionalities of the contract, preventing state-changing operations.

• unpause(): Resumes all operations after a pause.

Events

• LogSetSurplusBuffer(address indexed _caller, uint256 _data): Emitted when the surplus buffer is updated.

• LogCage(): Emitted when the system is shut down.

The AdminControls contract provides management capabilities for the Fathom FXD Protocol. It is designed to configure and control core components of the system, allowing administrative actions such as pausing and unpausing protocol operations, setting key contract addresses, and managing permissions.

Administrative role can be assigned to the Governance or Multisig account.

State Variables:

1. bookKeeper (address public): Stores the address of the BookKeeper contract which manages the core accounting logic for the protocol.

2. liquidationEngine (address public): Holds the address of the LiquidationEngine contract responsible for handling the liquidation processes.

3. priceOracle (address public): References the PriceOracle contract which provides price feeds for the assets.

4. positionManager (address public): Points to the PositionManager contract that manages user positions.

5. systemDebtEngine (address public): Contains the address of the SystemDebtEngine contract managing the system’s debt situations.

6. flashMintModule (address public): Holds the address of the FlashMintModule for flash loan functionalities.

7. stablecoinAdapter (address public): References the StablecoinAdapter which handles interactions related to the FXD stablecoin.

Functions:

• pauseProtocol (external): Pauses all core components of the protocol to halt operations.

• unpauseProtocol (external): Resumes operations of all core components after being paused.

• setBookKeeper (external, address _bookKeeper): Updates the address of the BookKeeper contract.

• setPositionManager (external, address _positionManager): Updates the address of the PositionManager contract.

• setLiquidationEngine (external, address _liquidationEngine): Updates the address of the LiquidationEngine contract.

• setSystemDebtEngine (external, address _systemDebtEngine): Updates the address of the SystemDebtEngine contract.

• setFlashMintModule (external, address _flashMintModule): Updates the address of the FlashMintModule contract.

• setPriceOracle (external, address _priceOracle): Updates the address of the PriceOracle contract.

• setStablecoinAdapter (external, address _stablecoinAdapter): Updates the address of the StablecoinAdapter contract.

Events:

• LogPauseProtocol (event): Emitted when the protocol is paused.

• LogUnpauseProtocol (event): Emitted when the protocol is unpaused.

• LogSetBookKeeper (event, address indexed newAddress): Emitted when the BookKeeper address is updated.

• LogSetPositionManager (event, address indexed newAddress): Emitted when the PositionManager address is updated.

• LogSetLiquidationEngine (event, address indexed newAddress): Emitted when the LiquidationEngine address is updated.

• LogSetSystemDebtEngine (event, address indexed newAddress): Emitted when the SystemDebtEngine address is updated.

• LogSetFlashMintModule (event, address indexed newAddress): Emitted when the FlashMintModule address is updated.

• LogSetPriceOracle (event, address indexed newAddress): Emitted when the PriceOracle address is updated.

• LogSetStablecoinAdapter (event, address indexed newAddress): Emitted when the StablecoinAdapter address is updated.

The CentralizedOraclePriceFeed contract utilizes a centralized oracle source to fetch the latest prices of assets. It introduces a delay in price updates to mitigate the risks associated with price manipulation and flash loan attacks. The delayed price update ensures that fetched prices do not immediately affect the system, providing a buffer to detect and react to potential price anomalies.

CentralizedOraclePriceFeed is named centralized because it utilizes Oracle data that can be fetched from off-chain centralized sources (like Chainlink, Supra, and other oracles), not from pure onchain (DEX) data. Oracles themselves can be decentralized, and CentralizedOraclePriceFeed isn't responsible for the quality of the data.

Storage Variables

• oracle: Address of the centralized oracle contract (address). This oracle provides the latest price data.

• accessControlConfig: Address of the access control contract (IAccessControlConfig). It is used to manage roles and permissions within the contract.

• latestPrice: Latest fetched price information stored as PriceInfo, which includes the price and the timestamp of the last update.

• delayedPrice: The price that is currently being used by the system, delayed by a certain period defined by timeDelay.

• timeDelay: The delay period (in seconds) that determines how long fetched price data must wait before being considered valid within the system.

• priceLife: The duration (in seconds) for which a price is considered valid after being updated.

• poolId: Identifier for the specific pool or asset that this price feed pertains to.

Functions

• setOracle(address _oracle): Updates the oracle address. This function can only be called by the owner or governance role.

• setTimeDelay(uint256 _seconds): Sets the time delay for the price update. This can only be adjusted by the owner or governance role.

• setPriceLife(uint256 _seconds): Sets the duration for which a price is considered valid.

• retrivePrice(): Fetches the latest price from the oracle and updates the price information in the contract.

Events

• LogSetTimeDelay(address indexed _caller, uint256 _seconds): Emitted when the time delay is updated.

• LogSetPriceLife(address indexed _caller, uint256 _second): Emitted when the price life duration is updated.

• LogPeekPriceFailed(address indexed _caller, string _reason): Emitted if fetching the latest price fails.

• Dynamic Investment Strategies: Engage in multiple investment strategies spanning decentralized finance, real-world assets, and trade finance. These strategies are designed to cater to different risk appetites and investment goals.

• Stablecoin Integration: Utilize the FXD stablecoin within the platform, the stable asset, to gain yields in on-chain native way.

• Decentralized Governance: Fathom Vaults operates under a community-driven Fathom governance model, allowing FXD holders to vote on key decisions, including strategy approvals and fee adjustments.

• Security and Transparency: Smart contracts are publicly auditable and have undergone rigorous security audits. Transparency in fee structure and strategy performance metrics is maintained to ensure trust and accountability.

• Accessibility and Integration: Designed with a focus on user experience, Fathom Vaults offers easy integration options for third-party services and developers, providing detailed documentation and access to on-chain data.

Fathom Vaults is a cutting-edge financial platform that leverages blockchain technology to offer optimized asset management solutions. Built on a robust and secure framework, Fathom Vaults allows users to participate in a variety of investment strategies that not only include traditional DeFi protocols but also extend into Real-World Assets (RWA) and Trade Finance. Central to the ecosystem is the FXD stablecoin, a stable digital currency that provides a stable medium of exchange and a store of value across various investment strategies.

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.