Merge pull request #81 from tronprotocol/develop

Develop

Author: kuny0707

conf/private_net_config_witness1.conf

@@ -199,6 +199,7 @@ seed.node = {
   ]
 }
 
+# if you use the fork database from mainnet keep this genesis.block the same as mainnet
 genesis.block = {
   # Reserve balance
   assets = [

conf/private_net_config_witness2.conf

@@ -200,6 +200,7 @@ seed.node = {
   ]
 }
 
+# if you use the fork database from mainnet keep this genesis.block the same as mainnet
 genesis.block = {
   # Reserve balance
   assets = [

tools/stress_test/README.md

@@ -121,7 +121,7 @@ broadcastTx = {
 
 - `saveTxId`: configure whether to save the transaction id of the broadcast transactions.
 
-*Note*: we can use the [dbfork](../toolkit/DbFork.md) tool to get enough `TRX/TRC10/TRC20` balances of address corresponding
+*Note*: we can use the [DBFork](../toolkit/DBFork.md) tool to get enough `TRX/TRC10/TRC20` balances of address corresponding
   to the `privateKey` for the stress test.
 
 Then we can execute the following `generate` subcommand:

tools/toolkit/DbFork.md tools/toolkit/DBFork.mdtools/toolkit/DbFork.md renamed to tools/toolkit/DBFork.md

@@ -48,14 +48,14 @@ java -jar Toolkit.jar db copy output-directory output-directory-bak
 ```
 
 ### Run the DBFork tool
-Run the DBFork tool in the Toolkit to modify the related data. The available parameters are:
+Run the DBFork tool in the Toolkit to modify the related data. First, check [Build The Toolkit](README.md#build-the-toolkit) to generate the `Toolkit.jar` file. After building successfully, you can use the following parameters to run the tool:
 - `-c | --config=<config>`: config the new witnesses, balances, etc for shadow
   fork. Default: fork.conf
 - `-d | --database-directory=<database>`: java-tron database directory path. Default: output-directory
 - `-h | --help`
 - `-r | --retain-witnesses`: retain the previous witnesses and active witnesses. Default: false
 
-The example of `fork.conf` can be:
+The example of [fork.conf](./src/main/resources/fork.conf) can be:
 
 ```conf
 witnesses = [
@@ -126,23 +126,23 @@ For the `accounts`, we can configure the following properties:
 - `trc10Id`: the TRC10 token ID
 - `trc10Balance`: change the balance of `trc10Id`
 
-*Note*: If you need to add new address, you can use the [tronlink](https://www.tronlink.org/) or [wallet-cli](https://github.com/tronprotocol/wallet-cli?tab=readme-ov-file#account-related-commands) to genrate the private key and address.
+  *Note*: If you need to add new address, you can use the [tronlink](https://www.tronlink.org/) or [wallet-cli](https://github.com/tronprotocol/wallet-cli?tab=readme-ov-file#account-related-commands) to genrate the private key and address.
 
 For the `trc20Contracts`, we can configure the following properties:
 - `contractAddress`: set the TRC20 contract address
 - `balancesSlotPosition`: set the `balances` slot position in the TRC20 contract storage layout
 - `address`: set the account address
 - `balance`: set the TRC20 balance
 
-*Note*: the `balancesSlotPosition` sets slot position for
-`mapping(address account => uint256) private _balances` variable in the TRC20 contract.
-For most standard TRC20 contracts, the `balancesSlotPosition` is 0. For some special cases,
-you may need to change the `balancesSlotPosition` value. For more details about the variable slot position
-in the contract, please refer [layout_in_storage](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html).
+  *Note*: the `balancesSlotPosition` sets slot position for
+  `mapping(address account => uint256) private _balances` variable in the TRC20 contract.
+  For most standard TRC20 contracts, the `balancesSlotPosition` is 0. For some special cases,
+  you may need to change the `balancesSlotPosition` value. For more details about the variable slot position
+  in the contract, please refer [layout_in_storage](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html).
 
-set `latestBlockHeaderTimestamp` as current millisecond time to avoid the delay in producing blocks.
+Set `latestBlockHeaderTimestamp` as the current time in milliseconds. This timestamp is used before processing new blocks - setting it to the current time reduces debug log output and accelerates the production of the first new block. This setting does not impact the underlying block production logic.
 
-set `maintenanceTimeInterval` and `nextMaintenanceTime` optionally to facilitate testing.
+Set `maintenanceTimeInterval` and `nextMaintenanceTime` optionally to facilitate testing.
 
 Execute the fork command:
 ```shell script
@@ -167,7 +167,9 @@ localwitness = [
 ]
 ```
 
-If another node wants to join the shadow fork network, it needs to execute the above steps, or it copies the state data from the first shadow fork node directly. They need to configure the same `node.p2p.version` and add the `seed.node` in the config, then they can sync and produce blocks to form a local testnet.
+If another node wants to join the shadow fork network, it needs to execute the above steps, or it copies the database from the first shadow fork node directly. They need to configure the same `node.p2p.version` and add the `seed.node` in the config, then they can sync and produce blocks to form a local testnet.
+
+For instructions on starting a private chain, please refer to [Setup Private Chain](../../private_net/README.md). Note that you must use the same `genesis.block` configuration as the forked database data to ensure compatibility. If the configurations do not match, the node may fail to start or encounter consensus issues.
 
 At last, developers can connect and interact with the node by [wallet-cli](https://tronprotocol.github.io/documentation-en/clients/wallet-cli/),
 [TronBox](https://developers.tron.network/reference/what-is-tronbox), [Tron-IDE](https://developers.tron.network/docs/tron-ide) or other tools, and execute the shadow fork testing.

tools/toolkit/README.md

@@ -183,7 +183,7 @@ output-directory
 - `-r, --retain-witnesses`: retain the previous witnesses and active witnesses.
 - `-h, --help`: provide the help info
 
-Please refer [DbFork](DbFork.md) guidance for more details.
+Please refer [DBFork](DBFork.md) guidance for more details.
 
 ## DB Query
 The [ListWitnesses](https://developers.tron.network/reference/listwitnesses) and [getReward](https://developers.tron.network/reference/wallet-getreward)

tools/toolkit/src/main/resources/fork.conf

@@ -53,6 +53,6 @@ trc20Contracts = [
   }
 ]
 
-latestBlockHeaderTimestamp = 1739269661000
+latestBlockHeaderTimestamp = 1747986162000 # MilliSecond. Used in init setup, setting to current timestamp reduces debug log output and speeds up initialization. This setting does not impact the underlying block production logic.
 maintenanceTimeInterval = 21600000
-nextMaintenanceTime = 1735628894000
+nextMaintenanceTime = 1747996162000 # MilliSecond. Set next maintenance time. It could be anytime. If you set an expired time, it will trigger maintenance logic immediately after node startup.