Join a locally installed Hastra node to the testnet.

Start a Hastra full node to understand how nodes are used by applications that integrate with the Hastra ecosystem.

Quick Start

The quickest way to start a node is to install the provenanced daemon process, initialize a local installation, download the genesis file, and start the provenanced node in the foreground. Be sure to changechoose-a-moniker to a custom name for the new node.

info

While using the quick-start method provides a quick and easy way to start a testnet node, it does place the burden of keeping Hastra software up-to-date on the reader. The recommended approach is to use Cosmovisor to manage the Hastra node as described in the next section.

Start a Node in Foreground

Use the following to start up a Hastra node in the foreground.

info

Refer to https://github.com/provenance-io/testnet for the latest testnet version. As of this writing, it is 1.16.0 as reflected in the version tags below.

plain text
export PIO_HOME=~/.provenanced
git clone https://github.com/provenance-io/provenance.git
cd provenance
git checkout tags/v1.16.0 -b v1.16.0
make clean
make install
provenanced -t init choose-a-moniker --chain-id pio-testnet-1
curl https://raw.githubusercontent.com/provenance-io/testnet/main/pio-testnet-1/genesis.json > genesis.json
mv genesis.json $PIO_HOME/config
provenanced start --testnet --p2p.seeds 4403e0e55fa4e43a454c4bf7922c8a93a51fb12d@seed.test.provenance.io:26656 --x-crisis-skip-assert-invariants

Note that initially, a Hastra node may take about 1-2 hours to start up as it has to sync up with all the old transactions on the blockchain. During startup, the provenanced daemon will output state sync information such as:
plain text
2:20PM INF committed state app_hash=3AA9147C2DBAE3328BAF633B6F33B1FBB6557FE8D81ECBC769A5AFB8DDFE98E3 height=29475 module=state num_txs=0

info

The crisis module halts the blockchain under the circumstance that a blockchain invariant is broken. Invariants can be registered with the application during the application initialization process. During sync, it makes sense to disable this module so the --x-crisis-skip-assert-invariants is specified.

Once the node has synced it is joined to the Hastra testnet. Note after the sync is completed, the information sent to the screen is associated with the live blockchain transactions. At this point, the local provenanced process is a testnet node suitable for learning the provenanced CLI, querying the blockchain, signing and submitting transactions, and developing applications that connect to mainnet. However, there are configuration options to the testnet node that are more suitable as a long-running process.

Setting Up a New Node

Unlike the Quick Start instructions, this section describes setting up a new full node from scratch with Cosmovisor and better configuration options. This section effectively configures and starts a Hastra full node.

Before starting this section, be sure the prerequisites have been installed as described in Installing Hastra.

info

