# euler-xyz/euler-vault-kit architecture

> Architecture diagram of the GitHub repository euler-xyz/euler-vault-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/euler-xyz/euler-vault-kit
- Repository: https://github.com/euler-xyz/euler-vault-kit

## Overview

The Euler Vault Kit is essentially a modular, on-chain library of smart contracts for building ERC-4626-style “credit vaults” on Ethereum. There is no UI/front-end; the primary components are Solidity contracts, a factory for deployment, a registry/config, a set of vault modules, and external dependencies/integration points.

##### Main System Type and Purpose
- Type: On-chain smart-contract library (no UI).
- Purpose: Deploy and manage “credit vaults” (ERC-4626 + borrowing) in a pluggable, modular fashion. Developers install via Foundry and integrate with other contracts or dApps.

##### Key Top-Level Components (derive from file structure & README)
a. GenericFactory (src/GenericFactory) – Deploys new vault instances.
b. SequenceRegistry (src/SequenceRegistry) – Stores ordered lists of modules/config for each vault type.
c. EVault Core (src/EVault)
– Shared storage and interfaces (src/EVault/shared/*).
– Modules (src/EVault/modules/*): BalanceForwarder, Governance, Liquidation, RiskManager, Vault.
d. ProtocolConfig & InterestRateModels (src/ProtocolConfig, src/InterestRateModels) – Global parameters and interest-rate logic.
e. Synths (src/Synths) – Optional synthetic assets integration.
f. Interfaces (src/interfaces) – ERC-4626, ERC-20, connector abstractions.
g. External Libraries (lib/*): OpenZeppelin, permit2, ethereum-vault-connector, forge-std.
h. Testing & Verification (test/*, certora/*, slither.config.json) – Off-chain test harness and formal tools.

##### Relationships & Data Flows
- User/client wallet or dApp → calls GenericFactory.createVault(params)
- GenericFactory → writes config to SequenceRegistry → deploys new EVault proxy
- EVault proxy delegates calls into modules (via internal dispatch)
– deposit/withdraw calls hit Vault module → updates balances
– borrow/repay calls hit Vault + RiskManager
– liquidation triggers call Liquidation module
– governance/admin calls hit Governance module → update ProtocolConfig
- EVault calls external ERC-20 tokens for transfers
- EVault may call ethereum-vault-connector to integrate with external yield protocols
- ProtocolConfig and InterestRateModels provide read-only parameters to modules
- Synths module mints/burns synthetic assets if configured

##### Important Patterns & Principles
- Modular contract design – each concern isolated in its own module
- Proxy / Factory pattern – GenericFactory + Registry + minimal proxy for upgradeability
- ERC-4626 standard compliance with extension for credit/borrow
- Pluggable interest-rate and protocol configuration
- Formal verification harnesses (Certora) and fuzz/invariant testing (Foundry, Echidna)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Ethereum Mainnet"
        subgraph "Factory & Registry Layer"
            GF["GenericFactory"]:::factory
            SR["SequenceRegistry"]:::factory
        end

        subgraph "Vault Core Layer"
            EVCore["EVault Proxy"]:::core
            SI["Shared Interfaces & Storage"]:::core

            subgraph "EVault Modules"
                VM["Vault"]:::module
                BF["BalanceForwarder"]:::module
                GOV["Governance"]:::module
                RM["RiskManager"]:::module
                LIQ["Liquidation"]:::module
            end
        end

        subgraph "Support Layer"
            PC["ProtocolConfig"]:::support
            IRM["InterestRateModels"]:::support
            SYN["Synths"]:::support
        end

        subgraph "Interfaces & Libraries"
            INT["Interfaces"]:::interface
            OZ["OpenZeppelin Contracts"]:::lib
            P2["Permit2"]:::lib
            EVC["Ethereum Vault Connector"]:::lib
        end
    end

    U["User / dApp Wallet"]:::external
    FS["Foundry & Forge"]:::external
    MD["Medusa & Echidna"]:::external
    CR["Certora"]:::external
    SL["Slither"]:::external
    GH["GitHub Actions"]:::external

    U -->|"createVault(params)"| GF
    GF -->|"registerSequence"| SR
    GF -->|"deploy Proxy"| EVCore

    EVCore -->|"uses Shared Storage"| SI
    EVCore --> VM
    EVCore --> BF
    EVCore --> GOV
    EVCore --> RM
    EVCore --> LIQ

    EVCore -->|"reads Params"| PC
    EVCore --> IRM
    EVCore --> SYN

    EVCore --> INT
    VM -->|"ERC-20 transfer"| INT
    BF --> EVC
    GOV --> PC
    RM --> PC
    LIQ --> INT

    FS -.-> U
    FS -.-> GF
    MD -.-> FS
    CR -.-> FS
    SL -.-> FS
    GH -.-> FS

    classDef factory fill:#FFE699,stroke:#333,color:#000;
    classDef core fill:#C9DAF8,stroke:#333,color:#000;
    classDef module fill:#D9EAD3,stroke:#333,color:#000;
    classDef support fill:#FFF2CC,stroke:#333,color:#000;
    classDef interface fill:#EAD1DC,stroke:#333,color:#000;
    classDef lib fill:#D0CECE,stroke:#333,color:#000;
    classDef external fill:#F4CCCC,stroke:#333,color:#000;

    click GF "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/GenericFactory"
    click SR "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/SequenceRegistry"
    click SI "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/shared"
    click VM "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/modules/Vault"
    click BF "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/modules/BalanceForwarder"
    click GOV "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/modules/Governance"
    click RM "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/modules/RiskManager"
    click LIQ "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/EVault/modules/Liquidation"
    click PC "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/ProtocolConfig"
    click IRM "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/InterestRateModels"
    click SYN "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/Synths"
    click INT "https://github.com/euler-xyz/euler-vault-kit/tree/master/src/interfaces"
    click OZ "https://github.com/euler-xyz/euler-vault-kit/tree/master/lib/openzeppelin-contracts"
    click P2 "https://github.com/euler-xyz/euler-vault-kit/tree/master/lib/permit2"
    click EVC "https://github.com/euler-xyz/euler-vault-kit/tree/master/lib/ethereum-vault-connector"
```
