👩💻Developers Documentation
You can see a high-level architecture of Atomica Liquidation Markets in the picture below.
There are three architectural layers of the protocol.
A protocol layer includes DAO Governance, Pool Factory, and Risk Markets.
A risk market layer contains a number of products that can connect with the Global Liquidity Pool on demand. It is not designed yet.
A product layer includes the Pool with a single Adapter, optional special-purpose-pools (SPPs), and Oracles (Figure 2).
Liquidity Pool
The Pool is a generic part of the protocol that provides basic interfaces for such user interactions as:
allocate
payback
join
exit
Now, let's look into each of the interactions more closely.
Allocate is a pool method that allows Adapters to request a certain amount of capital. The Pool checks if the requested amount corresponds to the allowance defined for this Adapter and then transfers funds. In case the funds are placed by Asset Manager (a separate component or a pool method) to the DeFi platforms, the Pool initiates their transfer in accordance with the business logic approved by DAO in the requested and allowed amounts. This method can be also called by SPPs, which have their own allowance defined in the pool deployment and approved by DAO.
Payback is a pool method that allows for returning the assets and some profit (if there is any) to the pool.
Join is a pool method that enables Liquidity Providers to deposit some assets (denominated in the Pool currency) in exchange for Pool Tokens. Liquidity Providers specify a deposited amount and are able to see the amount of Pool Tokens they can get.
Exit is a pool method that enables Liquidity Providers to exchange Pool Tokens for the assets in which the Pool is denominated. Exchange is performed according to the current Token Rate. Pools can have limitations of withdrawals defined in the deployment and approved by DAO. For instance, withdrawal is delayed in case a Keeper is participating in an auction, and there is a lack of liquidity in the Pool. Another example is a loss event is registered, and the Claim committee investigates the case.
If withdrawal is not limited, but the funds are placed by Asset Manager to DeFi platforms, the Pool initiates their transfer in accordance with the business logic approved by DAO for the requested and allowed amounts.
The Pool communicates with Liquidity Providers and Adapters. Liquidity Providers communicate with the Pool via a Pool Token. It means that all interactions are specified in the Pool Token Contract and/ or Pool Contract. Liquidity Providers use join and exit methods.
Adapters do not use a Pool Token. They communicate with the Pool via a set of rules defined in the Pool Settings. The latter are proposed in the deployment and approved by DAO.
The Pool has the following sources of liquidity:
Liquidity Providers capital. The assets submitted by Liquidity Providers in exchange for a Pool Token. In most cases, these assets guarantee yield.
Product Adapters income. The assets returned by a Product Adapter in the form of profit from liquidation operations.
Asset Manager income. Return on assets placed to DeFi platforms to get a competitive level of income, especially when a Product Adapter cannot provide competitive income by reasons beyond control (e.g., lack of liquidations).
Each Pool is denominated in a single currency (the first Pool - in DAI).
The deployed Pool is connected with a single Asset Manager (if it is a separate component) and a single Product Adapter. The Pool can be connected with multiple SPPs (Pool Adapters).
Pool Token
A Pool Token is an ERC20 token, which is unique for each Pool. We suggest the following standard token naming: - Risk Pool token name corresponds to ARPT_{extension}, where {extension} includes a covered platform name. - Liquidation Pool token name corresponds to ACLT_{extension}, where {extension} includes a source of a liquidations platform name (where liquidations happen).
Token name is a setting approved by DAO.
Base Token Rate is set at the Pool deployment by transferring some amount of the Pool base assets (Pool is nominated in). That will be the price for a single pool token.
Asset Manager**
An Asset Manager aims to get interest income on DeFi platforms in accordance with the settings approved by DAO. An Asset Manager can be designed and deployed as a separate component or as part of the Pool.
An Asset Manager implements the following functions:
Places funds to DeFi platforms in accordance with the settings approved by DAO.
Returns funds to the Pool on its request.
Gets assets from the Pool in accordance with the Pool settings (a schedule of pull actions, the allowance, etc.).
Returns the current balance of the placed assets. It is calculated as the amount of assets that can be withdrawn at the moment of request minus a fee for withdrawal at the moment of the request if there is any.
** for future releases.
Pool deployment
The Pool deployment is performed by a special protocol component - Pool Factory. On deployment, the agreed list* of the Pool settings has to be specified, for example:
lock-up conditions
a minimum balance
a token name
a token base rate
SPPs contracts
SPPs allowances
After the Pool deployment, it becomes fully functional.
*A list of the Pool settings, as well as their default values, is specified by DAO.
Product Adapter
A Product Adapter is a smart contract that aims to serve specific operations, such as liquidations for DeFi platforms, insurance operations, etc. The ultimate goal of a Product Adapter is to bring profit to the Pool.
Known Product Adapters:
A Keeper Adapter gets income from liquidations on DeFi platforms.
A list of known Product Adapters can be extended by new types.
A Product Adapter communicates with the Pool to get assets and pay them back. To get the assets, a Product Adapter sends a request to execute allocate method under such condition - It is allowed for a Product Adapter to get funds. - There are enough funds, so the Pool transfers them.
In case of a payback, a Product Adapter uses the like-named method.
Keeper Adapter (or Keeper)
A Keeper Smart Contract implements a bidding strategy approved by DAO. The Bidding strategy includes the following parameters for TEND/ DENT phases of auctions:
dentWindow - the time left in an auction to bid in DENT
multiBid - Y/ N
minDiscount - a different value per risk state value
tendWindow - the time left in an auction to bid in TEND.
tendDiscount - a discount to the current price at which it is possible to enter a bid for the TEND phase.
To generate bids, a Keeper consumes the data provided by a Risk Oracle and uses a Bid Generator Formula.
A special-purpose pool (Pool Adapter)**
A SPP can be created to serve the specific functions of the Product. The functionality of a SPP is custom for a Pool - Product Adapter pair. Howewer, standard templates can be created in future.
Examples of a SPP:
A Gas Pool denominated in ETH aims to compensate operational expenses for Keepers.
An Incentive Pool is needed to collect fees.
The Product can employ more than one SPP with different functions, e.g. a Keeper Adapter can use Gas and Incentive Pools.
** for future releases.
Pool Factory
A Pool Factory deploys Pool and Pool Token Smart Contracts. As an input, a Pool Factory gets Pool settings (a required list of the Pool Settings and their predefined values approved by DAO on the protocol deployment).
A Pool Factory can also implement the deployment functionality of Pool Adapters (SPPs).
Oracles
Oracles provide essential data to Adapters, Pools, etc. Some Oracles implement a specific logic for the Pool-Adapter pair, some can be generic enough to feed more than one such pair.
Risk Oracle for Atomica Liquidation Markets
A Risk Oracle provides data to a Keeper Adapter to trigger bidding and make the bids effective.
Components relations
Relation | Type |
Pool - Asset Manager | 1:1 |
Pool - Product Adapter | 1:1 |
Pool - Pool Adapter (Special Purpose Pool) | 1:M |
Product Adapter - Oracle | 1:M |
Asset Manager - Deposit Adapter | 1:M |
Gas compensation**
Each component of the protocol - such as a Pool, a Keeper, and an Asset Manager (if it is separated) - needs gas for their operations. Gas costs cover one of the SPPs - a Gas Pool that holds a certain amount of liquidity in the form of ETH. This is needed to support a certain level of operations - a Gas Pool Safe Balance that is defined as one of the Pool settings and approved by DAO.
A Keeper, a Pool, an Asset Manager, etc. can hold some ETH upfront for the first transaction (it is a setting of the protocol, as well). After the transaction takes place, they request the Gas Pool to compensate the spendings. This compensation is used for future transactions.
A Gas Pool can request assets from a Liquidity Pool in case its balance is lower than a Gas Pool Safe Balance.
** for future releases.
Last updated
