Launch a CVM Node

You can manually or automatically run a single node local network by following this page's automated script. Due to its simplicity and speed, running a single node setup is helpful for developers looking to test their applications and protocol features. Please see the Multi Node Setup page for more complicated setups.

Prerequisite Readings​

• Install Binary

Automated Script

Using the provided helper script on the CosVM repository's base level to create a reasonable default configuration for testing purposes is the simplest way to launch savvy nodes locally:

$ local_node.sh
...

TIP

To avoid overwriting any data for a real node used in production, it was decided to store the automatically generated testing configuration at ~/.tmp-cvmd instead of the default ~/.cvmd.

When working with the local_node.sh script, it is necessary to extend all cvmd commands, that target the local test node, with the --home ~/.tmp-cvmd flag. This is mandatory, because the home directory cannot be stored in the cvmd configuration, which can be seen in the output below. For ease of use, it might be sensible to export this directory path as an environment variable:

$ export TMP=$HOME/.tmp-cvmd`
$ cvmd config --home $TMP
{
"chain-id": "cvm_323-1",
"keyring-backend": "test",
"output": "text",
"node": "tcp://localhost:26657",
"broadcast-mode": "sync"
}

By altering the configuration variables, you can alter the local node script. For suggestions on what can be changed, see the script excerpt that follows

# Customize the name of your keys, the chain-id, moniker of the node, keyring backend, and more
KEYS[0]="dev0"
KEYS[1]="dev1"
KEYS[2]="dev2"
CHAINID="cvm_323-1"
MONIKER="localtestnet"
# Remember to change to other types of keyring like 'file' in-case exposing to outside world,
# otherwise your balance will be wiped quickly
# The keyring test does not require private key to steal tokens from you
KEYRING="test"
KEYALGO="eth_secp256k1"
LOGLEVEL="info"
# Set dedicated home directory for the cvmd instance
HOMEDIR="$HOME/.tmp-cvmd"
# to trace evm
#TRACE="--trace"
TRACE=""

[...]

  # Adjust this set a different maximum gas limit
  jq '.consensus_params["block"]["max_gas"]="10000000"' "$GENESIS" >"$TMP_GENESIS" && mv "$TMP_GENESIS" "$GENESIS"

[...]

Manual Deployment

This guide helps you create a single validator node that runs a network locally for testing and other development-related uses.

Initialize the chain​

Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the init subcommand:

$MONIKER=testing
$KEY=dev0
$CHAINID="cvm_323-1"

# The argument $MONIKER is the custom username of your node, it should be human-readable.
cvmd init $MONIKER --chain-id=$CHAINID

TIP

You can edit this moniker later by updating the config.toml file.

The command above creates all the configuration files needed for your node and validator to run, as well as a default genesis file, which defines the initial state of the network. All these configuration files are in ~/.cvmd by default, but you can overwrite the location of this folder by passing the --home flag.

Genesis Procedure​

Adding Genesis Accounts​

Before starting the chain, you need to populate the state with at least one account using the keyring:

cvmd keys add my_validator

Grant your local account some a CosVM tokens in the genesis file of your chain once you've created one. Additionally, by doing this, your chain will be made aware of the existence of this account:

cvmd add-genesis-account my_validator 10000000000ucvm

Now that your account has some tokens, you need to add a validator to your chain.

For this guide, you will add your local node (created via the init command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a gentx:

# Create a gentx
# NOTE: this command lets you set the number of coins.
# Make sure this account has some coins with the genesis.app_state.staking.params.bond_denom denom
cvmd add-genesis-account my_validator 1000000000stake,10000000000ucvm

A gentx does three things:

1. Registers the validator account you created as a validator operator account (i.e. the account that controls the validator).

2. Self-delegates the provided amount of staking tokens.

3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no --pubkey flag is provided, it defaults to the local node pubkey created via the cvmd init command above.

For more information on gentx, use the following command:

cvmd gentx --help

gentx collection​

The genesis file is by default devoid ofgentxs. A validator is essentially created at genesis through a transaction known as gentx, which binds staking tokens found in the genesis file under accounts to them. As soon as more than 2/ 3 of the validators( weighted by voting power) who receive a valid gentx log on after genesis_time, the chain will begin.

The following command can be used to manually add a gentx to the genesis file:

# Add the gentx to the genesis file

cvmd collect-gentxs

This command will add all the gentxs stored in ~/.cvmd/config/gentx to the genesis file.

Run Single Node​

Finally, check the correctness of the genesis.json file:

cvmd validate-genesis

Now that everything is set up, you can finally start your node:

cvmd start

TIP

To check all the available customizable options when running the node, use the --help flag.

Blocks ought to be entering.

You can run a single node with the previous command. The interaction with this node will be covered in the following section, but you might want to run a number of nodes simultaneously to observe how consensus develops.

The node can then be terminated using Ctrl+C.

Further Configuration​

Key Management​

To run a node with the same key every time: replace cvmd keys add $KEY in ./local_node.sh with:

echo "your mnemonic here" | cvmd keys add $KEY --recover

TIP

CosVM currently only supports 24 word mnemonics.

You can generate a new key/mnemonic with:

cvmd keys add $KEY

To export your CosVM key as an Ethereum private key (for use with Metamask for example):

cvmd keys unsafe-export-eth-key $KEY

For more about the available key commands, use the --help flag

cvmd keys -h

Selecting backend options​

Commands to use test as the keyring-backend are included in the instructions above. This keyring should not be used in production because it is unprotected and doesn't need to be entered with a password. If not, CosVM supports key storage via a file or OS keyring backend. The password prompt will appear through the command line if you add the flag -- keyring- backend file to any pertinent command to create and use a file stored key rather than making the OS keying the default key. Additionally, you can save this as a CLI configuration option.

cvmd config keyring-backend file

TIP

For more information about the Keyring and its backend options, click here.

Enable Tracing​

To enable tracing when running the node, modify the last line of the local_node.sh script to be the following command, where:

• $TRACER is the EVM tracer type to collect execution traces from the EVM transaction execution (eg. json|struct|access_list|markdown)

• $TRACESTORE is the output file which contains KVStore tracing (eg. store.txt)

cvmd start --evm.tracer $TRACER --tracestore $TRACESTORE --pruning=nothing $TRACE --log_level $L

Clearing data from chain​

Reset Data​

Alternatively, you can reset the blockchain database, remove the node's address book files, and reset the priv_validator.json to the genesis state.

DANGER

If you are running a validator node, always be careful when doing cvmd unsafe-reset-all. You should never use this command if you are not switching chain-id.

DANGER

IMPORTANT: Make sure that every node has a unique priv_validator.json. Do not copy the priv_validator.json from an old node to multiple new nodes. Running two nodes with the same priv_validator.json will cause you to double sign!

First, remove the outdated files and reset the data.

rm $HOME/.cvmd/config/addrbook.json $HOME/.cvmd/config/genesis.json
cvmd tendermint unsafe-reset-all --home $HOME/.cvmd

While maintaining the original priv_validator.json and config.toml, your node is now in perfect condition. Your node will still attempt to connect to any sentry or full nodes that have already been set up, but if they haven't also been upgraded, it might not succeed.

Delete Data​

Data for the cvmd binary should be stored at ~/.cvmd, respectively by default. To delete the existing binaries and configuration, run:

rm -rf ~/.cvmd

To clear all data except key storage (if keyring backend chosen) and then you can rerun the full node installation commands from above to start the node again.

Recording Transactions Per Second (TPS)​

In order to get a progressive value of the transactions per second, we use Prometheus to return the values. The Prometheus exporter runs at address http://localhost:8877 so please add this section to your Prometheus installation config.yaml file like this

global:
scrape_interval: 10s

external_labels:
  monitor: 'cosvm'

scrape_configs:
- job_name: 'cosvm'

  scrape_interval: 10s

  static_configs:
    - targets: ['localhost:8877']

and then run Prometheus like this

prometheus --config.file=prom_config.yaml

and then visit the Prometheus dashboard at http://localhost:9090/ then navigate to the expression area and enter the following expression

rate(cvmd_transactions_processed[1m])

which will show the rate of transactions processed.

TIP

CosVM currently only supports 24 word mnemonics.