Overview

The Euler Vault Kit (EVK) is a system for constructing credit vaults: ERC-4626 vaults extended with lending and borrowing. Borrower interest is their core yield source, unlike many ERC-4626 implementations that allocate assets to external strategies. Users can borrow from a credit vault when they have sufficient eligible collateral in other credit vaults. The liability vault decides which credit vaults it accepts as collateral.

Key components

Vault architecture

A vault consists of several components:

Underlying Asset: The ERC-20 token held by the vault. Each vault holds exactly one underlying asset.
EVault: The primary entry-point contract implementing common vault logic:
- Tracks deposits and borrows
- Accrues interest
- Validates position health
- Permits liquidations
Price Oracle: Interfaces with external pricing systems to compute collateral and liability values
IRM (Interest Rate Model): Computes interest rates to incentivize borrowing behavior
ProtocolConfig: Global protocol-level configuration controlling interest fee destinations and splits
Hook Target: Optional contract that can implement custom logic for vault operations through hooks
DToken: A read-only ERC-20 interface for debt amounts, making debt modifications visible in block explorers and trackable by tax-accounting software

Vault creation and governance

Vaults are created through a factory contract, which deploys a proxy pointing to the implementation contract. This pattern enables gas-efficient deployment and gives integrators a way to verify factory provenance. After creation, vaults can be either governed, where the creator retains or transfers governance rights, or finalized, where governance is revoked by setting governor to address(0).

Upgradeability vs immutability

When creating a vault, a boolean upgradeable flag is specified:

If upgradeable is true, the factory creates a beacon proxy, allowing the factory admin to upgrade the vault's implementation
If upgradeable is false, the factory creates a minimal proxy contract, making the vault immutable

The factory has a configured upgradeAdmin that can change the implementation for upgradeable vaults. Verify its current holder and control path onchain for the selected deployment. Vault creators choose whether a factory-admin implementation change can affect their vault or whether its implementation is immutable.

Governance risk

The combination of upgradeability and governance creates different risk profiles:

	Upgradeable	Immutable
Governed	Factory Admin + Governor	Governor
Finalized	Factory Admin	None

Immutability removes specific change authorities but also removes their recovery options. See EVK security for the resulting governance, oracle, collateral, and implementation tradeoffs.

Core functionality

Exchange rate and shares

Vaults implement the ERC-4626 standard, where shares represent proportional claims on vault assets. The exchange rate grows as interest accrues, and shares maintain the same decimals as the underlying asset. The exchange rate is calculated as:

exchangeRate = (cash + totalBorrows + VIRTUAL_DEPOSIT) / (totalShares + VIRTUAL_DEPOSIT)

The virtual deposit mechanism mitigates manipulation through rounding-based "stealth deposits" and keeps the exchange rate well-defined even with zero shares.

Token transfers

Vaults use two internal abstractions for token movements:

pullAssets: First attempts a Permit2-authorized transfer, then falls back to the underlying asset transferFrom
pushAssets: Uses transfer on the underlying asset, with checks to prevent transfers to virtual sub-accounts

Permit2 can improve user experience by allowing approvals to be created as signed messages bundled into the same EVC batch as operations like deposit. Users need to approve the Permit2 contract once, and some users may already have done this when interacting with Uniswap or other apps.

With the advent of EIP-7702, the need for Permit2 is reduced, as EIP-7702 allows approvals to be bundled with transactions in a more native way. However, not all networks support EIP-7702 yet, and many wallets are still catching up. As a result, Permit2 remains useful for smoother user experiences across different environments and wallet implementations.

Internal balance tracking

The vault uses internal balance tracking instead of reading its own balance from the underlying asset. This prevents users from manipulating the exchange rate through direct transfers and is more gas efficient. However, this means that rebasing/fee-on-transfer tokens are not supported, as the vault cannot track unexpected balance changes.

Balance forwarding

Balance forwarding enables automated distribution of rewards while keeping gas costs low. When an account opts in, every time its balance changes an external contract is notified of the updated balance. This external contract has no special privileges in the vault, but its balanceTrackerHook method must not revert or use up all gas. In practice, reward campaigns for Euler vaults run on offchain platforms such as Merkl, which do not rely on balance forwarding.

Interest rate models and compounding

Interest Rate Models (IRMs) determine the interest rate based on the vault's state, typically using a function of utilization. The most common function is a "linear-kink" model that starts with a gradual slope and becomes steep at a target utilization value.

Interest is compounded deterministically every second using exponentiation. Because accrued interest is added to totalBorrows, it increases utilization. The amount of interest owed/earned is independent of how frequently the contract is interacted with, except for the effect of accumulator rounding.

