# nervosnetwork/ckb architecture

> Architecture diagram of the GitHub repository nervosnetwork/ckb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nervosnetwork/ckb
- Repository: https://github.com/nervosnetwork/ckb

## Overview

##### Main Components Identification

The system can be broken down into these major components:

a. Core Components:
- Chain Management (/chain)
- Network Layer (/network)
- Transaction Pool (/tx-pool)
- Consensus/Verification (/verification)
- Script Execution Engine (/script)
- Storage Layer (/store, /db)

b. Supporting Components:
- RPC Interface (/rpc)
- Indexer Services (/util/indexer, /util/rich-indexer)
- Mining Interface (/miner)
- Configuration Management (/util/app-config)

##### Key Relationships to Highlight

a. Data Flow:
- Network → Transaction Pool → Chain
- Network → Block Verification → Chain
- Chain → Storage
- Mining Service → Transaction Pool → Chain

b. Control Flow:
- RPC Service → Core Services
- Chain Service → Verification Service
- Script Engine → Verification Service

##### Specific Implementation Details

- Rectangles: Core services
- Hexagons: External interfaces

##### Important Architectural Patterns

- The RISC-V based CKB-VM for script execution
- The improved Nakamoto consensus implementation
- The cell model for state storage
- The block verification pipeline
- The transaction pool management system

##### Additional Elements

Annotations for:
- Version compatibility (CKB 2021/2023 hardfork support)
- External dependencies
- Configuration points
- Monitoring/metrics collection points

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Interface Layer
    subgraph External
        RPC[RPC Interface]
        P2P[P2P Network Protocol]
        Mining[Mining Interface]
    end

    %% Core Services Layer
    subgraph CoreServices
        ChainSvc[Chain Service]
        NetworkSvc[Network Service]
        TxPool[Transaction Pool]
        VerifSvc[Verification Service]
        MiningSvc[Mining Service]
    end

    %% Core Logic Layer
    subgraph CoreLogic
        BlockProc[Block Processing]
        TxProc[Transaction Processing]
        ScriptVerif[Script Verification]
        Consensus[Consensus Rules]
        StateMan[State Management]
        BlockAssem[Block Assembly]
    end

    %% Storage Layer
    subgraph Storage
        DB[(Database)]
        StateStore[(State Storage)]
        BlockStore[(Block Storage)]
        TxStore[(Transaction Storage)]
    end

    %% Supporting Services
    subgraph Support
        Config[Configuration]
        Indexer[Indexer Service]
        RichIndexer[Rich Indexer]
        ScriptEngine[Script Engine]
    end

    %% Relationships
    RPC --> ChainSvc
    RPC --> TxPool
    P2P --> NetworkSvc
    Mining --> MiningSvc

    NetworkSvc --> TxPool
    NetworkSvc --> BlockProc
    TxPool --> ChainSvc
    BlockProc --> ChainSvc
    
    ChainSvc --> VerifSvc
    VerifSvc --> ScriptVerif
    ScriptVerif --> ScriptEngine
    
    MiningSvc --> TxPool
    TxPool --> BlockAssem
    BlockAssem --> ChainSvc
    
    ChainSvc --> StateMan
    StateMan --> StateStore
    ChainSvc --> BlockStore
    TxPool --> TxStore
    
    Config --> ChainSvc
    Config --> NetworkSvc
    Indexer --> ChainSvc
    RichIndexer --> ChainSvc

    %% Click Events
    click ChainSvc "https://github.com/nervosnetwork/ckb/blob/develop/chain/src/chain_service.rs"
    click NetworkSvc "https://github.com/nervosnetwork/ckb/blob/develop/network/src/network.rs"
    click TxPool "https://github.com/nervosnetwork/ckb/blob/develop/tx-pool/src/pool.rs"
    click VerifSvc "https://github.com/nervosnetwork/ckb/blob/develop/verification/src/lib.rs"
    click ScriptEngine "https://github.com/nervosnetwork/ckb/blob/develop/script/src/lib.rs"
    click DB "https://github.com/nervosnetwork/ckb/blob/develop/db/src/db.rs"
    click StateStore "https://github.com/nervosnetwork/ckb/blob/develop/store/src/store.rs"
    click RPC "https://github.com/nervosnetwork/ckb/blob/develop/rpc/src/server.rs"
    click Indexer "https://github.com/nervosnetwork/ckb/blob/develop/util/indexer/src/indexer.rs"
    click RichIndexer "https://github.com/nervosnetwork/ckb/blob/develop/util/rich-indexer/src/service.rs"
    click Mining "https://github.com/nervosnetwork/ckb/blob/develop/miner/src/miner.rs"
    click Config "https://github.com/nervosnetwork/ckb/blob/develop/util/app-config/src/app_config.rs"
    click BlockProc "https://github.com/nervosnetwork/ckb/blob/develop/verification/src/block_verifier.rs"
    click TxProc "https://github.com/nervosnetwork/ckb/blob/develop/verification/src/transaction_verifier.rs"
    click Consensus "https://github.com/nervosnetwork/ckb/blob/develop/spec/src/consensus.rs"
    click P2P "https://github.com/nervosnetwork/ckb/blob/develop/network/src/protocols/mod.rs"
    click BlockAssem "https://github.com/nervosnetwork/ckb/blob/develop/tx-pool/src/block_assembler/mod.rs"

    %% Styling
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef logic fill:#dfd,stroke:#333,stroke-width:2px
    classDef storage fill:#fdd,stroke:#333,stroke-width:2px
    classDef support fill:#dff,stroke:#333,stroke-width:2px

    class RPC,P2P,Mining external
    class ChainSvc,NetworkSvc,TxPool,VerifSvc,MiningSvc core
    class BlockProc,TxProc,ScriptVerif,Consensus,StateMan,BlockAssem logic
    class DB,StateStore,BlockStore,TxStore storage
    class Config,Indexer,RichIndexer,ScriptEngine support
```
