NAV Navbar
shell

Overview

Whiteblock is a full-stack blockchain testing platform that helps development teams quickly test and develop high-performing blockchain solutions.

The Whiteblock platform allows users to provision multiple fully-functioning nodes within a private test network over which they have complete control. Transactions, behaviors, and other application and network logic can be automated as nodes interact in real-time, allowing you to observe the performance of protocols, algorithms, decentralized applications, or changes to system infrastructure prior to deployment.

Each node exists within its own Virtual Local Area Network (VLAN) and is assigned a unique IP address. This provides logical separation between nodes. The links between these nodes can be manipulated and configured with latency, packet loss, and other WAN conditions according to user specification in order to replicate real-world performance with high accuracy.

Use Cases

Features

Blockchain Agnostic Choose from a list of supported blockchain systems to build within a private and controlled testing environment.

Bring Your Own Client If the logic of compiling and deploying your client can be defined within a Dockerfile, Whiteblock’s intuitive framework will generate and apply a custom wrapper during the build process to allow you to test your own system in the testing environment.

Automate Genesis Ceremony Quickly provision a functional blockchain network without the additional hassle of editing a configuration file every time a new test network is provisioned.

Account & Wallet Creation Indicate total number of accounts/wallets to be created within test network.

Pre-allocate Funds Fund wallets and accounts with a specified amount of assets. Start testing right away without the need to wait for mining rewards.

Transactional Logic Indicate the value and volume of transactions to automate activity. Measure transactions per second (TPS) and observe the effects of various environmental conditions on throughput.

Network Behavior Configure Wide Area Network (WAN) conditions between nodes, including latency, packet loss, and bandwidth constraints to replicate real-world performance within a safe and controlled environment.

Data Visualization The Whiteblock Explorer provides insight into TPS, uncle rate, and other relevant data points and performance metrics.

Reporting Generate concise reports to summarize your test cases.

Pipeline Integration Whiteblock seamlessly integrates with your CI/CD platform of choice to reduce development overhead.

Networking

Whiteblock's netconfig module allows you to configure and manipulate the links between nodes in order to emulate a real-world Wide Area Network (WAN) and replicate the conditions you would expect to encounter in a live production network.

Spec Details
Bandwidth Capabilities 10Kbps -1Gbps
Maximum Nodes >1000
Maximum Latency 10000ms
Packet Loss Models Random, Periodic, Burst, BER, Gilbert-Elliot
Time Accuracy Within .01ms

IP Scheme

Each node is provisioned within its own VLAN and assigned a unique address. These IP addresses can be from within the 10.x.x.x range reserved for private internets.

Since Whiteblock uses IPv4, each address will have 32-bits. Unless your Whiteblock environment has a large amount of nodes, the default IP scheme will assign an IP address of 10.1.0.2 to the first node in the network. The second node will be assigned 10.1.0.6. The third will be assigned 10.1.0.10 and so forth. With each consecutive node, the IP address increments by 4.

Multi-Server Environments

If your Whiteblock instance allows for large numbers of nodes (>1000), the services may span across several separate servers.

Within this topology, each server will be assigned a relatively unique serverId. This uniqueness need only apply to servers within your user space.

3 IP addresses are reserved from each subnet. Nodes within the same VLAN are able to route between each other by default.

For simplicity, the following variables will be used

Note the following rules:

A,B,C, and D must be greater than 0. D must be at least 2.

ceil(log2(A)) + B + C + D <= 32

Formula Detail
(2^B) The maximum number of servers.
(2^C) The number of cluster in a given server.
(2^D - 3) How many nodes are groups together in each cluster.
(2^D - 3) * (2^C) The max number of nodes on a server.
(2^D - 3) * (2^C) * (2^B) The maximum number of nodes that can be provisioned on the Whiteblock platform.

Clusters

Each cluster corresponds to a subnet, network of nodes, and VLAN. Nodes within the same cluster will have minimal latency applied to them. In the majority of cases it is best to just have one node per cluster, allowing for latency control between all of the nodes.

Logic

Bearing in mind the variables described in previous sections, given a node number X and a serverId of Y, Let Z be the cluster number, and I be the generated IP in big-endian:

Z = floor(X / (2^D - 3))) I = (A * 2^(B+C+D) ) + ( Y * 2^(B+C) ) + (Z * 2^C) + (X % (2^D - 3) + 2)

if Z == (2^C - 1) then I = I - 2

Explanation

After identifying the cluster of which the node is a member, the IP is calculated one segment at a time through addition. Due to the restrictions, each piece will fit neatly into place without overlap or risk of collision. Finally, we check if it is not the last cluster on the server and add 1 to the ip address if this is true.

Nodes

Within the Whiteblock platform, nodes are provided as application containers. The core of the node engine implements an intelligent wrapper for Docker containers in combination with a suite of proprietary testing libraries and additional logic engines.

This pattern allows the Whiteblock platform to provide a highly configurable environment without the resource intensive overhead associated with tradtional virtual machines. However, it's important to note that although the core engine of Whiteblock does rely on certain components mounted as Kernel-based Virtual Machines (KVM), the nodes themselves are not in KVM, but a slightly more robust and complex Docker container than you may be used to.

Naming Conventions

By default, each node is named whiteblock-node*N* where N indicates the node number. The Whiteblock platform uses zero-based numbering where the first node in the system is assigned an index of 0 rather than 1 in the sequence of nodes. As such, the first node in the network will be named whiteblock-node0, the second node in the network will consecutively be named whiteblock-node1, and so forth.

User Access

After the onboarding process, you will be able to add your ssh public key, to access the platform. If you need help with ssh keys, see Githubs tutorial on ssh.

SSH Access

Once you've been provided with your private key, place it in the appropriate directory and access the platform using the standard ssh command.

$ ssh <ip address>

Linux/Unix users can SSH into the Whiteblock environment using the standard ssh command. Alternatively, you can use an SSH client of your choice. Windows users should refer to the provided Windows documentation to install OpenSSH and do whatever it is Windows users are supposed to do.

If you’ve never used an SSH client before or have limited terminal experience, there are several open-source utilities available. PuTTY is a free and reliable client. Another alternative is MobaXterm but it is not free.

Custom Images

Beyond the default images that are included with the Whiteblock platform, you can use your own custom images. The docker images currently must just meet the platforms requirements, and of course, have the client you wish to run.

Operating System Requirements

Suggested Operating Systems

Supported Operating Systems

Almost any Linux based operating system is supported, as long as it has the ability to run the required packages listed in the next section.

Package Requirements

Debian

Debian

sudo apt update && sudo apt-get install -y iputils-ping openssh-server iperf3

Package Suggestions

Debian

Debian

    sudo apt update && sudo apt-get install -y tmux ca-certificates

Command Line Interface

After establishing an SSH connection, you will be greeted with the following output. Try getting started with the whiteblock build command!

---------------------------------------------------
---- The Scalable Blockchain Testing Platform ----
          _     _ _       _     _            _
