Monetd Reference

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

[..monetd] $ monetd help

Monetd is the daemon component of the Monet Toolchain; 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:
  monetd [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 monetd
  -v, --verbose   verbose output

Use "monetd [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 monetd 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 monetd, EVM-Lite, Babble and Geth.

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

[..monetd] $ monetd version
Monetd Version: 0.2.5-develop-9b16ad82
     EVM-Lite Version: 0.3.5-
     Babble Version: 0.5.8-
     Geth Version: 1.8.27

Keys

The keys subcommand is used to manage Monet Toolchain 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 monetd configuration folder. You can see the location for your instance with this command:

$ monetd config location

The help for the keys command is:

[..monetd] $ monetd keys help

Manage keys in the <keystore> folder.

Note that other Monet tools, like monetcli and monet-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, Monet 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:
  monetd 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/martin/.monet/keystore")
      --passfile string   file containing the passphrase

Global Flags:
  -v, --verbose   verbose output

Use "monetd 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 monetd 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 monetd 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.

[..monetd] $ monetd 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:
  monetd 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/martin/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

Inspect

[..monetd] $ monetd 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:
  monetd 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/martin/.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.

$ monetd keys inspect node0 --private
Passphrase:
Address:        0x02f6f3D24E447218d396C14F3B47f9Ea369DADf9
Public key:     0481d3528eec6138f8428932e4fe99571a4f77bd79ae13219540b0a929014cb490a4e5ced2f9e651b531522c2567b6dc5de75d485193615e768b8aa1190603d2c2
Private key:    bc553aaa7e55c5d0f58f6897ba9bffdb88233c420da622d363f2fe4bd6d78df1
$ monetd 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.

[..monetd] $ monetd 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:
  monetd 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/martin/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

An example session updating the passphrase for a key:

$ monetd 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 monetd commands.

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

Usage:
  monetd 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/martin/.monet/keystore")
      --passfile string   file containing the passphrase
  -v, --verbose           verbose output

An example session:

$ monetd keys list
node0
node1
node2

Config

The config subcommand initialises the configuration for a monetd 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
  • contract — display poa contract
  • 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

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 monetd. 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 Monet Toolchain configuration tool.

Clear

The clear subcommand safely clears any previous monetd 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.

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

Contract

The contract subcommand generates the Solidity source for a POA smart contract with the supplied node as the sole entry on the initial whitelist. This command is not used in the standard workflow, but is provided as a convenient mechanism to retrieve the solidity source.

[..monetd] $ monetd help config contract

Display the PoA smart contract.

Outputs the standard monetd contract, configured with the list of validators
in the initial whitelist. The validator arguments are either a moniker that
is in the keystore, or in the form moniker=address. The two forms can be mixed
in the same command line.

Usage:
  monetd config contract [validator] [validator] ... [flags]

Flags:
  -h, --help   help for contract

Global Flags:
  -v, --verbose   verbose output

A sample session is as follows. The contract is written to stdout, so you will probably wish to redirect it to a file or a pager.

$ monetd config contract node0 | more
pragma solidity >=0.4.22;

/// @title Proof of Authority Whitelist Contract

...

Location

The location subcommand displays the path to the configuration folder.

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

Usage:
  monetd config location [flags]

Flags:
  -h, --help   help for location

Global Flags:
  -v, --verbose   verbose output
Monetd Config        : /home/user/.monet/monetd-config/monetd.toml
Babble Peers         : /home/user/.monet/monetd-config/babble/peers.json
Babble Genesis Peers : /home/user/.monet/monetd-config/babble/peers.genesis.json
Babble Private Key   : /home/user/.monet/monetd-config/babble/priv_key
EVM-Lite Genesis     : /home/user/.monet/monetd-config/eth/genesis.json
Babble Database      : /home/user/.monet/monetd-data/babble-db
EVM-Lite Database    : /home/user/.monet/monetd-data/eth-db
Keystore        : /home/user/.monet/keystore

Build

The build subcommand initialises the bare-bones configuration to start monetd. 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.

[..monetd] $ monetd 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:
  monetd config build [moniker] [flags]

Flags:
      --address string    IP/hostname of this node (default "192.168.1.3")
      --config string     output directory (default "/home/martin/.monet/monetd-config")
  -h, --help              help for build
      --keystore string   keystore directory (default "/home/martin/.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 monetd node. If the peer specified does not include a port, the default gossip port (1337) is used.

[..monetd] $ monetd 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:
  monetd config pull [host:port] [flags]

Examples:
  monetd config pull "192.168.5.1:8080"

Flags:
      --address string    IP/hostname of this node (default "192.168.1.3")
      --config string     output directory (default "/home/martin/.monet/monetd-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 (default "node0")
      --keystore string   keystore directory (default "/home/martin/.monet/keystore")
      --passfile string   file containing the passphrase

Global Flags:
  -v, --verbose   verbose output

Run

The run subcommands starts the monetd 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.

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

Usage:
  monetd 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.1.3:1337")
      --babble.max-pool int         max number of pool connections (default 2)
      --babble.moniker string       friendly name
      --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/martin/.monet/monetd-config")
  -d, --data string                 data directory (default "/home/martin/.monet/monetd-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