Giverny Reference

giverny is the advanced configuration tool for the Monet Toolchain.

The current subcommands are:

  • help — help
  • version — outputs version information
  • keys — key management tools
  • server — configuration server management
  • network — configure and build networks
  • transactions — generate test transactions sets

Global Flag

The --verbose flag, or -v for short, turns on extended messages for each giverny command.

Help

giverny has context sensitive help accessed either by running giverny help or by adding a -h parameter to the relevant command.

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] $ giverny version
Monetd Version: 0.2.4-ec49cbca
     EVM-Lite Version: 0.3.4-
     Babble Version: 0.5.6-
     Geth Version: 1.8.27

Keys

The keys subcommand offers tools to manage keys.

Keys Flags

In addition to the --verbose flag, the keys subcommand defines addtional flags as follows:

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

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

Import

The import subcommand is used to import a pre-existing key pair into the monetd keystore, assigning the given moniker and setting a passphrase.

[..monetd] $ giverny help keys import

Import keys to [moniker] from private key file [keyfile].

Usage:
  giverny keys import [moniker] [keyfile] [flags]

Flags:
  -h, --help   help for import

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
      --json                      output JSON instead of human-readable format
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
      --passfile string           the file that contains the passphrase for the keyfile
  -v, --verbose                   verbose messages

Generate

The generate subcommand is used to bulk generate key pairs for a test net. The --prefix parameter defines a prefix for the account monikers. Then the --min-suffix and --max-suffix define the range of accounts names.

E.g. --prefix=Acc --min-suffix=1 --max-suffix=3 would generate accounts: Acc1, Acc2 and Acc3.

[..monetd] $ giverny help keys generate

The generate sub command is intended only for test nets. It generates a
number of key pairs and places them in the current monet keystore. The
accounts are names <prefix><suffix> where prefix is set by --prefix (default
"Account") and suffix is a number between --min-suffix and --max-suffix
inclusive. The defaults are 1 and 5.

Usage:
  giverny keys generate [flags]

Flags:
  -h, --help             help for generate
      --max-suffix int   maximum suffix for account monikers (default 5)
      --min-suffix int   minimum suffix for account monikers (default 1)
      --prefix string    prefix for account monikers (default "Account")

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
      --json                      output JSON instead of human-readable format
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
      --passfile string           the file that contains the passphrase for the keyfile
  -v, --verbose                   verbose messages

Server

The server subcommand is used for adminstering a REST server used to co-ordinate configurations between multiple nodes prior to the initial node of a network.

The server listens on port 8088. It writes logs to ~/.giverny/server/server.pid. [1]

For usage examples, see the recipes for setting up networks.

Start

To start the server in the foreground:

$ giverny server start

To start the server in the background:

$ giverny server start --background

Stop

To stop a server running in the background:

$ giverny server stop

Status

Reports on the status of the server. It both checks for the PID file in ~/.giverny/server/server.pid [1] and checks the the server is responding on localhost:8088.

$ giverny server status

Network

The network command is used to build complex monet networks. The new command generates the nodes and keys for a network, and automatically calls the build command which generates and builds genesis.json and peers.json files. You can adjust the network by editting the network.toml file. The location command outputs the relevant paths. The push command is used to push a giverny network node configuration to a docker or actual node so it can be used by monetd. start, stop and status are used to manage the docker instance.

The network name and node names must contain only standard letters (i.e. no accented versions), digits (0–9) or underscores (_).

Location

The giverny network location subcommand takes a single optional parameter network_name. If the network is specified it outputs the location of key files and folders for that network. If not, only the root giverny configuration folder is output.

Example without a network name:

$ giverny network location
/home/user/.giverny

Example with a network specified:

$ giverny network location node7
Network                 : node7
Giverny Config Dir      : /home/user/.giverny
Giverny Networks Dir    : /home/user/.giverny/networks/node7
Giverny KeyStore Dir    : /home/user/.giverny/networks/node7/keystore
Peers JSON              : /home/user/.giverny/networks/node7/peers.json
Genesis JSON            : /home/user/.giverny/networks/node7/genesis.json
Monetd TOML             : /home/user/.giverny/networks/node7/monetd.toml
Network TOML            : /home/user/.giverny/networks/node7/network.toml

New

The new subcommand creates a new test network configuration. It also invokes the build command automatically, unless the --no-build parameter is specified.

Syntax

[..monetd] $ giverny help network new

giverny network build

Usage:
  giverny network new [network_name] [flags]

