References

Note: Please note that these documents are still being drafted and subject to change. This page is particularly rough, so take it easy, buddy.

Command Line Interface

whiteblock <command> [FLAGS]

This application will deploy a blockchain, create nodes, and allow those nodes to interact in the network.

  • Available Commands:
    • build Build a blockchain using image and deploy nodes
    • get Get server and network information.
    • geth Run geth commands
    • help Displays help page
    • netconfig Network conditions
    • rpc Rpc interacts with the blockchain
    • ssh SSH into an existing container.
    • version Display Whiteblock CLI version
  • Flags:
    • -h, –help : help for whiteblock

Fowarding Commands

  • forward
    • forward {“nodes”:[<node1>,…<noden>],”port”:<port>,”data”:”<data to send to all the nodes given>”}
    • forward tcp data to specific nodes, pass data with c string escapes and receive data back with c string escapes, in a json array of strings
    • Example: {“nodes”:[1,2],”port”:80,”data”:”GET / HTTP/1.1rnrn”}
    • Response: JSON Array of the responses
    • Response Example: [“HTTP/1.1 200 OKrnrn”]

build

whiteblock build [FLAGS]

Aliases: build, create, init

Build will create and deploy a blockchain and the specified number of nodes. Each node will be instantiated in its own container and will interact individually as a participant of the specified network.

  • Flags:
    • -h, –help: help for build
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get

whiteblock get <command> [FLAGS]

Get will ouput server and network information and statstics.

  • Available Commands:
    • data Data will pull data from the network and output into a file.
    • nodes Nodes will show all nodes in the network.
    • server Get server information.
    • stats Get stastics of a blockchain
  • Flags:
    • -h, –help : help for get
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get data

whiteblock get data <command> [FLAGS]

Data will pull specific or all block data from the network and output into a file. You will specify the directory where the file will be downloaded.

  • Available Commands:
    • all All will pull data from the network and output into a file.
    • block Data block will pull data from the network and output into a file.
    • time Data time will pull data from the network and output into a file.
  • Flags:
    • -h, –help : help for data
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get data all

whiteblock get data all [PATH] [FLAGS]

Data all will pull all data from the network and output into a file. The directory where the file will be downloaded will need to be specified. If no directory is provided, default directory is set to ~/Downloads.

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for all
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get data block

whiteblock get data block <start block> <end block> [PATH] [FLAGS]

Data block will pull block data from the network from a given start and end block and output into a file. The directory where the file will be downloaded will need to be specified. If no directory is provided, default directory is set to ~/Downloads.

Params: Block numbers Format: <start block number> <end block number>

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for block
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get data time

whiteblock get data time <start time> <end time> [PATH] [FLAGS]

Data time will pull block data from the network from a given start and end time and output into a file. The directory where the file will be downloaded will need to be specified. If no directory is provided, default directory is set to ~/Downloads.

Params: Unix time stamps Format: <start unix time stamp> <end unix time stamp>

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for time
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get nodes

whiteblock get nodes [FLAGS]

Aliases: nodes, node

Nodes will output all of the nodes in the current network.

  • Flags:
    • -h, –help : help for server
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get server

whiteblock get server [FLAGS]

Aliases: server, servers

Server will allow the user to get server information.

  • Flags:
    • -h, –help : help for server
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get stats

whiteblock get stats <command> [FLAGS]

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

Response: JSON representation of network statistics

  • Available Commands:
    • all
    • block
    • time
  • Flags:
    • -h, –help : help for stats
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get stats all

whiteblock get stats all [FLAGS]

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

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for all
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get stats block

whiteblock get stats block <start block> <end block> [FLAGS]

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

Params: Block numbers Format: <start block number> <end block number>

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for block
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

get stats time

whiteblock get stats time <start time> <end time> [FLAGS]

Stats time will allow the user to get statistics by specifying a start time and stop time (unix time stamp).

Params: Unix time stamps Format: <start unix time stamp> <end unix time stamp>

Response: JSON representation of network statistics

  • Flags:
    • -h, –help : help for time
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

