Run a Mainnet Node

DAEMON_HOME

Your DAEMON_HOME is the folder that will contain everything about the blockchain state, configuration, genesis, etc. Ensure that this folder persists across upgrades and changes. This is especially important if you plan to run the node using a container approach (Docker, Kubernetes, etc).

Fetch / Build Binaries

Download

Download the executable directly from GitHub. For the latest releases, check the releases page. Choose the correct executable for your machine and operating system.

wget https://github.com/BitBadges/bitbadgeschain/releases/download/v1.0-betanet/bitbadgeschain-linux-amd64

Example: https://github.com/BitBadges/bitbadgeschain/releases/tag/v1.0-betanet

If this is your first time downloading, you will need to also download the Wasm VM runtime library as well. This is the libwasmvm.x86_64.so file and should be placed into /usr/lib. If not, you will get "error while loading shared libraries: libwasmvm.x86_64.so: cannot open shared object file: No such file or directory".

Example

wget https://github.com/BitBadges/bitbadgeschain/releases/download/v1.0-betanet/bitbadgeschain-linux-amd64
wget https://github.com/BitBadges/bitbadgeschain/releases/download/v1.0-betanet/libwasmvm.x86_64.so
mv libwasmvm.x86_64.so /usr/lib/

Build from Source

We refer you to the README of the blockchain code repository.

Docker

Running with Docker may be the easiest option, but it also is not compatible with automatic upgrades through Cosmovisor (see section below). This means you will sacrifice availability (which is especially important for validators who are slashed when down).

docker pull bitbadges/bitbadgeschain:latest

Handling Upgrades - Cosmovisor

BitBadges handles binary upgrades using Cosmovisor, a tool for automating upgrades with zero downtime. You can find detailed information in the Cosmos documentation and the Cosmovisor documentation.

We use Cosmos SDK v0.47.5, so please use a compatible Cosmovisor version. It is expected all validators are using Cosmovisor.

Upgrades will be announced in the Discord and are facilitated with the x/upgrades module behind the scenes. You, as the node operator, will have until the upgrade time to successfully handle the upgrade. If not completed by upgrade time, your node will halt at the upgrade height. If your node is a validator, it will be slashed.

Installation / Setup

Cosmovisor

RUN_COMMAND

Depending on your setup method, you may have different commands to run the binary. Throughout the rest of this documentation, we use RUN_COMMAND to avoid repeating ourselves. Please replace your command wherever you see RUN_COMMAND

Cosmovisor

# The "run" is important. Ex:
# cosmovisor run init -> Blockchain initialixation
# cosmosvisor init -> Cosmosvisor folder initialization
cosmovisor run ....

Plain Executable

./bitbadgeschaind ....

Docker

# Replace DAEMON_HOME
docker run -it \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 26660:26660 \
    -p 6060:6060 \
    -p 9090:9090 \
    -p 1317:1317 \
    --mount type=bind,source="$DAEMON_HOME",target=/root/.bitbadgeschain \
    bitbadges/bitbadgeschain:latest ... 

Initialization / Syncing

In order to catch up to the current consensus, you will need to get your node synced. This can be done from genesis (time consuming but no trust needed) or from a recent snapshot of the state (faster but requires a trusted node).

From Snapshot / State Sync

If you do not want to reconstruct the entire history of the chain from genesis, you can start from a checkpoint. This can potentially save you days of syncing but requires you to trust an existing node.

State Sync

You can configure your config.toml to use the Cosmos SDK state sync to quickly sync from a trusted node. Feel free to use the official RPC node to do this. We refer you to here https://docs.tendermint.com/v0.34/tendermint-core/state-sync.html or you can reference other Cosmos SDK state sync documentation.

Snapshot

You can get the necessary files from an existing snapshot, add them to your DAEMON_HOME, and start the chain.

From Genesis

Syncing from genesis means that you start with the blank genesis state and verify all transactions from block 1 to the current block. Thus, this may take while. Also, note that the chain binary may be upgraded over time. To continue syncing, you will always need the relevant binary for the current block. This means you must handle ALL chain upgrades (since you are syncing from genesis).

To initialize a new chain, run the following (depending on your build method). CHAIN_ID will be "bitbadges_1-1" for mainnet. Initialization should only be performed once.

RUN_COMMAND init <moniker> --chain-id CHAIN_ID

You'll need to replace <moniker> with a custom username for your node and the CHAIN_ID for the chain you want (bitbadges_1-1 for mainnet).

Take note of where your configuration files live. We expect it to be in /root/.bitbadgeschain but if it isn't, you will need to make sure it is correct with --home flags. We call this DAEMON_HOME.

If you are getting directories do not exist error, you may have to do the following first. These will be overwritten when the init command is executed, but it is just to get the errors out of there.

cd DAEMON_HOME
mkdir config
mkdir data
mkdir wasm

Fetching the Correct Genesis JSON

The init command creates a default genesis, but you will need to replace it with the agreed upon version.

To do this for betanet, execute the following:

cd DAEMON_HOME/config
rm genesis.json
curl -o genesis.json https://raw.githubusercontent.com/BitBadges/bitbadgeschain/master/betanet.genesis.json

Configuration

Inside the DAEMON_HOME/config folder, you'll find two files: config.toml and app.toml. Both files contain extensive comments to help you customize your node settings. You can also run RUN_COMMAND start --help for explanations.

Tweak these as desired. Some important ones are highlighted below.

Setting Seed Nodes

In order to pull data from other nodes, you need to have seed nodes or peers to pull from. You may use [e-mail]:26656 for our node ID for betanet. To establish connections with trusted nodes, edit config.toml. For instance:

seeds = "[e-mail]:26656"

These entries follow the format nodeId@listenaddress:port. Additionally, you can set up seed nodes by specifying them in the seeds field. Or, private peers at private_peer_ids.

Listen Addresses / Firewalls

Ensure that the listen address settings are correct, using your IP address or domain name if configured. Also, make sure that your firewall exposes the necessary ports (22, 1317, 9090, 26656, 26657, 26660). See here for more information and other best practices running a node in production: https://docs.cosmos.network/main/user/run-node/run-production#go.

Running the Node

Once you have the node all configured, run the following to start the chain. You should see blocks being synced if configured correctly.

RUN_COMMAND run start

Other Considerations

Setting up your node infrastructure correctly and with best practices is crucial to ensure security. There are many options for this, so below we just give some general guidelines.

• DDoS Mitigation: Being part of a network with a known IP address can expose you to DDoS attacks. Learn how to mitigate these risks here. Consider using sentry nodes and proxies.

• Key Management: Implement best practices for key management, including key management systems such as TMKMS. This is especially important for validators.

• Redundancy: Plan for infrastructure failures such as power outages to ensure the continuous operation of your validator. Consider setting up your software as a service to avoid relaunching it manually every time. Refer to the Cosmos documentation for guidance on configuring your node as a service.

• Consider also running your node + Cosmovisor as a service, so it relaunches automatically. See https://tutorials.cosmos.network/tutorials/9-path-to-prod/6-run.html and https://tutorials.cosmos.network/tutorials/9-path-to-prod/7-migration.html

Running a Validator

As explained in the Launch Phases docs, reach out to us in Discord if you plan to run a validating node and need $STAKE. This is free and only requires a quick application process.

Setup - Validator Keys

Follow the instructions in the Cosmos documentation and/or the Cosmos Tutorials to set up your validator keys. Replace simd with bitbadgeschaind or myproject with bitbadgeschain.

A validator handles two perhaps three, different keys. Most likely keys 2 and 3 are the same. Each has a different purpose:

1. The Tendermint consensus key is used to sign blocks on an ongoing basis. It is of the key type ed25519, which the KMS can keep. When Bech-encoded, the address is prefixed with cosmosvalcons and the public key is prefixed with cosmosvalconspub.

2. The validator operator application key is used to create transactions that create or modify validator parameters. It is of type secp256k1, or whichever type the application supports. When Bech-encoded, the address is prefixed with cosmosvaloper.

3. The delegator application key is used to handle the stake that gives the validator more weight. When Bech-encoded, the address is prefixed with cosmos and the public key is prefixed with cosmospub.

Consensus Key

The consensus key is HOT, meaning it is needed on the validator node to sign blocks. It is strongly recommended that this is set up with a signing service and key management system.

By default, when you ran the init command, it creates a key for you in ..../config/priv_validator_key.json.

This is convenient if you are starting a testnet, for which the security requirements are low. However, for a more valuable network, you should not store it directly in the node's filesystem. It should be stored in a more secure manner, such as with a signing service or key management system.

Operator / Delegator Key

The application / operator key should be COLD and NOT be stored on the validator node. This is just your standard public/private key pair used to sign transactions.

This can be generated (if you don't already have one) by running the following command.

bitbadgeschaind keys --keyring-backend file --keyring-dir /root/.bitbadgeschain/keys
add <name>

Adjust the command accordingly. Note you should run this and store it on your local desktop, not the validating node.

Joining the Validator Set

If you intend to run a validator node, execute the following command adjusted accordingly to join the set of validators (assuming you're not part of the initial genesis set). Run with --help for more details. Replace bitbadgeschaind tx with your run command (dependent on your build method). This is the same command as how you started the node (but replace start with tx).

RUN_COMMAND tx staking create-validator /path/to/validator.json \
  --chain-id="name_of_chain_id" \
  --gas="auto" \
  --gas-adjustment="1.2" \
  --gas-prices="0.025ubadge" \
  --from=mykey

This should be signed with your normal key pair for signing transactions. Ensure you have enough $BADGE credits to cover gas and your stake. The validator.json file should contain relevant information about your validator, including the consensus public key, moniker, website, security contact, details, commission rates, and min-self-delegation.

You can obtain the public validator consensus public key using thebitbadgeschaind tendermint show-validator command.