区块链仿真工具SimBlock使用

1. Environment requirements

SimBlock 可以在 Windows、MacOS、Ubuntu Linux 或任何支持 Java 的 Unix 平台上运行。

它需要以下版本的 JDK 和 Gradle。

请注意，SimBlock 的仓库中包含 Gradle Wrapper，因此您也可以自动安装 Gradle（我们稍后会提到）。

Software	Version
JDK	1.8.0 or later
Gradle	5.1.1 or later

2. 下载

Download the SimBlock repository as a zip file from GitHub and unzip, or clone the repository.

Release list: Releases · dsg-titech/simblock · GitHub
Command for clone: $ git clone git@github.com:dsg-titech/simblock.git

从GitHub和Unzip下载Simblock存储库作为ZIP文件，或克隆存储库。

发布列表：Releases · dsg-titech/simblock · GitHub

克隆命令：$ git clone git@github.com:dsg-titech/simblock.git

我的命令：

wget https://github.com/dsg-titech/simblock/archive/refs/tags/v0.8.0.zip
unzip v0.8.0.zip

2-a. 目录结构

The structure of the unzipped or cloned directory is as follows:（解压缩或者克隆后的目录结构如下所示）

simblock
+-- docs
+-- gradle
|   +-- wrapper
+-- simulator
    +-- src
        +-- dist
        |   +-- conf
        |   +-- out
        |       +-- graph
        +-- main
            +-- java
                +-- SimBlock
                    +-- ...
                    :

Directory 目录	Description 描述
docs	Documents about SimBlock (e.g., user manual)
gradle/wrapper	For Gradle wrapper
simulator/src/dist/conf	Directory in which to place the files that simulator reads
simulator/src/dist/out	Directory where files output by simulator are stored
simulator/src/main/java/SimBlock	Source codes

3. Build

此后，解压缩或克隆的存储库的根目录的名称表示为<root_dir>。

首先，打开一个终端软件（例如xterm，命令提示等），然后来到到<root_dir>目录。

3-a. 如果Gradle 已安装

You can build by the following Gradle command, if you have already installed Gradle.

如果您已经安装了Gradle，则可以通过以下Gradle命令进行构建。

没安装的话安装gradle

$ gradle build

If successful, build directory will be created under <ROOT_DIR>/simulator.

如果成功，将在<ROOT_DIR>/simulator下创建build目录。

<ROOT_DIR>
+-- simulator
    +-- build
        +-- classes
        +-- distributions
        +-- libs
        +-- scripts
        +-- tmp

Directory 目录	Description 说明
simulator/build/classes	Directory where built class files are stored 存储构建类文件的目录
simulator/build/distributions	Directory where distribution archive files (zip, tar) are stored 存储分发存档文件（zip、tar）的目录
simulator/build/libs	Directory where jar files are stored
simulator/build/scripts	Directory where startup scripts are stored 启动脚本的目录

Note that the startup scripts in simulator/build/scripts are generated for inclusion in the distribution archive; if you run the scripts with the directory structure as it is, an error will occur.

请注意，simulator/build/scripts 中的启动脚本是为了包含在分发存档中而生成的；如果按原样运行目录结构的脚本，将出现错误。

3-b. If Gradle is not installed（忽略）

You can use gradlew（gradlew.bat, for Windows user）in <ROOT_DIR> instead of running Gradle command.

您可以在<ROOT_DIR>中使用gradlew（gradlew.bat，适用于Windows用户），而不是运行Gradle命令。

$ gradlew build

This is a program called Gradle wrapper, which will automatically install Gradle if it is not installed and call it.

这是一个名为Gradle包装器的程序，如果未安装Gradle，它将自动安装Gradle并调用它

3-c. Discard build products（忽略）

The following Gradle command will delete the files generated by the above build process.

以下Gradle命令将删除上述构建过程生成的文件。

$ gradle clean

You can also instruct the execution of clean and build at one time as follows:

您还可以指示一次执行清理和构建，如下所示：

$ gradle clean build

在这种情况下，构建是在清理后执行的

4. Run SimBlock

There are two main ways to run SimBlock: by using Gradle command and by using build products.

4-a. Run with Gradle command

Run following Gradle command in <ROOT_DIR>, then the simulator starts up.

$ gradle :simulator:run

Output files of the simulator will be stored in <ROOT_DIR>/simulator/src/dist/output.