IRMs return interest rates in terms of "second percent yield" (SPY) values, which are per-second compounded interest rates scaled by 1e27. For consistency, conversion to annualized equivalents should use the number of seconds in the average Gregorian calendar year (365.2425 days).

Fees

Interest-fee settings and recipients are configuration-, deployment-, network-, and vault-dependent. Verify the current deployed settings for the relevant network and vault. A governance proposal alone does not prove that a change was executed.

Vault governors can configure the portion of accrued borrower interest allocated as fees through the interestFee parameter, subject to the applicable bounds. Accumulated fees are converted into vault shares. Once minted, those shares participate in the same asset-per-share changes as other shares.

The ProtocolConfig contract's protocolFeeShare determines how the accumulated interestFee shares are split between the vault's fee receiver and the protocol fee receiver, subject to the contract's cap. It is a split of the configured interest fee, not an additional percentage charged on top. Read the vault's interestFee, its fee receiver, and the applicable protocol share and receiver together.

Supply and borrow caps

Vault governors can configure:

Supply cap: Limit on the amount of underlying assets that can be deposited
Borrow cap: Limit on the amount that can be borrowed

Both caps are denominated in the underlying asset and are packed into 2-byte decimal floating point values. Caps can be transiently violated since they are only enforced at the end of a batch. If a cap was not in violation at the start of a batch but is at the end, the transaction will be reverted.

Dtoken (debt token)

Vaults provide a read-only ERC-20 interface for debts through the DToken contract. This interface tracks debt modifications through Transfer events and supports off-chain analysis and tax accounting. The DToken contract is the first (and only) contract created by EVault, so its address can be calculated from the vault's address and the nonce 1.

Sub-accounts

The EVC provides each user with 256 virtual account addresses, known as sub-accounts, that are separated from one another. This lets users manage multiple positions with different risk parameters while using a single wallet.

How sub-accounts work

In the EVC, every Ethereum address is associated with 256 accounts, which includes the primary account (referred to as the owner). These accounts are identified by IDs ranging from 0 to 255, with ID 0 specifically assigned to the owner account. To generate sub-account addresses, the system performs an XOR operation between the account ID and the Ethereum address. Additionally, the EVC keeps track of sub-account ownership through a look-up mapping called ownerLookup, which helps resolve sub-accounts back to their respective owner addresses.

Important considerations

Sub-account addresses are internal to the EVC and compatible vaults
Ordinary ERC-20 contracts cannot authenticate EVC ownership of a derived sub-account. Use an address that actually controls the token balance and allowance unless the exact external flow is EVC-aware and reviewed.
The EVC maintains a look-up mapping to resolve sub-accounts to their owner addresses
Sub-accounts are the only way an account can hold multiple Vault borrows concurrently in the EVK

Risk management

Health checks

Vaults implement two critical health check methods:

checkAccountStatus: Verifies account solvency
checkVaultStatus: Ensures vault-level limits are respected

These methods are invoked by the EVC at appropriate times, typically after all operations in a batch have been performed.

LTV (loan-to-value)

Each collateral vault is configured with an LTV that determines the maximum borrow amount against collateral. The system supports separate borrowing and liquidation LTVs. The borrowing LTV is used to limit new borrows, while the liquidation LTV is used when liquidating existing positions. This gap helps compensate for pricing delays and uncertainty, requiring larger price movements to get liquidated right after the position was created. The liquidation LTV can be smoothly ramped down by the vault governor when a collateral needs to be phased out.

Liquidations

When an account's risk-adjusted collateral value reaches or falls below its liability value, the account becomes eligible for liquidation. The liquidation system uses a reverse Dutch auction mechanism that scales the discount proportionally with how deeply in violation the position is. The mechanism has several practical effects:

Slightly unhealthy positions may not be profitable to liquidate
As prices move against the position, the discount increases
A liquidator may execute when the discount covers execution, pricing, gas, and market risk

The liquidation discount is limited by a maximum liquidation discount parameter that vault creators must set appropriately. The discount is proportional to how far below the threshold the account is, which means that in some cases a liquidator may prefer many small liquidations rather than one large liquidation.

Bad debt socialization

When enabled, bad debt socialization cancels uncollateralized debt and socializes the loss to all depositors. This can reduce first-withdrawer advantage during bad debt events, but it still means depositors absorb losses. Vault governors who do not want debt socialization can disable this functionality.

Advanced features

Hooks system

The hooks system lets vault governors apply onchain conditions to selected vault operations. It can pause operations, require an onchain allowlist or attestation, add flash-loan fees, enforce utilization caps, or set minimum debt sizes. A hook does not itself perform identity verification, sanctions screening, legal review, or make a vault compliant; document its data freshness, failure, upgrade, bypass, and emergency behavior.

For a full technical reference, see the EVK whitepaper or the EVK repository.