__      _| |__ (_) |_ ___| |__ | | ___   ___| | __
\ \ /\ / /  _ \| | __/ _ \ '_ \| |/ _ \ / __| |/ /
 \ V  V /| | | | | ||  __/ |_) | | (_) | (__|   <
    \_/\_/ |_| |_|_|\__\___|_.__/|_|\___/ \___|_|\_\

--------------- Whiteblock v.1.5 -----------------
Documentation: docs.whiteblock.io
Support: [email protected]
Telegram: t.me/whiteblockio
---------------------------------------------------
Last login: Sat Jan 3 18:15:05 2009 from 151.80.37.67

[email protected]:~$

The CLI application allows you to interact and send commands to the Whiteblock platform through your computer's terminal or command-line shell. A variety of commands are available to help you easily deploy a private blockchain test network within the Whiteblock testing environment and control or automate processes, behaviors, and actions. It has been designed to provide an intuitive user experience without requiring complex commands or advanced engineering knowledge.

CLI Reference

`$ whiteblock [COMMAND] [SUBCOMMAND] [FLAG] `
Commands Details
build provisions nodes running selected blockchain client, peers nodes, configures blockchain network, generates accounts, funds wallets, and automates various actions like genesis ceremony, depending on client specified.
console Logs into the client console
done Tears down the testnet
get shows various statistics related to network/blockchain performance; block count, transactions per second, uncle rate, etc.
iperf network performance measurement tool that measures IP throughput between nodes, measures bandwidth capacity, and packet loss.
miner Run miner commands.
netconfig network emulation engine that applies network conditions and impairments to the links between nodes.
ping sends ICMP ping command between two nodes to measure round-trip time and check if they’re able to respond to each other.
restart Attempt to restart a node
scp securely copies a file between Whiteblock master environment and node(s).
ssh logs in to nodes CLI to execute remote commands.
test Run test cases.
tx Run transaction commands.
version displays current version of Whiteblock CLI application.

build

The build command allows you to create and deploy a blockchain with a specified number of nodes that are each running the client of your choice. You can also indicate the amount of computational resources that should be reserved for each node consumes and also customize the configuration parameters for the blockchain client they're running.

Command

whiteblock build [subcommand] [flags]
Flags Type Details
-b, --blockchain string blockchain client each node will run.
-c, --cpus int number of vCPUs that will be assigned to each node.
-e, --env stringToString set environment variables for the nodes
-f, --file string parameters file
--freeze-before-genesis indicate that the build should freeze before starting the genesis ceremony
-i, --image string custom image or internal build build tag
-m, --memory int amount of RAM that will be assigned to each node.
-n, --nodes int number of nodes that will be provisioned within the network.
-o, --option stringToString blockchain specific options
-s, --servers string display server options
-t, --template stringToString Set a custom file template
-v, --validators int set the number of validators.
-y, --yes accepts all prompts and defers to default settings.

Required Parameters

In order to successfully execute, the build commands requires that you at least define the type of blockchain and the number of nodes you'd like to build in the network. If these values aren't explicitly provided, you won't be able to do anything and your own lack of creation will leave you trapped in a lifeless world.

Parameter Valid Arguments
Blockchain Geth, Parity, Pantheon, Syscoin, Rchain, EOS, Artemis, Beam, Cosmos or Custom
Nodes An integer value to indicate the number of nodes that will be built in the network. This number is limited by the Genesis plan to which you're subscribed.
Cpus The max CPU resource that a node can use
Memory The max RAM a node can use

There are two ways to specify build values: Command line flags or Build Wizard. Both of these methods are described as follows.

Command Line Flags

Example 1

whiteblock build -b ethereum -n 100 -c 4 -m 30gb -y

Example 1 would build an Ethereum network with 100 nodes, each with 4 CPUs and 30GB RAM:

The build commands accepts command line flags that allow you to define parameters, without the need for interactive input

You can indicate the value of these variables by appending the appropriate flag to the whiteblock build command.

Build Wizard

$ whiteblock build
blockchain (default):
nodes(default):
cpus(default):
memory(default):
Use default parameters? (yes/no)

The Build Wizard is an interactive module that allows you to indicate the values that will be used when building the blockchain network. If you run the build command without additional flags or if you neglect to indicate one or more required parameter needed in the build process, you will be dropped into the Build Wizard to define those parameters.

The values expected by the Build Wizard may change based on the blockchain client you've indicated. These details will be included in each client's respective section in this documentation.

Build Process

The output of the build command will help you keep track of the build process and display a percentage to indicate the current step in the build progress and a percentage for completion.

Build Started successfully: 64db8674-c0bc-4c86-9577-43d210551787
Configuring Network 11.718750% completed

After configuring the parameters with the build command, the build process will begin. This process could take several minutes, depending on the client that you're building and the computational resources that are available within your environment and assigned to each node. Whiteblock will be provisioning the nodes, configuring the client, creating and funding wallets/accounts, peering nodes, and automating other blockchain critical processes so you don't have to.

The output will indicate a percentage which indicates build progress. During this time period, it's recommended that you avoid clearing the terminal and maybe grab a snack, watch a video on YouTube, or go over your test plan.

During the build, on POSIX signal compatible systems, you are able to control the build with the following key bindings:

Control Sequence What it do
CTRL-C Cancels the in progress build
CTRL-Z Freezes the current build. You can resume using the fg command
CTRL-\ Exits the build command without any side effects

Custom Configuration Files

We support the ability to use a custom configuration file or a custom configuration file template. To view the files you can customize, you can use whiteblock get configs. To replace one of these files, you can use the -t flag like -t <file you wish to override>=<your custom configuration file>. If you plan on providing a custom configuration template, then you should query whiteblock get configs <blockchain> params.json to see what options you will be provided with. We use mustache for our file template, so let's say you have a parameter called "name", {{{name}}} in your config file will be replaced with the value of name.

Example: Using a custom genesis file template for geth

$ whiteblock build -b geth -n 3 -t"genesis.json=./mygenesis/json" 

Setting Custom Environment Variables

Sometimes you may wish to set up custom environment variables for the current client. The platform supports the ability to set environment variables for all nodes and/or specific nodes.

Example: Setting FOO to 1 for all nodes

$ whiteblock build -b geth -n 3 -e"FOO=1"

Example Setting BAR to 2 for nodes 2 and 4

$ whiteblock build -b geth -n 3 -e2"BAR=2" -e4"BAR=2"

Example Setting FOO to 1 for all nodes and setting BAR to 2 for nodes 1 and 3

$ whiteblock build -b geth -n 3 -e"FOO=1" -e1"BAR=2" -e3"BAR=2"

attach

Attach to a current in progress build process.

        whiteblock build attach
        Configuring Network 11.718750% completed

freeze

Freeze the set in progress build

        whiteblock build freeze

previous

Run the previous build, with some limitations. It will not include previous user specified files, with the exception of the file imported using the --file flag during the build process. The CLI will prompt you yes/no with a preview of what will be built unless provided with the -y flag

$ whiteblock build unfreeze

stop

Stop the current in progress build.

$ whiteblock build stop

unfreeze

Unfreeze the set in process build

$ whiteblock build unfreeze

console

Attach a console to the node command. This command is not supported for most blockchains and currently only Geth supports this command.

$ whiteblock console <node>

done

Tears down the constructed testnet. Building automatically implies tear down, so there is no need to use this command before going through the build process.

$ whiteblock done

get

The get command offers several general subcommands which output network and performance data.

Command

$ whiteblock get <command> 
Command Description
account displays account information.
block displays block data.
configs Get the resources for a blockchain
contracts Get contracts deployed to network.
default displays default configuration for the blockchain client.
log dumps data logs for a specific node.
nodes lists all nodes in the network.
running Will check if a test is running.
stats displays performance stastics.
tx outputs transactional data.

Account

Get information about the accounts

Command Description
info Get all accounts and some information about them

Command

$ whiteblock get account <command>

Get account information

$ whiteblock get account info
[
    {
        "account": "0x4dac3fdbb96e8089c762d783968ae7a4dbf1f067",
        "balance": "3364062500000000000000",
        "txCount": "0"
    },
    {
        "account": "0xcb901724d34fcccc44b373981f02546d521e8faf",
        "balance": "3470000000000000000000",
        "txCount": "0"
    },
    {
        "account": "0xb4ddf0482f5132e82100c48b0338bc9c02cf4f6f",
        "balance": "3781250000000000000000",
        "txCount": "0"
    }
]

block

Get block information.

Command

$ whiteblock get block <command | block number>

Command Description
info Get the information about a block
number Get the block number

Example 1

$ whiteblock get block 12
{
    "difficulty": "0x20240",
    "extraData": "0xd883010900846765746888676f312e31302e34856c696e7578",
    "gasLimit": "0x3dc106",
    "gasUsed": "0",
    "hash": "0xf9f8198c5427c1dbaf3891e19314ec44418623af41ad14e8d66a94e01f813206",
    "logsBloom": "0x000000000000000000000000000000000000000000000000000000000000000000000",
    "miner": "0xb4ddf0482f5132e82100c48b0338bc9c02cf4f6f",
    "nonce": "0x4c253a8291b6d5b0",
    "number": "0xc",
    "parentHash": "0xf4b8b07069bbf167921c645c1ff904abaad7355f6a90dbb0ccd35d848b75fb41",
    "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "size": "0x218",
    "stateRoot": "0x09ca7da6f50ed5794ecb900785245d9fb60ad6d6951e8757ab427f4c576b1ce9",
    "timestamp": "0x5c3fe8e2",
    "totalDifficulty": "0x199260",
    "transactions": [],
    "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc0016225e363b421",
    "uncles": []
}

Example 1 gets information about block 12

Example 2

$ whiteblock get block number
3232

Example 2 gets the current block height of the network

configs

Get the resources for a blockchain.

        whiteblock get configs <blockchain> [file]

contracts

Get contracts deployed to network.

$ whiteblock get contracts

default

Get the blockchain specific parameters for a deployed blockchain. Returns the params as a list of key value params, of name and type respectively

Command

$ whiteblock get default <blockchain>

Example 1:

$ whiteblock get default ethereum
{
    "chainId": 15468,
    "difficulty": 100000,
    "eip155Block": 0,
    "eip158Block": 0,
    "gasLimit": 4000000,
    "homesteadBlock": 0,
    "initBalance": 100000000000000000000,
    "maxPeers": 1000,
    "networkId": 15468
}

log

Get stdout and stderr from a node's blockchain process.

Flag Type Description:
-t, --tail int gets the last x lines of log

Command:

$ whiteblock get log <node> [flags]

Example 1:

$ whiteblock get log 0

Example 1 gets the full log of node 0.

Example 2:

$ whiteblock get log 1 --tail 10

Example 2 gets the last 10 lines of the log of node 1

Example 3:

$ watch wb get log 0 --tail $(tput lines)

Example 3 shows how the follow feature can be implemented using standard linux commands with the whiteblock utility

Example response:

$ whiteblock get log 0 --tail 6
coinbase: 0x0b7ed53df19776902d12d4c962423271c3975c2d
at block: 0 (Thu, 01 Jan 1970 00:00:00 UTC)
 datadir: /whiteblock/node1
 modules: admin:1.0 debug:1.0 eth:1.0 ethash:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0

>

nodes

Gets information on the nodes in the network, including its ip address, cpu usage, server and status.

Command:

$ whiteblock get nodes

Example Response: json [ { "cpu": 251.2, "ip":"10.1.0.2", "name": "whiteblock-node0", "server": 1, "up": true }, { "cpu": 257.3, "ip":"10.1.0.6", "name": "whiteblock-node1", "server": 1, "up": true }, { "cpu": 240.3, "ip":"10.1.0.10", "name": "whiteblock-node2", "server": 1, "up": true } ]

Aliases: nodes, node

running

Running will check whether or not a test or process is running. If true, it will output the test's name and information.

Response: true or false, on whether or not a test is running; The name of the test or nothing if there is not a test running.

Command

$ whiteblock get running

Example response:

true
pantheon transactions

stats

Stats will allow the user to get statistics regarding the network.

Commands Details:
all Will get all statistics of a blockchain
block Will get statistics of a blockchain
past Will get statistics of a blockchain from the past x blocks

Command

$ whiteblock get stats <command> [FLAGS]

Example all

$ whiteblock get stats all
{
    "blockTime": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "difficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasLimit": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasUsed": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "totalDifficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "tps": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "transactionCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "uncleCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    }
}

