# velvet-capital/velvet-v4 architecture

> Architecture diagram of the GitHub repository velvet-capital/velvet-v4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/velvet-capital/velvet-v4
- Repository: https://github.com/velvet-capital/velvet-v4

## Overview

##### Key system components
- Smart Contracts Modules:
- Core Contracts: Found under contracts/core that include submodules like access, calculations, checks, cooldown, interfaces, management, token, and user functionality.
- Configuration & Asset Management: Located within contracts/config (with separate assetManagement and protocol subdirectories) indicating configurable aspects of the contracts.
- Fee, Vault, Rebalance, Oracle & Wrappers: Separate directories for fee management, vault logic, rebalancing logic, oracle integrations, and contract wrappers for interfacing with external protocols (e.g., algebra, uniswapV3).
- Meta-Aggregator: A self-contained module (with its own README, interfaces, libraries, and tests) that likely aggregates or combines data and behaviors from multiple sources.
- Handlers & Front-end Helpers: These include contracts/handler (for external swap handling and integrations with services like Venus) and front-end helper modules (suggesting support for UI integration or simplified interaction with protocols).
- Mock and Upgradeability: The mock contracts directory (with changedDependencies subdirectories) indicates testing stubs or simulated environments for upgradeability and dependency changes.

##### Testing and Deployment Ecosystem
- Testing: There are dedicated directories for tests (segregated by network: Arbitrum and Bsc), Foundry specific tests, meta-aggregator tests, and additional calculation testing. This shows thorough coverage meant to validate various contract features and network-specific behavior.
- Deployment Scripts & Tasks:
- Scripts for deploying contracts and meta-aggregators (in the scripts directory, including files like deployContracts.ts, deployMetaAggregator.ts, etc.).
- Hardhat tasks (in the tasks directory) that facilitate operations like account management, balance checking, deploying portfolios, and more.
- Configuration: Files such as hardhat.config.ts, foundry.toml, and remix-compiler.config.js set up the compilation and runtime environment. The README also refers to the need for environment variables (.env file) that provide RPC URLs, chain IDs, and wallet configuration.

##### Relationships and interactions between components
- The central part of the architecture is the suite of smart contracts (organized across various directories). They interact with each other following dependencies such as core logic calling external or library contracts.
- Deployment and management scripts (in scripts and tasks directories) interact with these smart contracts for deployment automation, testing, and upgrades.
- Testing frameworks (using Hardhat and Foundry) verify behavior across multiple chains (as indicated by separate tests for Arbitrum and BSC). Each test suite verifies not just individual modules, but also interactions among them, such as deposit/withdrawal flows, upgradeability tests, and meta-aggregator functionality.
- External integrations are evident in the use of front-end helpers and wrappers to abstract interactions with protocols such as Algebra and Uniswap V3, along with liquidity management and perhaps oracle price feeds.

##### Important architectural patterns/design principles
- Modular Architecture: Each major piece of functionality (core, oracle, fee, vault, etc.) is encapsulated in its own directory, allowing isolated development and testing.
- Separation of Concerns: There is a clear split between the business logic (contracts/core), the configuration (contracts/config), the integration logic (wrappers, handlers, front-end-helpers), and the testing/deployment infrastructure.
- Upgradeability and Mocking: The presence of mocks and the upgradeability-related directories point to considerations around maintaining and evolving smart contract behaviors without interrupting operations.

##### Elements
- Clear labels for each component:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% System Boundary: Blockchain Environment
    subgraph "Blockchain Environment"
        subgraph "Smart Contracts"
            CoreContracts["Core Contracts"]:::contracts
            ConfigAssetMgmt["Configuration & Asset Management"]:::contracts
            FeeManagement["Fee Management"]:::contracts
            VaultLogic["Vault Logic"]:::contracts
            RebalanceLogic["Rebalancing Logic"]:::contracts
            OracleIntegrations["Oracle Integrations"]:::contracts
            ContractWrappers["Contract Wrappers (External Protocol Adapters)"]:::contracts
            FrontEndHelpers["Front-end Helpers"]:::contracts
            Handlers["Handlers for External Integrations"]:::contracts
            MetaAggregator["Meta-Aggregator Module"]:::contracts
            Mocks["Mock and Upgradeability"]:::contracts
        end
    end

    %% Deployment and Task Automation
    subgraph "Deployment & Task Automation"
        DeploymentScripts["Deployment Scripts"]:::deployment
        TaskAutomation["Task Automation"]:::deployment
    end

    %% Testing and Verification
    subgraph "Testing & Verification"
        TestingSuites["Testing Suites"]:::testing
    end

    %% Tooling and External Integration
    subgraph "Tooling & External Integration"
        Tooling["Configuration & Tooling Files"]:::tooling
        External["External Services (RPC,EnvVariables)"]:::external
    end

    %% Relationships among Smart Contracts
    ConfigAssetMgmt -->|"configures"| CoreContracts
    CoreContracts -->|"utilizes"| FeeManagement
    CoreContracts -->|"utilizes"| VaultLogic
    CoreContracts -->|"utilizes"| RebalanceLogic
    FeeManagement -->|"queries"| OracleIntegrations
    VaultLogic -->|"queries"| OracleIntegrations
    RebalanceLogic -->|"queries"| OracleIntegrations
    CoreContracts -->|"integrates"| MetaAggregator
    ContractWrappers -->|"interfaces with"| CoreContracts
    FrontEndHelpers -->|"assists"| ContractWrappers
    External -->|"feeds data to"| ContractWrappers
    External -->|"feeds data to"| Handlers

    %% Deployment and Task Automation interactions
    DeploymentScripts -->|"deploys"| CoreContracts
    TaskAutomation -->|"manages"| CoreContracts

    %% Testing interactions
    TestingSuites -->|"validates"| CoreContracts
    TestingSuites -->|"validates"| MetaAggregator

    %% Tooling interactions
    Tooling -->|"configures"| DeploymentScripts
    Tooling -->|"configures"| TestingSuites

    %% Click Events
    click CoreContracts "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/core"
    click ConfigAssetMgmt "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/config"
    click FeeManagement "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/fee"
    click VaultLogic "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/vault"
    click RebalanceLogic "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/rebalance"
    click OracleIntegrations "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/oracle"
    click ContractWrappers "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/wrappers"
    click FrontEndHelpers "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/front-end-helpers"
    click Handlers "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/handler"
    click MetaAggregator "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/meta-aggregator"
    click Mocks "https://github.com/velvet-capital/velvet-v4/tree/main/contracts/mock/upgradeability"
    click DeploymentScripts "https://github.com/velvet-capital/velvet-v4/tree/main/scripts"
    click TaskAutomation "https://github.com/velvet-capital/velvet-v4/tree/main/tasks"
    click TestingSuites "https://github.com/velvet-capital/velvet-v4/tree/main/test"
    click Tooling "https://github.com/velvet-capital/velvet-v4/blob/main/hardhat.config.ts"

    %% Class Definitions for Coloring
    classDef contracts fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef deployment fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef testing fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef tooling fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
