Vault Data

Account Balances

The Collateral Vault stores a ledger of all collateral associated with an account. This association is made by mapping the account to each collateral token and then to their balance breakdown. This account balance includes the available balance amount as well as the amount that is currently reserved (see: Collateral Reservations). Accounts may be Externally Owned Accounts (EOAs), external smart contracts unknown to the protocol (treated the same as EOAs for permissioning), or approved Collateralizable Contracts.

Collateral Reservations

While account balances store the total token amounts associated with an account, it is left to the Collateral Vault’s collateral reservations to track how much of those balances are being utilized as collateral elsewhere in the protocol. Vault reservations are utilized to secure collateral for the purpose of guaranteeing LOCs as well as staked funds in collateral pools. Any collateral that is being reserved cannot be withdrawn from the vault or used in another reservation. Reservations are created and modified by other Collateralizable Contracts via the ICollateral interface. A reservation consists of an id (set by the vault’s collateralReservationNonce), the account reserving the collateral, the token and amount to be reserved, and the Collateralizable Contract that manages the reservation. In addition, the collateral reservation contains a memorialization of the withdrawal fee in basis points as well as the claimable token amount (token amount minus the amount to be assessed as a fee).

Collateral Tokens

The Collateral Vault stores the mapping of collateralTokens to total vault token balance as well as whether the token is currently enabled for usage as collateral. An enabled token is eligible for depositing into the vault and staking into collateral pools. For a token to be effectively supported by the protocol, it should conform to the ERC-20 standard. In addition, token enablement/disablement is subject to Governance approval. If Governance decides to disable a previously supported token, existing collateral can still be claimed, unstaked, and released from collateral pools, used in existing LOCs (see: Letter Of Credit), and withdrawn from the vault.

Collateralizable Contracts

For smart contracts to be able to interact with the Collateral Vault, it must do so via its ICollateral interface. Only Governance approved contract addresses may interact with the vault through its interface functionality. To manage this, the vault’s contract state stores collateralizableContracts where the external contract addresses are mapped to their boolean approval status. Similarly to collateral tokens, when previously approved Collateralizable Contracts become disapproved, they enter a decrease-only state whereby the collateral reservations can no longer be created or increased. In the case of collateral pools, this means pool participants can still unstake and release their collateral as well as have their collateral claimed.

In addition, the Collateral Vault stores a mapping of each account’s token transfer approval amounts per Collateralizable Contract. This is a security measure in line with typical ERC-20 transfer allowances. This allows protocol users to be explicit about transfer allowances from within the protocol.

Protocol Fee

The protocol only has one built-in mechanism for assessing fees to its users and that is upon the withdrawal of collateral from the Collateral Vault. This can occur when a user withdraws an available balance from the vault to their wallet, a LOC gets converted/redeemed, or a pool’s collateral gets claimed. The fee setting is housed as withdrawalFeeBasisPoints within the CollateralVault contract and it is memorialized in each collateral reservation at the time of creation. Fees are retained in the Collateral Vault in the form of a delta between the token balances of the contract and the cumulative account balances. Governance can transfer the amassed fees to a destination of its choosing.

As of AtomAI launch, the protocol currently has its withdrawal fee initialized to 0. However, this is subject to change by Governance so it is important to always read the latest withdrawal fee from the Collateral Vault contract and any relevant collateral reservations.

Permitted Collateral Upgrade Contracts

A stored mapping of Collateral Vault addresses to whether they are enabled. When an address is set to true, users can move collateral between vaults through the ICollateralDepositTargets interface. This is vital to Collateral Vault upgradeability.