# tronprotocol/java-tron architecture

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

- Interactive diagram: https://gitdiagram.com/tronprotocol/java-tron
- Repository: https://github.com/tronprotocol/java-tron

## Overview

##### Project Type and Purpose
- This is a blockchain full‑node application (“java‑tron”) implementing the TRON Protocol in Java.
- It comprises a distributed P2P network layer, consensus engines (DPoS/PBFT), a smart‑contract VM (TVM), state storage, API layers (HTTP/gRPC), plug‑in actuators, and utilities.

##### High‑Level Module Breakdown (from file tree)
- actuator: Smart‑contract transaction executors (ActuatorFactory, AbstractActuator, native contracts).
- chainbase / core storage modules: On‑chain data persistence using LevelDB/RocksDB; capsules + stores manage blocks, accounts, contracts.
- common: Shared utilities (args parsing, caching, logging, metrics, zksnark wrappers).
- consensus: DPoS and PBFT engines, message definitions, block handling.
- crypto: All cryptographic primitives (EC keys, hashes, zksnark operations).
- framework: Application bootstrap (ApplicationFactory, ServiceContainer), network handlers (P2P, message processing), RPC/HTTP services, CLI.
- plugins: CLI tools / database utilities (DbConvert, ArchiveManifest).
- protocol: Protobuf definitions for wire formats (P2P, API, contracts).
- example: Sample custom actuator.
- docker / scripts / docs: Deployment tooling and documentation.

##### Key Interactions
- P2P Network Layer (framework/src/main/java/org/tron/core/net)
– Peers exchange messages (blocks, transactions) over TCP/UDP.
– MessageHandler routes to either consensus or transaction pool.
- Consensus Engines (consensus module & framework core consensus service)
– Receive new transactions/blocks → run DPoS/PBFT algorithms → propose & commit blocks.
- Transaction Execution (actuator + VM submodules)
– Consensus‑approved blocks feed into actuators which interpret transactions (Transfer, Freeze, Smart Contract deploy/invoke) via the TVM.
– Actuators update state in chainbase.
- State Storage (chainbase & framework accountstate/Trie)
– Blocks, accounts, contracts, receipts persisted in on‑disk DB.
– TrieService maintains Merkle Patricia tries for fast lookup.
- API Layer (framework/src/main/java/org/tron/core/services & /common/application)
– HTTP Servlets and gRPC stubs expose JSON‑RPC & REST endpoints for clients.
– Internally they query chainbase, submit transactions into P2P pool.
- Application Bootstrap (framework ApplicationFactory)
– Loads configuration, instantiates services (network, DB, consensus, API), wires dependencies.
– Exposes FullNode / SolidityNode entrypoints.
- External Services & Tools
– Docker container orchestrates ports (8090 HTTP, 18888 P2P, 50051 gRPC).
– start.sh / docker.sh simplify builds & launches.
– Prometheus metrics & logback for observability.

