# kaiachain/kaia architecture

> Architecture diagram of the GitHub repository kaiachain/kaia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaiachain/kaia
- Repository: https://github.com/kaiachain/kaia

## Overview

Kaia is a Go implementation of a blockchain, with node binaries that participate in consensus and expose network access. The principal user workflow is an application sending requests through an Endpoint Node’s RPC gateway; node services handle network communication and the worker executes and commits blockchain work against persistent state. Consensus and data-sync features provide distinct supporting branches, alongside developer-facing contract bindings and Service Chain bridging. Edges are limited to relationships shown in the README or source index; unsampled implementation details are not inferred.

Main entry points: [`work/worker.go`](https://github.com/kaiachain/kaia/blob/dev/work/worker.go) (Block Worker), [`blockchain/blockchain.go`](https://github.com/kaiachain/kaia/blob/dev/blockchain/blockchain.go) (Blockchain), [`consensus/istanbul/backend/engine.go`](https://github.com/kaiachain/kaia/blob/dev/consensus/istanbul/backend/engine.go) (Istanbul Backend), [`client/kaia_client.go`](https://github.com/kaiachain/kaia/blob/dev/client/kaia_client.go) (Kaia Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Node Access"]
  node_client["Kaia Client<br/>[kaia_client.go]"]
  node_rpc["RPC Server<br/>[server.go]"]
  node_node["Node Service<br/>[service.go]"]
  node_p2p["P2P Server<br/>[server.go]"]
  node_discovery["Peer Discovery<br/>[table_storage.go]"]
end

subgraph group_chain["Chain Runtime"]
  node_worker["Block Worker<br/>[worker.go]"]
  node_blockchain["Blockchain<br/>[blockchain.go]"]
  node_vm["Virtual Machine<br/>[evm.go]"]
  node_blob["Blob Storage<br/>[blob_storage.go]"]
end

subgraph group_consensus["Consensus"]
  node_engine["Engine Selector<br/>[engine.go]"]
  node_istanbul["Istanbul Backend<br/>[engine.go]"]
  node_istanbulcore["Istanbul Core<br/>[handler.go]"]
end

subgraph group_data["Persistence and Sync"]
  node_database[("Database Manager<br/>[db_manager.go]")]
  node_state[("State Database<br/>[database.go]")]
  node_dbsyncer["DB Syncer<br/>[query_engine.go]"]
  node_traces["Trace Repository"]
end

subgraph group_extensions["Extensions"]
  node_abigen["Binding Generator<br/>[main.go]"]
  node_contracts["Contract Bindings"]
  node_bridge["Service Chain Bridge<br/>[bridge_manager.go]"]
  node_vrank["Validator Ranking<br/>[handler.go]"]
end

node_application(("Application"))

node_application -->|"sends RPC"| node_rpc
node_rpc -.->|"serves requests"| node_node
node_node -->|"starts networking"| node_p2p
node_p2p -->|"uses discovery"| node_discovery
node_client -->|"calls RPC"| node_rpc
node_client -->|"uses types"| node_blockchain
node_client -->|"uses auction"| node_istanbul
node_worker -->|"uses chain"| node_blockchain
node_worker -->|"uses VM"| node_vm
node_worker -->|"uses state"| node_state
node_worker -->|"uses storage"| node_database
node_worker -->|"uses consensus"| node_istanbul
node_engine -->|"creates backend"| node_istanbul
node_istanbul -->|"starts core"| node_istanbulcore
node_dbsyncer -->|"writes rows"| node_database
node_traces -->|"uses chain data"| node_blockchain
node_abigen -->|"generates bindings"| node_contracts
node_bridge -->|"uses storage"| node_database
node_bridge -->|"uses bridge binding"| node_contracts
node_vrank -->|"uses consensus messages"| node_istanbulcore
node_blockchain -.->|"supports blob sidecars"| node_blob

click node_client "https://github.com/kaiachain/kaia/blob/dev/client/kaia_client.go"
click node_rpc "https://github.com/kaiachain/kaia/blob/dev/networks/rpc/server.go"
click node_node "https://github.com/kaiachain/kaia/blob/dev/node/service.go"
click node_p2p "https://github.com/kaiachain/kaia/blob/dev/networks/p2p/server.go"
click node_discovery "https://github.com/kaiachain/kaia/blob/dev/networks/p2p/discover/table_storage.go"
click node_worker "https://github.com/kaiachain/kaia/blob/dev/work/worker.go"
click node_blockchain "https://github.com/kaiachain/kaia/blob/dev/blockchain/blockchain.go"
click node_vm "https://github.com/kaiachain/kaia/blob/dev/blockchain/vm/evm.go"
click node_blob "https://github.com/kaiachain/kaia/blob/dev/blockchain/blob_storage.go"
click node_engine "https://github.com/kaiachain/kaia/blob/dev/consensus/engine/engine.go"
click node_istanbul "https://github.com/kaiachain/kaia/blob/dev/consensus/istanbul/backend/engine.go"
click node_istanbulcore "https://github.com/kaiachain/kaia/blob/dev/consensus/istanbul/core/handler.go"
click node_database "https://github.com/kaiachain/kaia/blob/dev/storage/database/db_manager.go"
click node_state "https://github.com/kaiachain/kaia/blob/dev/storage/statedb/database.go"
click node_dbsyncer "https://github.com/kaiachain/kaia/blob/dev/datasync/dbsyncer/query_engine.go"
click node_traces "https://github.com/kaiachain/kaia/blob/dev/datasync/chaindatafetcher/kas/repository_traces.go"
click node_abigen "https://github.com/kaiachain/kaia/blob/dev/cmd/abigen/main.go"
click node_contracts "https://github.com/kaiachain/kaia/blob/dev/contracts/bindings/kip247/GaslessSwapRouter.go"
click node_bridge "https://github.com/kaiachain/kaia/blob/dev/node/sc/bridge_manager.go"
click node_vrank "https://github.com/kaiachain/kaia/blob/dev/kaiax/vrank/impl/handler.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_rpc,node_node,node_p2p,node_discovery toneBlue
class node_worker,node_blockchain,node_vm,node_blob toneAmber
class node_engine,node_istanbul,node_istanbulcore toneMint
class node_database,node_state,node_dbsyncer,node_traces toneRose
class node_abigen,node_contracts,node_bridge,node_vrank,node_application toneIndigo
```

## Components

### Node Access

- [Kaia Client](https://github.com/kaiachain/kaia/blob/dev/client/kaia_client.go): `client/kaia_client.go`
- [RPC Server](https://github.com/kaiachain/kaia/blob/dev/networks/rpc/server.go): `networks/rpc/server.go`
- [Node Service](https://github.com/kaiachain/kaia/blob/dev/node/service.go): `node/service.go`
- [P2P Server](https://github.com/kaiachain/kaia/blob/dev/networks/p2p/server.go): `networks/p2p/server.go`
- [Peer Discovery](https://github.com/kaiachain/kaia/blob/dev/networks/p2p/discover/table_storage.go): `networks/p2p/discover/table_storage.go`

### Chain Runtime

- [Block Worker](https://github.com/kaiachain/kaia/blob/dev/work/worker.go): `work/worker.go`
- [Blockchain](https://github.com/kaiachain/kaia/blob/dev/blockchain/blockchain.go): `blockchain/blockchain.go`
- [Virtual Machine](https://github.com/kaiachain/kaia/blob/dev/blockchain/vm/evm.go): `blockchain/vm/evm.go`
- [Blob Storage](https://github.com/kaiachain/kaia/blob/dev/blockchain/blob_storage.go): `blockchain/blob_storage.go`

### Consensus

- [Engine Selector](https://github.com/kaiachain/kaia/blob/dev/consensus/engine/engine.go): `consensus/engine/engine.go`
- [Istanbul Backend](https://github.com/kaiachain/kaia/blob/dev/consensus/istanbul/backend/engine.go): `consensus/istanbul/backend/engine.go`
- [Istanbul Core](https://github.com/kaiachain/kaia/blob/dev/consensus/istanbul/core/handler.go): `consensus/istanbul/core/handler.go`

### Persistence and Sync

- [Database Manager](https://github.com/kaiachain/kaia/blob/dev/storage/database/db_manager.go): `storage/database/db_manager.go`
- [State Database](https://github.com/kaiachain/kaia/blob/dev/storage/statedb/database.go): `storage/statedb/database.go`
- [DB Syncer](https://github.com/kaiachain/kaia/blob/dev/datasync/dbsyncer/query_engine.go): `datasync/dbsyncer/query_engine.go`
- [Trace Repository](https://github.com/kaiachain/kaia/blob/dev/datasync/chaindatafetcher/kas/repository_traces.go): `datasync/chaindatafetcher/kas/repository_traces.go`

### Extensions

- [Binding Generator](https://github.com/kaiachain/kaia/blob/dev/cmd/abigen/main.go): `cmd/abigen/main.go`
- [Contract Bindings](https://github.com/kaiachain/kaia/blob/dev/contracts/bindings/kip247/GaslessSwapRouter.go): `contracts/bindings/kip247/GaslessSwapRouter.go`
- [Service Chain Bridge](https://github.com/kaiachain/kaia/blob/dev/node/sc/bridge_manager.go): `node/sc/bridge_manager.go`
- [Validator Ranking](https://github.com/kaiachain/kaia/blob/dev/kaiax/vrank/impl/handler.go): `kaiax/vrank/impl/handler.go`

### Other components

- **Application**

## Connections

- Application → RPC Server: sends RPC
- RPC Server → Node Service: serves requests
- Node Service → P2P Server: starts networking (evidence: `node/service.go`)
- P2P Server → Peer Discovery: uses discovery (evidence: `networks/p2p/server.go`)
- Kaia Client → RPC Server: calls RPC (evidence: `client/kaia_client.go`)
- Kaia Client → Blockchain: uses types (evidence: `client/kaia_client.go`)
- Kaia Client → Istanbul Backend: uses auction (evidence: `client/kaia_client.go`)
- Block Worker → Blockchain: uses chain (evidence: `work/worker.go`)
- Block Worker → Virtual Machine: uses VM (evidence: `work/worker.go`)
- Block Worker → State Database: uses state (evidence: `work/worker.go`)
- Block Worker → Database Manager: uses storage (evidence: `work/worker.go`)
- Block Worker → Istanbul Backend: uses consensus (evidence: `work/worker.go`)
- Engine Selector → Istanbul Backend: creates backend (evidence: `consensus/engine/engine.go`)
- Istanbul Backend → Istanbul Core: starts core (evidence: `consensus/istanbul/backend/engine.go`)
- DB Syncer → Database Manager: writes rows (evidence: `datasync/dbsyncer/query_engine.go`)
- Trace Repository → Blockchain: uses chain data (evidence: `datasync/chaindatafetcher/kas/repository_traces.go`)
- Binding Generator → Contract Bindings: generates bindings (evidence: `cmd/abigen/main.go`)
- Service Chain Bridge → Database Manager: uses storage (evidence: `node/sc/bridge_manager.go`)
- Service Chain Bridge → Contract Bindings: uses bridge binding (evidence: `node/sc/bridge_manager.go`)
- Validator Ranking → Istanbul Core: uses consensus messages (evidence: `kaiax/vrank/impl/handler.go`)
- Blockchain → Blob Storage: supports blob sidecars