Flags:
      --generate-pass       generate pass phrases
  -h, --help                help for new
      --initial-ip string   initial IP address of range
      --initial-peers int   number of initial peers
      --names string        file containing node configurations
      --no-build            disables the automatic build of a new network
      --no-save-pass        don't save pass phrase entered on command line
  -n, --nodes int           number of nodes in this configuration (default -1)
      --pass string         file containing a passphrase

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

Nodes

The number of nodes in this network is specified by the --nodes [int] parameter. The --initial-peers [int] parameter specifies the number of initial peers. If not set it assumes that all nodes are in the initial peer set.

IP Addresses

An initial IP address is supplied using the --initial-ip parameter. It is assumed the IP address range will be assigned by simply incrementing the last octet of the IP address for each node. N.B. the first node will be assigned the actual IP supplied by the initial-ip parameter.

Node Names

The default node names are a standard prefix of node with a unique integer suffix. You can override the default and supply a list of node names, which are used in the order supplied, via the --names parameter.

Node names must contain only standard Latin alphabet characters (ie a–z or A–Z with no accents), underscores (_), or digits (0–9).

Pass Phrases

There are numerous pass phrase flags for the new subcommand.

  • --pass [passfile] — uses the given pass phrase file for all nodes
  • --generate-pass — generates a unique passphrase for each key pair and writes it to a file nodename.txt in the network configuration keystore directory
  • --no-save-pass — suppresses saving pass phrases in the network configuration keystore directory

The typical use case scenarios for these flags would be:

  • None specified — you are prompted to enter the passphrase for each node which is saved
  • --pass only — the specified pass phrase is used, and saved in the config folder
  • --pass and --no-save-pass — the specified pass phrase is used and not saved in the config folder
  • --generate-pass only — pass phrases are generated and saved
  • --no-save-pass only — you are prompted to enter the passphrase for each node, which is not saved in the config folder

Build

By default giverny network new will run giverny network build automatically. This can be disabled by specifying the -no-build flag.

Examples

An example of the new subcommand:

$ giverny network new test11 --names sampledata/names.txt --nodes 7 --pass sampledata/pwd.txt --initial-peers 3 --initial-ip 192.168.1.19

Build

The giverny network build subcommand takes a configuration created by the new subcommand and builds peers.json and genesis.json files.

build can be run repeatably safely. It is envisaged that users will edit the network.toml file to adjust token allocations or change addresses.

--no-generate-keys disables the creation of any keys not already in the keystore.

A “built” network will have a file structure like this:

test7
├── compile.toml
├── contract0.abi
├── contract0.sol
├── genesis.json
├── keystore
│   ├── Amelia.json
│   ├── Amelia.txt
│   ├── Becky.json
│   ├── Becky.txt
│   ├── Chloe.json
│   ├── Chloe.txt
│   ├── Danu.json
│   ├── Danu.txt
├── monetd.toml
├── network.toml
└── peers.json

Export

The export subcommand takes a configuration that has been generated and exports it to the exports subfolder of the giverny configuration folders as a zip file. The network export command has a mandatory network name parameter, and optionally one or more node names. If the node names are omitted, all of the nodes for that network are exported.

Thus to export node nodename:

$ giverny network export nodename

On Linux this writes to $HOME/.giverny/exports/nodename_<account>.zip where there is one file for each account defined in the network.

Import

The import subcommand takes a configuration previously exported by the export and configures monetd to use the new configuration. You will always need to specify a network name and a node name for the import. The source for the import can be configured thus:

  • --from-exports — from the exports subfolder in the giverny configuration folders. This is the default output location for the export command.
  • --server — from a giverny server. The giverny server will look in the exports subfolder in the giverny configuration folders on the instance it is running on. N.B. do not run the giverny server on any instance with live key pairs or sensitive configuration, as it may be exposed.
  • --dir — specify the folder the export zip is in. Do not rename the zip file. This is used when a secondary channel is used to communicate the keys.
[1](1, 2) This location is for Linux instances. Mac and Windows uses a different path. The path for your instance can be ascertain with this command: giverny network location

List

The list subcommand lists the configured network names.

$ giverny network list
benchmark
benchnet
bulktransfers

Dump

The dump subcommand outputs the nodes in a named network in bar delimited format as below:

giverny network dump crowdfundnet
Amelia|172.77.5.10|0x7bBE1Df184142709d5B99C5788982D0bEE5d1167|true|false
Becky|172.77.5.11|0xC6a29c6378C20eA9E868EdD3538Ba58d09318f81|true|false
Chloe|172.77.5.12|0x7b225252dEe5aDa558a233c7B8B654Ef366EBe61|true|false
Danu|172.77.5.13|0xC0d14Ed110045d7A401ecC9E57628D55e56Fd4c4|true|false