Example past

$ whiteblock get stats past 10
{
    "blockTime": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "difficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasLimit": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasUsed": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "totalDifficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "tps": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "transactionCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "uncleCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    }
}

Example block

$ whiteblock get stats block 10 20
{
    "blockTime": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "difficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasLimit": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "gasUsed": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "totalDifficulty": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "tps": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "transactionCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    },
    "uncleCount": {
        "max": 0,
        "mean": 0,
        "standardDeviation": 0
    }
}

tx

Get a transaction by its hash. The user can find the transaction hash by viewing block information. To view block information, the command 'get block [block number]' can be used.

Commands Details:
info Get transaction information

Params: The transaction hash

Command

$ whiteblock get tx <command>

info command

$ whiteblock get tx info <hash>

info example shell $ whiteblock get tx info 0x9fc76417374aa880d4449a1f7f31ec597f00b1f3dd2d66f46d8b

{
 "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
 "nonce": 2,
 "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
 "blockNumber": 3,
 "transactionIndex": 0,
 "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
 "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",
 "value": "0x01123232",
 "gas": 314159,
 "gasPrice": "0x0974342d",
 "input": "0x57cb2fc4"
}

iperf

Configures the specified nodes in the network to act as client/server between one another in order to measure the maximum bandwidth between them and report MSS/MTU size. The syntax of this command is similar to the ping command where both node numbers are specified by number.

When running, the iperf command will configure the specified nodes as client/server. The default IP protocol is IPv4. The data stream packets can be either Transmission Control Protocol (TCP) or User Diagram Protocol (UDP). Use this tool to diagnose and measure the links between nodes.

Flag Type Description:
-b, --bandwidth string set target bandwidth in bits/sec (default 1 Mbit/sec); requires udp enabled
-d, --dualtest enable bidirectional test simultaneously
-t, --time string how long to run test for
-u, --udp enable udp

Command

$ whiteblock iperf <client node> <server node> [flags]

Example 1

$ whiteblock iperf 0 1

Example 1 runs iperf between node 0 and 1

miner

Starts/stops mining for some or all nodes

Commands Details:
start Start mining on all or some nodes
stop Stop mining on all or some nodes

start

Command

$ whiteblock miner start [node 1]...[node n]

stop

Command

$ whiteblock miner stop [node 1]...[node n]

netconfig

$ whiteblock netconfig <command>...
Flag Type Details:
-b, --bandwidth int Specifies the bandwidth of the network in megabytes per second
-d, --delay int Specifies the latency to add in milliseconds
-m, --limit int Sets packet limit (default 1000)
-l, --loss float Specifies the amount of packet loss to add as a percentage

The Whiteblock netconfig module is a high-performing network emulation engine which forwards packets, routes TCP/IP traffic between nodes and their respective networks, and can apply common network impairments to these links.

all

Command:

$ whiteblock netconfig all [flags]

Example:

$ whiteblock netconfig all -d 100 -b 100 -l 0.5

The provided example command tells the netconfig module to apply 100ms latency, 100 MBps bandwidth, and 0.5% packet loss for all nodes.

set

Command:

$ whiteblock netconfig set <node> [flags]

Example:

