# zeta-chain/node architecture

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

- Interactive diagram: https://gitdiagram.com/zeta-chain/node
- Repository: https://github.com/zeta-chain/node

## Overview

##### Project type and purpose
- ZetaChain is a monorepo for an EVM-compatible L1 blockchain built on Cosmos SDK + Ethermint (the “core chain”) plus a specialized “observer/signer” client (ZetaClient) that relays and signs cross-chain transactions, and auxiliary components (JSON-RPC server, CLI tools, E2E test harness, TS SDK).

##### High-level system components
a. Core Blockchain Node (“zetacored”)
- Cosmos SDK application (Go) exposing ABCI to Tendermint Core
- EVM module (Ethermint fork) + precompiles for native cross-chain operations
- Modular Cosmos SDK modules under x/ (authority, crosschain, observer, lightclient, emissions, fungible, ibccrosschain, etc.)
- gRPC & REST gateways for chain APIs
- Protobuf definitions (proto/zetachain/…) driving codegen
b. Observer/Signer Client (“zetaclientd”)
- Multi-chain observer services for Bitcoin, EVM, Solana, Sui, TON
- Signer components for cross-chain message authorization (TSS)
- Relayer logic: polls external chains → constructs ZetaCore transactions → submits via gRPC or CLI
c. JSON-RPC & Indexer Server (“server/”)
- Ethereum-compatible JSON-RPC namespaces and websockets (rpc/ and server/)
- Indexer service for chain data (blocks, txs) to support RPC methods
d. CLI Tools & Scripts
- Command-line binaries (zetacored, zetaclientd, zetatool) under cmd/
- Makefile, Dockerfiles, buf, codegen and release scripts
e. E2E Test Harness (e2e/)
- Docker-based localnet orchestration (contrib/localnet)
- Go-based E2E test runner interacting with all chain components
f. TypeScript SDK (typescript/)
- Generated TypeScript definitions from Protobuf + helper APIs

##### Component Interactions and Data Flows
- Tendermint Core <-ABCI-> Zetacored (Cosmos SDK app)
- Zetacored <-gRPC/REST-> CLI tools (zetacored CLI), ZetaClient submission
- Zetacored <-gRPC-> ZetaClient for transaction submission and query
- ZetaClient <-RPC-> External Chains (Bitcoin RPC, EVM JSON-RPC, Solana RPC, Sui/MVM, TON Lite API)
- ZetaClient (TSS) → multisig services (for cross-chain consensus)
- Server JSON-RPC <-> Zetacored (block and tx indexing) → clients (web3 UIs, scripts)
- E2E runner orchestrates containers for all above, drives tests

