Botcoin Reference¶

botcoin provides the core commands needed to configure and run a node. It has context sensitive help accessed either by running botcoin help or by adding a -h parameter to the relevant command.

[..botcoin] $ botcoin help

Botcoin is the daemon component of the Botcoin Network; a distributed
smart-contract platform based on the Ethereum Virtual Machine and Babble
consensus.

See the documentation at https://docs.monet.network/ for further information.

Usage:
  botcoin [command]

Available Commands:
  config      manage configuration
  help        Help about any command
  keys        manage keys
  run         run a node
  version     show version info

Flags:
  -h, --help      help for botcoin
  -v, --verbose   verbose output

Use "botcoin [command] --help" for more information about a command.

There are 5 subcommands. help is described above. The other 4 commands are described in separate sections below:

help — show help for the command and subcommands
version — shows the current version of botcoin and subsystems
keys — creates and manages keys
config — creates and manages configurations
run — runs the monet daemon, i.e. starts a node

Global Parameters¶

Global Parameters are available for all subcommands.

-d, –datadir string — overrides the default location of the configuration files
-h, –help — help command as discussed above
-v, –verbose — turns on verbose messages. Defaults to false.

Version¶

The version subcommand outputs the version number for botcoin, BVM, Babble and Geth.

If you compile your own tools, the suffices are the GIT branch and the GIT commit hash.

[..botcoin] $ botcoin version
Botcoin Version: 0.3.2-develop-77cd48e4
     EVM-Lite Version: 0.3.6-develop
     Babble Version: 0.5.10-develop
     Geth Version: 1.8.27

Keys¶

The keys subcommand is used to manage Botcoin keys. There are 4 subcommands, each described in a seperate section below:

inspect — inspect a keyfile
list — list keyfiles
new — create a new keyfile
update — change the passphrase on a keyfile

The keys subcommand writes and reads keys from the keystore sub-folder in the botcoin configuration folder. You can see the location for your instance with this command:

$ botcoin config location

The help for the keys command is:

[..botcoin] $ botcoin keys help

Manage keys in the <keystore> folder.

Note that other Botcoin Network, like botcoincli and botcoin-wallet, use the same
default keystore.

+------------------------------------------------------------------------------+
| Please take all the necessary precautions to secure these files and remember |
| the passwords, as it will be impossible to recover the keys without them.    |
+------------------------------------------------------------------------------+

Keys are associated with monikers and encrypted in password-protected files in
<keystore>/[moniker].json. Keyfiles contain JSON encoded objects, which Ethereum
users will recognise as the de-facto Ethereum keyfile format. Indeed, Botcoin and
the underlying consensus algorithm, Babble, use the same type of keys as
Ethereum. A key can be used to run a validator node, or to control an account
with a token balance.

Usage:
  botcoin keys [command]

Available Commands:
  inspect     inspect a keyfile
  list        list keyfiles
  new         create a new keyfile
  update      change the passphrase on a keyfile

Flags:
  -h, --help              help for keys
      --json              output JSON instead of human-readable format
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase

Global Flags:
  -v, --verbose   verbose output

Use "botcoin keys [command] --help" for more information about a command.

Parameters¶

All of the keys subcommands support the --passfile flag. This allows you to pass the path to a plain text file containing the passphrase for your key. This removes the interactive prompt to enter the passphrase that is the default mechanism.

Monikers¶

Keys generated by botcoin have a moniker associated with them. The moniker is used to manage the keys as it is far more user friendly that an Ethereum address or public key.

New¶

The new subcommand generates a new key pair and associates it with the specified moniker. You will be prompted for a passphrase which is used to encrypt the keyfile. It writes the encrypted keyfile to the botcoin keystore area by default. The moniker must be unique within your keystore. If you attempt to create a duplicate, the command will abort with an error.

[..botcoin] $ botcoin help keys new

Generate a new key identified by [moniker].

The keyfile will be written to <keystore>/[moniker].json. If the --passfile flag
is not specified, the user will be prompted to enter the passphrase manually.

Usage:
  botcoin keys new [moniker] [flags]

Flags:
  -h, --help   help for new

Global Flags:
      --json              output JSON instead of human-readable format
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

Inspect¶

[..botcoin] $ botcoin help keys inspect

Display the contents of a keyfile.