netconfig

whiteblock netconfig <command> [FLAGS]

Netconfig will introduce persistnace network conditions for testing. Use ‘?’ at any time for more help on configuring the network.

Custom Command: netconfig <engine number> <path number> <command>

set delay <amount> Specifies the latency to add [ms]; set loss loss <amount> Specifies the amount of packet loss to add [%]; set bw <amount> <type> Specifies the bandwidth of the network [bps|Kbps|Mbps|Gbps];

  • Available Commands:
    • bandwidth Set bandwidth
    • delay Set latency
    • loss Set packetloss
    • off Turn off emulation
    • on Turn on emulation
  • Flags:
    -h, –help: help for netconfig

netconfig bandwidth

whiteblock netconfig bandwidth <engine number> <path number> <amount> <bandwidth type> [FLAGS]

Aliases: bw

Bandwidth will constrict the network to the specified bandwidth. You will specify the amount of bandwdth and the type.

Fomat: bandwidth type: bps, Kbps, Mbps, Gbps

  • Flags:
    • -h, –help: help for bandwidth

netconfig delay

whiteblock netconfig delay <engine number> <path number> <amount> [FLAGS]

Aliases: delay, latancy, lat

Latency will introduce delay to the network. You will specify the amount of latency in ms.

  • Flags:
    • -h, –help: help for latency

netconfig loss

whiteblock netconfig loss <engine number> <path number> <percent> [FLAGS]

Aliases: packetloss

Packetloss will drop packets in the network. You will specify the amount of packet loss in %.

  • Flags:
    • -h, –help: help for loss

netconfig off

whiteblock netconfig off <engine number> [FLAGS]

Turn off emulation.

  • Flags:
    • -h, –help: help for off

netconfig on

whiteblock netconfig on <engine number> [FLAGS]

Turn on emulation.

  • Flags:
    • -h, –help: help for on

SSH

whiteblock ssh <server> <node> [FLAGS]

SSH will allow the user to go into the contianer where the specified node exists.

Response: stdout of the command

  • Flags:
    • -h, –help : help for ssh
    • -a, –server-addr : server address with port 5000 (default “localhost:5000”)

version

whiteblock version

Get whiteblock CLI client version

  • Flags: - -h, –help : help for version

Smart Contracts

contractadd

whiteblock contractadd <filename> [FLAGS]

Adds the specified smart contract into the /Downloads folder.

  • Flags:
    • -h, –help: help for contractadd
    • -p, –path string : File path where the smart contract is located

contractcompile

whiteblock contractcompile <filename> [FLAGS]

Compiles the specified smart contract.

  • Flags:
    • -h, –help: help for contractcompile
    • -p, –path string: File path where the smart contract is located