##### Architectural patterns & design principles
- Modular Cosmos SDK: each domain in x/ is a plug-in module (separation of concerns)
- Microservice for cross-chain observation & signing (ZetaClient)
- Adapter pattern: per-chain RPC adapters under zetaclient/chains/*
- Codegen from Protobuf for type safety across Go, TS, gRPC, OpenAPI
- CI pipeline with GitHub Actions for build, tests, releases

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Chain Zone
    subgraph "Core Chain Zone"
        direction TB
        A_tendermint["Tendermint Core"]:::core
        B_zetacored["Zetacored (Cosmos SDK + Ethermint)"]:::core
        C_modules["Modules (x/)"]:::core
        E_precompiles["EVM Precompiles"]:::core
        D_proto["Protobuf Definitions"]:::core
        F_grpc_rest["gRPC & REST Endpoints"]:::core
    end

    %% Observer/Signer Zone
    subgraph "Observer/Signer Zone"
        direction TB
        G_clientd["Zetaclientd"]:::client
        H_library["Zetaclient Core Lib"]:::client
        H1_chains["Chain Adapters (bitcoin, evm, solana, sui, ton)"]:::client
        H2_tss["TSS Signer & Keygen"]:::client
    end

    %% External Chains
    subgraph "External Chains"
        direction TB
        Ext_bitcoin["Bitcoin RPC"]:::external
        Ext_evmchain["EVM Chain RPC"]:::external
        Ext_solana["Solana RPC"]:::external
        Ext_sui["Sui RPC"]:::external
        Ext_ton["TON Lite API"]:::external
    end

    %% API Zone
    subgraph "API Zone"
        direction TB
        I_jsonrpc["JSON-RPC & WebSocket Server"]:::api
        J_indexer["Indexer Service"]:::api
    end

    %% Tooling & Test Zone
    subgraph "Tooling & Test Zone"
        direction TB
        K_cli_tools["CLI Binaries (cmd/)"]:::tooling
        L_e2e_runner["E2E Test Runner"]:::tooling
        M_localnet["Localnet Orchestration"]:::tooling
        N_ts_sdk["TypeScript SDK"]:::tooling
    end

    %% Connections
    A_tendermint -->|"ABCI"| B_zetacored
    B_zetacored -->|"uses"| C_modules
    B_zetacored -->|"uses"| E_precompiles
    D_proto -->|"codegen"| B_zetacored
    D_proto -->|"codegen"| N_ts_sdk
    B_zetacored -->|"exposes"| F_grpc_rest
    B_zetacored -->|"gRPC/REST"| K_cli_tools
    G_clientd -->|"relayer entrypoint"| H_library
    H_library -->|"implements"| H1_chains
    H_library -->|"implements"| H2_tss
    Ext_bitcoin -->|"RPC"| H1_chains
    Ext_evmchain -->|"RPC"| H1_chains
    Ext_solana -->|"RPC"| H1_chains
    Ext_sui -->|"RPC"| H1_chains
    Ext_ton -->|"RPC"| H1_chains
    H_library -->|"gRPC"| B_zetacored
    B_zetacored -->|"blocks/txs"| J_indexer
    I_jsonrpc -->|"queries"| B_zetacored
    J_indexer -->|"data"| I_jsonrpc
    L_e2e_runner --> M_localnet
    L_e2e_runner --> B_zetacored
    L_e2e_runner --> G_clientd
    L_e2e_runner --> I_jsonrpc

    %% Click Events
    click A_tendermint "https://github.com/zeta-chain/node/tree/develop/cmd/zetacored/"
    click B_zetacored "https://github.com/zeta-chain/node/tree/develop/cmd/zetacored/"
    click C_modules "https://github.com/zeta-chain/node/tree/develop/x/"
    click E_precompiles "https://github.com/zeta-chain/node/tree/develop/precompiles/"
    click D_proto "https://github.com/zeta-chain/node/tree/develop/proto/zetachain/zetacore/"
    click G_clientd "https://github.com/zeta-chain/node/tree/develop/cmd/zetaclientd/"
    click H_library "https://github.com/zeta-chain/node/tree/develop/zetaclient/"
    click H1_chains "https://github.com/zeta-chain/node/tree/develop/zetaclient/chains/bitcoin"
    click H1_chains "https://github.com/zeta-chain/node/tree/develop/zetaclient/chains/evm"
    click H1_chains "https://github.com/zeta-chain/node/tree/develop/zetaclient/chains/solana"
    click H1_chains "https://github.com/zeta-chain/node/tree/develop/zetaclient/chains/sui"
    click H1_chains "https://github.com/zeta-chain/node/tree/develop/zetaclient/chains/ton"
    click H2_tss "https://github.com/zeta-chain/node/tree/develop/zetaclient/tss/"
    click I_jsonrpc "https://github.com/zeta-chain/node/tree/develop/server/"
    click J_indexer "https://github.com/zeta-chain/node/tree/develop/server/"
    click K_cli_tools "https://github.com/zeta-chain/node/tree/develop/cmd/zetatool/"
    click K_cli_tools "https://github.com/zeta-chain/node/tree/develop/cmd/zetacore_utils/"
    click K_cli_tools "https://github.com/zeta-chain/node/tree/develop/cmd/zetae2e/"
    click L_e2e_runner "https://github.com/zeta-chain/node/tree/develop/e2e/"
    click M_localnet "https://github.com/zeta-chain/node/tree/develop/contrib/localnet/"
    click N_ts_sdk "https://github.com/zeta-chain/node/tree/develop/typescript/"

    %% Styles
    classDef core fill:#D6E8FF,stroke:#000,stroke-width:1px
    classDef client fill:#DFFFD6,stroke:#000,stroke-width:1px
    classDef external fill:#E8D6FF,stroke:#000,stroke-width:1px
    classDef api fill:#FFE8C6,stroke:#000,stroke-width:1px
    classDef tooling fill:#EDEDED,stroke:#000,stroke-width:1px
```