$ whiteblock netconfig set 0 -d 100 -b 100 -l 0.5

The provided example command tells the netconfig module to apply 100ms latency, 100 MBps bandwidth, and 0.5% packet loss for node 0. Packet loss is represented as a percentage and the expected argument expects a decimal value where 0.1 would represent a value of 0.1% packet loss.

$ whiteblock netconfig loss 0.01

The provided example command tells the netconfig module to apply 0.01% packet loss to the network.

clear

Removes network conditions from the entire network

Clear Command:

$ whiteblock netconfig clear

Example:

$ whiteblock netconfig clear

restart

Attempt to restart a node. First kills a node using the signal SIGINT, then wait for the process to terminate before reruning the nodes command again. Effectively restarting the node.

ping

The ping command is a simple implementation of the standard network diagnostic tool of the same name that's found on many computer. It's used to send an Internet Control Message Protocol (ICMP) Echo Request to a specific interface on a network in order to determine whether it is available, responsive, and can accept requests. In the context of the Whiteblock platform, the ping command allows one node to check and see if it can communicate with another node. More imperatively, you can use ping to measure the amount of latency or packet loss between nodes.

To ping between nodes, simply indicate the requesting and responding node numbers as an integer value.

Command

$ whiteblock ping <sender> <receiver>

Example 1

$ whiteblock ping 1 3

Example 1 sends ICMP pings from node 1 to node 3.

scp

To send a file named hello.sol from the a directory named /contracts in the master environment to the root directory of node 6:

$ whiteblock scp 6 /contracts/hello.sol /

The scp command allows you to securely copy files from the Whiteblock master environment to a specified node in the network.

whiteblock scp <node number> </file/to/send/path> </destination/path>

This command is useful for providing specific configuration files for individual nodes or deploying smart contracts.

ssh

The ssh command allows you to access the command line console for a specific node or provide a command you'd like a node to execute.

Command

    whiteblock ssh <node number> [command]

Example 1

$ whiteblock ssh 1

Example 1 tunnels the user into node 1 via ssh

Sending Remote Commands

To remotely execute a command on node 3 that deploys a smart contract in Rchain:

$ whiteblock ssh 3 rnode deploy --phlo-limit 2000 --pholo-price 1000 /contracts/dupe.rho file>

To send a command that you would like a specific node to execute, provide the command after the ssh command.

test

Runs a user defined test with the given whiteblock file.

Command

$ whiteblock test <file>

tx

Automate the sending of transactions

Commands Details:
send Sends a single transaction
start Send transactions
stop Stop transactions

send

Sends a single transaction via the given node, between two accounts

Command

$ whiteblock tx send --from <address> --destination <address> --value <amount> [flags]
Flag Type Details:
-d, --destination string Specifies where the transaction will be sent to
-f, --from string Specifies where the transaction will be sent from
-g, --gas string Specifies gas for tx
-p, --gasprice float Specifies gas price for tx
-n, --node int Specifies node to send tx
-v, --value float Specifies amount to send in the transaction

start

Start sending multiple transactions.

Command

$ whiteblock tx start <command>
Commands Details:
burst Send burst transactions
stream Send continuous transactions

start burst

Sends one burst of transactions to the blockchain to fill the transaction pool.

Command

$ whiteblock tx start burst --txs <number of tx> --value <value> [flags]
Flag Type Details:
-d, --destination string Specifies where the transaction will be sent to
-s, --size int Specifies the size of the transaction in bytes
-t, --txs int Specifies amount of transactions to send in the burst
-v, --value int Specifies amount to send in the transaction

start stream

This command will start sending a continual stream of transactions according to the given flags. Stream will send transactions as a continuous flow of tps. The user will need to run the command tx stop to stop running transactions.

Command

$ whiteblock tx start stream --tps <tps> [flags]
Flag Type Details:
-d, --destination string Specifies where the transaction will be sent to
-s, --size int Specifies the size of the transaction in bytes
-t, --tps int Specifies the transactions per second
-v, --value int Specifies amount to send in the transaction

stop

Stop the transactions.

Command

whiteblock tx stop [flags]

version

The version command allows you to check which version of Whiteblock Genesis you're currently running.

Command

whiteblock version

Example Result

whiteblock 1.5.7

RPC Interface

In order to allow a full range of accessibility to the platform, the router uses a WebSocket interface and an http interface. Both use json rpc Websocket interaction is done through the socket io protocol, client libraries for this can be found here.

The websocket rpc path is both / and /socket.io/

The http rpc path is /rpc

Non-Secure Connections are, by default, over port 5000 and localhost only.

Secure Connections are, by default, over port 5001 and exposed to all interfaces.

Generics

add_commands

Add commands to rpc. Takes an object representing the blockchain and commands to add

Params Format

{    
    "namespace":<short name for the blockchain>,
    "blockchain":<long name for the blockchain>,
    "port":<port which the rpc server is listening on>,
    "calls":<map of known functions to the rpc calls>
}

Example

{
    "jsonrpc": "2.0",
    "method": "add_commands",
    "params": {
        "namespace": "geth",
        "blockchain": "go-ethereum",
        "port": 8545,
        "calls": {
            "get_block_number": {
                "name": "eth_blockNumber",
                "type": "json_rpc2"
            },
            "mining": {
                "name": "eth_mining",
                "type": "json_rpc2"
            }
        }
    },
    "id": 3
}

run_tests

Runs the given rpc function and then optionally checks the result. Runs each test in index order. The result will either be a success message or the error object passed to the testing module.

Example Params

[
    {
        "function":"get_block_number",
        "times":5,
        "arguments":[],
        "delay":0,
        "check":true,
        "checks":[
            {
                "type":"regex",
                "data":"[0-9]*",
                "invert":false,
                "dom_path":["result"]
            }
        ]
    }
]

Stats

charts

Get the data for the front end charts, given a JSON object representing the blocks to retrieve data for. Set the end to -1 to get up to the current.

Params Format

{"start":<start point,inclusive>,"end":<end block,exclusive>}

Example Params

{"start":1,"end":1000}

Example Result

[
    {
        "blockNumber":553,
        "blockTime":1,
        "numberOfTransactions":1,
        "numberOfUncles":0,
        "gasLimit":6861391,
        "gasUsed":21000,
        "difficulty":1301725,
        "totalDifficulty":632292281,
        "size":651,
        "miner":"0x47a3d6ea062083945f080a509234f771b26a99a9"
    }
]

stats

get specific stats. Set startTime to 0, to default to using the block numbers

Params Format

{"startTime":<unix time stamp>,"endTime":<unix time stamp>,"startBlock":<block number>,"endBlock":<block number>}

Example

{
    "jsonrpc": "2.0",
    "method": "stats",
    "params": {
        "startTime": 0,
        "endTime": 0,
        "startBlock": 3,
        "endBlock": 20
    },
    "id": 3
}

Example

{
    "jsonrpc": "2.0",
    "method": "stats",
    "params": {
        "startTime": 1542825482,
        "endTime": 1542840263,
        "startBlock": 0,
        "endBlock": 0
    },
    "id": 3
}

Example Response

{
    "difficulty":{
        "max":1002271,
        "standardDeviation":2121.3641248027275,
        "mean":999010
    },
    "totalDifficulty":{
        "max":20020556,
        "standardDeviation":4606480.1924615465,
        "mean":12518222.9375
    },
    "gasLimit":{
        "max":4074846,
        "standardDeviation":18194.434054363843,
        "mean":4045176.9375
    },
    "gasUsed":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "blockTime":{
        "max":10,
        "standardDeviation":2.250925735484551,
        "mean":3
    },
    "transactionCount":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "uncleCount":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "tps":{
        "max":0,
        "standardDeviation":0,
    "mean":0
    }
}