The output contains the corresponding address and public key. If --private is
specified, the keyfile will be decrypted with the passphrase and the raw private
key will also be returned. If --passfile is not specified, the user will be
prompted to enter the passphrase manually.

Usage:
  botcoin keys inspect [moniker] [flags]

Flags:
  -h, --help      help for inspect
      --private   include the private key in the output

Global Flags:
      --json              output JSON instead of human-readable format
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

A sample session showing the command usage with and without the --private parameter.

$ botcoin keys inspect node0 --private
Passphrase:
Address:        0x02f6f3D24E447218d396C14F3B47f9Ea369DADf9
Public key:     0481d3528eec6138f8428932e4fe99571a4f77bd79ae13219540b0a929014cb490a4e5ced2f9e651b531522c2567b6dc5de75d485193615e768b8aa1190603d2c2
Private key:    bc553aaa7e55c5d0f58f6897ba9bffdb88233c420da622d363f2fe4bd6d78df1

$ botcoin keys inspect node0
Passphrase:
Address:        0x02f6f3D24E447218d396C14F3B47f9Ea369DADf9
Public key:     0481d3528eec6138f8428932e4fe99571a4f77bd79ae13219540b0a929014cb490a4e5ced2f9e651b531522c2567b6dc5de75d485193615e768b8aa1190603d2c2

Update¶

The update subcommand allows you to change the passphrase for an encrypted key file. You are prompted for the old passphrase, then you need to enter, and confirm, the new passphrase.

You can suppress the prompts by specifying the --passfile parameter to supply the current passphrase and --new-passphrase to supply the new passphrase.

[..botcoin] $ botcoin help keys update

Change the passphrase on a keyfile.

If --passfile is not specified, the user will be prompted to enter the current
passphrase manually. Likewise, if --new-passfile is not specified, the user will
be prompted to input and confirm the new password.

Usage:
  botcoin keys update [moniker] [flags]

Flags:
  -h, --help                  help for update
      --new-passfile string   the file containing the new passphrase

Global Flags:
      --json              output JSON instead of human-readable format
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

An example session updating the passphrase for a key:

$ botcoin keys update node0
Passphrase:
Please provide a new passphrase
Passphrase:
Repeat passphrase:

List¶

The list subcommand outputs a list of monikers corresponding to the keyfiles in the keystore. These are the valid monikers that can be specified to other botcoin commands.

[..botcoin] $ botcoin help keys list
List keyfiles in <keystore>

Usage:
  botcoin keys list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --json              output JSON instead of human-readable format
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

An example session:

$ botcoin keys list
node0
node1
node2

Config¶

The config subcommand initialises the configuration for a botcoin node. The configuration commands create all the files necessary for a node to join an existing network or to create a new one.

There are 5 subcommands each described in a separate section below:

clear — backup and clear configuration folder
location — show the location of the configuration files
build — create the configuration for a single-node network
pull — pull the configuration files from a node
whitelist — generate the poa/storage key value pairs for a given set of
peers. You should not need to use this command directly

The two most common scenarios are:

