# bnb-chain/bsc architecture

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

- Interactive diagram: https://gitdiagram.com/bnb-chain/bsc
- Repository: https://github.com/bnb-chain/bsc

## Overview

This project is a full-featured blockchain client for BNB Smart Chain—a fork of go-ethereum that remains EVM compatible while adding consensus modifications and staking-based governance (Proof of Staked Authority). In other words, it is not only an Ethereum client but also a full-stack blockchain system with network, state, consensus, smart contract execution, and RPC interfaces, along with tools for developer interaction (e.g., abigen, evm, bootnode).

##### Main Components
- Blockchain Node Client: A central “geth” component serving as the entry point into the network, responsible for node management, syncing, and configuration.
- Consensus Engine: In this case, the modified consensus (dubbed “Parlia”) that governs block production by a limited set of validators who are elected via staking. Represent the consensus module and include flows showing validator selection, block production, slashing, and finality mechanisms.
- Peer-to-Peer (P2P) Networking: A detailed module for node discovery (p2p packages, enode, discovery protocols) including bootnode, DNS-based discovery, and encrypted communications.
- Ethereum Virtual Machine (EVM): The sandbox responsible for executing smart contracts. This includes sections for opcode handling, state transition, and integration with precompiled contracts.
- Storage and State Management: Core components handling blockchain state, RLP encoding/decoding (rlp packages), trie and Merkle tree structures (trie, triedb, core/rawdb) for account state, receipts, and historical data.
- API and RPC Interfaces: Components exposing JSON-RPC endpoints over HTTP, WebSocket, and IPC; including modules for eth, net, web3, and node management.
- Auxiliary Tools and Utilities: Executables like clef (the standalone signing tool), abigen (code generator for contract bindings), evm (EVM debug/testing tool), and other helper modules (rlpdump, devp2p).
- Consensus-Related System Contracts: Modules that interact with on-chain governance and staking mechanisms to support validator rotation, slashing, and reward distribution.
- Cryptography: Libraries for hashing (blake2b, keccak), digital signature algorithms (secp256k1, bn256), and key management which are crucial for transaction signing, block integrity, and network security.

##### Relationships and Data Flow
- How the client receives external network messages via the P2P networking layer, which then feeds into the consensus engine.
- Interaction between cryptography libraries and core state/transaction modules (e.g., signing/verifying transactions).

##### Architectural Patterns & Design Principles
- Modular separation: Each package (such as consensus, core, crypto, p2p, and vm) is a self-contained module with defined interfaces. Represent these modules in distinct areas.
- Layered architecture: From network ingestion (p2p/discovery) to state processing (blockchain and trie databases), then EVM execution, and finally presentation via APIs.
- Extensibility and reusability: The presence of developer utilities (clef, abigen, evm, bootnode) shows that the system is built for flexibility and plugin-like expansion.
- Robust validation and state verification: Emphasize components for error handling (core/errors, consensus/errors) and testing (fuzzers, testdata) demonstrating a commitment to state integrity.

##### Technologies & Frameworks
- Written in Go with heavy leveraging of Go’s package structure and build tools (Makefile, Dockerfiles).
- Uses RLP encoding for data serialization, trie structures for state (Merkle Patricia Trie), and integrates with blockchain-specific domains like Ethereum’s solidity for smart contracts.
- Incorporates external APIs (e.g., JSON-RPC, web3) making it interoperable with Ethereum tooling.

##### Overall Detailing Advice
- Be detailed: label every main component and show interconnections.
- Clearly distinguish between internal processes (e.g., state update, consensus rounds) and external interfaces (e.g., RPC, P2P connections).
- Pointers to where additional documentation (e.g., CLI options, system contracts documentation) fits in the overall architecture context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interfaces"
        apiRpc["API & RPC Interfaces"]:::apiStyle
        auxTools["Auxiliary Tools & Utilities"]:::auxStyle
    end

    subgraph "Core Node"
        bcClient["Blockchain Node Client"]:::nodeStyle
    end

    subgraph "Network & Consensus"
        p2p["P2P Networking"]:::netStyle
        consensusEngine["Consensus Engine (Parlia)"]:::consensusStyle
        systemContracts["Consensus-Related System Contracts"]:::contractsStyle
    end

    subgraph "Execution & State"
        evm["EVM & Smart Contract Execution"]:::evmStyle
        subgraph "Storage & State Management"
            storageRawdb["Storage (RawDB)"]:::storageStyle
            storageState["Storage (State)"]:::storageStyle
            trie["Trie & Merkle Trees"]:::storageStyle
        end
        crypto["Cryptography"]:::cryptoStyle
    end

    %% Connections
    apiRpc -->|"txn_input"| bcClient
    auxTools -->|"dev_interaction"| bcClient
    bcClient -->|"node_management"| consensusEngine
    bcClient -->|"tx_execution"| evm
    bcClient -->|"network_messages"| p2p
    p2p -->|"peer_discovery"| consensusEngine
    consensusEngine -->|"state_updates"| storageRawdb
    consensusEngine -->|"state_updates"| storageState
    consensusEngine -->|"state_updates"| trie
    consensusEngine -->|"validator_set"| systemContracts
    evm -->|"state_read_write"| storageRawdb
    evm -->|"state_read_write"| storageState
    evm -->|"state_read_write"| trie
    evm -->|"uses_crypto"| crypto

    %% Styles
    classDef apiStyle fill:#f4e542,stroke:#333,stroke-width:2px;
    classDef auxStyle fill:#ff9f1c,stroke:#333,stroke-width:2px;
    classDef nodeStyle fill:#2ec4b6,stroke:#333,stroke-width:2px;
    classDef netStyle fill:#e71d36,stroke:#333,stroke-width:2px;
    classDef consensusStyle fill:#38618c,stroke:#333,stroke-width:2px;
    classDef contractsStyle fill:#8ac926,stroke:#333,stroke-width:2px;
    classDef evmStyle fill:#a8dadc,stroke:#333,stroke-width:2px;
    classDef storageStyle fill:#457b9d,stroke:#333,stroke-width:2px;
    classDef cryptoStyle fill:#6a4c93,stroke:#333,stroke-width:2px;

    %% Click Events
    click bcClient "https://github.com/bnb-chain/bsc/tree/master/cmd/geth"
    click consensusEngine "https://github.com/bnb-chain/bsc/tree/master/consensus/parlia"
    click p2p "https://github.com/bnb-chain/bsc/tree/master/p2p"
    click evm "https://github.com/bnb-chain/bsc/tree/master/core/vm"
    click storageRawdb "https://github.com/bnb-chain/bsc/tree/master/core/rawdb"
    click storageState "https://github.com/bnb-chain/bsc/tree/master/core/state"
    click trie "https://github.com/bnb-chain/bsc/tree/master/trie"
    click apiRpc "https://github.com/bnb-chain/bsc/tree/master/eth"
    click apiRpc "https://github.com/bnb-chain/bsc/tree/master/rpc"
    click apiRpc "https://github.com/bnb-chain/bsc/tree/master/node"
    click auxTools "https://github.com/bnb-chain/bsc/tree/master/cmd/clef"
    click auxTools "https://github.com/bnb-chain/bsc/tree/master/cmd/abigen"
    click auxTools "https://github.com/bnb-chain/bsc/tree/master/cmd/evm"
    click auxTools "https://github.com/bnb-chain/bsc/tree/master/cmd/bootnode"
    click systemContracts "https://github.com/bnb-chain/bsc/tree/master/core/systemcontracts"
    click crypto "https://github.com/bnb-chain/bsc/tree/master/crypto"
```