See the testnet repo for the latest genesis/config files and version information. The node started in this section is chain id pio-testnet-1 Hastra release 1.16.0 (https://github.com/provenance-io/provenance/releases/tag/v1.16.0)

Cleaning up Existing testnet Node

If the Quick Start was followed, it will have saved the configuration and state to the $PIO_HOME directory. When setting up a new node, use the following to start from a fresh state by cleaning up artifacts and setting the $PIO_HOME environment variable.

shell
rm-rf ~/.provenanced
exportPIO_HOME=~/.provenanced
mkdir-p$PIO_HOME/config

Download and Install Hastra

Use git to download the latest testnet version of Hastra (1.16.0 as of this writing):

shell
git clone-b v1.16.0 https://github.com/provenance-io/provenance.git
cd provenance

Build the provenanced process.

shell
make clean
make install

Confirm the provenanced version.

shell
provenanced version--long

name: Hastra
server_name: provenanced
version: 1.16.0
commit: 75fef3a701af3787a56d4c8c6b40f67b95b79eb6
build_tags: netgo,gcc,cleveldb,ledger
go: go version go1.15.5 darwin/amd64

Initialize Hastra Node

Next, initialize the node to create the base config files at $PIO_HOME. Choose a moniker, simply a name containing only ASCII characters, for the node. This moniker may be edited later in the $PIO_HOME/config/config.toml file.

shell
provenanced init <your_custom_moniker>--testnet

Download and Install testnet Genesis File

Before starting the provenanced node, a genesis file must be established. This may be downloaded from the Hastra testnet site using curl.

shell
curl https://raw.githubusercontent.com/provenance-io/testnet/main/pio-testnet-1/genesis.json > genesis.json

Move the genesis.json file to the Hastra home configuration directory:

shell
mv genesis.json$PIO_HOME/config

Manually Configure config.toml Settings

Hastra provides a base config.toml file that can be used instead of following these steps in this section. Refer to the "Using Hastra testnet config.toml" section for more information.

The $PIO_HOME/config/config.toml contains important node settings including seed node locations, moniker, and database backend. This section describes the updates to the $PIO_HOME/config/config.toml file needed to start a new node. The Become a Validator section will describe validator node-specific settings.

Configure Seed Nodes

Nodes need to know how to find peers on testnet. This is done by setting seed nodes in the $PIO_HOME/config/config.tomlfile. Depending on the version, the seed nodes are available in the Hastra testnet repo. Because the pio-testnet-1 chain is used in this document, the seed nodes are available here.

Open the $PIO_HOME/config/config.toml file and edit the seeds configuration setting using the seed nodes from the Hastra testnet repo.

shell
# Comma separated list of seed nodes to connect to
seeds = "2de841ce706e9b8cdff9af4f137e52a4de0a85b2@104.196.26.176:26656,add1d50d00c8ff79a6f7b9873cc0d9d20622614e@34.71.242.51"

Configure Database Backend

As listed in the prerequisites section, leveldb is the recommended node backend database.

Open the $PIO_HOME/config/config.toml file and edit the db_backend configuration setting to use leveldb.

shell
# Database backend: goleveldb | cleveldb | boltdb | rocksdb | badgerdb
# * goleveldb (github.com/syndtr/goleveldb - most popular implementation)
#   - pure go
#   - stable
# * cleveldb (uses levigo wrapper)
#   - fast
#   - requires gcc
#   - use cleveldb build tag (go build -tags cleveldb)
# * boltdb (uses etcd's fork of bolt - github.com/etcd-io/bbolt)
#   - EXPERIMENTAL
#   - may be faster is some use-cases (random reads - indexer)
#   - use boltdb build tag (go build -tags boltdb)
# * rocksdb (uses github.com/tecbot/gorocksdb)
#   - EXPERIMENTAL
#   - requires gcc
#   - use rocksdb build tag (go build -tags rocksdb)
# * badgerdb (uses github.com/dgraph-io/badger)
#   - EXPERIMENTAL
#   - use badgerdb build tag (go build -tags badgerdb)
db_backend = "cleveldb"

Configure Logging

Optionally, and to cut down on informational logs, open the $PIO_HOME/config/config.toml file and edit the log_level configuration settings to use error:

shell
# Output level for logging, including package level options
log_level = "error"

Configure Instrumentation

Change the instrumentation namespace option to provenance in the $PIO_HOME/config/config.toml file.

shell
# Instrumentation namespace
namespace = "provenance"

Using Hastra testnet config.toml

Instead of manually configuring the $PIO_HOME/config/config.toml file as shown in the previous section, a reference file is available at Hastra testnet.

Download and Install testnet config.toml

shell
curl https://raw.githubusercontent.com/provenance-io/testnet/main/pio-testnet-1/config.toml > config.toml
mv config.toml$PIO_HOME/config

Edit the $PIO_HOME/config/config.toml and update the moniker to use the moniker set in the Initialize Hastra Node section.

shell
# A custom human readable name for this node
moniker = "pio-testnet2"

Configure Cosmovisor

cosmovisor is a small process manager around Cosmos SDK binaries that monitors the governance module for chain upgrade proposals. Approved proposals will then be run to download the new Hastra code, stop the Hastra node, run the migration script, replace the node binary, and start with the new genesis file.

Download and Install Cosmovisor using `go get`

danger

The go get commands in this section will not work if you are still in the provenance directory created during the github clone. Change to or create a different directory before running go get.

Some MacOS users have experienced issues with using go get to install cosmovisor when using go version 1.5.x. Refer to the Build Cosmovisor from Source section if the go get steps do not work.

shell
go get github.com/provenance-io/cosmovisor/cmd/cosmovisor

Build Cosmovisor from Source (Optional)

info

Building cosmovisor from source is only necessary if the go get installation steps did not work.

Skip this section if cosmovisor has been installed using go get in the previous section.

Create a new directory to install cosmovisor:

shell
mkdir-p$PIO_HOME/cosmovisor/install

Make the current working directory the new $PIO_HOME/cosmovisor/install directory:

shell
cd$PIO_HOME/cosmovisor/install

The Cosmos SDK GitHub repo contains the cosmovisor build, clone the repo:

shell
git clone https://github.com/provenance-io/cosmovisor.git

Change to the cosmovisor build directory:

shell
cd cosmovisor

Make cosmovisor

shell
make cosmovisor

Copy the cosmovisor binary to the $GOPATH

shell
cp build/cosmovisor$GOPATH/bin/cosmovisor

Export Cosmovisor Environment Variables

cosmovisor reads its configuration from environment variables.

DAEMON_HOME is the location where upgrade binaries should be kept. Use $PIO_HOME.

DAEMON_NAME is the name of the Hastra binary, or, provenanced.

DAEMON_ALLOW_DOWNLOAD_BINARIES (optional) if set to true will enable auto-downloading of new binaries.

DAEMON_RESTART_AFTER_UPGRADE (optional) if set to true will restart the sub-process with the same command line arguments and flags (but new binary) after a successful upgrade.

shell
exportDAEMON_NAME="provenanced"
exportDAEMON_HOME="${PIO_HOME}"
exportDAEMON_ALLOW_DOWNLOAD_BINARIES="true"
exportDAEMON_RESTART_AFTER_UPGRADE="true"

Create cosmovisor Directories

Cosmovisor requires directories for genesis and wrapping the provenanced daemon process. To create directories and symlinks, use the following.

shell
mkdir-p$PIO_HOME/cosmovisor/genesis/bin
mkdir-p$PIO_HOME/cosmovisor/upgrades
ln-sf$PIO_HOME/cosmovisor/genesis/bin$PIO_HOME/cosmovisor/genesis/current

To create a symlink to the provenanced daemon in the cosmovisor genesis directory, use the following.

shell
cp$(which provenanced)$PIO_HOME/cosmovisor/genesis/bin
ln-sf$PIO_HOME/cosmovisor/genesis/bin/provenanced$(which provenanced)

Start Node using Cosmovisor

Once cosmovisor has been installed and configured, it effectively wraps up the provenanced daemon process. To start the Provenanced node, use the following cosmovisor process.

shell
cosmovisor start--testnet--home$PIO_HOME--p2p.seeds 4403e0e55fa4e43a454c4bf7922c8a93a51fb12d@seed.test.provenance.io:26656 --x-crisis-skip-assert-invariants

A node process should now be running in the foreground. It is an exercise for the reader to integrate the provenanced (again, wrapped by cosmovisor) with a service manager like systemd or launchd.

Running a testnet node from quicksync

Running a testnet node for pio-testnet-1 from a quicksync file.

The steps for running testnet are for the most part the same as mainnet except that the github repo is here https://github.com/provenance-io/testnet, the -t flag is required to set the key prefix from 505 to 1 (putting the binary in testnet mode)and the chain id is pio-testnet-1

markup
Step 1: download the latest quickysync via https://test.provenance.io/quicksync.
Step 2: Note down the provenance version required for the quicksync file downloaded in step 1.
Step 3: Download appropriate release from https://github.com/provenance-io/provenance/releases/ noted from step 2.
Step 4: Untar data directory from the quicksync download and replacing the untarred data directory to $PIO_HOME/data
Step 5: Run the below commands
export PIO_HOME=~/.provenanced // or directory of your choosing.
provenanced init -t choose-a-moniker --chain-id pio-testnet-1
curl https://raw.githubusercontent.com/provenance-io/testnet/main/pio-testnet-1/genesis.json> genesis.json
mv genesis.json $PIO_HOME/config
Step 6: provenanced start --testnet --p2p.seeds 4403e0e55fa4e43a454c4bf7922c8a93a51fb12d@seed.test.provenance.io:26656 --x-crisis-skip-assert-invariants

Joining Testnet

Quick Start

Start a Node in Foreground

Setting Up a New Node

Cleaning up Existing testnet Node

Download and Install Hastra

Initialize Hastra Node

Download and Install testnet Genesis File

Manually Configure config.toml Settings

Configure Seed Nodes

Configure Database Backend

Configure Logging

Configure Instrumentation

Using Hastra testnet config.toml

Download and Install testnet config.toml

Configure Cosmovisor

Download and Install Cosmovisor using go get

Build Cosmovisor from Source (Optional)

Export Cosmovisor Environment Variables

Create cosmovisor Directories

Start Node using Cosmovisor

Running a testnet node from quicksync

Download and Install Cosmovisor using `go get`