Ethereum

  • eth::get_block_number
    • Description: Get the current highest block number of the chain
    • Params: None
    • Response: The block number e.g. 10
  • eth::get_block
    • Description: Get the data of a block
    • Params: The block number
    • Format: <Block Number>
    • Example: 10
    • Response: JSON Representation of the block. Example
  • eth::get_accounts
    • Description: Get the unlocked accounts
    • Params: None
    • Response: A JSON array of the accounts
  • eth::get_balance
    • Description: Get the current balance of an account
    • Params: Account address
    • Format: <address>
    • Example: 0xbfa767eae64753e4c426ea42470abf7e4fc305ab
    • Response: The integer balance of the account in wei
  • eth::send_transaction
    • Description: Send a transaction between two accounts
    • Params: Sending account, receiving account, gas, gas price, amount to send, transaction data, nonce
    • Format: <from> <to> <gas> <gas price> <value> [data] [nonce]
    • Example: 0xbfa767eae64753e4c426ea42470abf7e4fc305ab 0x8d12a197cb00d4747a1fe03395095ce2a5cc6819 0x015f90 0x165a0bc00 0xde0b6b3a7640000
    • Response: The transaction hash
  • eth::get_transaction_count
    • Description: Get the transaction count sent from an address, optionally by block
    • Params: The sender account, a block number
    • Format: <address> [block number]
    • Example: 0xbfa767eae64753e4c426ea42470abf7e4fc305ab
    • Response: The transaction count
  • eth::get_transaction
    • Description: Get a transaction by its hash
    • Params: The transaction hash
    • Format: <hash>
    • Example: 0x402c257c85c398154b8b16fa612df13e197135f63d1be9e03b6d2d55285e8670
    • Response: JSON representation of the transaction. Example
  • eth::get_transaction_receipt
    • Description: Get the transaction receipt by the tx hash
    • Params: The transaction hash
    • Format: <hash>
    • Example: 0x402c257c85c398154b8b16fa612df13e197135f63d1be9e03b6d2d55285e8670
    • Response: JSON representation of the transaction receipt. Example
  • eth::get_hash_rate
    • Description: Get the current hash rate per node
    • Params: None
    • Response: The hash rate of a single node in the network
  • eth::start_transactions
    • Description: Start sending transactions according to the given parameters, value = -1 means randomize value.
    • Params: The amount of transactions to send in a second, the value of each transaction in wei, the destination for the transaction
    • Format: <tx/s> <value> [destination]
    • Example: 100 0xde0b6b3a7640000 0x8d12a197cb00d4747a1fe03395095ce2a5cc6819
    • Response: None
  • eth::stop_transactions
    • Description: Stops the sending of transactions if transactions are currently being sent
    • Params: None
    • Response: None
  • eth::start_mining
    • Description: Send the start mining signal to nodes, may take a while to take effect due to DAG generation
    • Params: A list of the nodes to start mining or None for all nodes
    • Format: [node 1 number] [node 2 number]…
    • Example: 0 1 2 3
    • Response: The number of nodes which successfully received the signal to start mining
  • eth::stop_mining
    • Description: Send the stop mining signal to nodes
    • Params: A list of the nodes to stop mining or None for all nodes
    • Format: [node 1 number] [node 2 number]…
    • Example: 0 1 2 3
    • Response: The number of nodes which successfully received the signal to stop mining
  • eth::block_listener
    • Description: Get all blocks and continue to subscribe to new blocks
    • Params: The block number to start at or None for all blocks
    • Format: [block number]
    • Example: 12
    • Response: Will emit on eth::block_listener for every block after the given block or 0 that exists/has been created
  • eth::get_recent_sent_tx
    • Description: Get a number of the most recent transactions sent
    • Params: The number of transactions to retrieve
    • Format: [number]
    • Example: 5
    • Response: Data on the 5 last sent transactions
    • Response Example:
    {"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"]]}]}]}
    

Starting Transactions

const io = require('socket.io-client')
const socket = io('http://localhost:5000', {
    path: '/'
})

socket.on('connect', () => {
    console.log("Starting the transactions")
    socket.emit("eth::stop_transactions")//kill any previous transaction logic
    socket.emit("eth::start_transactions","1 0xde0b6b3a7640000")//Start sending the transactions
})

socket.open();

Note: Any configuration option can be left out, and this entire section can even be null, the example contains all of the defaults.

Ethereum Options

  • chainId: The chain id set in the genesis.conf
  • networkId: The network id
  • difficulty: The initial difficulty set in the genesis.conf file
  • initBalance: The initial balance for the accounts
  • maxPeers: The maximum number of peers for each node
  • gasLimit: The initial gas limit
  • homesteadBlock: Set in genesis.conf
  • eip155Block: Set in genesis.conf
  • eip158Block: Set in genesis.conf

Example (using defaults)

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

geth

whiteblock geth <command> [FLAGS]

Geth will allow the user to get infromation and run geth commands.

  • Available SubCommands:
    • block_listener Get block listener
    • get_accounts Get account information
    • get_balance Get account balance information
    • get_block Get block information
    • get_block_number Get block number
    • get_hash_rate Get hasg rate
    • get_recent_sent_tx Get recently sent transaction
    • get_transaction Get transaction information
    • get_transaction_count Get transaction count
    • get_transaction_receipt Get transaction receipt
    • send_transaction Sends a transaction
    • start_mining Start Mining
    • start_transactions Start transactions
    • stop_mining Stop mining
    • stop_transactions Stop transactions
  • Flags:
    • -h, –help: help for geth
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

