Single node

Single Node

Following this page, you can run a single node local network manually or by using the already prepared automated script. Running a single node setup is useful for developers who want to test their applications and protocol features because of its simplicity and speed. For more complex setups, please refer to the Multi Node Setup page.

Prerequisite Readings

• Install Binary

Automated Script

The simplest way to start a local HyperPaxeer node is by using the provided helper script on the base level of the HyperPaxeer repository, which will create a sensible default configuration for testing purposes:

$ 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-hyperpaxd instead of the default ~/.hyperpaxd. :::

When working with the local_node.sh script, it is necessary to extend all hyperpaxd commands, that target the local test node, with the --home ~/.tmp-hyperpaxd flag. This is mandatory, because the home directory cannot be stored in the hyperpaxd 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-hyperpaxd`
$ hyperpaxd config --home $TMP
{
"chain-id": "hyperpax_125-1",
"keyring-backend": "test",
"output": "text",
"node": "tcp://localhost:26657",
"broadcast-mode": "sync"
}

You can customize the local node script by changing the configuration variables. See the following excerpt from the script for ideas on what can be adjusted:

# 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="hyperpax_125-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 hyperpaxd instance
HOMEDIR="$HOME/.tmp-hyperpaxd"
# 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="hyperpax_125-4"

# The argument $MONIKER is the custom username of your node, it should be human-readable.
hyperpaxd 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 ~/.hyperpaxd 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:

hyperpaxd keys add my_validator

Once you have created a local account, go ahead and grant it some ahpx tokens in your chain’s genesis file. Doing so will also make sure your chain is aware of this account’s existence:

hyperpaxd add-genesis-account my_validator 10000000000ahpx

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
hyperpaxd add-genesis-account my_validator 1000000000stake,10000000000ahpx

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 hyperpaxd init command above.

For more information on gentx, use the following command:

hyperpaxd gentx --help

Collecting gentx

By default, the genesis file do not contain any gentxs. A gentx is a transaction that bonds staking token present in the genesis file under accounts to a validator, essentially creating a validator at genesis. The chain will start as soon as more than 2/3rds of the validators (weighted by voting power) that are the recipient of a valid gentx come online after genesis_time.

A gentx can be added manually to the genesis file, or via the following command:

# Add the gentx to the genesis file
hyperpaxd collect-gentxs

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

Run Single Node

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

hyperpaxd validate-genesis

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

hyperpaxd start

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

You should see blocks come in.

The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them.

You can then stop the node using Ctrl+C.

Further Configuration

Key Management

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

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

:::tip HyperPaxeer currently only supports 24 word mnemonics. :::

You can generate a new key/mnemonic with:

hyperpaxd keys add $KEY

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

hyperpaxd keys unsafe-export-eth-key $KEY

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

hyperpaxd keys -h

Keyring backend options

The instructions above include commands to use test as the keyring-backend. This is an unsecured keyring that doesn’t require entering a password and should not be used in production. Otherwise, HyperPaxeer supports using a file or OS keyring backend for key storage. To create and use a file stored key instead of defaulting to the OS keyring, add the flag --keyring-backend file to any relevant command and the password prompt will occur through the command line. This can also be saved as a CLI config option with:

hyperpaxd 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)

hyperpaxd start --evm.tracer $TRACER --tracestore $TRACESTORE --pruning=nothing $TRACE --log_level $LOGLEVEL --minimum-gas-prices=0.0001ahpx --json-rpc.api eth,txpool,personal,net,debug,web3

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 hyperpaxd 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/.hyperpaxd/config/addrbook.json $HOME/.hyperpaxd/config/genesis.json
hyperpaxd tendermint unsafe-reset-all --home $HOME/.hyperpaxd

Your node is now in a pristine state while keeping the original priv_validator.json and config.toml. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven’t also been upgraded.

Delete Data

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

rm -rf ~/.hyperpaxd

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: 'HyperPaxeer'

scrape_configs:
- job_name: 'HyperPaxeer'

  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(hyperpaxd_transactions_processed[1m])

which will show the rate of transactions processed.

:::tip HyperPaxeer currently only supports 24 word mnemonics. :::