config build - config build creates the configuration for a single-node
network, based on one of the keys in [<keystore>. This is a quick and easy way to get started with botcoin. See Getting Started.
config pull - config pull is used to join an existing network. It fetches the
configuration from one of the existing nodes. See Joining a Network.

For more complex scenarios, please refer to Giverny Reference, which is a specialised Botcoin configuration tool.

Clear¶

The clear subcommand safely clears any previous botcoin configurations. It renames the previous configuration with a .~n~ suffix, where n is the lowest integer where the resultant filename does not already exist.

The configurations are renamed and not deleted to avoid the potential for inadvertent deletion of keys.

$ botcoin config clear
Renaming /home/user/.monet to /home/user/.monet.~1~

Location¶

The location subcommand displays the path to the configuration folder.

[..botcoin] $ botcoin help config location
Show the default locations of botcoin configuration files.

Usage:
  botcoin config location [flags]

Flags:
  -h, --help   help for location

Global Flags:
  -v, --verbose   verbose output

Botcoin Config        : /home/user/.monet/botcoin-config/botcoin.toml
Babble Peers         : /home/user/.monet/botcoin-config/babble/peers.json
Babble Genesis Peers : /home/user/.monet/botcoin-config/babble/peers.genesis.json
Babble Private Key   : /home/user/.monet/botcoin-config/babble/priv_key
EVM-Lite Genesis     : /home/user/.monet/botcoin-config/eth/genesis.json
Babble Database      : /home/user/.monet/botcoin-data/babble-db
EVM-Lite Database    : /home/user/.monet/botcoin-data/eth-db
Keystore        : /home/user/.monet/keystore

Build¶

The build subcommand initialises the bare-bones configuration to start botcoin. It uses one of the accounts from the keystore to define a network consisting of a unique node, which is automatically added to the PoA whitelist. Additionally, all the accounts in the keystore are credited with a large amount of tokens in the genesis file. This command is mostly used for testing.

If the --address flag is omitted, the first non-loopback address for this instance is used.

[..botcoin] $ botcoin help config build

Create the configuration for a single-node network.

Use the keystore account identified by [moniker] to define a network with a
single node. All the accounts in <keystore> are also credited with a large
amount of tokens in the genesis file. This command is mostly used for testing.
If the --address flag is omitted, the first non-loopback address is used.

Usage:
  botcoin config build [moniker] [flags]

Flags:
      --address string    IP/hostname of this node (default "192.168.0.13")
      --config string     output directory (default "/home/user/.monet/botcoin-config")
  -h, --help              help for build
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase

Global Flags:
  -v, --verbose   verbose output

Pull¶

The pull subcommand is used to join an existing network. It takes the address of a running peer, and downloads the following set of files into the configuration directory <config>:

babble/peers.json : The current validator-set
babble/peers.genesis.json : The initial validator-set
eth/genesis.json : The genesis file

It also builds all the other configuration files required to run a botcoin node. If the peer specified does not include a port, the default gossip port (1337) is used.

[..botcoin] $ botcoin help config pull

The pull subcommand is used to join an existing network. It takes the address
(host:port) of a running node, and downloads the following set of files into the
configuration directory <config>:

- babble/peers.json         : The current validator-set
- babble/peers.genesis.json : The initial validator-set
- eth/genesis.json          : The genesis file

Additionally, this command configures the key and network address of the new
node. The --key flag identifies a keyfile by moniker, which is expected to be in
the <keystore>. If --passfile is not specified, the user will be prompted to
enter the passphrase manually. If the --address flag is omitted, the first
non-loopback address is used.

Usage:
  botcoin config pull [host:port] [flags]

Examples:
  botcoin config pull "192.168.5.1:8080"

Flags:
      --address string    IP/hostname of this node (default "192.168.0.13")
      --config string     output directory (default "/home/user/.monet/botcoin-config")
  -f, --force             don't prompt before manipulating files
  -h, --help              help for pull
      --key string        moniker of the key to use for this node
      --keystore string   keystore directory (default "/home/user/.monet/keystore")
      --passfile string   file containing the passphrase

Global Flags:
  -v, --verbose   verbose output

Run¶

The run subcommands starts the botcoin node running. Whilst there are legacy parameters --babble.* and --eth.*, we strongly recommend that they are not used. The equivalent changes can be made in the configuration files.

[..botcoin] $ botcoin help run
Run a node.

Usage:
  botcoin run [flags]

Flags:
      --api-listen string           IP:PORT of HTTP API service (default ":8080")
      --babble.advertise string     advertise IP:PORT of Babble node
      --babble.bootstrap            bootstrap Babble from database (default true)
      --babble.cache-size int       number of items in LRU caches (default 50000)
      --babble.heartbeat duration   heartbeat timer milliseconds (time between gossips) (default 200ms)
      --babble.listen string        bind IP:PORT of Babble node (default "192.168.0.13:1337")
      --babble.maintenance-mode     start babble in suspended (non-gossipping) state
      --babble.max-pool int         max number of pool connections (default 2)
      --babble.moniker string       friendly name
      --babble.suspend-limit int    number of undetermined-events since last run that will trigger automatic suspension (default 300)
      --babble.sync-limit int       max number of Events per sync (default 1000)
      --babble.timeout duration     TCP timeout milliseconds (default 1s)
  -c, --config string               configuration directory (default "/home/user/.monet/botcoin-config")
  -d, --data string                 data directory (default "/home/user/.monet/botcoin-data")
      --eth.cache int               megabytes of memory allocated to internal caching (min 16MB / database forced) (default 128)
      --eth.min-gas-price string    minimum gasprice of transactions submitted through this node (ex 1K, 1M, 1G, etc.) (default "0")
  -h, --help                        help for run

Global Flags:
  -v, --verbose   verbose output