geth block_listener

whiteblock geth block_listener [block number] [FLAGS]

Get all blocks and continue to subscribe to new blocks

Format: [block number] Params: The block number to start at or None for all blocks Response: Will emit on eth::block_listener for every block after the given block or 0 that exists/has been created

  • Flags:
    • -h, –help: help for block_listener

geth get_accounts

whiteblock geth get_accounts [FLAGS]

Get a list of all unlocked accounts

Response: A JSON array of the accounts

  • Flags:
    • -h, –help: help for get_accounts

geth get_balance

whiteblock geth get_balance <address> [FLAGS]

Get the current balance of an account

Format: <address> Params: Account address Response: The integer balance of the account in wei

  • Flags: - -h, –help: help for get_balance

geth get_block

whiteblock geth get_block <block number> [FLAGS]

Get the data of a block

Format: <Block Number> Params: Block number

  • Flags:
    • -h, –help: help for get_block

geth get_block_number

whiteblock geth get_block_number [FLAGS]

Get the current highest block number of the chain

Response: The block number

  • Flags:
    • -h, –help: help for get_block_number

geth get_hash_rate

whiteblock geth get_hash_rate [FLAGS]

Get the current hash rate per node

Response: The hash rate of a single node in the network

  • Flags:
    • -h, –help: help for get_hash_rate

geth get_recent_sent_tx

whiteblock geth get_recent_sent_tx [NUMBER] [FLAGS]

Get a number of the most recent transactions sent

Format: [number] Params: The number of transactions to retrieve Response: JSON object of transaction data

  • Flags:
    • -h, –help: help for get_recent_sent_tx

geth get_transaction

whiteblock geth get_transaction <hash> [FLAGS]

Get a transaction by its hash

Format: <hash> Params: The transaction hash

Response: JSON representation of the transaction.

  • Flags:
    • -h, –help: help for get_transaction

geth get_transaction_count

whiteblock geth get_transaction_count <address> [BLOCK NUMBER] [FLAGS]

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

Format: <address> [block number] Params: The sender account, a block number Response: The transaction count

  • Flags:
    • -h, –help: help for get_transaction_count

geth get_transaction_receipt

whiteblock geth get_transaction_receipt <hash> [FLAGS]

Get the transaction receipt by the tx hash

Format: <hash> Params: The transaction hash Response: JSON representation of the transaction receipt.

  • Flags:
    • -h, –help: help for get_transaction_receipt

geth send_transaction

whiteblock geth send_transaction <from address> <to address> <gas> <gas price> <value to send> [FLAGS]

Send a transaction between two accounts

Format: <from> <to> <gas> <gas price> <value> Params: Sending account, receiving account, gas, gas price, amount to send, transaction data, nonce Response: The transaction hash

  • Flags: - -h, –help: help for send_transaction

geth start_mining

whiteblock geth start_mining [node 1 number] [node 2 number]... [FLAGS]

Send the start mining signal to nodes, may take a while to take effect due to DAG generation

Format: [node 1 number] [node 2 number]… Params: A list of the nodes to start mining or None for all nodes Response: The number of nodes which successfully received the signal to start mining

  • Flags:
    • -h, –help: help for start_mining

geth start_transactions

whiteblock geth start_transactions <tx/s> <value> [DESTINATION] [FLAGS]

Start sending transactions according to the given parameters, value = -1 means randomize value.

Format: <tx/s> <value> [destination] Params: The amount of transactions to send in a second, the value of each transaction in wei, the destination for the transaction

  • Flags:
    • -h, –help: help for start_transactions
    • geth stop_mining

geth stop_mining

whiteblock geth stop_mining [node 1 number] [node 2 number]... [FLAGS]

