# ton-blockchain/ton architecture

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

- Interactive diagram: https://gitdiagram.com/ton-blockchain/ton
- Repository: https://github.com/ton-blockchain/ton

## Overview

##### Project Type and Purpose
- This is the TON monorepo: a reference implementation of a full blockchain node and tooling suite, including the full-node/validator, lite-client, tonlib library, FunC compiler (tolk), Fift assembler, emulators, storage daemon, and various utilities.
- It’s a distributed peer-to-peer system with multiple protocols (ADNL, DHT, Overlay, RLDP) and components for consensus (Catchain), storage (TonDb, cell storage, archive DB), execution (TVM), and client APIs (lite-client, HTTP/RPC).

##### High-Level Components
a. Network Layer
- ADNL (abstract datagram layer)
- DHT (peer discovery)
- Overlay network & FEC broadcast
- RLDP / RLDP2 (reliable packet delivery)
- HTTP server (microhttpd) for RPC endpoints
b. Consensus Layer
- Catchain module (block proposal, confirmation)
c. Storage Layer
- TonDb (RocksDB-based persistent cell store)
- Archive-DB, State-DB, StaticFilesDB
- Optional external “storage-daemon” process (smart-contract storage provider)
d. Execution Layer
- TVM (virtual machine): crypto/vm modules, cell parsing, dispatch, stack, op-code tables
- FunC compiler (tolk) & Fift assembler libraries/tools
e. API & Client Layer
- lite-client (CLI & library)
- tonlib (C++ library + JSON wrapper)
- validator-engine-console & validator-engine
- third-party clients (Android, C++ examples)
f. Build & Deployment
- Assembly scripts (Linux/MacOS/AppImage/Android/WebAssembly)
- Docker manifests
- CMake build system

##### Relationships and Data Flows
- Peer Discovery: HTTP/UDP → ADNL ←→ DHT
- P2P Messaging: ADNL → Overlay → RLDP → Catchain messages
- Consensus: Catchain feeds validated blocks into Validator
- Storage: Validator writes blocks/cells into TonDb and ArchiveDB
- Execution: Validator invokes TVM to run smart contracts in blocks
- Client Queries: lite-client/tonlib → HTTP RPC → Validator → TVM/Storage → JSON response
- Smart-Contract Compilation: FunC (tolk) / Fift produce BOC code deployed on chain
- Optional Storage Daemon: storage-daemon ↔ Validator via internal API for off-chain storage