Add

The add subcommand adds a node to the specified network. The resultant network will then need to be built using the build subcommand.

[..monetd] $ giverny help network add

giverny network add

Usage:
  giverny network add [network_name] [node_name] [moniker] [flags]

Flags:
      --generate-pass       generate pass phrases
  -h, --help                help for add
      --initial-ip string   IP
      --no-save-pass        don't save pass phrase entered on command line
      --pass string         filename of a file containing a passphrase

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

Start

The start subcommand starts a docker network. Individual nodes are not started unless the --start-nodes parameter is specified. If the --force-network parameter is set, then the network is forced down if it is already running.

[..monetd] $ giverny help network start

giverny network start

Starts a network. Does not start individual nodes. The --force-network parameter
stops and restarts the network.

Usage:
  giverny network start [network] [flags]

Flags:
      --force-network   force network down if already exists
  -h, --help            help for start
      --start-nodes     start nodes
      --use-existing    use existing network if already exists

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

Stop

The stop subcommand stops a docker network and all the nodes within it.

[..monetd] $ giverny help network stop

giverny network stop

Stop a node and all the nodes within it.

Usage:
  giverny network stop [network] [node]  [flags]

Flags:
  -h, --help     help for stop
      --remove   stop and remove node

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

Status

The status subcommand shows the docker network status

$ giverny network status

Networks

crowdfundnet   663db79442357cb8814b7ff40076abdd6479a2f5b24ab7087deceaf07913999a  bridge
none   257f919e7203933bb10aadf17637552b16acb5490b5c8141815e2f19c01ff1fe  null
bridge   37b969bb113d1707ce01328803bc57d0dc86bb349f617112d242f82ade0ada76  bridge
host   b89aa9c3a413c14af09cbab6b3ee4450c2cf1cfdbc0449cb28d1f73e4c296d8b  host

Containers

/Danu   a67496705d1e5bf6dc0b92a7c4ec69d6c055dc2d08a3193d0e2f5c0fde74564b  Up 10 seconds
/Chloe   d7da80c6e3c7b92a61975208d72e5d4864d5c5b31bb67859d3c1bbb3feb38b43  Up 11 seconds
/Becky   dbe47cb5ff517f47f18c4307c09de95ef86fe75279657e342d3bcfee2d6f1a1e  Up 11 seconds
/Amelia   0f08e59ef698aecc62b2c6945d8c351c7902c90f13e6c4828ef9ab7c9ee27ec3  Up 12 seconds

Push

The push subcommand creates a named node on a built docker network. If the docker network has not yet been build, there is no need to push the node.

[..monetd] $ giverny help network push

giverny network push

Usage:
  giverny network push [network] [node] [flags]

Flags:
  -h, --help   help for push

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages

Transactions

The transaction commands are used to generate transactions sets for end to end testing of networks.

Generate

The generate subcommand is used to generate transaction sets from the network.toml file.

The following flags can be set:

    --count int        number of tranactions to generate (default 20)
    --faucet string    faucet account moniker (default "Faucet")
-h, --help             help for generate
    --ips string       ips.dat file path
-n, --network string   network name
    --surplus int      additional credit to allocate each account from the faucet above the bare minimum (default 1000000)

Solo

The solo subcommand is used to generate transactions sets from a single funded account. Look in e2e/tools/build-trans.sh for an end to end example using the solo command.

[..monetd] $ giverny help transactions solo

Solo transactions generate a transaction set without needing access
to the network toml file. You just need a well funded faucet account.
The additional accounts can be generated using giverny keys generate

Usage:
  giverny transactions solo [flags]

Flags:
      --accounts string       comma separated account list
      --count int             number of tranactions to solo (default 20)
      --faucet string         faucet account moniker (default "Faucet")
  -h, --help                  help for solo
      --max-trans-value int   maximum transaction value (default 10)
      --output string         output file (default "trans.json")
      --round-robin           set sender accounts round robin
      --surplus int           additional credit to allocate each account from the faucet above the bare minimum (default 1000000)

Global Flags:
  -g, --giverny-data-dir string   Top-level giverny directory for configuration and data (default "/home/martin/.giverny")
  -m, --monet-data-dir string     Top-level monetd directory for configuration and data (default "/home/martin/.monet")
  -v, --verbose                   verbose messages