Vault

The Vault is the core abstract contract inherited by every cUSD deployment. It holds the backing assets deposited by cUSD minters and lent out to whitelisted Operators, tracking total supplies and borrows per asset. Mint/burn/redeem operations flow through the Minter for fee calculation and through the FractionalReserve layer for liquidity management — the Vault itself only tracks principal amounts, leaving interest calculations to the Lender.

Mechanics

Minting cUSD

Depositing a backing asset in exchange for cUSD:

Deposit cap check: _amountIn is silently capped to the remaining deposit capacity for the asset.
Fee calculation: The Minter computes (amountOut, fee) based on the asset's current allocation ratio vs. its optimal ratio.
Slippage / deadline check: Reverts if amountOut < _minAmountOut or the deadline has passed.
Transfer in: The asset is pulled from msg.sender and totalSupplies[asset] is incremented.
Mint: amountOut cUSD is minted to _receiver; if a fee applies, an additional fee cUSD is minted to the insurance fund.

Burning cUSD

Exchanging cUSD for a single backing asset:

Fee calculation: The Minter computes the post-fee asset output and fee amount.
cUSD burn: _amountIn cUSD is burned from msg.sender.
Divest: The FractionalReserve layer divests amountOut + fee of the asset from the active yield strategy if needed to cover the withdrawal.
Transfer out: amountOut is sent to _receiver; fee is sent to the insurance fund. totalSupplies[asset] is decremented.

Redeeming cUSD

Proportional withdrawal across every backing asset:

Amount calculation: The Minter computes proportional amountsOut and fees for each asset in the vault.
cUSD burn: _amountIn cUSD is burned from msg.sender.
Divest many: The FractionalReserve layer divests the required amounts across all assets.
Transfer out: For each asset, amountsOut[i] is sent to _receiver and fees[i] to the insurance fund.

Borrowing and Repaying

These paths are access-controlled and called only by the Lender contract:

Borrow: Divests the asset from the yield strategy if needed, decrements available balance, transfers to _receiver, increments totalBorrows[asset].
Repay: Accepts the asset back from the Lender via transferFrom, decrements totalBorrows[asset].

Utilization Tracking

The vault tracks a cumulative utilization index per asset — a time-weighted integral of the utilization ratio. This is consumed by the RateOracle to compute borrow interest rates.

utilizationIndex += utilization * (block.timestamp - lastUpdate)
utilization = totalBorrows / totalSupplies  (ray format, 1e27 = 100%)

The index is updated on every mint, burn, borrow, and repay via the updateIndex modifier.

Architecture

Core Functions