all_stats

Get the current overtime chain statistics

Example

{
    "jsonrpc": "2.0",
    "method": "all_stats",
    "params": null,
    "id": 3
}

Example result

{
    "difficulty":{
        "max":1002271,
        "standardDeviation":2121.3641248027275,
        "mean":999010
    },
    "totalDifficulty":{
        "max":20020556,
        "standardDeviation":4606480.1924615465,
        "mean":12518222.9375
    },
    "gasLimit":{
        "max":4074846,
        "standardDeviation":18194.434054363843,
        "mean":4045176.9375
    },
    "gasUsed":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "blockTime":{
        "max":10,
        "standardDeviation":2.250925735484551,
        "mean":3
    },
    "transactionCount":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "uncleCount":{
        "max":0,
        "standardDeviation":0,
        "mean":0
    },
    "tps":{
        "max":0,
        "standardDeviation":0,
    "mean":0
    }
}

Emulate

netem

Set network conditions for individual nodes

Params Format

[<testnet id>,<condition 1> ,<condition 2>...]

Example params

[
    "a24a67c1-bc98-423a-ad3f-87eff5b9fa54",
    {
        "node":0,
        "limit":1000,
        "loss":0.1,
        "delay":10,
        "rate":"10mbps"
    },
    {
        "node":1,
        "limit":1000,
        "loss":0.2,
        "delay":15,
        "rate":"10mbps"
    },
]

netem_all

Set network conditions for all nodes

Params Format

[<testnet id>,<condition>,[condition2 ...]]

Example params

[
    "a24a67c1-bc98-423a-ad3f-87eff5b9fa54",
    {
        "limit":1000,
        "loss":0.1,
        "delay":10,
        "rate":"10mbps"
    }
]

netem_delete

Turn off emulation, returning whether or not turning it off was successful

Params Format

[<testnet id>]

