.. _monetd_commands_rst:

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.

.. include:: _static/includes/monetd_help.txt
    :code: bash

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.


.. include:: _static/includes/monetd_version.txt
    :code: bash

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:

.. code:: bash

    $ monetd config location

The help for the keys command is:

.. include:: _static/includes/monetd_keys_help.txt
    :code: bash

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.

.. include:: _static/includes/monetd_help_keys_new.txt
    :code: bash


Inspect
~~~~~~~

.. include:: _static/includes/monetd_help_keys_inspect.txt
    :code: bash


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

.. code:: bash

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

.. code:: bash

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


.. include:: _static/includes/monetd_help_keys_update.txt
    :code: bash

An example session updating the passphrase for a key:

.. code:: bash

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

.. include:: _static/includes/monetd_help_keys_list.txt
    :code: bash


An example session:

.. code:: bash

    $ 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
- **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 ``monetd``.
                 See :ref:`quickstart_rst`.

- config pull - config pull is used to join an existing network. It fetches the
                configuration from one of the existing nodes. See
                :ref:`join_rst`.

For more complex scenarios, please refer to :ref:`giverny_rst`, 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.

.. code:: bash

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


Location
~~~~~~~~

The ``location`` subcommand displays the path to the configuration folder.

.. include:: _static/includes/monetd_help_config_location.txt
    :code: bash

.. code:: bash

    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.

.. include:: _static/includes/monetd_help_config_build.txt
    :code: bash

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.

.. include:: _static/includes/monetd_help_config_pull.txt
    :code: bash

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.

.. include:: _static/includes/monetd_help_run.txt
    :code: bash