`mint(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

function mint(
    address _asset,
    uint256 _amountIn,
    uint256 _minAmountOut,
    address _receiver,
    uint256 _deadline
) external returns (uint256 amountOut);

Deposit _asset and receive cUSD. Requires ERC20 approval from msg.sender to the vault. _amountIn is silently reduced to the remaining deposit cap if exceeded.

Parameter	Type	Description
`_asset`	`address`	Whitelisted backing asset to deposit
`_amountIn`	`uint256`	Amount of asset to deposit
`_minAmountOut`	`uint256`	Minimum cUSD to receive (slippage protection)
`_receiver`	`address`	Recipient of the minted cUSD
`_deadline`	`uint256`	Unix timestamp after which the tx reverts

Returns: amountOut — cUSD minted to _receiver (excludes fee).

`burn(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

function burn(
    address _asset,
    uint256 _amountIn,
    uint256 _minAmountOut,
    address _receiver,
    uint256 _deadline
) external returns (uint256 amountOut);

Burn _amountIn cUSD and receive _asset. The caller must hold the cUSD.

Parameter	Type	Description
`_asset`	`address`	Backing asset to withdraw
`_amountIn`	`uint256`	Amount of cUSD to burn
`_minAmountOut`	`uint256`	Minimum asset to receive (slippage protection)
`_receiver`	`address`	Recipient of the asset
`_deadline`	`uint256`	Unix timestamp after which the tx reverts

Returns: amountOut — asset sent to _receiver (excludes fee).

`redeem(uint256 _amountIn, uint256[] calldata _minAmountsOut, address _receiver, uint256 _deadline)`

function redeem(
    uint256 _amountIn,
    uint256[] calldata _minAmountsOut,
    address _receiver,
    uint256 _deadline
) external returns (uint256[] memory amountsOut);

Burn _amountIn cUSD and receive a proportional share of every backing asset. _minAmountsOut must have one entry per vault asset in the same order as assets().

Returns: amountsOut — asset amounts sent to _receiver (one per vault asset).

`borrow(address _asset, uint256 _amount, address _receiver)`

function borrow(address _asset, uint256 _amount, address _receiver) external;

Access-controlled. Called by the Lender to transfer assets to an Operator. Reverts with InsufficientReserves if available balance is too low.

`repay(address _asset, uint256 _amount)`

function repay(address _asset, uint256 _amount) external;

Access-controlled. Called by the Lender when an Operator repays. Pulls _amount from msg.sender via transferFrom.

`availableBalance(address _asset)`

function availableBalance(address _asset) external view returns (uint256 amount);

Returns totalSupplies[_asset] - totalBorrows[_asset] — the amount currently available to borrow or withdraw.

`utilization(address _asset)`

function utilization(address _asset) external view returns (uint256 ratio);

Returns the current utilization ratio in ray format (1e27 = 100%). For example, 5e26 = 50% utilization.

`currentUtilizationIndex(address _asset)`

function currentUtilizationIndex(address _asset) external view returns (uint256 index);

Returns the up-to-date cumulative utilization index including the current unsettled period. Used by the RateOracle for interest rate calculations.

`getRemainingMintCapacity(address _asset)`

function getRemainingMintCapacity(address _asset) external view returns (uint256 remainingMintCapacity);

Returns how much more of _asset can be deposited before hitting the deposit cap. Returns 0 if the cap is already reached.

Admin Functions

Function	Description
`addAsset(address _asset)`	Add a new backing asset to the vault
`removeAsset(address _asset)`	Remove an asset (only if `totalSupplies == 0`)
`pauseAsset(address _asset)`	Pause minting, burning, and borrowing for a specific asset
`unpauseAsset(address _asset)`	Resume operations for a paused asset
`pauseProtocol()`	Pause all vault operations globally
`unpauseProtocol()`	Resume all vault operations
`setInsuranceFund(address)`	Update the insurance fund address
`rescueERC20(address _asset, address _receiver)`	Recover a non-vault, non-strategy token sent to the contract by mistake

Data Structures

`VaultStorage`

ERC-7201 namespaced storage for the Vault module.

struct VaultStorage {
    EnumerableSet.AddressSet assets;
    mapping(address => uint256) totalSupplies;
    mapping(address => uint256) totalBorrows;
    mapping(address => uint256) utilizationIndex;
    mapping(address => uint256) lastUpdate;
    mapping(address => bool) paused;
    address insuranceFund;
}

Field	Type	Description
`assets`	`EnumerableSet.AddressSet`	Set of whitelisted backing assets
`totalSupplies`	`mapping(address => uint256)`	Total asset deposited (principal, not accounting for yield)
`totalBorrows`	`mapping(address => uint256)`	Total asset currently borrowed by Operators
`utilizationIndex`	`mapping(address => uint256)`	Cumulative time-weighted utilization integral per asset
`lastUpdate`	`mapping(address => uint256)`	Timestamp of the last index update per asset
`paused`	`mapping(address => bool)`	Per-asset pause state
`insuranceFund`	`address`	Address that receives minting/burning fees in cUSD

`MintBurnParams`

struct MintBurnParams {
    address asset;
    uint256 amountIn;
    uint256 amountOut;
    uint256 minAmountOut;
    address receiver;
    uint256 deadline;
    uint256 fee;
}

`RedeemParams`

struct RedeemParams {
    uint256 amountIn;
    uint256[] amountsOut;
    uint256[] minAmountsOut;
    address receiver;
    uint256 deadline;
    uint256[] fees;
}

Events

Event	Key Parameters	Emitted when
`Mint`	`minter, receiver, asset, amountIn, amountOut, fee`	cUSD minted
`Burn`	`burner, receiver, asset, amountIn, amountOut, fee`	cUSD burned for a single asset
`Redeem`	`redeemer, receiver, amountIn, amountsOut, fees`	cUSD redeemed across all assets
`Borrow`	`borrower, asset, amount`	Operator borrow executed
`Repay`	`repayer, asset, amount`	Operator repayment received
`AddAsset`	`asset`	New backing asset added
`RemoveAsset`	`asset`	Backing asset removed
`PauseAsset`	`asset`	Asset paused
`UnpauseAsset`	`asset`	Asset unpaused

Errors

Error	Condition
`PastDeadline`	`block.timestamp > deadline`
`Slippage`	`amountOut < minAmountOut`
`InvalidAmount`	`amountOut == 0`
`AssetPaused`	Mint/burn/borrow attempted on a paused asset
`AssetNotSupported`	Asset is not in the vault's asset list
`AssetAlreadySupported`	`addAsset` called for an already-listed asset
`AssetHasSupplies`	`removeAsset` called while `totalSupplies > 0`
`AssetNotRescuable`	`rescueERC20` called for a listed or strategy-held asset
`InvalidMinAmountsOut`	`_minAmountsOut.length` doesn't match `assets().length`
`InsufficientReserves`	Available balance is less than the amount requested

Usage Examples

1. Minting cUSD

interface IVault {
    function mint(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)
        external returns (uint256 amountOut);
    function getMintAmount(address _user, address _asset, uint256 _amountIn)
        external view returns (uint256 amountOut, uint256 fee);
}

address vault    = 0x...; // cUSD vault proxy
address usdc     = 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48;
uint256 amountIn = 10_000e6; // 10,000 USDC

// 1. Preview the mint
(uint256 expectedOut, ) = IVault(vault).getMintAmount(msg.sender, usdc, amountIn);

// 2. Approve and mint
IERC20(usdc).approve(vault, amountIn);
uint256 cusdReceived = IVault(vault).mint(
    usdc,
    amountIn,
    expectedOut * 99 / 100, // 1% slippage tolerance
    msg.sender,
    block.timestamp + 5 minutes
);

2. Checking vault utilization before borrowing

interface IVault {
    function availableBalance(address _asset) external view returns (uint256);
    function utilization(address _asset) external view returns (uint256 ratio);
    function totalSupplies(address _asset) external view returns (uint256);
    function totalBorrows(address _asset) external view returns (uint256);
}

function vaultStatus(address vault, address asset)
    external
    view
    returns (uint256 available, uint256 utilizationPct)
{
    available       = IVault(vault).availableBalance(asset);
    utilizationPct  = IVault(vault).utilization(asset) / 1e25; // convert ray to bps (1e27 → 100%)
}

3. Redeeming cUSD across all assets

interface IVault {
    function assets() external view returns (address[] memory);
    function getRedeemAmount(address _user, uint256 _amountIn)
        external view returns (uint256[] memory amountsOut, uint256[] memory fees);
    function redeem(uint256 _amountIn, uint256[] calldata _minAmountsOut, address _receiver, uint256 _deadline)
        external returns (uint256[] memory amountsOut);
}

address vault      = 0x...;
uint256 cusdAmount = 5_000e18;

// Preview
(uint256[] memory expected, ) = IVault(vault).getRedeemAmount(msg.sender, cusdAmount);

// Apply 1% slippage tolerance to each asset
uint256[] memory minOut = new uint256[](expected.length);
for (uint256 i; i < expected.length; i++) {
    minOut[i] = expected[i] * 99 / 100;
}

IVault(vault).redeem(cusdAmount, minOut, msg.sender, block.timestamp + 5 minutes);

Navigation Menu

Uh oh!

Vault

Mechanics

Minting cUSD

Burning cUSD

Redeeming cUSD

Borrowing and Repaying

Utilization Tracking

Architecture

Core Functions

`mint(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

`burn(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

`redeem(uint256 _amountIn, uint256[] calldata _minAmountsOut, address _receiver, uint256 _deadline)`

`borrow(address _asset, uint256 _amount, address _receiver)`

`repay(address _asset, uint256 _amount)`

`availableBalance(address _asset)`

`utilization(address _asset)`

`currentUtilizationIndex(address _asset)`

`getRemainingMintCapacity(address _asset)`

Admin Functions

Data Structures

`VaultStorage`

`MintBurnParams`

`RedeemParams`

Events

Errors

Usage Examples

1. Minting cUSD

2. Checking vault utilization before borrowing

3. Redeeming cUSD across all assets

Uh oh!

FilesExpand file tree

vault.md

Latest commit

History

vault.md

File metadata and controls

Vault

Mechanics

Minting cUSD

Burning cUSD

Redeeming cUSD

Borrowing and Repaying

Utilization Tracking

Architecture

Core Functions

mint(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)

burn(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)

redeem(uint256 _amountIn, uint256[] calldata _minAmountsOut, address _receiver, uint256 _deadline)

borrow(address _asset, uint256 _amount, address _receiver)

repay(address _asset, uint256 _amount)

availableBalance(address _asset)

utilization(address _asset)

currentUtilizationIndex(address _asset)

getRemainingMintCapacity(address _asset)

Admin Functions

Data Structures

VaultStorage

MintBurnParams

RedeemParams

Events

Errors

Usage Examples

1. Minting cUSD

2. Checking vault utilization before borrowing

3. Redeeming cUSD across all assets

`mint(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

`burn(address _asset, uint256 _amountIn, uint256 _minAmountOut, address _receiver, uint256 _deadline)`

`redeem(uint256 _amountIn, uint256[] calldata _minAmountsOut, address _receiver, uint256 _deadline)`

`borrow(address _asset, uint256 _amount, address _receiver)`

`repay(address _asset, uint256 _amount)`

`availableBalance(address _asset)`

`utilization(address _asset)`

`currentUtilizationIndex(address _asset)`

`getRemainingMintCapacity(address _asset)`

`VaultStorage`

`MintBurnParams`

`RedeemParams`