Example params

    ["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

Build

nodes

Get the nodes in the network.

Example Result

    [{"name":"whiteblock-node0","server":1,"ip":"10.1.0.2"}]

get_servers

Get the availible servers as a JSON mapping

Example Result

{
  "cloud": {
    "addr": "127.0.0.1",
    "id": 1,
    "ips": null,
    "max": 200,
    "nodes": 0,
    "subnetID": 1
  }
}

get_testnet

Get the test net

Params Format

[<testnet id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

get_resources

Get the resources used for a given blockchain or a file's contents depending on the number of arguments

Params Format

[<blockchain> ,[ file name]]

get_build

Fetches the build as stored in genesis, by the given testnet id

Params Format

[<testnet id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

delete_testnet

Delete a testnet by id * Response: Success or an error

Params Format

[<testnet id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

build

Builds out the network according to the given specifications, sets up the infrastructure and does all of the necessary program build steps

Params Format

{
    "servers":<server ids to be built on>,
    "blockchain":<The blockchain to build>,
    "nodes":<Total number of node>,
    "image":<The docker image>,
    "resources":[{"cpus":<The number of cpus to use as a decimal value>,"memory":<The hard memory limit for each node>}..,]
}

Example Params

        {
            "servers":[3],
            "blockchain":"ethereum",
            "nodes":3,
            "image":"ethereum:latest",
            "resources":[{
                "cpus":"2.5",
                "memory":"12gb"
            }],
            "params":{
                "chainId": 12345
            }
        }

Example Result

"dca9c809-09c8-4b39-9099-2dcb3795c776"

get_params

Get the default parameters for a blockchain. Returns the params as a list of key value params, of name and value respectively.

Params Format

    [<blockchain>]

Example Result

[
    ["chainId","int"],
    ["networkId","int"],
    ["difficulty","int"],
    ["initBalance","string"],
    ["maxPeers","int"],
    ["gasLimit","int"],
    ["homesteadBlock","int"],
    ["eip155Block","int"],
    ["eip158Block","int"]
]

get_defaults

Get the blockchain specific parameter defaults for a given blockchain, as a JSON object.

Params Format

[<blockchain>]

Example Response

{
    "chainId":15468,
    "networkId":15468,
    "difficulty":100000,
    "initBalance":100000000000000000000,
    "maxPeers":1000,
    "gasLimit":4000000,
    "homesteadBlock":0,
    "eip155Block":0,
    "eip158Block":0
}

State

status_nodes

Get the status of the currently running nodes, including current cpu usage and whether or not it is up.

Params Format

[<testnet id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

Example Result

[
    {
        "name":"whiteblock-node0",
        "ip":"10.1.0.2",
        "server":1,
        "up":true,
        "cpu":167
    },
    {
        "name":"whiteblock-node1",
        "ip":"10.1.0.6",
        "server":1,
        "up":true,
        "cpu":137
    }
]

state::progress

* Check the progress on a currently running task, returning it as a JSON object.

Example Result

{"progress":0.000000,"stage":""}

state::info

Get state information, mainly useful for debuging, as a JSON object.

state::is_running

Check whether or not there is a test running

Example Result

false

state::what_is_running

Get the name of the currently running test or nothing if there is not a test running

Example Result

"Pantheon Transactions"

Utilities

nodes

Get the nodes on given testnet id as an array of JSON objects.

Params Format

[<build id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

Example Result

[
    {
        "id": 1647,
        "testNetId": 134,
        "server": 3,
        "localId": 0,
        "ip": "10.6.0.2",
        "label": ""
    },
    {
        "id": 1648,
        "testNetId": 134,
        "server": 3,
        "localId": 1,
        "ip": "10.6.0.6",
        "label": ""
    }
]

log

Get stdout and stderr from a node

Params Format

{"testnetid":<testnet id>,"node":<node number>,"lines":<number of lines from end of file>}

Example Result

{"server":4,"node":0}

stop_build

Stop the build corresponding to the given build id

Params Format

[<build id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

Example Result

"Stop signal has been sent"

get_block_number

Get the current highest block number of the chain

Example Result

10

get_block

Get the data of the block corresponding to the given block number as a JSON object

Params Format

[<Block Number>]

Example Params

[10]

Ethereum

These are ethereum specific commands which are implemented natively on the our backend. The namespacing eth:: is optional, as it will be implied if there is an ethereum blockchain built on your testnet.

eth::generate_accounts

Generate the given number of accounts via transactions

Params Format

[<number>]

Example Params

[500]

eth::accounts_status

Get the status of all availible accounts

Example Result

[
    {
        "account":"0xc1e2c3c9bbf790c6298a433462aa5266a428cbaa",
        "balance":"100000000000000000000",
        "txCount":"100"
    }
]

eth::nodes_status

Get the status of all of the nodes

Example Result

[
    {
        "node":0,
        "peers":2,
        "accounts":[
            "0x2a638f57b840159087bb7f54e0a867a2c2289853",
            "0xb40416e9dbd1e2007ab4b9b62660861e8658fa59",
            "0x7013f38b71f4e87ebdb46989219407ea6e52c6d0"
        ],
        "txpool":{
            "pending":"0",
            "queued":"0"
        },
        "hashrate":59973,
        "coinbase":"0x2a638f57b840159087bb7f54e0a867a2c2289853"
    }
]

eth::get_accounts

Get the unlocked accounts as a JSON array

Example Result

[
    "0xbdb3c1c4442ce11bb758828a7b3bf6983e6897c7",
    "0x33e6099c5a45b8b6241919e57f9a773afe682166",
    "0xaaaaf4e8e247a8c05c940ffe76a67c4f5398d9aa"
]

eth::get_balance

Get the current balance of an account in wei

Params Format

[<address>]

Example Params

["0xbfa767eae64753e4c426ea42470abf7e4fc305ab"]

Example Result

100000000000000000000

eth::send_transaction

Send a transaction between two accounts. Returns the transaction hex.

Params Format

[<from> <to> <gas> <gas price> <value> [tx data] [nonce]]

Example Params

[
    "0xbfa767eae64753e4c426ea42470abf7e4fc305ab",
    "0x8d12a197cb00d4747a1fe03395095ce2a5cc6819",
    "0x015f90",
    "0x165a0bc00",
    "0xde0b6b3a7640000"]

Example Result

    "0x402c257c85c398154b8b16fa612df13e197135f63d1be9e03b6d2d55285e8670"

eth::get_transaction_count

Get the transaction count sent from an address, optionally by block

Params Format

[<sending address>,[block number]]

Example Params

    "0xbfa767eae64753e4c426ea42470abf7e4fc305ab"

Example Result

345

eth::get_transaction

Get a transaction by its hash

Params Format

[<hash>]

Example Params

"0x402c257c85c398154b8b16fa612df13e197135f63d1be9e03b6d2d55285e8670"

Example Result. See also Example.

{
    "blockHash":"0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber":"0x5daf3b", 
    "from":"0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gas":"0xc350",
    "gasPrice":"0x4a817c800",
    "hash":"0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "input":"0x68656c6c6f21",
    "nonce":"0x15", 
    "to":"0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionIndex":"0x41", 
    "value":"0xf3dbb76162000", 
    "v":"0x25", 
    "r":"0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea",
    "s":"0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c"
}

eth::get_transaction_receipt

Get the transaction receipt by the tx hash

Params Format

[<hash>]

Example Params

"0x402c257c85c398154b8b16fa612df13e197135f63d1be9e03b6d2d55285e8670"

Example Result. See also Example.

{
     "transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
     "transactionIndex":  "0x1",
     "blockNumber": "0xb", 
     "blockHash": "0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b",
     "cumulativeGasUsed": "0x33bc",
     "gasUsed": "0x4dc", 
     "contractAddress": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", 
     "logs": [{
         // logs as returned by getFilterLogs, etc.
     }],
     "logsBloom": "0x00...0", // 256 byte bloom filter
     "status": "0x1"
}

eth::get_hash_rate

Get the current hash rate per node

Example Result

"0x38a"

eth::start_transactions

Start sending transactions according to the given parameters, value = -1 means randomize value. In order the parameters are: the amount of transactions to send in a second, the value of each transaction in wei, the destination for the transaction. Value can be octal, decimal, or hexidecimal.

Params Format

[<tx/s> <value> [destination]]

Example Params

100 "0xde0b6b3a7640000" "0x8d12a197cb00d4747a1fe03395095ce2a5cc6819"

Example Result

"Started"

eth::stop_transactions

Stops the sending of transactions if transactions are currently being sent

eth::start_mining

Send the start mining signal to nodes, may take a while to take effect due to DAG generation. Will start mining on the given list of the nodes r all nodes if no nodes are given. Responds with the number of miners which are were started.

Params Format

[[node 1 number]...[node n number]]

Example Params

[0,2,3]

Example Result

3

eth::stop_mining

Send the stop mining signal to given nodes or none for all nodes

Params Format

[[node 1 number],[node 2 number]...]

Example Params

[0,1,2,3]

eth::get_recent_sent_tx

Get a number of the most recent transactions sent

Params Format

[[number]]

Example Params

[5]

Example Result

{
   "results":[
      {
         "statement_id":0,
         "series":[
            {
               "name":"transactions",
               "columns":[
                  "time",
                  "from",
                  "gas",
                  "gas_price",
                  "to",
                  "txid",
                  "value"
               ],
               "values":[
                  [
                     "2018-11-08T18:02:59.700086831Z",
                     "0x1949d6d0dfb19048563b602d9a02c06420421429",
                     "0x15f90",
                     "0x3B9ACA00",
                     "0xd9075634d9725f05a1a84343fb40a31d9964ffa5",
                     "0xaffad4a457d79448f211654be8eae1ca6fa8e005936d72528d394fe724adb903",
                     "0xDE0B6B3A7640000"
                  ],
                  [
                     "2018-11-08T18:02:59.698273467Z",
                     "0x1949d6d0dfb19048563b602d9a02c06420421429",
                     "0x15f90",
                     "0x3B9ACA00",
                     "0xd9075634d9725f05a1a84343fb40a31d9964ffa5",
                     "0x8f08bc904c7fbf2e3c695bd71237432137e4f22a20287eda880ed8b409032580",
                     "0xDE0B6B3A7640000"
                  ],
                  [
                     "2018-11-08T18:02:59.655393436Z",
                     "0xd9075634d9725f05a1a84343fb40a31d9964ffa5",
                     "0x15f90",
                     "0x3B9ACA00",
                     "0xe33e509fea81ea03333a3659c98108196ac438a7",
                     "0x21ed0c41959ec9aecf36461cd5b42e65505090e8dbd514ba3b123a3889a5735e",
                     "0xDE0B6B3A7640000"
                  ],
                  [
                     "2018-11-08T18:02:59.651551261Z",
                     "0x1949d6d0dfb19048563b602d9a02c06420421429",
                     "0x15f90",
                     "0x3B9ACA00",
                     "0xd9075634d9725f05a1a84343fb40a31d9964ffa5",
                     "0xfc9b2658bdc95669ffd38e8ff02b9995d894542db52161fbe41ee5dcaed70628",
                     "0xDE0B6B3A7640000"
                  ],
                  [
                     "2018-11-08T18:02:59.628233357Z",
                     "0xd9075634d9725f05a1a84343fb40a31d9964ffa5",
                     "0x15f90",
                     "0x3B9ACA00",
                     "0xe33e509fea81ea03333a3659c98108196ac438a7",
                     "0x15597db936fc88d8a781ea7da6dce1260a05f10070ab75cd8328659d1343390a",
                     "0xDE0B6B3A7640000"
                  ]
               ]
            }
         ]
      }
   ]
}

Syscoin

sys::start_test

Start the propogation/tps test for syscoin

Params Format

    [<seconds to wait> <percentage> <number of assets> <num of tx per asset>]

Example Params

[11,97,10,250]

sys::get_recent_test_results

Get recent test results up to the given number or until the beginning of time

Params Format

[[number]]

Example Params

[5]

Eos

eos::get_info

Roughly equivalent to calling cleos get info on the given node, or node 0.

Params Format

[[node]]

Example Params

[1]

Example Result

{
  "server_version": "2dc8d339",
  "chain_id": "aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906",
  "head_block_num": 52169577,
  "last_irreversible_block_num": 52169250,
  "last_irreversible_block_id": "031c0a22df30109fa81deba3adbf977a11ec02d6b3f7ede5d77c51379958db4a",
  "head_block_id": "031c0b692e22d68f27fa6af8501a75b43bb7fd45c257d2b37f9d15f9291acc04",
  "head_block_time": "2019-04-10T04:15:01.000",
  "head_block_producer": "eosbeijingbp",
  "virtual_block_cpu_limit": 200000000,
  "virtual_block_net_limit": 1048576000,
  "block_cpu_limit": 164449,
  "block_net_limit": 1042784,
  "server_version_string": "mainnet-1.6.2"
}

eos::send_transaction

Send a transaction on the eos network and return the tx id

Params Format

"<node> <from> <to> <amount> [symbol=SYS] [code=eosio.token] [memo=]"

Example Params

[0,"userxxxx3233","userxxxxx424",10]

Example Result

"64dfffbe27a4cedf076e22a7ceb44621ee6211e8ba4e91a3d88ec98040b1b492"

eos::run_burst_tx

Send the given number of transactions in a burst

Params Format

[<number of transaction> [tx size=174]]

Example Params

5000

Example Result

"success"

eos::run_constant_tps

Run transactions on the eos network at a constant pace

Params Format

[<tps> [tx size=174]]

Example Params

200

Example Result

"success"

Events

All events are not availible through the HTTP API and must be accessed through the Websocket API

chart_listener

Get the data for the front end charts. Will continue to stream new chart data as it comes in. The param is the block number to start streaming the data at, leave empty to start from the beginning.

Params Format

[[block number]]

Example Params

[1]

Example Result

[
    {
        "blockNumber":553,
        "blockTime":1,
        "numberOfTransactions":1,
        "numberOfUncles":0,
        "gasLimit":6861391,
        "gasUsed":21000,
        "difficulty":1301725,
        "totalDifficulty":632292281,
        "size":651,
        "miner":"0x47a3d6ea062083945f080a509234f771b26a99a9"
    }
]

block_listener

Generic of block listener. The param is the block number to start streaming the data at, leave empty to start from the beginning

Params Format

[[block number]]

Example Params

[1]

build_status

Gives the current progress of the build on an interval. Subscribes the user to a feed of the build progress.

Params Format

[<testnet id>]

Example Params

["a24a67c1-bc98-423a-ad3f-87eff5b9fa54"]

Example Result

{"progress":50.000000,"error":null,"stage":"Bootstrapping network","frozen":false}

CI/CD

The Whiteblock genesis platform provides support for CI/CD tooling. Teams utilizing Genesis to continuously test latest iterations of their client will find the deployment process expedited by automation support. As of version 1.5 Jenkins is supported.

Jenkins

  1. Log into Whiteblock here
  2. Generate a new api key
  3. Install the cloudbees credentials plugin in jenkins
  4. Go to credentials
  5. Click global credentials
  6. Click add credentials
  7. Set kind as secret text
  8. Set the id to whiteblock_jwt
  9. Paste your api token into the password field
  10. Click ok to save the credential
  11. Goto the build configuration for the project you wish to integrate with the whiteblock platform.
  12. In the Binding section, click Add and then select secret text
  13. Call the variable WHITEBLOCK_JWT and then select Specific credentials
  14. Click the select box next to add and then select whiteblock_jwt
  15. Add the following to your build script
    wget https://whiteblock.io/releases/cli/v1.5.7/whiteblock
    chmod +x ./whiteblock
    ./whiteblock login $WHITEBLOCK_JWT [biome alias or id]
    #Some whiteblock commands you would like to run go here
    ./whiteblock logoff

Whiteblock commands will have a non zero exit code on failure. This is can be used to check the failure or success of your program. This also applies to the custom test you have made with the Whiteblock file, on failure, it will return a non-zero exit code and print out the result of the query which failed. (Generally what is contained in the error section of the JSON RPC response).

Eos

Build

Build using previous configurations:

$ whiteblock build previous

To start the build process, use the following command:

$ whiteblock build -b eos

Build

Build using -b flag:

$ whiteblock build -b eos

Type the number of nodes and y to use default parameters:

nodes (30): 30
Use default parameters? (y/n) y

Type the number of nodes and type y to use default parameters >>>

Progress:

[email protected]:~$ whiteblock build -b eos
nodes: 30
Use default parameters? (y/n) y
2019/01/13 07:13:21  Build in Progress
Setting up services    45.411817%

Progress bar >>>

During this build process, the Whiteblock framework is deploying the nodes, peering them with one another, configuring VLANs, generating and funding accounts and wallets, and initializing the blockchain.

In the process of initializing the EOS system, a single node acts as the master of ceremonies to generate the genesis block that starts the blockchain. Afterwards, this node steps down and the rest of the nodes in the network need to vote on which of the 21 amongst them will be elected block producers. Every node in the network that wants to vote is required to do so using SYS, which is the symbol for the native EOS token.

Once this process is complete, block producers will immediately begin minting blocks and you can start changing network conditions, automating transactions, deploying smart contracts, and testing however you see fit using the eos command.

Custom Parameters

Example build

$ whiteblock build -b eos -n 30
Use default parameters? (y/n) n
userAccounts (int):
blockProducers (int):
accountCPUStake (int):
accountRAMStake (int):
accountNetStake (int):
accountFunds (int):
bpCpuStake (int):
bpNetStake (int):
bpRamStake (int):
bpFunds (int):
maxBlockNetUsage (int):
targetBlockNetUsagePct (int):
maxTransactionNetUsage (int):
basePerTransactionNetUsage (int):
netUsageLeeway (int):
contextFreeDiscountNetUsageNum (int):
contextFreeDiscountNetUsageDen (int):
maxBlockCpuUsage (int):
targetBlockCpuUsagePct (int):
maxTransactionCpuUsage (int):
minTransactionCpuUsage (int):
maxTransactionLifetime (int):
deferredTrxExpirationWindow (int):
maxTransactionDelay (int):
maxInlineActionSize (int):
maxInlineActionDepth (int):
maxAuthorityDepth (int):
initialChainId (string):
chainStateDbSizeMb (int):
reversibleBlocksDbSizeMb (int):
contractsConsole (bool):
p2pMaxNodesPerHost (int):
allowedConnection (string):
maxClients (int):
connectionCleanupPeriod (int):
syncFetchSpan (int):
maxImplicitRequest (int):
pauseOnStartup (bool):
maxTransactionTime (int):
maxIrreversibleBlockAge (int):
keosdProviderTimeout (int):
txnReferenceBlockLag (int):
plugins ([]string):
2019/01/16 21:55:24 build:  Build in Progress
Sending build context to Whiteblock

If you don't want to use the provided default parameters during your build and would instead like to specify your own, simply indicate the values you would like to specify by typing n when prompted. Alternatively, you can provide your own custom configuration file and specify the path to this configuration file using the -f flag.

Start the build process with eos and 30 nodes:

$ whiteblock build -b eos -n 30

Use default parameters? (y/n) n

Example build with -y flag

$ whiteblock build -b eos -n 30 -y
2019/01/16 21:55:24 build:  Build in Progress
Sending build context to Whiteblock

You will be prompted to input the parameters that you still need to provide to start building. In order to build with default settings, use flag -y

$ whiteblock build -b eos -n 30 -y

Geth

Geth is the client for ethereum that is written in golang. This application uses the Proof of Work consensus algorithm, which requires certain nodes to be mining nodes. Ethereum offers the functionality of smart contracts, which is written in solidity. For more information regarding the Ethereum network, please visit here.

Build

Building Geth with flags:

$ whiteblock build -b geth -n <number of nodes>

When building the network, Whiteblock will automate several processes, including the following:

Custom Parameters

Example:

$ whiteblock build -b geth -f whiteblock build -f /home/whiteblock/config/custom_comnfiguration.json

Default parameters are given for convenience but specific parameters can be provided to customize the configuration of the network. During the build progress, simply type n when prompted Use default Parameters?. Then a series of parameters will follow. The value can be given or if the default for that specific parameter is wanted, simply hitting enter will provide the default value.

Alternatively, you can provide your own custom configuration file and specify the path to this configuration file using the -f flag

Start Mining

The Ethereum blockchain requires the network to have certain nodes mining. This is how blocks are created and the more miners there are, the more secure the network becomes. To begin mining, run the command whiteblock miner start. This will have all the nodes start mining and this will initiate the network to begin producing blocks and process transactions.

Example:

$ whiteblock miner start

Test Case Scenario: Throughput

As a simple test case, the throughput of the network can be measured.

Run Transactions

Example:

$ whiteblock tx start stream -t 100 -v 1

To begin, we will run some transactions by running the command whiteblock tx start stream -t 100 -v 1. The -t flag is used to indicate "Transactions Per Second" and the -v flag is used to indicate the "Value" in Eth.

Get Data

Example:

$ whiteblock get stats all

After running the transactions, you can see the throughput of the network by running the command whiteblock get stats all. This will output all the relevant statistics of the current blockchain. Further details on these statistics can be found in .

Introduce Network Conditions

Example:

$ whiteblock netconfig all -d 100

You can now introduce real world network conditions and see how these network conditions affect the throughput of the network. To set a global latency of 100ms to all nodes, run the command whiteblock netconfig all -d 100. The -d flag is used to indicate the delay (latency) of the network. Other network conditions can be configured and more details can be found here .

Compare Data

Example:

$ whiteblock get stats all

All the while this is going on, you can continue to monitor the statistics that is outputted from whiteblock get stats all. You can observe the drop in thorughput in the presence of latency in the network.

Pantheon

Pantheon is an open source Ethereum client written in Java. Pantheon is MainNet-compatible, and includes features like consensus algorithms that are applicable to enterprise use. Aside from the Ethereum public network, Pantheon is also supported on private networks, and test networks such as Rinkeby and Ropsten. Pantheon implements Proof of Work and Proof of Authority consensus mechanisms. More information on the technical aspects of the Pantheon client can be found in the Pantheon Documentation.

Building Pantheon

Building Pantheon with flags:

$ whiteblock build -b pantheon -n <number of nodes> -i <the whiteblock compatible image you wish to test>

When building the network, Whiteblock will automate several processes, including the following:

Custom Parameters

Example:

$ whiteblock build -b pantheon -f <custom parameters file> -i <the Whiteblock compatible docker image> 

Default parameters are given for convenience but specific parameters can be provided to customize the configuration of the network. During the build progress, simply type n when prompted Use default Parameters?. Then a series of parameters will follow. The value can be given or if the default for that specific parameter is wanted, simply hitting enter will provide the default value.

Alternatively, you can provide your own custom configuration file and specify the path to this configuration file using the -f flag If you would like to see the out of the box supported parameters, you can use the whiteblock get config cmd.

Getting the default supported parameters

$ whiteblock get config pantheon params.json

Test Case Scenario: Throughput

As a simple test case, the throughput of the network can be measured.

Run Transactions

Example:

$ whiteblock tx start stream -t 100 -v 1

To begin, we will run some transactions by running the command whiteblock tx start stream -t 100 -v 1. The -t flag is used to indicate "Transactions Per Second" and the -v flag is used to indicate the "Value" in Eth.

Get Data

Example:

$ whiteblock get stats all

After running the transactions, you can see the throughput of the network by running the command whiteblock get stats all. This will output all the relevant statistics of the current blockchain. Further details on these statistics can be found in .

Introduce Network Conditions

Example:

$ whiteblock netconfig all -d 100

You can now introduce real world network conditions and see how these network conditions affect the throughput of the network. To set a global latency of 100ms to all nodes, run the command whiteblock netconfig all -d 100. The -d flag is used to indicate the delay (latency) of the network. Other network conditions can be configured and more details can be found here .

Compare Data

Example:

$ whiteblock get stats all

All the while this is going on, you can continue to monitor the statistics that is outputted from whiteblock get stats all. You can observe the drop in throughput in the presence of latency in the network.

To check the log data of specific nodes you can use whiteblock get log 0. The 0 is in reference to node 0.

Example:

$ whiteblock get log 0

If you would like to view data in stream form you can use watch wb get log 0 --tail $(tput lines).

Example:

$ watch wb get log 0 --tail $(tput lines)

CI/CD Integration

CI/CD Integration for Pantheon is supported.

Getting started with Jenkins and Whiteblock

RChain

RChain is a blockchain platform for distributed applications which implements a Proof of Stake consensus algorithm. RChain also presents Rholang, a unique smart contract programming language based on [Rho calculus]. More information on the technical aspects of this system can be found in the RChain developer portal.

Whiteblock's implementation of the RChain client is built on v0.8.2 and an example test plan using the Whiteblock platform can be found in the RChain GitHub.

Build

Building Rchain with flags:

$ whiteblock build -b rchain -v <number of validators> -n <number of nodes>

Provisioning 10 validator nodes within the network using flags:

$ whiteblock build -b rchain -v 10

Static nodes that are not performing as validators can be specified using the -n flag.

Provisioning 10 validator nodes and 5 static nodes with flags:

$ whiteblock build -b rchain -v 10 -n 5

Build using default parameters:

[email protected]:~$ whiteblock build -b rchain -v 10 -n 5
Use default parameters? (y/n) y
2019/01/13 07:13:21  Build in Progress
Setting up services    24.411817%

When building the network, Whiteblock will automate several processes, including the following:

The number of validators should be specified with the -v flag. The first among the provisioned nodes will be assigned the role of validator. For example, if you've specified a number of 10 validators in a network of 50 total nodes, nodes 0 - 10 will be delegated the role of validators.

Configuration

An example of Whiteblock's default rnode.toml file:

[server]
host = "localhost"
port = 44010
http-port = 44011
no-upnp = false
default-timeout = 5000
bootstrap = "rnode://<address>@<ip>protocol=40400&discovery=40404"
standalone = false
data-dir = "/RChain/data"
map-size = 200000000
in-memory-store = false

[grpc-server]
host = "grpc"
port = 44012

[tls]
certificate = "/RChain/ssl/node.certificate.pem"
key = "/RChain/ssl/node.key.pem"

# [validators]
# count = 5
# bonds-file = "/validator/bonds"
# known = "v1"
# public-key = "88888"
# private-key = "99999"
# sig-algorithm = "ed25519"
# wallets-file = "/validator/wallet"

The RNode application refers to an rnode.toml file for configuring different functions and processes.

Whiteblock automatically generates an rnode.toml file during the build process. This configuration file does not persist between builds. An example configuration file is provided in the right-hand column.

If you would like to define your own values to populate the configuration file, you can do so through the Build Wizard by providing n as your response when prompted.

Use default parameters? (y/n) y

By responding with n, you can define these parameters on your own and will then be prompted to provide values for each entry.

Alternatively, you can provide your own configuration file using the -f flag to indicate the path to the configuration file.

whiteblock build -b rchain -v 5 -n 10 -f /home/master/custom-rchain.toml

For example, the above command would build an RChain network with 5 validators and 10 static nodes that would each refer to the custom-rchain.toml file located in the home directory of the Whiteblock master environment.

Deploying Contracts

Deploying a smart contract from a specific node can be done using the ssh command and there are two ways to go about doing so. The first option would be directly connecting to a node's terminal and manually deploying the contract using the appropriate command.

Deploying the dupe.rho contract via node 4:

$ whiteblock ssh 4 rnode deploy --phlo-limit 1000 --pholo-price 500 rchain/rholang/examples/dupe.rho

The second option would be providing the RNode command after indicating the node number in the ssh command.

$ whiteblock ssh <node number> rnode deploy --phlo-limit <value> --pholo-price <value> <path to .rho file>