Java-tron Code Structure¶
Java-tron is a TRON network client developed based on the Java language. It implements all the functions mentioned in the TRON white paper, including consensus mechanism, cryptography, database, TVM virtual machine, network management, etc. We can run a TRON node by starting Java-tron. In this article, we will describe the code structure of Java-tron in detail, and introduce the functions of its various modules, to facilitate the subsequent code analysis and development of developers.
Java-tron adopts a modular code structure; the code structure is clear and easy to maintain and expand. Currently Java-tron is divided into 7 modules: protocol, common, chainbase, consensus, actuator, crypto, framework, the following introduces the functions of each module and its code organization.
For a distributed network such as blockchain, a concise and efficient data interaction protocol is very important. The protocol module defines:
- Inter-node communication protocol
- Communication protocol between modules within the node
- Agreement for Services Provided Externally
The above protocols adopt the
Google Protobuf data exchange format. Compared with JSON and XML, the
Google Protobuf format is more efficient and flexible and can be compiled by the ProtoBuf compiler to generate language-specific serialization and deserialization source code for the defined protocol files. Protobuf is the basis for java-tron to achieve cross-language and cross-platform.
protocol module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/protocol , its directory structure is as follows:
|-- protos |-- api | |-- api.proto | |-- zksnark.proto |-- core |-- Discover.proto |-- Tron.proto |-- TronInventoryItems.proto |-- contract
protos/api/- The gRPC interface and data structure provided by the Java-tron node externally
protos/core/- Data structure for communication between nodes and between modules within nodes
Discover.proto- Node discovers related data structures
TronInventoryItems.proto- Data structure related to block transferring between nodes
contract/- Contract related data structures
Tron.proto- Other important data structures, including accounts, blocks, transactions, resources, super representatives, voting, and proposals...
The common module encapsulates common components and tools, such as exception handling, metrics monitoring tools, etc which make it easy to use by other modules.
common module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/common, its directory structure is as follows:
|-- /common/src/main/java/org/tron |-- common | |-- args | |-- config | |-- entity | |-- logsfilter | |-- overlay | |-- parameter | |-- prometheus | |-- runtime | |-- setting | |-- utils |-- core |-- config |-- db |-- db2 |-- exception
common/prometheus- Prometheus metrics monitoring
common/utils- The wrapper class of basic data type
core/config- Node configuration related classes
core/exception- All exception handling related classes
Chainbase is a database module. For probabilistic consensus algorithms such as PoW, PoS and DPoS, situations of switching to a new chain, however unlikely, are inevitable. Because of this, chainbase defines an interface standard supporting databases that can roll back. This interface requires databases to have a state rollback mechanism, a checkpoint-based disaster tolerant mechanism and so on.
In addition, the chainbase module features a well-designed abstract interface. Any database that implements the interface can be used for underlying storage on the blockchain, granting more flexibility to developers. LevelDB and RocksDB are two default implementations.
chainbase module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/chainbase, its directory structure is as follows:
|-- chainbase.src.main.java.org.tron |-- common | |-- bloom | |-- error | |-- overlay | |-- runtime | |-- storage | | |-- leveldb | | |-- rocksdb | |-- utils | |-- zksnark |-- core |-- actuator |-- capsule |-- db | |-- RevokingDatabase.java | |-- TronStoreWithRevoking.java | |-- ...... |-- db2 | |-- common | |-- core | |-- SnapshotManager.java | |-- ...... |-- net |-- service |-- store
common/- Common components, such as exception handling, tools, etc
storage/leveldb/Implemented the use of LevelDB as the underlying storage database
storage/rocksdb/Implemented the use of RocksDB as the underlying storage database
core/- The core code of the chainbase module
The encapsulation class of each data structure, such as AccountCapsule, BlockCapsule, etc. AccountCapsule is the encapsulation class of Account data structure, which provides modification and query of account data; BlockCapsule is the encapsulation class of Block data structure, which provides modification and query of block data.
Various databases, such as
AccountStoreis the account database, the database name is
account, which stores all account information in the TRON network;
ProposalStoreis the proposal database, and the database name is
proposal, which stores all the proposal information in the TRON network.
Implemented rollbackable databases, including two rollbackable databases:
AbstractRevokingStorelocated in the
SnapshotManagerlocated in the
db2/directory. Compared with
SnapshotManagerhas a more stable data rollback function and supports the extension of the underlying database. Therefore, Java-tron uses
SnapshotManagerto roll back the database. Several important interfaces and implementation classes are as follows:
RevokingDatabase.java- It is the interface of the database container, used to manage all rollbackable databases,
SnapshotManageris an implementation of this interface
TronStoreWithRevoking.java- It is the base class that supports rollbackable databases. All rollbackable databases are their implementations, such as
The consensus mechanism is a crucial module in blockchains. Common ones are PoW, PoS, DPoS and PBFT, etc. While Paxos, Raft, etc, are applied to consortium blockchains and other trusted networks. The consensus mechanism should match the business scenario. For instance, PoW is not suitable for real-time games that are sensitive to consensus efficiency, while PBFT can make an optimized choice for exchanges demanding high real-time capability. In this sense, a replaceable consensus is a creative innovation and an essential link in building application-specific blockchains. Even star blockchain programs like Cosmos SDK are still at a stage where the application layer provides developers with limited autonomy and the consensus at the base level is subject to Tendermint. Therefore, the ultimate goal of the consensus module is to make consensus switch as easy as configuring parameters for application developers.
consensus module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/consensus, its directory structure is as follows:
|-- consensus/src/main/java/org/tron/consensus |-- Consensus.java |-- ConsensusDelegate.java |-- base | |-- ConsensusInterface.java | |-- ...... |-- dpos |-- pbft
start- start the consensus service with customizable startup parameters
stop- stop the consensus service
receiveBlock- define the consensus logic of receiving blocks
validBlock- define the consensus logic of validating blocks
applyBlock- define the consensus logic of processing blocks
Currently, Java-tron implements DPOS consensus and PBFT consensus based on the
ConsensusInterface interface, which is located in the
pbft/ directories respectively. Developers can also implement the
ConsensusInterface interface according to their own business needs to customize the consensus mechanism.
Ethereum was the first to introduce the virtual machine and define the smart contract. However, smart contracts are constrained in terms of their functions and not flexible enough to accommodate the needs of complex applications. This is one of the reasons why java-tron supports the creation of a chain of applications. For the reasons mentioned, java-tron includes a separate module, Actuator, offering application developers a brand new way of development. They can choose to implant their application codes into a chain instead of running them on virtual machines.
Actuator is the executor of transactions, while applications can be viewed as a cluster of different types of transactions, each of which is executed by a corresponding actuator.
actuator module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/actuator, its directory structure is as follows:
|-- actuator/src/main/java/org/tron/core |-- actuator | |-- AbstractActuator.java | |-- ActuatorCreator.java | |-- ActuatorFactory.java | |-- TransferActuator.java | |-- VMActuator.java | |-- ...... |-- utils |-- vm
actuator/- The executors of various types of transactions in the TRON network which define the processing logic of different types of transactions. For example,
TransferActuatoris the processing class for transferring TRX, and
FreezeBalanceActuatoris the processing class for staking TRX to obtain resource
utils/- tools needed to execute transaction
vm/- TRON virtual machine related code
Actuator module defines the
Actuator interface, which includes 4 different methods:
execute- execute specific actions of transactions, such as state modification, communication between modules, logic execution, etc.
validate- validate authenticity of transactions
getOwnerAddress- acquire the address of transaction initiators
calcFee- define the logic of calculating transaction fees
Depending on their businesses, developers may set up Actuator accordingly and customize the processing of different types of transactions.
Crypto is a relatively independent module, but it is also a very important module. Data security in Java-tron is almost entirely guaranteed by this module. Currently, SM2 and ECKey encryption algorithms are supported.
crypto module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/crypto, its directory structure is as follows:
|-- crypto/src/main/java/org/tron/common/crypto |-- Blake2bfMessageDigest.java |-- ECKey.java |-- Hash.java |-- SignInterface.java |-- SignUtils.java |-- SignatureInterface.java |-- cryptohash |-- jce |-- sm2 |-- zksnark
jce- Provide SM2 and ECKey encryption algorithm and signature algorithm
zksnark- Provide a zero-knowledge proof algorithm
The framework is the core module of java-tron and the entrance of the node. The framework module is responsible for the initialization of each module and business logic. The framework module includes the services provided externally, the node discovery and node management process related to the P2P network, and the block broadcasting and processing procedures.
framework module's source code is located at:
https://github.com/tronprotocol/java-tron/tree/develop/framework, its directory structure is as follows:
|-- framework/src/main/java/org/tron |-- common | |-- application | |-- backup | |-- logsfilter | |-- net | |-- overlay | | |-- client | | |-- discover | | |-- message | | |-- server | |-- runtime | |-- zksnark |-- core | |-- Wallet.java | |-- capsule | |-- config | |-- consensus | |-- db | |-- metrics | |-- net | |-- services | |-- trie | |-- zen |-- keystore |-- program | |-- FullNode.java |-- tool
program/FullNode.java- It is the entry point of the program and initializes external HTTP, gRPC and json-rpc interface services
core/services- Defines the externally provided services, its subdirectory
http/contains all http interface processing classes,
json-rpc/contains all json-rpc interface processing classes
common/overlay/discover- Node discovery logic
common/overlay/server- Node management and block synchronization logic among nodes
core/net- Message processing, its subdirectory
/serviceis transaction and block broadcasting, block fetching and synchronization logic
core/db/Manager.java- Transaction and block verification and processing logic
This article mainly introduces the code structure of Java-tron, as well as the function, location and directory structure of each functional module. Through this article, you will have a general understanding of the overall structure and key interfaces of Java-tron, which is helpful for subsequent code analysis and development.