Skip to content

Commit 789cb2e

Browse files
vivian1912vivian1912
committed
add java-tron code structure doc
1 parent c1b4352 commit 789cb2e

File tree

2 files changed

+261
-1
lines changed

2 files changed

+261
-1
lines changed

‎docs/developers/code-structure.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Java-tron Code Structure
2+
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.
3+
4+
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](#protocol), [common](#common), [chainbase](#chainbase), [consensus](#consensus), [actuator](#actuator), [crypto](#crypto), [framework](#framework), the following introduces the functions of each module and its code organization.
5+
6+
7+
8+
## protocol
9+
10+
For a distributed network such as blockchain, a concise and efficient data interaction protocol is very important. The protocol module defines:
11+
12+
* Inter-node communication protocol
13+
* Communication protocol between modules within the node
14+
* Agreement for Services Provided Externally
15+
16+
The above protocols adopt the [`Google Protobuf`](https://developers.google.com/protocol-buffers) 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.
17+
18+
[protocol](https://github.com/tronprotocol/java-tron/tree/develop/protocol) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/protocol` , its directory structure is as follows:
19+
20+
```
21+
|-- protos
22+
|-- api
23+
| |-- api.proto
24+
| |-- zksnark.proto
25+
|-- core
26+
|-- Discover.proto
27+
|-- Tron.proto
28+
|-- TronInventoryItems.proto
29+
|-- contract
30+
```
31+
32+
* `protos/api/` - The gRPC interface and data structure provided by the Java-tron node externally
33+
* `protos/core/` - Data structure for communication between nodes and between modules within nodes
34+
* `Discover.proto` - Node discovers related data structures
35+
* `TronInventoryItems.proto` - Data structure related to block transferring between nodes
36+
* `contract/` - Contract related data structures
37+
* `Tron.proto` - Other important data structures, including accounts, blocks, transactions, resources, super representatives, voting, and proposals...
38+
39+
40+
41+
## common
42+
43+
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.
44+
45+
[common](https://github.com/tronprotocol/java-tron/tree/develop/common) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/common`, its directory structure is as follows:
46+
47+
```
48+
|-- /common/src/main/java/org/tron
49+
|-- common
50+
| |-- args
51+
| |-- config
52+
| |-- entity
53+
| |-- logsfilter
54+
| |-- overlay
55+
| |-- parameter
56+
| |-- prometheus
57+
| |-- runtime
58+
| |-- setting
59+
| |-- utils
60+
|-- core
61+
|-- config
62+
|-- db
63+
|-- db2
64+
|-- exception
65+
```
66+
67+
68+
* `common/prometheus` - Prometheus metrics monitoring
69+
* `common/utils` - The wrapper class of basic data type
70+
* `core/config` - Node configuration related classes
71+
* `core/exception` - All exception handling related classes
72+
73+
74+
75+
76+
## chainbase
77+
78+
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.
79+
80+
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.
81+
82+
[chainbase](https://github.com/tronprotocol/java-tron/tree/develop/chainbase) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/chainbase`, its directory structure is as follows:
83+
```
84+
|-- chainbase.src.main.java.org.tron
85+
|-- common
86+
| |-- bloom
87+
| |-- error
88+
| |-- overlay
89+
| |-- runtime
90+
| |-- storage
91+
| | |-- leveldb
92+
| | |-- rocksdb
93+
| |-- utils
94+
| |-- zksnark
95+
|-- core
96+
|-- actuator
97+
|-- capsule
98+
|-- db
99+
| |-- RevokingDatabase.java
100+
| |-- TronStoreWithRevoking.java
101+
| |-- ......
102+
|-- db2
103+
| |-- common
104+
| |-- core
105+
| |-- SnapshotManager.java
106+
| |-- ......
107+
|-- net
108+
|-- service
109+
|-- store
110+
```
111+
112+
113+
* `common/` - Common components, such as exception handling, tools, etc
114+
* `storage/leveldb/` Implemented the use of LevelDB as the underlying storage database
115+
* `storage/rocksdb/` Implemented the use of RocksDB as the underlying storage database
116+
* `core/` - The core code of the chainbase module
117+
* `capsule/`
118+
119+
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.
120+
121+
* `store/`
122+
123+
Various databases, such as `AccountStore`, `ProposalStore`, etc. `AccountStore` is the account database, the database name is `account`, which stores all account information in the TRON network; `ProposalStore` is the proposal database, and the database name is `proposal`, which stores all the proposal information in the TRON network.
124+
125+
* `db/` and `db2/`
126+
127+
Implemented rollbackable databases, including two rollbackable databases: `AbstractRevokingStore` located in the `db/` directory and `SnapshotManager` located in the `db2/` directory. Compared with `AbstractRevokingStore`, `SnapshotManager` has a more stable data rollback function and supports the extension of the underlying database. Therefore, Java-tron uses `SnapshotManager` to roll back the database. Several important interfaces and implementation classes are as follows:
128+
129+
* `RevokingDatabase.java` - It is the interface of the database container, used to manage all rollbackable databases, `SnapshotManager` is an implementation of this interface
130+
* `TronStoreWithRevoking.java` - It is the base class that supports rollbackable databases. All rollbackable databases are their implementations, such as `BlockStore`, `TransactionStore`, etc
131+
132+
133+
## consensus
134+
135+
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.
136+
137+
[consensus](https://github.com/tronprotocol/java-tron/tree/develop/consensus) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/consensus`, its directory structure is as follows:
138+
```
139+
|-- consensus/src/main/java/org/tron/consensus
140+
|-- Consensus.java
141+
|-- ConsensusDelegate.java
142+
|-- base
143+
| |-- ConsensusInterface.java
144+
| |-- ......
145+
|-- dpos
146+
|-- pbft
147+
```
148+
consensus module divides the consensus process into several important parts that are defined in `ConsensusInterface`:
149+
150+
1. `start` - start the consensus service with customizable startup parameters
151+
2. `stop` - stop the consensus service
152+
3. `receiveBlock` - define the consensus logic of receiving blocks
153+
4. `validBlock` - define the consensus logic of validating blocks
154+
5. `applyBlock` - define the consensus logic of processing blocks
155+
156+
Currently, Java-tron implements DPOS consensus and PBFT consensus based on the `ConsensusInterface` interface, which is located in the `dpos/` and `pbft/` directories respectively. Developers can also implement the `ConsensusInterface` interface according to their own business needs to customize the consensus mechanism.
157+
158+
159+
## actuator
160+
161+
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.
162+
163+
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.
164+
165+
[actuator](https://github.com/tronprotocol/java-tron/tree/develop/actuator) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/actuator`, its directory structure is as follows:
166+
```
167+
|-- actuator/src/main/java/org/tron/core
168+
|-- actuator
169+
| |-- AbstractActuator.java
170+
| |-- ActuatorCreator.java
171+
| |-- ActuatorFactory.java
172+
| |-- TransferActuator.java
173+
| |-- VMActuator.java
174+
| |-- ......
175+
|-- utils
176+
|-- vm
177+
```
178+
179+
* `actuator/` - The executors of various types of transactions in the TRON network which define the processing logic of different types of transactions. For example, `TransferActuator` is the processing class for transferring TRX, and `FreezeBalanceActuator` is the processing class for staking TRX to obtain resource
180+
* `utils/` - tools needed to execute transaction
181+
* `vm/` - TRON virtual machine related code
182+
183+
Actuator module defines the `Actuator` interface, which includes 4 different methods:
184+
185+
* `execute` - execute specific actions of transactions, such as state modification, communication between modules, logic execution, etc.
186+
* `validate` - validate authenticity of transactions
187+
* `getOwnerAddress` - acquire the address of transaction initiators
188+
* `calcFee` - define the logic of calculating transaction fees
189+
190+
Depending on their businesses, developers may set up Actuator accordingly and customize the processing of different types of transactions.
191+
192+
## crypto
193+
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.
194+
195+
[crypto](https://github.com/tronprotocol/java-tron/tree/develop/crypto) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/crypto`, its directory structure is as follows:
196+
```
197+
|-- crypto/src/main/java/org/tron/common/crypto
198+
|-- Blake2bfMessageDigest.java
199+
|-- ECKey.java
200+
|-- Hash.java
201+
|-- SignInterface.java
202+
|-- SignUtils.java
203+
|-- SignatureInterface.java
204+
|-- cryptohash
205+
|-- jce
206+
|-- sm2
207+
|-- zksnark
208+
```
209+
210+
* `sm2` and `jce` - Provide SM2 and ECKey encryption algorithm and signature algorithm
211+
* `zksnark` - Provide a zero-knowledge proof algorithm
212+
213+
## framework
214+
215+
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.
216+
217+
[framework](https://github.com/tronprotocol/java-tron/tree/develop/framework) module's source code is located at: `https://github.com/tronprotocol/java-tron/tree/develop/framework`, its directory structure is as follows:
218+
219+
```
220+
|-- framework/src/main/java/org/tron
221+
|-- common
222+
| |-- application
223+
| |-- backup
224+
| |-- logsfilter
225+
| |-- net
226+
| |-- overlay
227+
| | |-- client
228+
| | |-- discover
229+
| | |-- message
230+
| | |-- server
231+
| |-- runtime
232+
| |-- zksnark
233+
|-- core
234+
| |-- Wallet.java
235+
| |-- capsule
236+
| |-- config
237+
| |-- consensus
238+
| |-- db
239+
| |-- metrics
240+
| |-- net
241+
| |-- services
242+
| |-- trie
243+
| |-- zen
244+
|-- keystore
245+
|-- program
246+
| |-- FullNode.java
247+
|-- tool
248+
```
249+
250+
* `program/FullNode.java` - It is the entry point of the program and initializes external HTTP, gRPC and json-rpc interface services
251+
* `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
252+
* `common/overlay/discover` - Node discovery logic
253+
* `common/overlay/server` - Node management and block synchronization logic among nodes
254+
* `core/net` - Message processing, its subdirectory `/service` is transaction and block broadcasting, block fetching and synchronization logic
255+
* `core/db/Manager.java` - Transaction and block verification and processing logic
256+
257+
## Summary
258+
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.
259+

‎mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@ nav:
3333
- Issue Workflow: developers/issue-workflow.md
3434
- Configure the IDE: developers/run-in-idea.md
3535
- Development Example: developers/demo.md
36-
- GPG Key: developers/gpg.md
36+
- Core Modules:
37+
- Overview: developers/code-structure.md
3738
- For DAPP developers:
3839
- Dapp Development Tool: contracts/compiler.md
3940
- Wallet-cli:

0 commit comments

Comments
 (0)