# informalsystems/tendermint-rs architecture

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

- Interactive diagram: https://gitdiagram.com/informalsystems/tendermint-rs
- Repository: https://github.com/informalsystems/tendermint-rs

## Overview

##### Main components
- Core Libraries: At the heart are the crates providing the core data structures and serialization – for example, the "tendermint" crate (which handles Tendermint’s blockchain data structures, block headers, signatures, etc.) and "tendermint-proto" (dealing with protobuf generated types and wire-level interaction).
- ABCI Layer: The "abci" crate forms a low-level framework for building ABCI applications (used by blockchain applications to interface with the Tendermint consensus engine).
- Light Client Functionality: Note the “light-client” crate for verifying signed headers and tracking validator set changes, the "light-client-detector" for detecting attacks, and related CLI/JS wrappers ("light-client-cli" and "light-client-js").
- RPC and P2P: The "tendermint-rpc" crate provides client functionality for Tendermint’s RPC and “p2p” offers peer connectivity (using the secret connection protocol).
- Configuration and Testing: There are supplementary crates such as "config", "test", and "testgen" supporting configuration and property-based testing.
- Tools and Docker: Also, tools for generating test data, building images, and even a proto-compiler exist under the “tools” directory.
- Documentation and Specifications: The "docs" directory (with ADRs, specifications, and TLA+ models) shows that the system is grounded in formal specifications, and there’s an emphasis on adhering to a rigorous design.

##### Relationships and interactions
- The RPC client ("tendermint-rpc") interacts with external Tendermint nodes (written in Go) and uses the “proto” crate for protobuf serialization.
- The light client components verify block headers and validator sets by consuming data structures from the core "tendermint" library and interacting with the RPC and P2P layers.
- The ABCI library is used to build blockchain applications that communicate with Tendermint for consensus.
- The “p2p” crate handles secure network communication (via secret connections), which might feed data to the light client or RPC components.
- Tools and testing utilities (found in "tools", "test", and "testgen") connect to these libraries to simulate, test, and validate consensus and blockchain behavior based on TLA+ specifications.

##### Architectural patterns and design principles
- Modular design through distinct crates: each library is responsible for a well-defined domain (e.g., core data structures, ABCI interfacing, light client verification, network communication).
- Protocol separation: There are clear interfaces between the RPC, P2P, and application layers. The use of a dedicated "proto" crate reinforces separation between protocol representation and business logic.
- Layering: For example, the light client uses core blockchain structures, interacts with the RPC layer for network data, and employs consensus verification that aligns with the TLA+ protocols.
- Testability: A robust suite of tests (unit tests, model-based tests in the "light-client" and "rpc" directories, etc.) is an integral part of the design.
- Extensibility: With multiple language interfaces (Rust libraries, a CLI, and even a JavaScript (or WASM) interface), the architecture is designed to be accessed from different runtimes and contexts.

##### Elements
– RPC <-> Tendermint Nodes (external system)
– P2P feeds into the light client for header verification
– The CLI and JS interfaces function as wrappers for light client capabilities
- Also depicting the role of configuration and testing tools, positioned in a secondary layer outside the runtime system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Level 1: External System
    EC["External Tendermint\nCore (Go)"]:::external

    %% Level 2: RPC & P2P
    subgraph "RPC & P2P"
        R["rpc"]:::net
        P2P["p2p"]:::net
    end

    %% Level 3: Light Client Components
    subgraph "Light Client Components"
        LC["light-client"]:::lib
        LCV["light-client-verifier"]:::lib
        LCD["light-client-detector"]:::lib
        LCLI["light-client-cli"]:::lib
        LCJS["light-client-js"]:::lib
    end

    %% Level 4: Core Libraries
    subgraph "Core Libraries"
        T["tendermint"]:::lib
        PROTO["proto"]:::lib
    end

    %% Level 5: ABCI Application Framework
    subgraph "ABCI Application Framework"
        A["abci"]:::lib
    end

    %% Level 6: Support & Tools
    subgraph "Support & Tools"
        CFG["config"]:::tool
        TST["test"]:::tool
        TOLS["tools"]:::tool
        DOCS["docs"]:::doc
    end

    %% Connections between External system and RPC layer
    EC -->|"RPC_request"| R
    R -->|"RPC_response"| EC

    %% RPC & P2P feed into Light Client components
    R -->|"provides_headers"| LC
    P2P -->|"feeds_network"| LC

    %% Internal Light Client interactions
    LC -->|"verifies"| LCV
    LC -->|"detects"| LCD
    LC -->|"CLI_wrapper"| LCLI
    LC -->|"JS_interface"| LCJS

    %% Core Library usage across components
    LC -->|"uses"| T
    LC -->|"serialization"| PROTO
    R -->|"serialization"| PROTO
    A -->|"interfaces"| T
    A ---|"utilizes"| T

    %% Support & Tools connecting to core components
    TOLS -.-> LC
    TST -.-> LC
    TST -.-> R
    CFG -.-> R
    DOCS -.-> T
    DOCS -.-> A

    %% Click Event Mapping
    click T "https://github.com/informalsystems/tendermint-rs/tree/main/tendermint/"
    click PROTO "https://github.com/informalsystems/tendermint-rs/tree/main/proto/"
    click A "https://github.com/informalsystems/tendermint-rs/tree/main/abci/"
    click LC "https://github.com/informalsystems/tendermint-rs/tree/main/light-client/"
    click LCD "https://github.com/informalsystems/tendermint-rs/tree/main/light-client-detector/"
    click LCLI "https://github.com/informalsystems/tendermint-rs/tree/main/light-client-cli/"
    click LCJS "https://github.com/informalsystems/tendermint-rs/tree/main/light-client-js/"
    click LCV "https://github.com/informalsystems/tendermint-rs/tree/main/light-client-verifier/"
    click R "https://github.com/informalsystems/tendermint-rs/tree/main/rpc/"
    click P2P "https://github.com/informalsystems/tendermint-rs/tree/main/p2p/"
    click CFG "https://github.com/informalsystems/tendermint-rs/tree/main/config/"
    click TST "https://github.com/informalsystems/tendermint-rs/tree/main/test/"
    click TOLS "https://github.com/informalsystems/tendermint-rs/tree/main/tools/"
    click DOCS "https://github.com/informalsystems/tendermint-rs/tree/main/docs/"

    %% Styles Definitions
    classDef lib fill:#A9D0F5,stroke:#084B8A,stroke-width:2px;
    classDef net fill:#F5BCA9,stroke:#8A0808,stroke-width:2px;
    classDef tool fill:#F3E2A9,stroke:#B18904,stroke-width:2px;
    classDef doc fill:#82FA58,stroke:#2E8B57,stroke-width:2px;
    classDef external fill:#F6CEC5,stroke:#F70D1A,stroke-width:2px;
```