Send the stop mining signal to nodes

Format: [node 1 number] [node 2 number]… Params: A list of the nodes to stop mining or None for all nodes Response: The number of nodes which successfully received the signal to stop mining

  • Flags:
    • -h, –help: help for stop_mining

geth stop_transactions

whiteblock geth stop_transactions [FLAGS]

Stops the sending of transactions if transactions are currently being sent

  • Flags:
    • -h, –help: help for stop_transactions
Geth (Go-Ethereum)

Note: Any configuration option can be left out, and this entire section can even be null, the example contains all of the defaults

Options

  • chainId: The chain id set in the genesis.conf
  • networkId: The network id
  • difficulty: The initial difficulty set in the genesis.conf file
  • initBalance: The initial balance for the accounts
  • maxPeers: The maximum number of peers for each node
  • gasLimit: The initial gas limit
  • homesteadBlock: Set in genesis.conf
  • eip155Block: Set in genesis.conf
  • eip158Block: Set in genesis.conf

Example (using defaults)

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

Syscoin

Syscoin (RegTest)

Options:

  • rpcUser: The username credential

  • rpcPass: The password credential

  • masterNodeConns: The number of connections to set up for the master nodes

  • nodeConns: The number of connections to set up for the normal nodes

  • percentMasternodes: The percentage of the network consisting of master nodes

  • options: Options to set enabled for all nodes

  • senderOptions: Options to set enabled for senders

  • receiverOptions: Options to set enabled for receivers

  • mnOptions: Options to set enabled for master nodes

  • extras: Extra options to add to the config file for all nodes

  • senderExtras: Extra options to add to the config file for senders

  • receiverExtras: Extra options to add to the config file for receivers

  • mnExtras: Extra options to add to the config file for master nodes

  • sys::start_test
    • Description: Start the propogation/tps test for syscoin
    • Params: The max number of test results to retrieve
    • Format: {“waitTime”:<seconds to wait>,”minCompletePercent”:<percentage>,”numberOfTransactions”:<number of tx>}
    • Example:
    {
        "waitTime":11,
        "minCompletePercent":97.7,
        "numberOfTransactions":500
    }
    
  • sys::get_recent_test_results
    • Description: Get recent test results
    • Params: The max number of test results to retrieve
    • Format: [number]
    • Example: 5
    • Response: Data on the last x test results
whiteblock sys <command> [FLAGS]

Alias: SYS, syscoin

Sys will allow the user to get infromation and run SYS commands.

  • Available Commands:
    • test SYS test commands.
  • Flags:
    • -h, –help : help for sys

sys test

whiteblock sys test <command> [FLAGS]

Available Commands: results Get results from a previous test. start Starts propagation test.

  • Flags:
    • -h, –help : help for test

sys test start

whiteblock sys test start <wait time> <min complete percent> <number of tx> [FLAGS]

Sys test start will start the propagation test. It will wait for the signal start time, have nodes send messages at the same time, and require to wait a minimum amount of time then check receivers with a completion rate of minimum completion percentage.

Format: <wait time> <min complete percent> <number of tx> Params: Time in seconds, percentage, number of transactions

  • Flags:
    • -h, –help : help for start
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

sys test results

whiteblock sys test results <test number> [FLAGS]

Sys test results pulls data from a previous test or tests and outputs as csv.

Format: <test number> Params: Test number

  • Flags:
    • -h, –help : help for results
    • -a, –server-addr string: server address with port 5000 (default “localhost:5000”)

Example (using defaults)

{
    "rpcUser":"username",
    "rpcPass":"password",
    "masterNodeConns":25,
    "nodeConns":8,
    "percentMasternodes":90,
    "options":[
        "server",
        "regtest",
        "listen",
        "rest"
    ],
    "senderOptions":[
        "tpstest",
        "addressindex"
    ],
    "mnOptions":[],
    "receiverOptions":[
       "tpstest"
    ],
    "extras":[],
    "senderExtras":[],
    "receiverExtras":[],
    "mnExtras":[]
}