Collateral Vault

Overview

The Collateral Vault is the central place where collateral tokens and account balances are stored. It serves as the primary financial entry and exit point for the ecosystem, allowing users to deposit, transfer, and withdraw their collateral. In addition to being a storage mechanism, the vault is where collateral is housed for utilization throughout the protocol. Other protocol connected smart contracts, known as Collateralizable Contracts, are able to create reservations of collateral on users’ behalf. These reservation records are stored in the Collateral Vault and ensure that protocol users can leverage their collateral from a central and secure location. Collateralizable Contracts must be first approved by Anvil’s Governance, and can only leverage users’ collateral with their authorization.

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 Anvil’s 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.

Functionality

General Functions

Functions List

Function Name

Description

Read Functions

getCollateralToken(...)

Gets a collateral token’s enabled status when provided with a token address.

getAccountCollateralBalance(...)

Gets the token available and reserved balances of an account when provided with an account address and a token address.

getCollateralReservation(...)

Gets details of a collateral reservation when provided with the reservation id.

getClaimableAmount(...)

Gets the claimable amount when provided with a collateral reservation id.

getCollateralizableTokenAllowance(...)

Gets the token allowance when provided with an account address, a Collateralizable Contract address, and a token address.

getWithdrawalFeeBasisPoints(...)

Gets the current protocol withdrawal fee in basis points.

Note: Collateral reservations may be subject to a different previously captured withdrawal fee value from the time of creation.

supportsInterface(...)

Gets whether the Collateral Vault supports an interface given the interface id.

Write Functions

claimCollateral(...)

Claims some or all of the collateral of a reservation to a provided address. Used by pool claimants and LOC beneficiaries.

depositAndApprove(...)

Allows a Collateralizable Contract to handle both token allowance approval and depositToAccount(...) steps in the same call since they are both necessary to accomplish a deposit.

depositFromAccount(...)

Used by Time Based Collateral Pool for its depositAndStake(...) function whereby the pool can have a users’ collateral transferred into its vault account and then added to a collateral reservation for staking provided it has user authorization.

depositToAccount(...)

Allows users to deposit collateral into the vault as well as allows for other calling vaults to transfer user collateral via the ICollateralDepositTarget interface in the case of vault upgrades.

modifyCollateralizableTokenAllowance(...)

Used by Collateralizable Contracts to modify the contracts token allowance from the user provided the contract address, token address, and the amount (positive or negative) by which the allowance will be modified.

modifyCollateralizableTokenAllowanceWithSignature(...)

Same as modifyCollateralizableTokenAllowance(...) above but more explicit whereby the user signs the data to process the allowance change including the Collateralizable Contract address which the allowance modification is targeting. This is used by Letter Of Credit and Time Based Collateral Pool.

modifyCollateralReservation(...)

Allows a Collateralizable Contract to modify a collateral reservation when provided with the reservation id and the (positive or negative) amount to change. This function is utilized by Letter Of Credit when a user modifies their LOC’s collateral and by Time Based Collateral Pool for staking and unstaking.

poolCollateral(...)

Called by Time Based Collateral Pool when a user stakes collateral from their vault account into a pool instance. This transfers the provided token and amount from the users account to the pool instance’s account within the vault.

releaseAllCollateral(...)

Collateralizable Contracts call this function to remove a collateral reservation and adjust the account’s available and reserved balances accordingly. This is utilized by Letter Of Credit when a LOC is canceled and by Time Based Collateral Pool when a pool instance is reset.

reserveClaimableCollateral(...)

Creates a collateral reservation when provided with the reserving account, token, and the amount that should be claimable. The function will then calculate the full reservation amount to be reserved with the fee.

reserveCollateral(...)

Similar to reserveClaimableCollateral(...). Creates a collateral reservation when provided with the reserving account, token, and the total amount to be reserved. The function will calculate the claimable amount after deducting the fee.

transferCollateral(...)

Transfers available collateral from one vault account to another when provided with the origin address, destination address, token and amount. This transfer will not incur a fee. This function is also leveraged by Time Based Collateral Pool when moving a pool participant’s funds into the pool instance account for the purpose of staking.

upgradeAccount(...)

Moves the user’s collateral from the current vault to a new approved collateral vault (see: Permitted Collateral Upgrade Contracts) that has implemented the ICollateralDepositTarget interface. Accepts multiple pairings of tokens and their amounts to be moved. Can only be done by the account sender.

withdraw(...)

Withdraws sender’s funds from the vault to an external address when provided with the token, amount, and destination. The current protocol withdrawal fee will be subtracted from the withdrawal amount.

Governance

These are functions that can only be performed via the execution of a successful Governance proposal (see: Proposal Process). They are decorated in the published contract code with the onlyOwner modifier.

Function List

Function Name

Description

upsertCollateralizableContractApprovals(...)

Updates the approval status of one or more Collateralizable Contracts. Used when upgrading contracts, expanding the protocol, adding new Time Based Collateral Pool instances (proxies), and removing support for existing contracts.

upsertCollateralTokens(...)

Updates the status of collateral tokens that are approved for use. Used when adding new token support and removing support for existing tokens.

upsertCollateralUpgradeContractApproval(...)

Updates the approval status of a ICollateralDepositTarget contract that may be sent an account's available collateral upon the account’s request. Used when upgrading to a new Collateral Vault contract.

withdrawFromProtocolBalance(...)

Withdraws unaccounted for token balances to a desired address. Used to send amassed protocol fees and errant token transfers to the destination of Governance’s choice.

Interfaces

ICollateral

Functionality to be used by approved Collateralizable Contracts when interacting on users’ behalf. These functions deal with reading vault settings, performing CRUD operations on collateral reservations, and modifying token allowances.

Supported Functions