# elys-network/elys architecture

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

- Interactive diagram: https://gitdiagram.com/elys-network/elys
- Repository: https://github.com/elys-network/elys

## Overview

Based on our analysis of both the enormous file tree and the README, the Elys project is a full-fledged blockchain built using the Cosmos SDK and CometBFT (the underlying consensus engine formerly known as Tendermint). It is designed to be fast, scalable, and secure for decentralized applications. The system is highly modular, with each module (located primarily in the “api”, “app”, “x”, and “cmd” directories) responsible for discrete functions such as automated market making (amm), asset profiling, staking variations (estaking, stablestake), leveraged positions (leveragelp), governance (masterchef, commitment, parameter), oracle functionality, as well as other domain-specific modules (tokenomics, perpetual, tradeshield, transferhook, tier, etc.).

- Daemon/Node (elysd): Located in “cmd/elysd”, this is the main executable that runs the blockchain node.
- Core Application & Blockchain Logic: The “app” folder houses the entry point (app.go, genesis.go, etc.) and overall encoding, simulation, and export mechanisms which bootstrap the blockchain.
- Modules: Many functional modules exist under “api/elys” and “x”. Each module implements aspects like AMM, asset profiles, burner, commitment, epochs, estaking, oracle, parameter, perpetual, stablestake, tier, tokenomics, tradeshield, and others. Each module generally follows the Cosmos SDK module pattern with its own keeper, message server, query methods, and state management.
- Protobuf and API Definitions: The “proto” directory contains all the protocol buffer definitions (for gRPC and REST endpoints) that standardize external communication.
- Client/CLI & WASM Bindings: In the “wasmbindings” and some “client/cli” directories (within “x” folders and also “price_feeder”), there are modules, clients, and bindings for managing both CLI interactions and wasm-based calls.
- Deployment and DevOps: Directories like “.github”, “dockernet”, “Dockerfile”, and various “scripts” (for testing, migration, orchestration, and releasing) indicate CI/CD pipelines, testing frameworks, and deployment orchestration.

- How transactions from the CLI or REST/gRPC API endpoints reach the daemon “elysd”.
- Within elysd, illustrate how the core application forwards transactions (and governance “proposal” messages, etc.) to the appropriate module’s message server.
- How the consensus engine (CometBFT) interacts with elysd for achieving consensus, block production, and state commitment.
- Involvement of external services (for example, the oracle modules that connect to external price feeds as indicated in “oracle”, “price_feeder”, and related script examples).
- Incorporate the development and deployment tools (GitHub Actions workflows, Docker/Compose setups, and price feeder configurations) as supporting infrastructure that interacts with various layers.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that each functional area is implemented as a separate module following the Cosmos SDK “module” pattern—each with its own state, message handlers, queries, and simulation tests.
- API-first design: The use of gRPC (with generated pb.go files in both “api/elys” and “proto”) and REST endpoints points to a design that exposes services for both querying and transaction processing.
- Separation of Concerns: Distinguish between core blockchain logic (in “app” and “cmd”), modular functionality (in “x” and “api/elys”), and external/deployment concerns (in “dockernet”, “scripts”, “.github”).
- Extensibility: Many modules have comprehensive testing and migration directories, suggesting that the system is built to evolve and upgrade seamlessly.

##### Relevant Technologies and Frameworks
- Cosmos SDK for blockchain framework.
- CometBFT (Tendermint) for consensus.
- Go as the primary programming language (with extensive Go module and build tool usage shown by go.mod, Makefile, and various build scripts).
- Protobuf for defining APIs and message schemas.
- Tools like buf, protoc-gen-go-cosmos-orm, and others for code generation.
- Docker and docker-compose for containerization of node deployments and testing networks.

##### Specific Elements
- Clear labels: Name each component (e.g., “elysd Daemon”, “AMM Module”, “Oracle Module”, “gRPC/REST API”, “Consensus Engine”).
- Interactions between modules (e.g., how the Commitment module might interact with the Tokenomics module or how hooks between Accounted Pool and AMM or Leveragelp are set up).

