# zenanetwork/zena architecture

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

- Interactive diagram: https://gitdiagram.com/zenanetwork/zena
- Repository: https://github.com/zenanetwork/zena

## Overview

##### Project Type & Purpose
- Zenanet is a full-stack blockchain application: a Cosmos SDK–based chain (Zenad) with a pluggable EVM module.
- It exposes both Cosmos gRPC and Ethereum‐style JSON-RPC APIs, runs Tendermint consensus, supports IBC, custom precompiles, and integrates an Ethereum Virtual Machine.

##### High-Level Components
A. External Clients
- Ethereum-compatible wallets & tools (MetaMask, Hardhat, Truffle)
- `zenad` CLI
- IBC relayer / other Cosmos SDK chains
B. Networking & Consensus
- Tendermint Core (P2P, consensus engine)
- ABCI proxy between Tendermint and application
C. Application Layer (Zenad)
- CLI (`cmd/zenad`)
- JSON-RPC server (`server/json_rpc.go`) & WebSocket (`rpc/websockets.go`)
- gRPC query & Tx servers (`api/...`, generated from `proto/`)
- AnteHandler middleware (`ante/`) for transaction pre-processing (fees, signatures, gas)
- Cosmos SDK Modules (`x/*`):
– `x/evm` (EVM execution, transaction pool, EIP-1559)
– `x/erc20`, `x/feemarket`, `x/ibc/transfer`, `x/precisebank`, `x/vm`
– Standard Cosmos modules (bank, staking, gov, authz, etc.)
- Precompiles (`precompiles/*`): Solidity ABI wrappers invoked inside EVM
- Keepers & MsgServers (module state management & message handlers)
- State machine & KV store (IAVL/Merkle tree)
D. Indexer
- Separate service (`indexer/kv_indexer.go`) subscribing to Tendermint events to build search indexes

##### Component Interactions & Data Flows
- Clients (CLI or wallets) ➞ issue commands or JSON-RPC/gRPC requests over HTTP/WebSocket
- RPC layer (`server/`, `rpc/`) ➞ translates into gRPC or Cosmos SDK Msgs
- AnteHandler (`ante/`) ➞ performs fee checks, signature verification, nonce, gas consumption
- MsgServer & Keepers (`x/.../keeper`, `x/.../types`) ➞ execute module logic, update state
- Precompiles invoked during EVM transactions via `x/evm` ➞ call into Go methods in `precompiles/`
- Writes to KV Store ➞ Tendermint commits block, emits events
- Indexer & RPC backend subscribe to events for queries and indexing
- IBC module (`x/ibc/transfer`) handles cross-chain packets via relayer

##### Architectural Patterns & Principles
- Modular plugin architecture: each `x/…` directory is a self-contained module plugged into the Cosmos SDK app
- ABCI separation: consensus (Tendermint) vs. application (Zenad) decoupling
- Middleware stack: AnteHandler → Router → Module handlers → Post-Handlers
- Auto-generated API layers: Protobuf + buf → gRPC code + JSON-RPC bindings

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        MetaMask["MetaMask & Tools"]:::external
        CLI["CLI (zenad)"]:::external
        Relayer["IBC Relayer"]:::external
    end

    %% API Facade
    subgraph "API Facade"
        JSONRPC["JSON-RPC Server"]:::api
        WS["WebSocket RPC"]:::api
        Backend["RPC Backend"]:::api
        GRPC["gRPC Query & Tx Servers"]:::api
    end

    %% Application Layer
    subgraph "Application Layer"
        Ante["AnteHandler Middleware"]:::middleware
        App["Cosmos SDK App Setup"]:::middleware
    end

    %% Modules
    subgraph "Modules"
        EVMMod["EVM Module (x/vm)"]:::module
        ERC20["ERC20 Module (x/erc20)"]:::module
        Fee["FeeMarket Module (x/feemarket)"]:::module
        IBCMod["IBC Transfer Module (x/ibc/transfer)"]:::module
        PB["PreciseBank Module (x/precisebank)"]:::module
        StdModules["Standard Cosmos Modules"]:::module
    end

    %% Precompiles
    Precomp["Precompiles"]:::precompile

    %% State & Consensus
    KVStore["KV Store (IAVL/Merkle)"]:::datastore
    Tendermint["Tendermint Core"]:::consensus

    %% Indexer
    subgraph "Indexer"
        Indexer["Indexer Service"]:::datastore
        IndexerService["Indexer Backend"]:::datastore
    end

    %% Data Flows
    MetaMask -->|JSON-RPC/gRPC calls| JSONRPC
    CLI -->|Commands/Tx| JSONRPC
    CLI -->|Commands/Tx| GRPC
    Relayer -->|IBC Packets| IBCMod

    JSONRPC -->|translates to Msgs| Ante
    WS -->|translates to Msgs| Ante
    Backend -->|calls| Ante
    GRPC -->|calls| Ante

    Ante -->|routes to modules| EVMMod
    Ante -->|routes to modules| ERC20
    Ante -->|routes to modules| Fee
    Ante -->|routes to modules| IBCMod
    Ante -->|routes to modules| PB
    Ante -->|routes to modules| StdModules

    EVMMod -->|EVM Execution| Precomp
    EVMMod -->|state updates| KVStore
    ERC20 -->|state updates| KVStore
    Fee -->|state updates| KVStore
    IBCMod -->|state updates| KVStore
    PB -->|state updates| KVStore
    StdModules -->|state updates| KVStore

    KVStore -->|commit blocks| Tendermint
    Tendermint -->|events| Indexer
    Tendermint -->|events| JSONRPC

    Indexer -->|writes indexes| IndexerService

    %% Click Events
    click CLI "https://github.com/zenanetwork/zena/blob/main/cmd/zenad/main.go"
    click JSONRPC "https://github.com/zenanetwork/zena/blob/main/server/json_rpc.go"
    click WS "https://github.com/zenanetwork/zena/blob/main/rpc/websockets.go"
    click Backend "https://github.com/zenanetwork/zena/blob/main/rpc/backend/backend.go"
    click GRPC "https://github.com/zenanetwork/zena/tree/main/api/cosmos/evm"
    click Ante "https://github.com/zenanetwork/zena/blob/main/zenad/ante/ante.go"
    click App "https://github.com/zenanetwork/zena/blob/main/zenad/app.go"
    click EVMMod "https://github.com/zenanetwork/zena/blob/main/x/vm/module.go"
    click ERC20 "https://github.com/zenanetwork/zena/blob/main/x/erc20/module.go"
    click Fee "https://github.com/zenanetwork/zena/blob/main/x/feemarket/module.go"
    click IBCMod "https://github.com/zenanetwork/zena/blob/main/x/ibc/transfer/module.go"
    click PB "https://github.com/zenanetwork/zena/blob/main/x/precisebank/genesis.go"
    click Precomp "https://github.com/zenanetwork/zena/tree/main/precompiles/"
    click Indexer "https://github.com/zenanetwork/zena/blob/main/indexer/kv_indexer.go"
    click IndexerService "https://github.com/zenanetwork/zena/blob/main/server/indexer_service.go"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,color:#1B4F72;
    classDef api fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef middleware fill:#A9DFBF,stroke:#1E8449,color:#145A32;
    classDef module fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef precompile fill:#F5B7B1,stroke:#C0392B,color:#78281F;
    classDef datastore fill:#D5D8DC,stroke:#566573,color:#17202A;
    classDef consensus fill:#D6EAF8,stroke:#2874A6,color:#1B4F72;
```