##### Architectural Patterns & Principles
- Layered modular architecture with clear protocol separation
- Actor-model concurrency (tdactor) for internal scheduling and I/O
- Event-driven P2P networking with reliable packet protocols
- Separation of persistent storage (TonDb) from in-memory execution (TVM)
- Extensibility via plugin-style smart contract languages (FunC, Fift, Wasm)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Network Layer
    subgraph "Network Layer"
        ADNL["ADNL"]:::network
        DHT["DHT"]:::network
        Overlay["Overlay & FEC"]:::network
        RLDP["RLDP"]:::network
        RLDP2["RLDP2"]:::network
        HTTP["HTTP Server"]:::network
    end

    %% Consensus Layer
    subgraph "Consensus Layer"
        Catchain["Catchain"]:::consensus
    end

    %% Storage Layer
    subgraph "Storage Layer"
        TonDb["TonDb (RocksDB)"]:::db
        ArchiveDB["Archive-DB"]:::db
        StateDB["State-DB"]:::db
        StaticFilesDB["StaticFilesDB"]:::db
        StorageDaemon["storage-daemon"]:::db
    end

    %% Execution Layer
    subgraph "Execution Layer"
        TVM["TVM (VM Core)"]:::exec
        CryptoPrims["Crypto Primitives"]:::exec
        Fift["Fift Assembler"]:::exec
        Func["FunC Compiler (tolk)"]:::exec
    end

    %% API & Client Layer
    subgraph "API & Client Layer"
        LiteClient["lite-client"]:::api
        Tonlib["tonlib"]:::api
        VEConsole["validator-engine-console"]:::api
        VEEngine["validator-engine"]:::api
        AndroidClient["Android App"]:::api
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        Assembly["Assembly Scripts"]:::build
        Docker["Docker Manifests"]:::build
        CMake["CMake Build System"]:::build
    end

    %% Data Flows
    HTTP -->|"HTTP/UDP"| ADNL
    ADNL <--> DHT
    ADNL --> Overlay
    Overlay --> RLDP
    RLDP --> RLDP2
    RLDP2 --> Catchain
    Catchain --> VEEngine
    VEEngine -->|writes blocks| TonDb
    VEEngine -->|writes blocks| ArchiveDB
    VEEngine -->|writes state| StateDB
    VEEngine -->|writes files| StaticFilesDB
    VEEngine -->|executes contracts| TVM
    TVM --> CryptoPrims
    LiteClient -->|RPC| HTTP
    Tonlib -->|RPC| HTTP
    HTTP --> VEEngine
    VEEngine --> TVM
    VEEngine --> TonDb
    TVM -->|uses| CryptoPrims
    Func -->|compiles contracts| VEEngine
    Fift -->|assembles contracts| VEEngine
    StorageDaemon <--> VEEngine
    AndroidClient -->|example calls| HTTP

    %% Click Events
    click ADNL "https://github.com/ton-blockchain/ton/tree/master/adnl/"
    click DHT "https://github.com/ton-blockchain/ton/tree/master/dht/"
    click Overlay "https://github.com/ton-blockchain/ton/tree/master/overlay/"
    click RLDP "https://github.com/ton-blockchain/ton/tree/master/rldp/"
    click RLDP2 "https://github.com/ton-blockchain/ton/tree/master/rldp2/"
    click HTTP "https://github.com/ton-blockchain/ton/blob/master/http/http-server.cpp"
    click Catchain "https://github.com/ton-blockchain/ton/tree/master/catchain/"
    click TonDb "https://github.com/ton-blockchain/ton/blob/master/crypto/vm/db/TonDb.cpp"
    click ArchiveDB "https://github.com/ton-blockchain/ton/blob/master/validator/db/archive-db.cpp"
    click StateDB "https://github.com/ton-blockchain/ton/blob/master/validator/db/statedb.cpp"
    click StaticFilesDB "https://github.com/ton-blockchain/ton/blob/master/validator/db/staticfilesdb.cpp"
    click StorageDaemon "https://github.com/ton-blockchain/ton/tree/master/storage/storage-daemon/"
    click TVM "https://github.com/ton-blockchain/ton/blob/master/crypto/vm/vm.cpp"
    click CryptoPrims "https://github.com/ton-blockchain/ton/tree/master/crypto/common/"
    click Fift "https://github.com/ton-blockchain/ton/tree/master/crypto/fift/"
    click Func "https://github.com/ton-blockchain/ton/tree/master/tolk/"
    click LiteClient "https://github.com/ton-blockchain/ton/tree/master/lite-client/"
    click Tonlib "https://github.com/ton-blockchain/ton/tree/master/tonlib/"
    click VEConsole "https://github.com/ton-blockchain/ton/tree/master/validator-engine-console/"
    click VEEngine "https://github.com/ton-blockchain/ton/tree/master/validator-engine/"
    click AndroidClient "https://github.com/ton-blockchain/ton/tree/master/example/android/"
    click Assembly "https://github.com/ton-blockchain/ton/tree/master/assembly/"
    click Docker "https://github.com/ton-blockchain/ton/tree/master/docker/"
    click CMake "https://github.com/ton-blockchain/ton/blob/master/CMakeLists.txt"

    %% Styles
    classDef network fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef consensus fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef db fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef exec fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef api fill:#e6ccff,stroke:#333,stroke-width:1px
    classDef build fill:#e0e0e0,stroke:#333,stroke-width:1px
```