- The “elysd” node running on top of Cosmos SDK with underlying CometBFT consensus.
- One layer for service/API access showing exposed gRPC, REST, and CLI endpoints.
- A detailed depiction of functional modules (AMM, AssetProfile, Burner, Commitment, Epochs, Clock, Estaking, Leveragelp, Masterchef, Oracle, Parameter, Perpetual, Stablestake, Tier, Tokenomics, Tradeshield, Transferhook, etc.) with their internal keepers, message interfaces, and query capabilities.
- Supporting infrastructure for deployments and testing (Docker, GitHub workflows, and scripts) as additional context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    CI["Client Interface"]:::client
    CB["CLI Bindings"]:::client
    WB["WASM Bindings"]:::client

    %% Core Components
    ED["elysd Daemon"]:::core
    CA["Core Application"]:::core
    CE["Consensus Engine (CometBFT)"]:::consensus

    %% External Services
    EPS["External Price Feeds"]:::infra

    %% API Definitions
    PD["Protobuf Definitions"]:::infra

    %% API Modules Subgraph
    subgraph "API Modules"
        A_API["AMM (API)"]:::module
        O_API["Oracle (API)"]:::module
        C_API["Commitment (API)"]:::module
        S_API["Stablestake (API)"]:::module
        T_API["Tokenomics (API)"]:::module
    end

    %% SDK Modules Subgraph
    subgraph "SDK Modules"
        A_SDK["AMM (SDK)"]:::module
        O_SDK["Oracle (SDK)"]:::module
        C_SDK["Commitment (SDK)"]:::module
        S_SDK["Stablestake (SDK)"]:::module
        T_SDK["Tokenomics (SDK)"]:::module
    end

    %% DevOps and Deployment Subgraph
    subgraph "DevOps & Deployment"
        GH["GitHub Actions"]:::deployment
        DKR["Docker"]:::deployment
        DN["Dockernet"]:::deployment
        SCR["Scripts"]:::deployment
        MF["Makefile"]:::deployment
    end

    %% Connections - Data Flow
    CI -->|"submitTx"| ED
    CB -->|"bridgeTx"| ED
    WB -->|"bridgeTx"| ED

    ED -->|"processTx"| CA

    CA -->|"routeTx"| A_API
    CA -->|"routeTx"| O_API
    CA -->|"routeTx"| C_API
    CA -->|"routeTx"| S_API
    CA -->|"routeTx"| T_API
    CA -->|"routeTx"| A_SDK
    CA -->|"routeTx"| O_SDK
    CA -->|"routeTx"| C_SDK
    CA -->|"routeTx"| S_SDK
    CA -->|"routeTx"| T_SDK

    CA -->|"commitState"| CE
    CE -->|"updateState"| CA

    PD -->|"defineAPIs"| A_API
    PD -->|"defineAPIs"| O_API
    PD -->|"defineAPIs"| C_API
    PD -->|"defineAPIs"| S_API
    PD -->|"defineAPIs"| T_API
    PD -->|"defineAPIs"| CB
    PD -->|"defineAPIs"| WB

    GH -->|"deploy/update"| CA
    DKR -->|"deploy"| CA
    DN -->|"deploy"| CA
    SCR -->|"deployScripts"| CA
    MF -->|"build"| CA

    O_API -->|"fetchPrice"| EPS
    EPS -->|"priceData"| O_API

    %% Connections - External Interfaces to API
    CI ---|"interface"| PD

    %% Styles
    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#00cc00,stroke-width:2px;
    classDef client fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef infra fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef consensus fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef deployment fill:#d9d9d9,stroke:#666666,stroke-width:2px;

    %% Click Events
    click ED "https://github.com/elys-network/elys/tree/main/cmd/elysd"
    click CA "https://github.com/elys-network/elys/tree/main/app"
    click PD "https://github.com/elys-network/elys/tree/main/proto"
    click CB "https://github.com/elys-network/elys/tree/main/wasmbindings/client"
    click WB "https://github.com/elys-network/elys/tree/main/wasmbindings"
    click GH "https://github.com/elys-network/elys/blob/main/.github"
    click DKR "https://github.com/elys-network/elys/tree/main/Dockerfile"
    click DN "https://github.com/elys-network/elys/tree/main/dockernet"
    click SCR "https://github.com/elys-network/elys/tree/main/scripts"
    click MF "https://github.com/elys-network/elys/tree/main/Makefile"
    click A_API "https://github.com/elys-network/elys/tree/main/api/elys/amm"
    click O_API "https://github.com/elys-network/elys/tree/main/api/elys/oracle"
    click C_API "https://github.com/elys-network/elys/tree/main/api/elys/commitment"
    click S_API "https://github.com/elys-network/elys/tree/main/api/elys/stablestake"
    click T_API "https://github.com/elys-network/elys/tree/main/api/elys/tokenomics"
    click A_SDK "https://github.com/elys-network/elys/tree/main/x/amm"
    click O_SDK "https://github.com/elys-network/elys/tree/main/x/oracle"
    click C_SDK "https://github.com/elys-network/elys/tree/main/x/commitment"
    click S_SDK "https://github.com/elys-network/elys/tree/main/x/stablestake"
    click T_SDK "https://github.com/elys-network/elys/tree/main/x/tokenomics"
```
