SimBlock User Guide

1. Environment requirements

SimBlock is available on operating systems such as Windows, MacOS, Ubuntu Linux or any Unix platform that supports Java.
It requires JDK and Gradle with the following versions.

Note that the repository of SimBlock includes Gradle wrapper so that you can also install Gradle automatically (we mention it later).

Software	Version
JDK	1.8.0 or later
Gradle	5.1.1 or later

2. Download

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

Release list: https://github.com/dsg-titech/simblock/releases
Command for clone: $ git clone git@github.com:dsg-titech/simblock.git

2-a. Directory structure

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

Hereafter, the name of the root directory of the unzipped or cloned repository is denoted as <ROOT_DIR>.

First, open a terminal software (e.g., xterm, command prompt, etc.) and move to <ROOT_DIR>.

3-a. If Gradle is installed

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

$ gradle build

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

<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
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.

3-b. If Gradle is not installed

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

$ gradlew build

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

3-c. Discard build products

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

$ gradle clean

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

$ gradle clean build

In this case, build is executed after clean.

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.

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. Simulator parameter

Parameter	Location of definition	Description
List of region	BlockChainSimulator.settings.NetworkConfiguration#REGION_LIST	Regions where nodes can exist.
List of latency	BlockChainSimulator.settings.NetworkConfiguration#LATENCY	List of latency assigned to each region. (unit: millisecond)
List of upload bandwidth	BlockChainSimulator.settings.NetworkConfiguration#UPLOAD_BANDWIDTH	List of upload bandwidth assigned to each region. (unit: bit per second)
List of download bandwidth	BlockChainSimulator.settings.NetworkConfiguration#DOWNLOAD_BANDWIDTH	List of download bandwidth assigned to each region. (unit: bit per second)
Distribution of region	BlockChainSimulator.settings.NetworkConfiguration#REGION_DISTRIBUTION	The distribution of node's region. Each value means the rate of the number of nodes in the corresponding region to the number of all nodes.
Distribution of degree	BlockChainSimulator.settings.SimulationConfiguration#DEGREE_DISTRIBUTION	The cumulative distribution of number of outbound links. Cf. Andrew Miller et al., "Discovering bitcoin's public topology and influential nodes", 2015.
Number of nodes	BlockChainSimulator.settings.SimulationConfiguration#NUM_OF_NODES	The number of nodes participating in the blockchain network.
Routing table	BlockChainSimulator.settings.SimulationConfiguration#TABLE	The kind of routing tables.
Block interval	BlockChainSimulator.settings.SimulationConfiguration#INTERVAL	The expected value of block generation interval. The difficulty of mining is automatically adjusted by this value and the sum of mining power. (unit: millisecond)
Average mining power	BlockChainSimulator.settings.SimulationConfiguration#AVERAGE_MINING_POWER	The average mining power of each node. Mining power corresponds to Hash Rate in Bitcoin, and is the number of mining (hash calculation) executed per millisecond.
Standard deviation of mining power	BlockChainSimulator.settings.SimulationConfiguration#STDEV_OF_MINING_POWER	The mining power of each node is determined randomly according to the normal distribution whose average is AVERAGE_MINING_POWER and standard deviation is STDEV_OF_MINING_POWER.
Max block Height	BlockChainSimulator.settings.SimulationConfiguration#END_BLOCK_HEIGHT	The block height when a simulation ends.
Block size	BlockChainSimulator.settings.SimulationConfiguration#BLOCK_SIZE	Block size. (unit: byte)
CBR usage rate	BlockChainSimulator.settings.SimulationConfiguration#CBR_USAGE_RATE	The usage rate of compact block relay (CBR) protocol.
Churn node rate	BlockChainSimulator.settings.SimulationConfiguration#CHURN_NODE_RATE	The rate of nodes that cause churn.
Compact block size	BlockChainSimulator.settings.SimulationConfiguration#COMPACT_BLOCK_SIZE	Compact block size（unit: byte）
CBR failure rate for control node	BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_RATE_FOR_CONTROL_NODE	CBR failure rate for a node that always connect network.
CBR failure rate for churn node	BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_RATE_FOR_CHURN_NODE	CBR failure rate for a node that causes churn.
CBR failure block size distribution for control node	BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_BLOCK_SIZE_DISTRIBUTION_FOR_CONTROL_NODE	The distribution of data size that a control node receives when fails CBR.
CBR failure block size distribution for churn node	BlockChainSimulator.settings.SimulationConfiguration#CBR_FAILURE_BLOCK_SIZE_DISTRIBUTION_FOR_CHURN_NODE	The distribution of data size that a churn node receives when fails 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.

6. Output

The simulator outputs the simulation results to standard output and some files. The file output location is <ROOT_DIR>/simulator/src/dist/out for execution by Gradle command. SimBlock/output for run with build product.

output contents are as follows:

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.

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.

Discard products

The following Gradle command will delete the files generated by $ gradle eclipse.

$ gradle cleanEclipse

You can also instruct the execution of cleanEclipse and eclipse at one time as follows:

$ gradle cleanEclipse eclipse

In this case, eclipse is executed after cleanEclipse.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

usage.md

usage.md

SimBlock User Guide

1. Environment requirements

2. Download

2-a. Directory structure

3. Build

3-a. If Gradle is installed

3-b. If Gradle is not installed

3-c. Discard build products

4. Run SimBlock

4-a. Run with Gradle command

4-b. Run with build product

4-c. Other ways

5. Simulator parameter

6. Output

7. Import to IDE

7-a. For IntelliJ IDEA

Discard products

7-b. For Eclipse

Discard products

Files

usage.md

Latest commit

History

usage.md

File metadata and controls

SimBlock User Guide

1. Environment requirements

2. Download

2-a. Directory structure

3. Build

3-a. If Gradle is installed

3-b. If Gradle is not installed

3-c. Discard build products

4. Run SimBlock

4-a. Run with Gradle command

4-b. Run with build product

4-c. Other ways

5. Simulator parameter

6. Output

7. Import to IDE

7-a. For IntelliJ IDEA

Discard products

7-b. For Eclipse

Discard products