到这里已经成功运行，我们可以将/simulator/src/dist/output/output.json上传到SimBlock Visualizer来可视化区块链仿真：

当然，可以继续看下面的介绍来属性simbolck的使用。

4-b. Run with build product（忽略）

Extract the distribution archive (zip, tar) of <ROOT_DIR>/simulator/build/distributions. Then, the following directory structure will be created.

SimBlock
+-- bin
+-- conf
+-- lib
+-- output

A script for execution is in bin directory.

By executing runSimBlock (runSimBlock.bat for Windows) in the terminal, the simulator starts up.

Output files of the simulator will be stored in output directory.

4-c. Other ways（忽略）

The extracted distribution archive contains the jar file of SimBlock (lib/simulator.jar). Of course, it is also possible to execute this jar file directly with the java command. Note that it is required to set the classpath appropriately.

You can also run SimBlock on IDEs, such as Eclipse. It is explained later in the section of "Import to IDE".

5. 仿真参数

参数

定义的位置

描述

区域列表

BlockChainSimulator.settings.NetworkConfiguration#REGION_LIST

节点可以存在的区域列表。

延迟列表

BlockChainSimulator.settings.NetworkConfiguration#LATENCY

分配给每个区域的延迟列表。（单位：毫秒）

上传带宽列表

BlockChainSimulator.settings.NetworkConfiguration#UPLOAD_BANDWIDTH

分配给每个区域的上传带宽列表。（单位：比特每秒）

下载带宽列表

BlockChainSimulator.settings.NetworkConfiguration#DOWNLOAD_BANDWIDTH

分配给每个区域的下载带宽列表。（单位：比特每秒）

区域分布

BlockChainSimulator.settings.NetworkConfiguration#REGION_DISTRIBUTION

节点区域的分布。每个值表示该区域内节点数量与所有节点数量之比。

度数分布

BlockChainSimulator.settings.SimulationConfiguration#DEGREE_DISTRIBUTION

出站连接数的累积分布。参考：Andrew Miller 等人，“Discovering bitcoin's public topology and influential nodes”，2015年。

节点数量

BlockChainSimulator.settings.SimulationConfiguration#NUM_OF_NODES

参与区块链网络的节点数量。

路由表

BlockChainSimulator.settings.SimulationConfiguration#TABLE

路由表的种类。

区块间隔

BlockChainSimulator.settings.SimulationConfiguration#INTERVAL

区块生成间隔的期望值。挖矿难度会根据该值和挖矿能力的总和自动调整。（单位：毫秒）

平均挖矿能力

BlockChainSimulator.settings.SimulationConfiguration#AVERAGE_MINING_POWER

每个节点的平均挖矿能力。挖矿能力对应于比特币中的哈希率，即每毫秒执行的挖矿（哈希计算）次数。

挖矿能力标准差

BlockChainSimulator.settings.SimulationConfiguration#STDEV_OF_MINING_POWER

每个节点的挖矿能力根据正态分布随机确定，其均值为 AVERAGE_MINING_POWER，标准差为 STDEV_OF_MINING_POWER。

最大区块高度

BlockChainSimulator.settings.SimulationConfiguration#END_BLOCK_HEIGHT

模拟结束时的区块高度。

区块大小

BlockChainSimulator.settings.SimulationConfiguration#BLOCK_SIZE

区块大小。（单位：字节）

CBR使用率

BlockChainSimulator.settings.SimulationConfiguration#CBR_USAGE_RATE

紧凑区块中继（CBR）协议的使用率。

节点变动率

BlockChainSimulator.settings.SimulationConfiguration#CHURN_NODE_RATE

造成节点变动的节点比例。

紧凑区块大小

BlockChainSimulator.settings.SimulationConfiguration#COMPACT_BLOCK_SIZE

紧凑区块大小。（单位：字节）

控制节点CBR失败率

BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_RATE_FOR_CONTROL_NODE

始终连接网络的控制节点的CBR失败率。

节点变动节点CBR失败率

BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_RATE_FOR_CHURN_NODE

造成节点变动的节点的CBR失败率。

控制节点CBR失败区块大小分布

BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_BLOCK_SIZE_DISTRIBUTION_FOR_CONTROL_NODE

控制节点在CBR失败时接收的数据大小分布。

节点变动节点CBR失败区块大小分布

BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_BLOCK_SIZE_DISTRIBUTION_FOR_CHURN_NODE

变动节点在CBR失败时接收的数据大小分布。

SimBlock.settings package has two classes which have these parameters: NetworkConfiguration.java and SimulationConfiguration.java. The former has parameters related to network parameters, and the latter has blockchain parameters. By changing these parameters and doing build, you can conduct different patterns of simulation.（ SimBlock.settings 包含两个类，它们具有这些参数：NetworkConfiguration.java 和 SimulationConfiguration.java。前者包含与网络参数相关的参数，后者包含与区块链参数相关的参数。通过修改这些参数并进行构建，可以进行不同模式的模拟。）

6. Output

模拟器将模拟结果输出到标准输出和一些文件。文件输出位置为

<ROOT_DIR>/simulator/src/dist/out（通过 Gradle 命令执行时）以及 SimBlock/output（通过构建产品运行时）。输出内容如下：

Standard output and out.txt

- The following is listed under block ID

- - ＜node ID, propagation time＞

- - - Propagation time: The time from when the block of the block ID is generated to when the node of the node ID is reached.

Blocklist.txt

- ＜fork information, block height, block ID＞

- - Fork information: One of "OnChain" and "Orphan". "OnChain" denote block is on Main chain. "Orphan" denote block is an orphan block.

graph/

- ${number}.txt: Network information when block height is ${number}

- - ＜node ID, node ID＞

- - - Connection from left node ID to right node ID.

output.json

- This file is listing occurred events. By uploading this file into SimBlock Visualizer, you can see the visualization.

- - ＜event, content＞
  - Event

- - - add-link: Add a node to neighbor nodes.
    - remove-link: Remove a node from neighbor nodes.
    - flow-block: Block transmmission.
    - simulation-end: Simulation end.

- - content

- - - timestamp: Order of events.
    - block-id: Block id.
    - transmission-timestamp: Timestamp when a block is transmitted.
    - reception-timestamp: Timestamp when a block is recieved.
    - begin-node-id: Source node.
    - end-node-id: End node.

7. Import to IDE

By using Gradle, you can generate configuration files of an IDE and easily import them into it.

通过使用 Gradle，您可以生成 IDE 的配置文件，并轻松地将其导入到 IDE 中。

7-a. For IntelliJ IDEA

By executing the following Gradle command, configuration files for IntelliJ IDEA are generated.

$ gradle idea

Generated files are listed as follows:

File

<ROOT_DIR>/<ROOT_DIR>.iml

<ROOT_DIR>/<ROOT_DIR>.ipr

<ROOT_DIR>/<ROOT_DIR>.iws

<ROOT_DIR>/simulator/simulator.iml

With IntelliJ IDEA, select File -> Open and select <ROOT_DIR>.ipr. <ROOT_DIR>/simulator will be imported as a module.

Then, you can run the simulator with the IDE. For example, select <ROOT_DIR>/simulator/src/main/java/SimBlock/simulator/Main.java from the tool window of the project structure, right click and execute Run 'Main.main ()'. Output files will be stored in <ROOT_DIR>/simulator/src/dist/output. Do not import as Gradle project if offered.

Discard products

The following Gradle command will delete the files generated by $ gradle idea. Note that <ROOT_DIR>.iws file will not be deleted. Also, if the project is left open in the IDE, the deleted files may be automatically regenerated by the IDE.)

$ gradle cleanIdea

You can also instruct the execution of cleanIdea and idea at one time as follows:

$ gradle cleanIdea idea

In this case, idea is executed after cleanIdea.

7-b. For Eclipse

By executing the following Gradle command, configuration files for Eclipse are generated.

$ gradle eclipse

Generated files are listed as follows:

File

<ROOT_DIR>/.project

<ROOT_DIR>/simulator/.classpath

<ROOT_DIR>/simulator/.project

<ROOT_DIR>/simulator/.settings

With Eclipse, select File -> Open Projects from File System and select <ROOT_DIR> as Import source. Check the listed two Eclipse projects, and click Finish. <ROOT_DIR>/simulator and <ROOT_DIR> will be imported as a project respectively.

Then, you can run the simulator with the IDE. For example, select the simulator project from Package Explorer, right-click and execute Run As -> Java Application to start the simulator. Output files will be stored in <ROOT_DIR>/simulator/src/dist/output.