##### Architectural Patterns & Principles
- Modular microservices within a monorepo: each Gradle subproject is loosely coupled.
- Factory patterns for actuators, consensus, message creation.
- Event‑driven messaging in P2P and backup subsystems.
- Plugin‑style extensibility (custom actuators, database tools).
- Separation of concerns: network / consensus / execution / storage / API layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        Clients("External Clients (CLI / Wallet)"):::external
    end

    subgraph "API Layer"
        JSONRPC("HTTP JSON-RPC"):::api
        gRPC("gRPC"):::api
        CLItools("CLI Tools"):::api
    end

    subgraph "Application Core"
        AppFactory("ApplicationFactory / ServiceContainer"):::core
    end

    subgraph "Network Layer"
        P2P("P2P Network Layer"):::network
        MsgHandler("MessageHandler"):::network
    end

    subgraph "Consensus Layer"
        DPoS("DPoS Engine"):::cons
        PBFT("PBFT Engine"):::cons
        ConsService("ConsensusService"):::cons
    end

    subgraph "Execution Layer"
        TxnPool("Transaction Pool / PendingManager"):::exec
        TVM("TVM / Actuator Layer"):::exec
        ActFactory("ActuatorFactory"):::exec
    end

    subgraph "Storage Layer"
        ChainBase("ChainBase (BlockStore, TxStore)"):::storage
        TrieSvc("TrieService"):::storage
    end

    subgraph "Crypto & Protocol"
        Crypto("Crypto Library"):::infra
        Proto("Protocol Buffers"):::infra
    end

    subgraph "Config & Deployment"
        Docker("Docker & Scripts"):::infra
        StartSh("start.sh"):::infra
    end

    Clients -->|SubmitTx| JSONRPC
    Clients -->|SubmitTx| gRPC
    Clients -->|CLI Commands| CLItools

    JSONRPC -->|Invoke| AppFactory
    gRPC -->|Invoke| AppFactory
    CLItools -->|Invoke| AppFactory

    AppFactory --> P2P
    AppFactory --> TxnPool
    AppFactory --> ConsService
    AppFactory --> JSONRPC
    AppFactory --> gRPC

    P2P --> MsgHandler
    MsgHandler -->|"TransactionMessage"| TxnPool
    MsgHandler -->|"BlockMessage"| ConsService

    TxnPool -->|ProposeTx| ConsService
    ConsService --> DPoS
    ConsService --> PBFT
    DPoS --> ConsService
    PBFT --> ConsService

    ConsService -->|"NewBlock"| TVM
    TVM --> ActFactory
    TVM --> ChainBase
    ChainBase --> TrieSvc

    JSONRPC -->|GetAccount / GetBlock| ChainBase
    gRPC -->|GetAccount / GetBlock| ChainBase
    CLItools -->|DB Utilities| ChainBase

    AppFactory --> Crypto
    P2P --> Proto
    JSONRPC --> Proto
    gRPC --> Proto

    AppFactory -.->|ConfiguredBy| Docker
    AppFactory -.->|ConfiguredBy| StartSh

    classDef external fill:#bddbfa,stroke:#000,stroke-width:1px
    classDef api fill:#dcd0ff,stroke:#000,stroke-width:1px
    classDef core fill:#cdeac0,stroke:#000,stroke-width:1px
    classDef network fill:#ade8f4,stroke:#000,stroke-width:1px
    classDef cons fill:#b0f2b6,stroke:#000,stroke-width:1px
    classDef exec fill:#ffcc99,stroke:#000,stroke-width:1px
    classDef storage fill:#fff5ba,stroke:#000,stroke-width:1px
    classDef infra fill:#f0f0f0,stroke:#000,stroke-width:1px

    click AppFactory "https://github.com/tronprotocol/java-tron/blob/develop/framework/src/main/java/org/tron/common/application/ApplicationFactory.java"
    click P2P "https://github.com/tronprotocol/java-tron/tree/develop/framework/src/main/java/org/tron/core/net"
    click ConsService "https://github.com/tronprotocol/java-tron/blob/develop/framework/src/main/java/org/tron/core/consensus/ConsensusService.java"
    click DPoS "https://github.com/tronprotocol/java-tron/tree/develop/consensus/src/main/java/org/tron/consensus"
    click PBFT "https://github.com/tronprotocol/java-tron/tree/develop/consensus/src/main/java/org/tron/consensus"
    click TxnPool "https://github.com/tronprotocol/java-tron/blob/develop/framework/src/main/java/org/tron/core/db/PendingManager.java"
    click TVM "https://github.com/tronprotocol/java-tron/tree/develop/actuator/src/main/java/org/tron/core/actuator"
    click ActFactory "https://github.com/tronprotocol/java-tron/tree/develop/actuator/src/main/java/org/tron/core/actuator"
    click ChainBase "https://github.com/tronprotocol/java-tron/tree/develop/chainbase/src/main/java/org/tron/core/db"
    click TrieSvc "https://github.com/tronprotocol/java-tron/blob/develop/framework/src/main/java/org/tron/core/db/accountstate/TrieService.java"
    click JSONRPC "https://github.com/tronprotocol/java-tron/tree/develop/framework/src/main/java/org/tron/core/services"
    click Docker "https://github.com/tronprotocol/java-tron/tree/develop/docker/Dockerfile"
    click Docker "https://github.com/tronprotocol/java-tron/blob/develop/docker/docker-entrypoint.sh"
    click Docker "https://github.com/tronprotocol/java-tron/blob/develop/docker/docker.sh"
    click StartSh "https://github.com/tronprotocol/java-tron/blob/develop/start.sh"
    click Crypto "https://github.com/tronprotocol/java-tron/tree/develop/crypto/src/main/java/org/tron/common/crypto"
    click Proto "https://github.com/tronprotocol/java-tron/tree/develop/protocol/src/main/protos"
```
