Skip to content

Beacon chain simulator

Jump to bottom
Mikhail Kalinin edited this page Mar 11, 2019 · 24 revisions

A simulator is a tool that runs a standalone beacon chain instance with a number of assumptions and limitations. The main goal of simulator is to try beacon chain consensus algorithms executing in different circumstances like with a 100% honest validator set and some bad actors in it, network drops and delays. The other goal is to measure performance, check out bottlenecks and look for ways of design improvement and optimizations.

Parameters

There is a number of parameters affecting beacon chain runtime. Some of them are hard coded in the simulator but valuable consensus parameters are configurable by the user.

Built-in parameters

There is a set of immutable simulation parameters:

  • time - beacon chain time is driven by a routine called ControlledSchedulers which method addTime adds a slot to overall system time and processes all the events that correspond to this time slot; during simulation addTime is triggered by infinite loop adding 1 millisecond in each iteration.
  • thread model - all the system (including all peers asynchronous tasks) runs on a single main thread. This makes the simulator runs deterministic (alongside with fixed random seed) and preserves same behaviour across different runs.
  • network - there is a special storage in memory that aids network simulation; attestations and blocks are simply propagated to all peers in the "network".
  • database - simulator doesn't store anything on disk, each time it starts with clean in-memory database.
  • eth1 chain - simulator starts with a set of initial validators defined by user, validator registration is not handled by simulation.

Configurable parameters

  • genesis-time - sets Genesis time in seconds using Unix timestamp notation.
  • seed - an integer number that will be used as a seed to generate credentials of initial validator set, if not specified random value will be used; setting this parameter preserves validator credentials between simulations. Taking into account the single-threaded model different runs with same seed should be absolutely identical.
  • bls-verify - whether BLS verification is enabled during simulation or not, disabled by default; this flag doesn't affect BLS signature creation, it only skips its verification part allowing simulation to run faster.
  • beacon chain parameters - values of beacon chain constants defined by the spec could be overridden.
  • peers - describes groups of peers with different behavior that are participating in simulation.

Peer groups

  • validator - a flag indicating whether this is a validator group or chain observers that passively imports the chain.
  • count - number of peers in the group.
  • blsPrivateKey - sets the specific validator key. count should be equal to 1 if this option is not null. null means the personal keypair will generated for each peer in this group
  • systemTimeShift - system clock shift for this peer(s) in milliseconds.
  • wireInboundDelay - network lag of inbound messages for this peer(s) in milliseconds.
  • wireOutboundDelay - network lag of outbound messages for this peer(s) in milliseconds.

Installation guide

Prerequisites

To run a simulator you need to install Java 8 or later. There are many guidelines in Internet, even the official one, from Oracle.

Build from sources

Clone the repo and execute build command:

git clone https://github.com/harmony-dev/beacon-chain-java.git
cd beacon-chain-java
./gradlew clean build -x test

Unpack the distribution:

unzip start/cli/build/distributions/cli-0.1.0.zip

Use default setup to check it out:

cd cli-0.1.0/bin
./simulator run default

Run simulation

To run simulation with simple plan create plan.yml file:

genesis-time: 600
peers:
  - count: 64
    validator: true

Then execute following command to start simulation:

./simulator run plan.yml

Do not wait too long, just cancel that run cause it's gonna take a while before something shows up in the output.

Disable BLS verification and set random seed:

genesis-time: 600
bls-verify: false
seed: 1
peers:
  - count: 64
    validator: true

Re-run the command, the output should be similar to:

./simulator run plan.yml 
18:39:23.135 #  INFO  - Simulation parameters:
---
peers:
- count: 64
  validator: true
seed: 1
bls-verify: false
genesis-time: 600

18:39:24.485 #  INFO  - Creating validators...
[DEBUG] (main) Using Console logging
18:39:35.747 #  INFO  - Validators created
18:39:35.926 #  INFO  - Creating observer peer...
18:39:36.089 #  INFO  - Time starts running ...
18:39:50.922 #  INFO  - Slot 1, committee: [ShardCommittee[1: [16]]], blocks: 2, attestations: 2, peers states differ:  5bee3827: 1 peers, 00000000: 1 peers, 5214b336: 65 peers
18:40:06.414 #  INFO  - Slot 2, committee: [ShardCommittee[2: [17]]], blocks: 1, attestations: 1, peers states differ:  52182f4c: 1 peers, 27062150: 65 peers
18:40:23.699 #  INFO  - Slot 3, committee: [ShardCommittee[3: [35]]], blocks: 1, attestations: 1, peers states differ:  e1df0cc2: 1 peers, 87e0fbee: 65 peers
Clone this wiki locally