Euler Earn architecture

Euler Earn follows a modular design with carefully designed components that work together to create a secure, flexible yield aggregation protocol.

Core components

EulerEarn

The main contract that implements the ERC-4626 standard and coordinates all aspects of the vault's functionality. It manages deposits, withdrawals, strategy allocations, harvesting, and more.

Key responsibilities:

• Asset allocation to strategies
• Processing deposits and withdrawals
• Harvesting yield from strategies
• Managing interest smearing
• Handling loss deduction

EulerEarnFactory

Factory contract that deploys new Euler Earn vaults using the Clones pattern. Each vault is initialized with:

• Underlying asset
• Name and symbol
• Initial cash allocation points
• Smearing period

Access control system

Euler Earn uses a robust role-based access control system that allows for fine-grained permissions:

Each role has a specific set of permissions:

Role	Permissions
Default Admin	- Manages admin roles, including itself
Strategy Operator	- Add strategies - Remove strategies
Euler Earn Manager	- Set performance fee and recipient - Manage strategy rewards - Configure hooks - Skim non-asset tokens
Withdrawal Queue Manager	- Re-order withdrawal queue
Guardian	- Set strategy caps - Adjust allocation points - Toggle emergency status
Rebalancer	- Execute rebalance operations

Data structures

Strategy

struct Strategy {
    uint120 allocated;        // Amount of asset deposited into strategy
    uint96 allocationPoints;  // Number of points allocated to this strategy
    AmountCap cap;            // Optional cap in terms of deposited underlying asset
    StrategyStatus status;    // Strategy status (Inactive, Active, Emergency)
}

Strategy status

enum StrategyStatus {
    Inactive,  // Strategy not recognized by withdrawal queue
    Active,    // Functional strategy, can be rebalanced and harvested
    Emergency  // Circuit-breaker activated for a problematic strategy
}

Key processes

Rebalancing

Rebalancing is the process that actually allocates user deposits to strategies based on their allocation points:

1. Calculate target allocation for each strategy: (total allocatable assets * strategy allocation points) / total allocation points
2. For each strategy:
   • If current allocation < target: Deposit the difference (limited by available cash)
   • If current allocation > target: Withdraw the difference (limited by withdrawable amount)

Harvesting

Harvesting collects yield from all strategies:

1. Loop through strategies in withdrawal queue order
2. For each strategy, calculate yield as: strategy.previewRedeem(shares) - strategy.allocated
3. Aggregate total yield (positive or negative)
4. Apply performance fee if yield is positive
5. If yield is negative, apply loss deduction
6. Make harvested positive yield available for gulping

Interest smearing

To prevent sudden exchange rate jumps, positive yield is gradually distributed to depositors:

1. Harvested yield is added to a separate accounting variable
2. Over the configured smearing period (default 1 day), this yield is gradually released
3. The gulp() function triggers distribution of pending interest

Loss deduction

When a strategy loses value or is marked as Emergency:

1. First attempt to deduct loss from undistributed interest
2. If insufficient, socialize the remaining loss among all depositors
3. This reduces the vault's exchange rate, affecting all depositors equally

Withdrawal process

When a user requests a withdrawal:

1. First try to satisfy withdrawal from cash reserve
2. If insufficient, withdraw from strategies in withdrawal queue order
3. If a withdrawal would trigger a harvest (due to cooldown period passed), estimate if this would result in a loss
4. Adjust withdrawal amount based on estimated value after potential loss

Integration points

ERC-4626 compatibility

Euler Earn implements the standard ERC-4626 interface, making it compatible with any systems designed to work with these vaults.

ERC20Votes support

Native integration with ERC20Votes contract to support Compound-like voting and delegation.

Hooks system

Euler Earn implement the same hooks implementation as the Euler Vault Kit. Customizable hook system allows for extending the following functionality:

• Before deposits/mints
• Before withdrawals/redeems
• Before adding a strategy
• Before removing a strategy

Rewards management

Built-in system for handling rewards from underlying strategies:

• Opt in/out of strategy rewards
• Enable/disable specific reward tokens
• Claim rewards to designated recipients