# vemo-network/vemo-core-protocol architecture

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

- Interactive diagram: https://gitdiagram.com/vemo-network/vemo-core-protocol
- Repository: https://github.com/vemo-network/vemo-core-protocol

## Overview

##### Main Components
- Smart Contract Modules:
- Account Modules – Found mostly in directories like src/accounts and src/abstract/execution. These likely include account management logic (e.g., “AccountV3” in the README).
- Voucher Modules – These contracts (with VoucherFactory, VoucherAccount implementations, etc.) handle voucher creation, data registry associations, and collection management.
- Vesting Modules – Vemo Vesting Factory components are deployed to manage vesting pools.
- Wallet Modules – Vemo Wallet contracts (WalletFactory Proxy, Account Wallet Proxy, and wallet implementations) provide the user’s wallet functionality.
- Supporting Libraries and Helpers:
- The lib folder contains imported libraries for account abstraction, ERC6551 standards, OpenZeppelin implementations, and upgradeability patterns (openzeppelin-foundry-upgrades).
- The src/helpers directory includes helper components for NFT descriptors (including submodules like DelegationURI, NFTAccount, VoucherURI), which are important for token metadata and integrations.
- Deployment and Scripting Resources:
- The script directory contains deployment and verification scripts for both voucher and wallet contracts.
- The foundry.toml, remappings.txt, and package.json indicate build configuration and dependency management.
- Testing Modules:
- The “test” folder is structured into modules for testing accounts, factories, gas profiling, and mocks. This highlights both unit and integration tests for the contracts.

##### Relationships and Interactions
- How the Wallet, Voucher, and Vesting factory contracts are central “nodes” in the system.
- The “Factory” contracts deploy and manage new instances (e.g., VoucherFactory, WalletFactory).
- The account registry and data registry serve as central stores providing valid addresses and state management for deployed contracts.
- The helpers, especially in NFTDescriptor, interact with the voucher/account modules to encode metadata and assist in URI delegation.
- External interactions:
- Interaction with blockchain networks (e.g., ARB, BNB, AVAX) as specified in the README deployment sections.
- Integration with external services (e.g., Etherscan for contract verification and the use of Cast command-line tools).

##### Architectural Patterns and Design Principles
- The project shows a modular design: segregating contracts into clear domains (accounts, vouchers, vesting, and deployment).
- Upgradeability and abstraction patterns are evident via separate implementations (Impl directories and upgrade scripts), the use of proxies, and the consistent separation between interface contracts and implementation details.
- Use of industry-standard libraries like OpenZeppelin reinforces safe and maintainable smart contract development practices.

##### Relevant Technologies, Frameworks, and Tools
- Solidity as the programming language.
- Foundry for building, testing, and deployment (commands like forge build, forge test, forge script).
- Integration with OpenZeppelin contracts (both standard and upgradeable versions).
- Deployment scripts written for various networks, reflecting cross-chain deployment considerations.
- Testing frameworks with gas-reporting and snapshot abilities.

##### Being Detailed and Exhaustive
- Don’t shy away from splitting components into as many parts as needed; for example, separate “Factory Components” from “Implementation Components” where proxies are used.
- That the labels (addresses, roles defined in the README, network specifics) are mentioned where relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-chain Core Contracts
    subgraph "On-chain Core Contracts"
        A["Accounts Contract (src/accounts)"]:::core
        B["Execution Module (src/abstract/execution)"]:::core
        C["Voucher Module (Factory & Account)"]:::core
        D["Voucher URI Helper (src/helpers/NFTDescriptor/VoucherURI)"]:::core
        E["Vemo Vesting Factory"]:::core
        F["Wallet Factory & Proxy"]:::core
        G["Registry (Account/Data)"]
        H["Blockchain Networks (ARB,BNB,AVAX)"]:::external
        I["Etherscan & Cast"]:::external
    end

    %% Supporting Libraries & Helpers
    subgraph "Supporting Libraries & Helpers"
        L1["Account Abstraction Library"]:::lib
        L2["ERC6551 Library"]:::lib
        L3["OpenZeppelin Contracts"]:::lib
        L4["OpenZeppelin Upgradeable"]:::lib
        L5["Foundry Upgrades"]:::lib
        L6["Solidity Bytes Utils"]:::lib
        L7["NFT Descriptor Helpers"]:::lib
    end

    %% Deployment & Scripting Resources
    subgraph "Deployment & Scripting"
        DS1["Voucher Deployment Scripts"]:::deploy
        DS2["Wallet Deployment Scripts"]:::deploy
        DS3A["foundry.toml"]:::deploy
        DS3B["remappings.txt"]:::deploy
        DS3C["package.json"]:::deploy
    end

    %% Testing Modules
    subgraph "Testing"
        T1["Voucher Tests"]:::test
        T2["Wallet Tests"]:::test
        T3["Other Tests (accounts, gasProfiling, lib, mock)"]:::test
    end

    %% Relationships in On-chain Core Contracts
    A -->|"triggers"| B
    C -->|"assigns roles"| G
    F -->|"uses"| G
    DS1 -->|"deploys"| C
    DS2 -->|"deploys"| F
    E -->|"deployed on"| H
    F -->|"deployed on"| H
    I -->|"verifies/contracts"| C

    %% Link between Voucher Module and Voucher URI Helper
    C -->|"utilizes"| D

    %% Supporting Libraries interactions
    L7 -->|"supports metadata"| D

    %% Deployment Config links to Deployment Scripts
    DS3A --> DS1
    DS3B --> DS1
    DS3C --> DS1
    DS3A --> DS2
    DS3B --> DS2
    DS3C --> DS2

    %% Testing connections to Core Modules
    T1 -->|"tests"| C
    T2 -->|"tests"| F

    %% Click Events for Component Mappings
    click A "https://github.com/vemo-network/vemo-core-protocol/tree/main/src/accounts"
    click B "https://github.com/vemo-network/vemo-core-protocol/tree/main/src/abstract/execution"
    click D "https://github.com/vemo-network/vemo-core-protocol/tree/main/src/helpers/NFTDescriptor/VoucherURI"
    click DS1 "https://github.com/vemo-network/vemo-core-protocol/tree/main/script/voucher"
    click T1 "https://github.com/vemo-network/vemo-core-protocol/tree/main/test/factory/Voucher"
    click E "https://github.com/vemo-network/vemo-core-protocol/blob/main/doc/create_vesting_pool.md"
    click DS2 "https://github.com/vemo-network/vemo-core-protocol/tree/main/script/wallet"
    click T2 "https://github.com/vemo-network/vemo-core-protocol/tree/main/test/factory/Wallet"
    click L1 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/account-abstraction"
    click L2 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/erc6551"
    click L3 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/openzeppelin-contracts"
    click L4 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/openzeppelin-contracts-upgradeable"
    click L5 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/openzeppelin-foundry-upgrades"
    click L6 "https://github.com/vemo-network/vemo-core-protocol/tree/main/lib/solidity-bytes-utils"
    click L7 "https://github.com/vemo-network/vemo-core-protocol/tree/main/src/helpers/NFTDescriptor"
    click DS3A "https://github.com/vemo-network/vemo-core-protocol/blob/main/foundry.toml"
    click DS3B "https://github.com/vemo-network/vemo-core-protocol/blob/main/remappings.txt"
    click DS3C "https://github.com/vemo-network/vemo-core-protocol/blob/main/package.json"

    %% Class Definitions for styling
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef lib fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef deploy fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef test fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#F5F5F5,stroke:#000,stroke-width:2px;
```
