Overview

cheqd Cosmos CLI can be used manage keys on a node.Keys are closely related to accounts and on-ledger authentication.

Account addresses are on a cheqd node are an encoded version of a public key. Each account is linked with at least one public-private key pair. Multi-sig accounts can have more than one key pair associated with them.

To submit a transaction on behalf of an account, it must be signed with an account's private key.

Cosmos supports multiple keyring backends for the storage and management of keys. Each node operator is free to use the key management method they prefer.

By default, the cheqd-noded binary is configured to use the os keyring backend, as it is a safe default compared to file-based key management methods.

For test networks or local networks, this can be overridden to the test keyring backend which is less secure and uses a file-based key storage mechanism where the keys are stored un-encrypted. To use the test keyring backend, append --keyring-backend test to each command that is related to key management or usage.

Types of keys on a cheqd node

Each cheqd validator node has at least two keys.

Node key

• Default location is $HOME/config/node_key.json

• Used for peer-to-peer communication

Validator key

• Default location is $HOME/config/priv_validator_key.json

• Used to sign consensus messages

Node-related commands in cheqd CLI

Creating a key

When a new key is created, an account address and a mnemonic backup phrase will be printed. Keep mnemonic safe. This is the only way to restore access to the account if they keyring cannot be recovered.

Command

cheqd-noded keys add <alias>

Restoring a key from backup mnemonic phrase

Allows restoring a key from a previously-created BIP39 mnemonic phrase.

Command

cheqd-noded keys add --recover <alias>

Listing available keys on a node

Command

cheqd-noded keys list

Using a key for transaction signing

Most transactions will require you to use --from <key-alias> param which is a name or address of private key with which to sign a transaction.

Command

cheqd-noded tx <module> <tx-name> --from <key-alias>

Overview

A cheqd-node instance can be controlled and configured using the cheqd Cosmos CLI.

This document contains the commands for node operators that relate to node management, configuration, and status.

Node-related commands in cheqd CLI

Starting a node

cheqd-noded start

Getting node ID / node address

Node ID or node address is a part of peer info. It's calculated from node's pubKey as hex(address(nodePubKey)). To get node id run the following command on the node's machine:

cheqd-noded tendermint show-node-id

Get validator address

Validator address is a function of validator's public key. To get bech32 encoded validator address run this command on node's machine:

$ cheqd-noded tendermint show-address
cheqdvalcons1sg4azh7qwk6akm0eadkgvgq2kegtzksr09a685

There are several ways to get hex-encoded validator address:

1. Convert from bech32

   Copy

   cheqd-noded keys parse <bech-32-encoded-address>

2. Query node using CLI:

   Copy

   cheqd-noded status

   Look for "ValidatorInfo":{"Address":"..."}

Getting validator public key

Validator public key is used in create-validator transactions. To get bech32 encoded validator public key, run the following command on the node's machine:

$ cheqd-noded tendermint show-validator

{"@type":"/cosmos.crypto.ed25519.PubKey","key":"y8v/nsf+VFCnJ7c9ZM/C4tUMnWKHhU+K+B82B+5vUZg="}

Sharing peer information

Peer info is used to connect to peers when setting up a new node. It has the following format:

<node-id>@<node-url>

Example:

ba1689516f45be7f79c7450394144711e02e7341@3.13.19.41:26656

Using this information other participants will be able to join your node.

ℹ️ Overview

cheqd is a public self-sovereign identity (SSI) network for building secure 🔐 and private 🤫 self-sovereign identity systems on Cosmos 💫. Our core vision is to add viable commercial models to decentralised digital 🆔

cheqd-node is the ledger/node component of the cheqd network tech stack, built using Cosmos SDK and Tendermint.

▶️ Quick start for joining cheqd networks

Join our cheqd Discord Server for help, questions, and support if you are looking to join our mainnet or testnet. Either the cheqd team, or one of your fellow node operators will be happy to offer some guidance.

✅ Mainnet

Getting started as a node operator on the cheqd network mainnet is as simple as...

1. Install the latest stable release of cheqd-node software (currently v2.x.x) on a hosting platform of your choice by following the setup guide.

2. Once you have acquired CHEQ tokens, promote your node to a validator

If successfully configured, your node would become the latest validator on the cheqd mainnet. Welcome to the new digital ID revolution!

🚧 Testnet

Our testnet is the easiest place for developers and node operators to get started if you're not quite ready yet to dive into building apps on our mainnet. To get started...

1. Install the latest stable release of cheqd-node software (currently v2.x.x) on a hosting platform of your choice by following the setup guide.

2. Acquire testnet CHEQ tokens through our testnet faucet.

3. Once you have acquired CHEQ tokens, promote your node to a validator

🧑‍💻 Using cheqd

Once installed, cheqd-node can be controlled using the cheqd Cosmos CLI guide.

📌 Currently supported functionality

• Basic token functionality for holding and transferring tokens to other accounts on the same network

• Creating, managing, and configuring accounts and keys on a cheqd node

• Staking and participating in public-permissionless governance

• Governance framework for public-permissionless self-sovereign identity networks

• Creating did:cheqd method DIDs, DID Documents ("DIDDocs")

• Querying DIDs/DIDDocs using our Universal Resolver driver

• Creating and managing Verifiable Credentials anchored to DIDs on cheqd mainnet

• Creating on-ledger DID-Linked "resources" (e.g., schemas, visual representations of credentials, etc) that can be used in DIDDocs and Verifiable Credentials. This is used to support AnonCreds on cheqd

• Custom pricing for DID and Resources with burn to manage inflation

• Revocation registry/list support to revoke issued credentials

• Trust registry support to manage accreditations betweeen organisations, using DIDs and DID-Linked Resources

• Holder-pays-issuer and verifier-pays-issuer payment rails for Verifiable Credential exchange.

We plan on adding new functionality rapidly and on a regular basis and welcome feedback on our cheqd Discord server.

See our detailed Product Docs below for more information:

🛠 Developing & contributing to cheqd

cheqd-node is written in Go and built using Cosmos SDK. The Cosmos SDK Developer Guide explains a lot of the basic concepts of how the cheqd network functions.

If you want to build a node from source or contribute to the code, please read our guide to building and testing.

Creating a local network

If you are building from source, or otherwise interested in running a local network, we have instructions on how to set up a new network for development purposes.

🐞 Bug reports & 🤔 feature requests

If you notice anything not behaving how you expected, or would like to make a suggestion / request for a new feature, please create a new issue and let us know.

💬 Community

The cheqd Discord is our primary chat channel for the open-source community, software developers, and node operators.

Please reach out to us there for discussions, help, and feedback on the project.

🙋 Find us elsewhere

Context

We provide for installation by those who want to run on Docker-based systems.

Docker-based installations are useful when running non-validator (observer) nodes that can be auto-scaled according to demand, or if you're a developer who setup a localnet / access node CLI without running a node.

⚠️ It is NOT recommended to run a validator node using Docker since you need to be absolutely certain about not running two Docker containers as validator nodes simultaneously. If two Docker containers with the same validator keys are active at the same time, this could be perceived by the network as a validator compromise / double-signing infraction and result in jailing / slashing.

Pre-requisites

pre-requisites below, either as individual installs or using (if running on a developer machine):

1. Docker Engine v20.10.x and above (use docker -v to check)

2. Docker Compose v2.3.x and above (use docker compose version to check)

Our Docker Compose files . The primary difference in usage is that Docker Compose's new implementation uses docker compose commands (with a space), rather than the legacy docker-compose although they are supposed to be drop-in replacements for each other.

Special guidance for Mac OS running on Apple silicon (M-series chips)

Most issues with Docker that get raised with us are typically with for.

Other issues are due to developers . If your issues are specifically with Docker Compose, make sure the command used is docker compose (with a space).

Usage

Fetch the latest stable Docker image

Modify environment variables used by Docker Compose

Both of the .env files are signposted with the REQUIRED and OPTIONAL parameters that can be defined. You must fill out the required configuration parameters.

Start Docker container

Using Docker Compose

Once the environment variable files are edited, bringing up a Docker container is as simple as:

Using Docker

If you decide not to use the Docker Compose method, you'll need to configure node settings and volumes for the container manually.

Once you've configured these manually, start using

Alternatively, if you want to just start with the bash terminal without actually starting a node, you could use:

Stop running container

To stop a detached container that was started using Docker Compose, use:

If you also want to remove the container volumes when stopping, add the --volumes flag to the command:

Be careful with removing volumes, since critical data such as node/validator keys will also be removed when volumes are removed. There's no way to get these back, unless you've backed them up independently.

Advanced usage

We have additional guides for the following advanced usage scenarios:

Overview

There are two command line interface (CLI) tools for interacting with a running cheqd-node instance:

• cheqd Cosmos CLI: This is intended for node operators. Typically for node configuration, setup, and Cosmos keys.

• Identity SDKs: Such as Veramo SDK plugin for cheqd, for identity transactions with DIDs, Verifiable Credentials, and DID-Linked Resources.

This document is focussed on providing guidance on how to use the cheqd Cosmos CLI.

cheqd Cosmos CLI commands by functionality

• Node management

• Key management

• Account management

• Token transactions

Overview

A cheqd-node instance can be controlled and configured using the cheqd Cosmos CLI.

This document contains the commands for reading and writing token transactions.

Token-related transaction commands in cheqd CLI

Querying ledger

Command

cheqd-noded query <module> <query> <params> --node <url>

Arguments

• --node: IP address or URL of node to send the request to

Example

$ cheqd-noded query bank balances 

cheqd1lxej42urme32ffqc3fjvz4ay8q5q9449f06t4v --node https://rpc.cheqd.network:443

Submitting transactions

Command

cheqd-noded tx <module> <tx> <params> --node <url> --chain-id <chain> --fees <fee>

Arguments

• --node: IP address or URL of node to send request to

• --chain-id: i.e. cheqd-testnet-6

• --fees: Maximum fee limit that is allowed for the transaction.

Status codes

Pay attention at return status code. It should be 0 if a transaction is submitted successfully. Otherwise, an error message may be returned.

Example

$ cheqd-noded tx bank send alice 

cheqd10dl985c76zanc8n9z6c88qnl9t2hmhl5rcg0jq 10000ncheq --node http://localhost:26657 --chain-id cheqd-testnet-6 --fees 50ncheq

Context

Cosmos SDK and Tendermint has a concept of pruning, which allows reducing the disk utilisation and storage required on a node.

There are two kinds of pruning controls available on a node:

1. Tendermint pruning: This impacts the ~/.cheqdnode/data/blockstore.db/ folder by only retaining the last n specified blocks. Controlled by the min-retain-blocks parameter in ~/.cheqdnode/config/app.toml.

2. Cosmos SDK pruning: This impacts the ~/.cheqdnode/data/application.db/ folder and prunes Cosmos SDK app-level state (a logical layer higher than Tendermint, which is just peer-to-peer). These are set by the pruning parameters in the ~/.cheqdnode/config/app.toml file.

This can be done by modifying the pruning parameters inside /home/cheqd/.cheqdnode/config/app.toml file.

Instructions

⚠️ In order for either type of pruning to work, your node should be running the latest stable release of cheqd-node (at least v1.3.0+).

You can check which version of cheqd-noded you're running using:

cheqd-noded version

The output should be a version higher than v1.3.0. If you're on a lower version, you either manually upgrade the node binary or use the interactive installer to execute an upgrade while retaining settings.

The instructions below assume that the home directory for the cheqd user is set to the default value of /home/cheqd. If this is not the case for your node, please modify the commands below to the correct path.

Check systemd service status

Follow similar instructions as mentioned in the installer guide to check systemd service status:

systemctl status cheqd-cosmovisor.service

(Substitute with cheqd-noded.service if you're running a standlone node rather than with Cosmovisor.)

Switch to the cheqd user and configuration directory

Switch to the cheqd user and then the .cheqdnode/config/ directory.

sudo su cheqd
cd ~

Display current directory usage/size for the node data folder

Before you make changes to pruning configuration, you might want to capture the existing usage first (only copy the command bit, not the full line):

root@hostname ~# du -h -d 1 /home/cheqd/.cheqdnode/data/ 2>/dev/null
60G     /home/cheqd/.cheqdnode/data/blockstore.db
80K     /home/cheqd/.cheqdnode/data/evidence.db
1021M   /home/cheqd/.cheqdnode/data/cs.wal
274G    /home/cheqd/.cheqdnode/data/application.db
50G     /home/cheqd/.cheqdnode/data/tx_index.db
72K     /home/cheqd/.cheqdnode/data/snapshots
45G     /home/cheqd/.cheqdnode/data/state.db
428G    /home/cheqd/.cheqdnode/data/

The du -h -d 1 ... command above prints the disk usage for the specified folder down to one folder level depth (-d 1 parameter) and prints the output in GB/MB (-h parameter, which prints in human-readable values).

Open the app.toml file for editing

Open the app.toml file once you've switched to the ~/.cheqdnode/config/ folder using your preferred text editor, such as nano:

cd ~/.cheqdnode/config/
nano app.toml

Instructions on how to use text editors such as nano is out of the scope of this document. If you're unsure how to use it, consider following guides on how to use nano.

Choose a Cosmos SDK pruning strategy

⚠️ If your node was configured to work with release version v1.2.2 or earlier, you may have been advised to run in pruning="nothing" mode due to a bug in Cosmos SDK.

Ensure you've upgraded to the latest stable release (using the installer) or otherwise. When running a validator node, you're recommended to change this value to pruning="default".

The file should already be populated with values. Edit the pruning parameter value to one of following:

1. pruning="nothing" (highest disk usage): This will disable Cosmos SDK pruning and set your node to behave like an "archive" node. This mode consumes the highest disk usage.

2. pruning="default" (recommended, moderate disk usage): This keeps the last 100 states in addition to every 500th state, and prunes on 10-block intervals. This configuration is safe to use on all types of nodes, especially validator nodes.

3. pruning="everything" (lowest disk usage): This mode is not recommended when running validator nodes. This will keep the current state and also prune on 10 blocks intervals. This settings is useful for nodes such as seed/sentry nodes, as long as they are not used to query RPC/REST API requests.

4. pruning="custom" (custom disk usage): If you set the pruning parameter to custom, you will have to modify two additional parameters:

   • pruning-keep-recent: This will define how many recent states are kept, e.g., 250 (contrast this against default).

   • pruning-interval: This will define how often state pruning happens, e.g., 50 (contrast against default, which does it every 10 blocks)

   • pruning-keep-every: This parameter is deprecated in newer versions of Cosmos SDK. You can delete this line if it's present in your app.toml file.

Although the paramters named pruning-* are only supposed to take effect if the pruning strategy is custom, in practice it seems that in Cosmos SDK v0.46.10 these settings still impact pruning. Therefore, you're advised to comment out these lines when using default pruning.

Example configuration file with recommended settings:

pruning = "default"

# These are applied if and only if the pruning strategy is custom.
#pruning-keep-recent = "0"
#pruning-interval = "0"

Choose a Tendermint pruning strategy

Configuring min-retain-blocks parameter to a non-zero value activates Tendermint pruning, which specifies minimum block height to retain. By default, this parameter is set to 0, which disables this feature.

Enabling this feature can reduce disk usage significantly. Be careful in setting a value, as it must be at least higher than 250,000 as calculated below:

• Unbonding time (14 days) converted to seconds = 1,210,000 seconds

• ...divided by average block time = approx. 6s / block

• = approx. 210,000 blocks

• Adding a safety margin (in case average block time goes down) = approx. 250,000 blocks

Therefore, this setting must always be updated to carefully match a valid value in case the unbonding time on the network you're running on is different. (E.g., this value is different on mainnet vs testnet due to different unbonding period.)

Using the recommended values, on the current cheqd mainnet this section would look like the following:

# Note: Tendermint block pruning is dependant on this parameter in conunction
# with the unbonding (safety threshold) period, state pruning and state sync
# snapshot parameters to determine the correct minimum value of
# ResponseCommit.RetainHeight.
min-retain-blocks = 250000

Save changes in the file

Save and exit from the app.toml file. Working with text editors is outside the scope of this document, but in general under nano this would be Ctrl+X, "yes" to Save modified buffer, then Enter.

Switch user and restart service

ℹ️ NOTE: You need root or at least a user with super-user privileges using the sudo prefix to the commands below when interact with systemd.

If you switched to the cheqd user, exit out to a root/super-user:

exit

Usually, this will switch you back to root or other super-user (e.g., ubuntu).

Restart systemd service:

sudo systemctl restart cheqd-cosmovisor.service

(Substitute with cheqd-noded.service above if you're running without Cosmovisor)

Check the systemd service status and confirm that it's running:

systemctl status cheqd-cosmovisor.service

Our installer guide has a section on how to check service status.

Next steps

If you activate/modify any pruning configuration above, the changes to disk usage are NOT immediate. Typically, it may take 1-2 days over which the disk usage reduction is progressively applied.

If you've gone from a higher disk usage setting to a lower disk usage setting, re-run the disk usage command to comapre the breakdown of disk usage in the node data directory:

du -h -d 1 /home/cheqd/.cheqdnode/data/ 2>/dev/null

The output shown should show a difference in disk usage from the previous run before settings were changed for the application.db folder (if the pruning parameters were changed) and/or the blockstore.db folder (if min-retain-blocks) was changed.

Context

This document describes how to use install and configure a new instance of cheqd-node using an interactive installer which supports the following functionality:

1. Setup a new observer/validator node from scratch

2. Configure a node to work with the testnet/mainnet network

3. Upgrade an existing node installation

Alternatively, if you want to manage network upgrades manually, you can also opt for a standadalone installation.

Pre-requisites for using interactive installer

⚠️ Read our guidance on hardware, software, and networking pre-requisites for nodes before you get started!

This document specifies the CPU/RAM requirements, firewall ports, and operating system requirements for running cheqd-node.

The interactive installer is written in Python 3 and is designed to work on Ubuntu Linux 20.04 LTS systems. The script has been written to work pre-installed Python 3.x libraries generally available on Ubuntu 20.04.

Software installed by installer

1. Cosmovisor (default, but can be skipped): The installer configures Cosmovisor by default, which is a standard Cosmos SDK tool that makes network upgrades happen in an automated fashion. This makes the process of upgrading to new releases for network-wide upgrades easier.

2. cheqd-noded binary (mandatory): This is the main piece of ledger-side code each node runs.

3. Dependencies: In case you request the installer to restore from a snapshot, dependencies such as pv will be installed so that a progress bar can be shown for snapshot extraction. Otherwise, no additional software is installed by the installer.

External URLs accessed by the installer

• Github.com: Fetch latest releases, configuration files, and network settings.

• Cloudflare DNS (optional): Used to fetch an externally-resolvable IP address, if this option is selected during install.

• Network snapshot server (optional): If requested by the user, the script will fetch latest network snapshots published on snapshots.cheqd.net and then download snapshot files from the snapshot CDN endpoint (snapshots-cdn.cheqd.net)

Usage

⚠️ The guidance below is intended for straightforward new installations or upgrades.

If your scenario is more complex, such as in case of upgrading a validator or moving a validator, please review the guidance under our validator guide.

By default, the installer will attempt to create a backup of the ~/.cheqdnode/config/ directory and important files under ~/.cheqdnode/data/ before making any destructive changes. These backups are created under the cheqd user's home directory in a folder called backup (default location: /home/cheqd/backup). However, for safety, you're recommended to also make manual backups when upgrading a node.

If you're setting up a new node from scratch, you can safely ignore the advice above.

Stop any running services related to node services

Stop the running services related to your node. If running via Cosmovisor:

sudo systemctl stop cheqd-cosmovisor.service

Or if running standalone:

sudo systemctl stop cheqd-noded.service

Download and start interactive installer

To get started, download the interactive installer script:

curl -O https://raw.githubusercontent.com/cheqd/cheqd-node/main/installer/installer.py

Then, start the interactive installer:

sudo python3 installer.py

ℹ️ NOTE: You need to execute this as root or at least a user with super-user privileges using the sudo prefix to the command.

(Fresh install) Answer prompts for installing from scratch (or overwriting existing)

The interactive installer guides you through setting up and configuring a node installation by asking as series of questions.

All the questions specify the default answer/value for that question in square ([]) brackets, for example, [default: 1]. If a default value exists, you can just press Enter without needing to type the whole answer.

1. Choose release version

Binary release version to install, automatically fetched from Github. The first release displayed in the list will always be the latest stable version. Other versions displayed below it are pre-release/beta versions.

Latest stable cheqd-noded release version is Name: v1.3.0
List of cheqd-noded releases: 
1. v1.3.0
2. v1.4.0-develop.1
3. v1.3.1-develop.1
4. v1.3.0-develop.3
5. v1.3.0-develop.2
Choose list option number above to select version of cheqd-node to install [default: 1]:

2. Set home directory for cheqd user

By default, a new user/group called cheqd will be created and a home directory created for it. The default location is /home/cheqd and any configuration data directories being created under this path at /home/cheqd/.cheqdnode.

3. Select network to join

Join either the existing mainnet (chain ID: cheqd-mainnet-1) or testnet (chain ID: cheqd-testnet-6) network.

Select cheqd network to join:
1. Mainnet (cheqd-mainnet-1)
2. Testnet (cheqd-testnet-6) [default: 1]:

4. Choose Cosmovisor configuration options

The next few questions are used to configure Cosmovisor-related options. Read an explanation of Cosmovisor configuration options in Cosmos SDK documentation, or choose to install with the default settings.

1. Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]: Use Cosmovisor to run node

2. Do you want Cosmovisor to automatically download binaries for scheduled upgrades? (yes/no) [default: yes]: By default, Cosmovisor will attempt to automatically download new binaries that have passed software upgrade proposals voted on the network. You can choose to do this manually if you want more control.

3. Do you want Cosmovisor to automatically restart after an upgrade? (yes/no) [default: yes]: By default, Cosmovisor will automatically restart the node after an upgrade height is reached and an upgrade carried out.

You can also choose no to installing with Cosmovisor on the first question, in which case a standalone binary installation is carried out.

5. Define node configuration

The next set of questions sets common node configuration parameters. These are the minimal configuration parameters necessary for a node to function, but advanced users can later customise other settings.

Answers to these prompts are saved in the app.toml and /config.toml files, which are written under /home/cheqd/.cheqdnode/config/ by default (but can be different if a different home directory was set above). An explanation of some these settings are available in requirements for running a node and the validator guide.

1. Provide a moniker for your cheqd-node [default: <hostname>]:: Moniker is a human-readable name for your cheqd-node. This is NOT the same as your validator name, and is only used to uniquely identify your node for Tendermint P2P address book.

2. What is the externally-reachable IP address or DNS name for your cheqd-node? [default: Fetch automatically via DNS resolver lookup]:: External address is the publicly accessible IP address or DNS name of your cheqd-node. This is used to advertise your node's P2P address to other nodes in the network. If you are running your node behind a NAT, you should set this to your public IP address or DNS name. If you are running your node on a public IP address, you can leave this blank to automatically fetch your IP address via DNS resolver lookup. (Automatic fetching sends a dig request to whoami.cloudflare.com)

3. Specify your node's P2P port [default: 26656]: Tendermint peer-to-peer traffic port

4. Specify your node's RPC port [default: 26657]: Tendermint RPC port

5. Specify persistent peers [default: none]: Persistent peers are nodes that you want to always keep connected to. Values for persistent peers should be specified in format: <nodeID>@<IP>:<port>,<nodeID>@<IP>:<port>.

6. Specify minimum gas price [default: 50ncheq]: Minimum gas prices is the price you are willing to accept as a validator to process a transaction. Values should be entered in format <number>ncheq (e.g., 50ncheq)

7. Specify log level (trace|debug|info|warn|error|fatal|panic) [default: error]:: The default log level of error is generally recommended for normal operation. You may temporarily need to change to more verbose logging levels if trying to diagnose issues if the node isn't behaving correctly.

8. Specify log format (json|plain) [default: json]:: JSON log format allows parsing log files more easily if there's an issue with your node, hence it's set as the default.

6. Choose whether to restore from snapshot

When setting up a new node, you typically need to download all past blocks on the network, including any upgrades that were done along the way with the specific binary releases those upgrades went through.

Since this can be quite cumbersome and take a really long time, the installer offers the ability to download a recent blockchain snapshot for the selected network from snapshots.cheqd.net.

If you skip this step, you'll need to manually synchronise with the network.

⚠️ Chain snapshots can range from 10 GBs (for testnet) to 100 GBs (for mainnet). Therefore, this step can take a long time.

If you choose this option, you can step away and return to the installer while it works in the background to complete the rest of the installation. You might want to change settings in your SSH client / server to keep SSH connections alive, since some hosts terminate connection due to inactivity.

(Alternative path) Answer prompts for upgrading an existing installation

If you're running the installer on a machine where an existing installation is already present, you'll be prompted whether you want to update/upgrade the existing installation:

Existing cheqd-node binary detected.

Do you want to upgrade an existing cheqd-node installation? (yes/no) [default: yes]:

If you choose no, this will treat the installation as if installing from scratch and prompt with the questions in section above.

If you choose yes, this will retain existing node configuration and prompt with a different set of questions as outlined below. Choosing "yes" is the default since in most cases, you would want to retain the existing configuration while updating the node binary to a newer version.

1. Choose release version for upgrade

Choose binary release version to upgrade the node to.

2. Install or bump Cosmovisor version

If Cosmovisor is detected as installed, you'll be offered the option to bump it to the latest default version. Otherwise, you will be given the option of installing it.

3. Configure Cosmovisor settings

The next section allows you to customise Cosmovisor settings. The explanations of the options are same those given above.

4. Update systemd configuration

By default, the installer will update the systemd system service settings for the following:

• cheqd-cosmovisor.service (if installed with Cosmovisor) or cheqd-noded.service (if installed without Cosmovisor): This is the service that runs the node in the background 24/7.

• rsyslog.service: Configures node-specific logging directories and settings.

• logrotate.service and logrotate.timer: Configures log rotation for node service to limit the duration/size of logs retained to sensible values. By default, this keeps 7 days worth of logs, and compresses logs if they grow larger than 100 MB in size.

Actions taken by the installer after prompts

Once all prompts have been answered, the installer attempts to carry out the changes requested. This includes:

1. Setting up a new cheqd user/group.

2. Downloading cheqd-noded and Cosmovisor binaries, as applicable.

3. Setting environment variables required for node binary / Cosmovisor to function.

4. Creating directories for node data and configuration.

5. If present, backing up existing node directories and configuration.

6. Downloading and extracting snapshots (if requested).

The installer is designed to terminate the installation process and stop making changes if it encounters an error. If this happens, please reach out to us on our community Slack or Discord for how to proceed and recover from errors (if any).

What to do after the installer finishes

⚠️ The guidance below is intended for straightforward new installations or upgrades.

If your scenario is more complex, such as in case of upgrading a validator or moving a validator, please review the guidance under our validator guide.

If the installer finishes successfully, it will exit with a success message:

[INFO]: Installation steps completed successfully
[INFO]: Installation of cheqd-noded v1.3.0 completed successfully!

[INFO]: Please review the configuration files manually and use systemctl to start the node.

[INFO]: Documentation: https://docs.cheqd.io/node

Otherwise, if the installation failed, it will exit with an error message which elaborates on the specific error encountered during setup.

The following steps are only recommended if installation has been successful.

Check systemd service is enabled

Check that the node-related systemd service is enabled. This ensures that the node service automatically restarted, even if the service fails or if the machine is rebooted.

If installed with Cosmovisor:

root@hostname ~# systemctl status cheqd-cosmovisor.service
● cheqd-cosmovisor.service - Service for running cheqd-node daemon
  Loaded: loaded (/lib/systemd/system/cheqd-cosmovisor.service; enabled; vendor preset: enabled)

The output line after the systemctl status cheqd-cosmovisor.service command should say enabled after Loaded path and vendor preset.

If installed without Cosmovisor (standalone binary install):

root@hostname ~# systemctl status cheqd-noded.service
● cheqd-noded.service - Service for running cheqd-node daemon
  Loaded: loaded (/lib/systemd/system/cheqd-noded.service; enabled; vendor preset: enabled)

The output line after the systemctl status cheqd-noded.service command should say enabled after Loaded path and vendor preset.

Start systemd service

Once the node is installed/upgraded, restart the systemd service to get the node running. These steps require root or super-user privileges as a pre-requisite.

If installed with Cosmovisor:

sudo systemctl start cheqd-cosmovisor.service

If installed without Cosmovisor:

sudo systemctl start cheqd-cosmovisor.service

Check node service is running (and stays running)

The command above should start the node service. Ideally, the node service should start running and remain running. You can check this by running the command below a couple of times in succession and checking that the output line remains as Active: running rather than any other status.

(Previous commands can be recalled in bash by pressing the up arrow key on your keyboard to repeat or cycle through previous commands.)

If installed with Cosmovisor:

root@hostname ~# systemctl status cheqd-cosmovisor.service
● cheqd-cosmovisor.service - Service for running cheqd-node daemon
  Loaded: loaded (/lib/systemd/system/cheqd-cosmovisor.service; enabled; vendor preset: enabled)
  Active: active (running) since Mon 2023-03-13 14:48:57 GMT; 1 weeks 0 days ago

The output line after the systemctl status cheqd-cosmovisor.service command should say enabled after Loaded path and vendor preset.

If installed without Cosmovisor (standalone binary install):

root@hostname ~# systemctl status cheqd-noded.service
● cheqd-noded.service - Service for running cheqd-node daemon
  Loaded: loaded (/lib/systemd/system/cheqd-noded.service; enabled; vendor preset: enabled)
  Active: active (running) since Mon 2023-03-13 14:48:57 GMT; 1 weeks 0 days ago

Confirm that node is gaining new blocks

Once the systemd service is confirmed as running, check that the node is catching up on new blocks by repeating this command 3-5 times:

(Previous commands can be recalled in bash by pressing the up arrow key on your keyboard to repeat or cycle through previous commands.)

cheqd-noded status

Note: The cheqd-noded status may not return a successful response immediately after starting the systemd service. For instance, you might get the following output:

root@hostname ~# cheqd-noded status
Error: post failed: Post "http://localhost:26657": dial tcp [::1]:26657: connect: connection refused

If you encounter the output above, as long as systemctl status ... returns Active, this "error" above is completely normal. This is because it takes a few minutes after systemctl start for the node services to properly start running. Please wait for a few minutes, and then re-run the cheqd-noded status command.

The output might say catching_up: true if the node is still catching up, or catching_up: false if it's fully caught up.

root@hostnames ~# cheqd-noded status
{"NodeInfo":{"protocol_version":{"p2p":"8","block":"11","app":"0"},"id":"<node-id>","listen_addr":"<external-address>:26656","network":"cheqd-mainnet-1","version":"0.34.26","channels":"40202122233038606100","moniker":"<moniker>","other":{"tx_index":"on","rpc_address":"tcp://0.0.0.0:26657"}},"SyncInfo":{"latest_block_hash":"082E9ACC41E72BCB566DDF9132B9011C470629F54E9F0F32B0A619265A42F1F6","latest_app_hash":"302F62AB35B8D463D398E83CF7C0597A2DCC27DF7C3C5165F7AEC4CA6B4C3C7F","latest_block_height":"7153781","latest_block_time":"2023-03-20T18:02:41.952748008Z","earliest_block_hash":"A20320D647F4EC8E6D7EC95A3F25B13B86807907BD8231A24BF3EA8171E645D3","earliest_app_hash":"2B7DA548AFF3FA8886E602993BB13CFCD0E97E7F943AF129B5DBA92284B9284A","earliest_block_height":"6903781","earliest_block_time":"2023-03-03T16:12:02.371081673Z","catching_up":false},"ValidatorInfo":{"Address":"9CE4242862F7CB95B22D2EC60CB625F6B09C9562","PubKey":{"type":"tendermint/PubKeyEd25519","value":"CGe/qgutfjKuPSFQK3ZBraNRjcyKzEvy6hd2JX73Vns="},"VotingPower":"35373490103"}}

If the node is catching up, the time needed to fully catch up will depend on how far behind your node is. The latest_block_height value in the output shown above will indicate how far behind the node is. This number should display a larger value every time you re-run the command.

❓ The absolute newest block height across the entire network is displayed in the block explorer. Check the mainnet explorer or the testnet explorer (depending on which network you've joined) to understand the network-wide latest block height vs your node's delta.

Next steps

If you're configuring a validator, check out our validator guide for further configuration steps to carry out.

Overview

A cheqd-node instance can be controlled and configured using the cheqd Cosmos CLI.

This document contains the commands for account management.

Account-related commands in cheqd CLI

Querying account balances

Command

cheqd-noded query bank balances <address>

Example

cheqd-noded query bank balances cheqd1lxej42urme32ffqc3fjvz4ay8q5q9449f06t4v

Transferring tokens

Command

cheqd-noded tx bank send <from> <to-address> <amount> --node <url> --chain-id <chain> --fees <fee>

Arguments

• from can be either key alias or address. If it's an address, corresponding key should be in keychain.

Example

$ cheqd-noded tx bank send alice 
cheqd10dl985c76zanc8n9z6c88qnl9t2hmhl5rcg0jq 10000ncheq --node http://localhost:26657 --chain-id cheqd --fees 50ncheq

Validator nodes can get "jailed" along with a penalty imposed (through its stake getting slashed). Unlike a proof-of-work (PoW) network (such as Ethereum or Bitcoin), proof-of-stake (PoS) networks (such as the cheqd network, built using ) use from validators.

Conditions that cause a validator to be jailed

There are two scenarios in which a validator could be jailed, one of which has more serious consequences than the other.

Temporary: Jailed due to downtime

When a validator "misses" blocks or doesn't participate in consensus, it can get temporarily jailed. By enforcing this check, PoS networks like ours ensure that validators are actively participating in the operation of the network, ensuring that their nodes remain secure and up-to-date with the latest software releases, etc.

The duration on how this is calculated is defined in the . Jailing occurs based on a sliding time window (called the ) calculated as follows.

1. The signed_blocks_window (set to 25,920 blocks on mainnet) defines the time window that is used to calculate downtime.

2. Within this window of 25,920 blocks, at least 50% of the blocks must be signed by a validator. This is defined in the genesis parameter min_signed_per_window (set to 0.5 for mainnet).

3. Therefore, if a validator misses 12,960 blocks within the last 25,920 blocks it meets the criteria for getting jailed.

   1. To convert this block window to a time period, consider the block time of the network, i.e., at what frequency a new block is created. The or any other explorer configured for cheqd network (such as ).

   2. Let's assume the block time was 6 seconds. This equates to 12,960 * 6 = 77,760 seconds = ~21.6 hours. This means if the validator is not participating in consensus for more than ~21.6 hours (in this example), it will get temporarily jailed.

   3. Since the block time of the network is variable on the number of nodes participating, network congestion, etc it's always important to calculate the time period on latest block time figures.

What happens when a validator is temporarily jailed for downtime

1. 1% of all of the stake delegated to the node is slashed, i.e., burned and disappears forever. This includes any stake delegated to the node by external parties. (If a validator gets jailed, delegators may decide to switch whom they delegate to.) The percentage of stake to be slashed is defined in the slash_fraction_downtime genesis parameter.

Step 1: Check your Node is up to date

During the downtime of a Validator Node, it is common for the Node to miss important software upgrades, since they are no longer in the active set of nodes on the main ledger.

Therefore, the first step is checking that your node is up to date. You can execute the command

The expected response will be the latest cheqd-noded software release. At the time of writing, the expected response would be

Step 2: Upgrading to latest software

Step 3: Confirming the Node is up to date

Once again, check if your node is up to date, following Step 1.

Expected response: In the output, look for the text latest_block_height and note the value. Execute the status command above a few times and make sure the value of latest_block_height has increased each time.

The node is fully caught up when the parameter catching_up returns the output false.

Additionally,, you can check this has worked:

It shows you a page and field "version": "0.6.0".

Step 4: Unjailing command

If everything is up to date, and the node has fully caught, you can now unjail your node using this command in the cheqd CLI:

This document offers guidance for validators looking to move thier node instance to another one, for example in case of changing VPS provider or something like this.

The main tool required for this is cheqd's .

Preparations

Before completing the move, ensure the following checks are completed:

1. Copy config directory and data/priv_validator_state.json to safe place

Check that your config directory and data/priv_validator_state.json are copied to a safe place where they will cannot affected by the migration

2. Stop the service on your current node

If you are using cosmosvisor, use systemctl stop cheqd-cosmovisor

For all other cases, use systemctl stop cheqd-noded.

3. Confirm that your previous node / service was stopped

This step is of the utmost important

If your node is not stopped correctly and two nodes are running with the same private keys, this will lead to a double signing infraction which results in your node being permemently jailed (tombstoned) resulting in a 5% slack of staked tokens.

You will also be required to complete a fresh setup of your node.

Installation

Only after you have completed the preparation steps to shut down the previous node, the installation should begin.

Once this has been completed, you will be able to move your existing keys back and settings.

Installation with the latest snapshot

The answers for installer quiestion could be:

1. Select Version

Here you can pick up the version what you want.

2. Select Home directory

Set path for cheqd user's home directory [default: /home/cheqd]:.

This is essentialy a question about where the home directory, cheqdnode, is located or will be.

It is up to operator where they want to store data, config and log directories.

3. Setup node

Do you want to setup a new cheqd-node? (yes/no) [default: yes]:

Here the expected answer is No.

The main idea is that our old config directory will be used and data will be restored from the snapshot.

We don't need to setup the new one.

4. Select Network

Select cheqd network to join (testnet/mainnet) [default: mainnet]:

For now, we have 2 networks, testnet and mainnet.

Type whichever chain you want to use or just keep the default by clicking Enter.

5. Specify Cosmovisor option

Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]:.

This is also up to the operator.

6. Specify if you are using a snapshot

CAUTION: Downloading a snapshot replaces your existing copy of chain data. Usually safe to use this option when doing a fresh installation. Do you want to download a snapshot of the existing chain to speed up node synchronisation? (yes/no) [default: yes].

On this question we recommend to answer Yes, cause it will help you to catchup with other nodes in the network. That is the main feature from this installer.

Example

Post-install steps

1. Copy your settings

• Copy config directory to the CHEQD_HOME_DIRECTORY/.cheqdnode/

• Copy data/priv_validator_state.json to the CHEQD_HOME_DIRECTORY/.cheqdnode/data

• Make sure that permissions are cheqd:cheqd for CHEQD_HOME_DIRECTORY/.cheqdnode directory. For setting it the next command can help $ sudo chown -R cheqd:cheqd CHEQD_HOME_DIRECTORY/.cheqdnode

Where CHEQD_HOME_DIRECTORY is the home directory for cheqd user. By default it's /home/cheqd or what you answered during the installation for the second question.

2. Setup external address

You need to specify here new external address by calling the next command under the cheqd user:

3. Check that service works

The latest thing in this doc is to run the service and check that all works fine.

where <service-name> is a name of service depending was Install Cosmovisor selected or not.

• cheqd-cosmovisor if Cosmovisor was installed.

• cheqd-noded in case of keeping cheqd-noded as was with debian package approach.

For checking that service works, please run the next command:

where <service-name> has the same meaning as above.

The status should be Active(running)

How do I stake more tokens after setting up a validator node?

When you set up your Validator node, it is recommended that you only stake a very small amount from the actual Validator node. This is to minimise the tokens that could be locked in an unbonding period, were your node to experience signficiant downtime.

You should delegate the rest of your tokens to your Validator node from a different key alias.

How do I do this?

You can add (as many as you want) additional keys you want using the function:

When you create a new key, a mnemonic phrase and account address will be printed. Keep the mnemonic phrase safe as this is the only way to restore access to the account if they keyring cannot be recovered.

You can view all created keys using the function:

You are able to transfer tokens between key accounts using the function.

You can then delegate to your Validator Node, using the function

We use a second/different Virtual Machine to create these new accounts/wallets. In this instane, you only need to install cheqd-noded as a binary, you don't need to run it as a full node.

And then since this VM is not running a node, you can then append the --node parameter to any request and target the RPC port of the VM running the actual node.

That way:

1. The second node doesn't need to sync the full blockchain; and

2. You can separate out the keys/wallets, since the IP address of your actual node will be public by definition and people can attack it or try to break in

How much storage should I provision?

I’d recommend at least 250 GB at the current chain size. You can choose to go higher, so that you don’t need to revisit this. Within our team, we set alerts on our cloud providers/Datadog to raise alerts when nodes reach 85-90% storage used which allows us to grow the disk storage as and when needed, as opposed to over-provisioning.

Is there any way to use less storage?

Here’s the relevant section in the file:

How do I monitor the status of my node?

• Green: 90-100% blocks signed

• Amber: 70-90% blocks signed

• Red: 1-70% blocks signed

Please join the channel 'mainnet-alerts' on the cheqd community slack.

Are there any other ways to optimise?

Yes! Here are a few other suggestions:

• You can check the current status of disk storage used on all mount points manually through the output of df -hT

• The default storage path for cheqd-node is on /home/cheqd. By default, most hosting/cloud providers will set this up on a single disk volume under the / (root) path. If you move and mount /home on a separate disk volume, this will allow you to expand the storage independent of the main volume. This can sometimes make a difference, because if you leave /home tree mounted on / mount path, many cloud providers will force you to bump the whole virtual machine category - including the CPU and RAM - to a more expensive tier in order to get additional disk storage on /. This can also result in over-provisioning since the additional CPU/RAM is likely not required.

• You can also optimise the amount of logs stored, in case the logs are taking up too much space. There’s a few techniques here:

• In config.toml you can set the logging level to error for less logging than the default which is info. (The other possible value for this is debug)

• [Set the log rotation configuration to use different/custom parameters such as what file-size to rotate at, number of days to retain etc.

What is Commission rate and is it important?

As a Validator Node, you should be familiar with the concept of commission. This is the percentage of tokens that you take as a fee for running the infrastructure on the network. Token holders are able to delegate tokens to you, with an understanding that they can earn staking rewards, but as consideration, you are also able to earn a flat percentage fee of the rewards on the delegated stake they supply.

There are three commission values you should be familiar with:

The first is the maximum rate of commission that you will be able to move upwards to.

Please note that this value cannot be changed once your Validator Node is set up, so be careful and do your research.

The second parameter is the maximum amount of commission you will be able to increase by within a 24 hour period. For example if you set this as 0.01, you will be able to increase your commission by 1% a day.

The third value is your current commission rate.

Points to note: lower commission rate = higher likelihood of more token holders delegating tokens to you because they will earn more rewards. However, with a very low commission rate, in the future, you might find that the gas fees on the Network outweight the rewards made through commission.

higher commission rate = you earn more tokens from the existing stake + delegated tokens. But the tradeoff being that it may appear less desirable for new delegators when compared to other Validators.

What is Gas and Gas Prices?

When setting up the Validator, the Gas parameter is the amount of tokens you are willing to spend on gas.

For simplicity, we suggest setting:

AND setting:

These parameters, together, will make it highly likely that the transaction will go through and not fail. Having the gas set at auto, without the gas adjustment will endanger the transaction of failing, if the gas prices increase.

Gas prices also come into play here too, the lower your gas price, the more likely that your node will be considered in the active set for rewards.

We suggest the set:

should fall within this recommended range:

1. Low: 25ncheq

2. Medium: 50ncheq

3. High: 100ncheq

How do I change my public name and description

Your public name, is also known as your moniker.

You are able to change this, as well as the description of your node using the function:

Should I set my firewall port 26656 open to the world?

Yes, this is how you should do it. Since it's a public permissionless network, there's no way of pre-determining what the set of IP addresses will be, as entities may leave and join the network. We suggest using a TCP/network load balancer and keeping your VM/node in a private subnet though for security reasons. The LB then becomes your network edge which if you're hosting on a cloud provider they manage/patch/run.

This document provides guidance on how configure and promote a cheqd node to validator status. Having a validator node is necessary to participate in staking rewards, block creation, and governance.

Preparation steps

Step 1: Ensure you have a cheqd node installed as a service

You must already have a running cheqd-node instance installed using one of the supported methods.

Please also ensure the node is fully caught up with the latest ledger updates.

1. (recommended method)

Step 2: Generate a new account key

Follow the guidance on to create a new account key.

When you create a new key, a new account address and mnemonic backup phrase will be printed. Keep the mnemonic phrase safe as this is the only way to restore access to the account if they keyring cannot be recovered.

P.S. in case of using Ledger Nano device it would be helpful to use

1. Get your node ID

   Follow the guidance on to fetch your node ID.

2. Get your validator account address

   The validator account address is generated in Step 1 above when a new key is added. To show the validator account address, follow the .

   (The assumption above is that there is only one account / key that has been added on the node. In case you have multiple addresses, please jot down the preferred account address.)

Promote a node to validator after acquiring CHEQ tokens for staking

1. Ensure your account has a positive balance
2. Get your node's validator public key
3. Promote your node to validator status by staking your token balance

   You can decide how many tokens you would like to stake from your account balance. For instance, you may want to leave a portion of the balance for paying transaction fees (now and in the future).

   To promote to validation, submit a create-validator transaction to the network:

   Parameters required in the transaction above are:

   • amount: Amount of tokens to stake. You should stake at least 1 CHEQ (= 1,000,000,000ncheq) to successfully complete a staking transaction.

   • from: Key alias of the node operator account that makes the initial stake

   • min-self-delegation: Minimum amount of tokens that the node operator promises to keep bonded

   • pubkey: Node's bech32-encoded validator public key from the previous step

   • commission-rate: Validator's commission rate. The minimum is set to 0.05.

   • commission-max-rate: Validator's maximum commission rate, expressed as a number with up to two decimal points. The value for this cannot be changed later.

   • commission-max-change-rate: Maximum rate of change of a validator's commission rate per day, expressed as a number with up to two decimal points. The value for this cannot be changed later.

   • chain-id: Unique identifier for the chain.

     • For cheqd's current mainnet, this is cheqd-mainnet-1

     • For cheqd's current testnet, this is cheqd-testnet-6

   • gas: Maximum gas to use for this specific transaction. Using auto uses Cosmos's auto-calculation mechanism, but can also be specified manually as an integer value.

   • gas-adjustment (optional): If you're using auto gas calculation, this parameter multiplies the auto-calculated amount by the specified factor, e.g., 1.4. This is recommended so that it leaves enough margin of error to add a bit more gas to the transaction and ensure it successfully goes through.

   • gas-prices: Maximum gas price set by the validator. Default value is 50ncheq.

Please note the parameters below are just an “example”.

You will see the commission they set, the max rate they set, and the rate of change. Please use this as a guide when thinking of your own commission configurations. This is important to get right, because the commission-max-rate and commission-max-change-rate cannot be changed after they are initially set.

1. Check that your validator node is bonded

   Checking that the validator is correctly bonded can be checked via any node:

   Find your node by moniker and make sure that status is BOND_STATUS_BONDED.

2. Check that your validator node is signing blocks and taking part in consensus

   Query the latest block. Open <node-address:rpc-port/block in a web browser. Make sure that there is a signature with your validator address in the signature list.

Using Ledger Nano device

To use your Ledger Nano you will need to complete the following steps:

• Set-up your wallet by creating a PIN and passphrase, which must be stored securely to enable recovery if the device is lost or damaged.

• Connect your device to your PC and update the firmware to the latest version using the Ledger Live application.

• Install the Cosmos application using the software manager (Manager > Cosmos > Install).

• Adding a new key In order to use the hardware wallet address with the cli, the user must first add it via cheqd-noded. This process only records the public information about the key.

To import the key first plug in the device and enter the device pin. Once you have unlocked the device navigate to the Cosmos app on the device and open it.

To add the key use the following command:

Note

The --ledger flag tells the command line tool to talk to the ledger device and the --index flag selects which HD index should be used.

When running this command, the Ledger device will prompt you to verify the genereated address. Once you have done this you will get an output in the following form:

Next steps

On completion of the steps above, you would have successfully bonded a node as validator to the cheqd testnet and participating in staking/consensus.

Context

This document describes the hardware and software pre-requisites for setting up a new cheqd-node instance and joining the existing testnet/mainnet. The recommended installation method is to use the .

Alternative installation methods and a developer guide to building from scratch are covered at the end of this page.

Hardware requirements

For most nodes, the RAM/vCPU requirements are relatively static and do not change over time. However, the disk storage space needs to grow as the chain grows and will evolve over time.

It is recommended to mount disk storage for blockchain data as an expandable volume/partition separate from your root partition. This allows you mount the node data/configuration path on /home (for example) and increase the storage if necessary independent of the root / partition since hosting providers typically force an increase in CPU/RAM specifications to grow the root partition.

Extended information on . The figures below have been updated from the default Tendermint recommendations to account for current cheqd network chain size, real-world usage accounting for requests nodes need to handle, etc.

Recommended hardware specifications

• 4-8 GB RAM (2 GB RAM minimum)

• x64 2.0 GHz 2-4 vCPU or equivalent (x64 1.4 GHz 1 vCPU or equivalent minimum)

• 650 GB SSD (500 GB minimum)

⚠️ Storage requirements for the blockchain grows with time. Therefore, these minimum storage figures are expected to increase over time. Read our validator guide for "pruning" settings to optimise storage consumed.

Storage volumes

We recommend using a storage path that can be kept persistent and restored/remounted (if necessary) for the configuration, data, and log directories associated with a node. This allows a node to be restored along with configuration files such as node keys and for the node's copy of the ledger to be restored without triggering a full chain sync.

Operating system

We plan on supporting other operating systems in the future, based on demand for specific platforms by the community.

Networking configuration

Ports

To function properly, cheqd-node requires two types of ports to be configured. Depending on the setup, you may also need to configure firewall rules to allow the correct ingress/egress traffic.

Node operators should ensure there are no existing services running on these ports before proceeding with installation.

P2P port

The P2P port is used for peer-to-peer communication between nodes. This port is used for your node to discover and connect to other nodes on the network. It should allow traffic to/from any IP address range.

• By default, the P2P port is set to 26656.

• Inbound TCP connections on port 26656 (or your custom port) should be allowed from any IP address range.

• Outbound TCP connections must be allowed on all ports to any IP address range.

• The default P2P port can be changed in $HOME/.cheqdnode/config/config.toml.

RPC port

The RPC port is intended to be used by client applications as well as the cheqd-node CLI. Your RPC port must be active and available on localhost to be able to use the CLI. It is up to a node operator whether they want to expose the RPC port to public internet.

• By default, the RPC port is set to 26657

• Inbound and outbound TCP connections should be allowed from destinations desired by the node operator. The default is to allow this from any IPv4 address range.

• TLS for the RPC port can also be setup separately. Currently, TLS setup is not automatically carried out in the install process described below.

• The default RPC port can be changed in $HOME/.cheqdnode/config/config.toml.

Firewall configuration

In addition to the P2P/RPC ports above, you need to allow the following ports in terms of firewall access for the node to function correctly:

1. Domain Name System (DNS): Allow outbound traffic on TCP & UDP port 53 which allows your node to make DNS queries. Without this, your node will fail to make DNS lookups necessary to reach the peer-to-peer traffic ports for other nodes.

Sentry nodes (optional)

While this setup is not compulsory, node operators with higher stakes or a need to have more robust network security may consider setting up a sentry-validator node architecture.

Alternative installation methods

Further information

Context

Blockchain applications (especially when running validator nodes) are a-typical from "traditional" web server applications because their performance characteristics tend to be different in the way specified below:

1. Tend to be more disk I/O heavy: Traditional web apps will typically offload data storage to persistent stores such as a database. In case of a blockchain/validator node, the database is on the machine itself, rather than offloaded to separate machine with a standalone engine. Many blockchains use for their local data copies. (In Cosmos SDK apps, such as cheqd, this is the , but can also be , , etc.) The net result is the same as if you were trying to run a database engine on a machine: the system needs to have fast read/write performance characteristics.

2. Validator nodes cannot easily be auto-scaled: Many traditional applications can be horizontally (i.e., add more machines) or vertically (i.e., make current machine beefier) scaled. While this is possible for validator nodes, it must be done with extreme caution to ensure there aren't two instances of the same validator active simultaneously. This can be perceived by network consensus as a sign of compromised validator keys and lead to the . These concerns are less relevant for non-validating nodes, since they have a greater tolerance for missed blocks and can be scaled horizontally/vertically.

3. Docker/Kubernetes setups are not recommended for validators (unless you really know what you're doing): Primarily due to the double-signing risk, it's (../setup-and-configure/docker.md) unless you have a strong DevOps practice. The other reason is related to the first point, i.e., a Docker setup adds an abstraction layer between the actual underlying file-storage vs the Docker volume engine. Depending on the Docker (or similar abstraction) storage drivers used, you may need to for optimal performance.

Diagnosing a CPU/memory leak

⚠️ Please ensure you are running the since they may contain fixes/patches that improve node performance.

What does a CPU/memory leak look like?

If you've got monitoring built in for your machine, a memory (RAM) leak would look like a graph where memory usage grows to 100%, falls off a cliff, grows to 100% again (the process repeats itself).

Normal memory usage may grow over time, but will not max out the available memory up to 100%. The graph below is taken from a server run by the cheqd team, over a 14-day period:

Figure 1: Graph showing normal memory usage on a cheqd-node server

What does a CPU leak look like?

A "CPU leak", i.e., where one or more process(es) consume increasing amounts of CPU is rarer, but could also happen if your machine has too few vCPUs and/or underpowered CPUs.

Figure 2: Graph showing normal CPU usage on a cheqd-node server

Figure 4: Graph showing CPU usage on Hetzner cloud, adding up to more than 100%

Check what accounting metric your monitoring tool uses to get a realistic idea of whether your CPU is overloaded or not.

Determining CPU/memory usage with command-line tools

If you don't have a monitoring application installed, you could use the built-in top or htop command.

Figure 2: Output of htop showing CPU and memory usage

htop is visually easier to understand than top since it breaks down usage per-CPU, as well as memory usage.

Troubleshooting system clock synchronisation issues

The net result of your system clock being out of sync is that your node:

• Constantly tries to dial peers to try and fetch new blocks

• Connection gets rejected by some/all of them

• Keeps retrying the above until CPU/memory get exhausted, or the node process crashes

To check if your system clock is synchronised, use the following command (note: only copy the command, not the sample output):

The timezone your machine is based in doesn't matter. You should check whether it reports System clock synchronized: yes and NTP service: active.

Resolving system clock issues

NTP firewall rules

You may also need to allow outbound UDP traffic on port 123 explicitly, depending on your firewall settings. This port is used by the Network Time Protocol (NTP) service.

Troubleshooting node connectivity issues

The JSON output should be similar to below:

Look for the n_peers value at the beginning: this shows the number of peers your node is connected. A healthy node would typically be connected to anywhere between 5-50 nodes.

Next, search the results for the term is_outbound. The number of matches for this term should exactly be the same as the value of n_peers, since this is printed once per peer. The value of is_oubound may either be true or false.

A healthy node should have a mix of is_outbound: true as well as is_outbound: false. If your node reports only one of these values, it's a strong indication that your node is unidirectionally connected/reachable, rather than bidirectionally reachable.

Unidirectional connectivity may cause your node to work overtime to stay synchronised with latest blocks on the network. You may fly by just fine - until there's a loss of connectivity to critical mass of peers and then your node goes offline.

Furthermore, your node might fetch the address book from seed nodes, and then try to resolve/contact them (and fail) due to connectivity issues.

Is your node's external address reachable?

Ideally, the IP address or DNS name set in external_address property in your config.toml file should be externally reachable.

Once you have tcptraceroute installed, from this external machine you can execute the following command in tcptraceroute <hostname> <port> format (note: only copy the actual command, not sample output):

A successful run would result in tcptraceroute reaching the destination server on the required port (e.g., 26656) and then hanging up. If the connection times out consistently at any of the hops, this could indicate there's a firewall / router in the path dropping or blocking connections.

Resolving connectivity issues due to blocked firewall ports

1. Inbound TCP traffic on at least port 26656 (or custom P2P port)

2. Optionally, inbound TCP traffic on other ports (RPC, gRPC, gRPC Web)

3. Outbound TCP traffic on all ports

Router vs firewall issues

Besides firewalls, depending on your network infrastructure, your connectivity issue instead might lie in a router or Network Address Translation (NAT) gateway.

Operating system firewalls

In addition to infrastructure-level firewalls, Ubuntu machines also come with firewall on the machine itself. Typically, this is either disabled or set to allow all traffic by default.

Connectivity issues due to blocked DNS traffic

Another common reason for unidirectional node connectivity occurs when the correct P2P inbound/outbound traffic is allowed in firewalls, but DNS traffic is blocked by a firewall.

Your node needs the ability to lookup DNS queries to resolve nodes with DNS names as their external_address property to IP addresses, since other peers may advertise their addresses as a DNS name. Seed nodes set in config.toml are a common example of this, since these are advertised as DNS names.

Your node may still scrape by if DNS resolution is blocked, for example, by obtaining an address book from a peer that has already done DNS -> IP resolution. However, this approach can be liable to break down if the resolution is incorrect or entries outdated.

Firewall rules to allow DNS traffic

To enable DNS lookups, your infrastructure/OS-level firewalls should allow:

1. Outbound UDP traffic on port 53: This is the most commonly-used port/protocol.

Checking whether DNS resolution works

If the lookup fails, that could indicate DNS queries or blocked, or there are no externally-resolvable IPs where the node can be reached.

Other troubleshooting steps

Is your machine underpowered?

Typically, this problem is seen if you (non-exhaustive list):

• Have only one CPU (bump to at least two CPU)

• Only 1-2 GB of RAM (bump to at least 4 GB)

Most cloud providers should allow dynamically scaling these two factors without downtime. Monitor - especially over a period of days/weeks - whether this improves the situation or not. If the CPU/memory load behaviour remains similar, that likely indicates the issue is different.

Scaling CPU/memory without downtime may be different you're running a physical machine, or if your cloud provider doesn't support it. Please follow the guidance of those hosting platforms.

Context

Updates to the ledger code running on cheqd mainnet/testnet is voted in via governance proposals on-chain for "breaking" software changes.

We use semantic versioning to define our software release versions. The latest software version running on chain is in the v1.x.x family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be compatible within the family and does not require an on-chain upgrade proposal to be made.

Latest on-chain software upgrade

Creating a new software upgrade proposal

Network-wide software upgrades are typically initiated by the core development team behind the cheqd project. The process followed for the network upgrade is defined in our guide on creating a Software Upgrade proposal via network governance.

Legacy software upgrade proposals

This section lists previous software upgrade proposals which are no longer valid for the active mainnet/testnet.

Context

ℹ️ We provide installation instructions using pre-built Docker images if you just want to setup and use a Docker-based node.

These advanced instructions are intended for developers who want to build their own custom Docker image. You can also build a binary using Golang, or run a Docker-based localnet.

Pre-requisites

Install Docker pre-requisites below, either as individual installs or using Docker Desktop (if running on a developer machine):

1. Docker Engine v20.10.x and above (use docker -v to check)

2. Docker Compose v2.3.x and above (use docker compose version to check)

Our Docker Compose files use Compose v2 syntax. The primary difference in usage is that Docker Compose's new implementation uses docker compose commands (with a space), rather than the legacy docker-compose although they are supposed to be drop-in replacements for each other.

Special guidance for Mac OS running on Apple silicon (M-series chips)

Most issues with Docker that get raised with us are typically with developers running Mac OS with Apple M-series chips, which Docker has special guidance for.

Other issues are due to developers using the legacy docker-compose CLI rather than the new docker compose CLI. If your issues are specifically with Docker Compose, make sure the command used is docker compose (with a space).

Instructions

Clone the repository

Clone the cheqd-node repository from Github. (Github has instructions on how to clone a repo.)

(Optional) Inspect and modify Dockerfile

Inspect the Dockerfile to understand build arguments and variables. This is only really necessary if you want to modify the Docker build.

Or, If you want to use Docker buildx engine, look at the usage/configuration in our Github build workflow.

Note: If you're building on a Mac OS system with Apple M-series chips, you should modify the FROM statement in the Dockerfile to FROM --platform=linux/amd64 golang:1.18-alpine AS builder. Otherwise, Docker will try to download the Mac OS darwin image for the base Golang image and fail during the build process.

Build the image

Using Docker Compose

If you're planning on passing/modifying a lot of build arguments from their defaults, you can modify the Docker Compose file and the associated environment files to define the build/run-time variables in a one place. This is the recommended method.

Note that a valid Docker Compose file will only have one build and image section, so modify/comment this as necessary. See our instructions for how to use Docker Compose for mainnet/testnet to understand how this works.

Sample command (modify as necessary):

docker compose -f docker/localnet/docker-compose.yml build

Using Docker

If you don't want to use docker compose build, or build using docker build and then run it using Docker Compose, a sample command you could use is (modify as necessary)

docker build . -f docker/Dockerfile --target runner --tag cheqd-node:build-local

Next steps

Once you built a Docker image, you can:

• Configure a Docker-based node installation for mainnet/testnet

• Run a localnet using this custom Docker image

If you're running a validator node, it's important to backup your validator's keys and state - especially before attempting any updates or shifting nodes.

What to backup from a validator node

Each validator node has three files/secrets that must be backed up, in case you want to restore or move a node. Anything not in scope listed below can be easily restored from snapshot or otherwise replaced with fresh copies, and as such this list is the bare minimum that needs to be backed up.

$CHEQD_HOME is the data directory for your node, which defaults to /home/cheqd/.cheqdnode

Validator private key

The validator private key is one of the most important secrets that uniquely identifies your validator, and what this node uses to sign blocks, participate in consensus etc. This file is stored under $CHEQD_HOME/config/priv_validator_key.json.

Node key

In the same folder as your validator private key, there's another key called $CHEQD_HOME/config/node_key.json. This key is used to derive the node ID for your validator.

Backing up this key means if you move or restore your node, you don't have to change the node ID in the configuration files any peers have. This is only relevant (usually) if you're running multiple nodes, e.g., a sentry or seed node.

For most node operators who run a singular validator node, this node key is NOT important and can be refreshed/created as new. It is only used for Tendermint peer-to-peer communication. Hypothetically, if you created a new node key (say when moving a node from one machine to another), and then restored the priv_validator_key.json, this is absolutely fine.

Validator private state

The validator private state is stored in the data folder, not the config folder where most other configuration files are kept - and therefore often gets missed by validator operators during backup. This file is stored at $CHEQD_HOME/data/priv_validator_state.json.

This file stores the last block height signed by the validator and is updated every time a new block is created. Therefore, this should only be backed up after stopping the node service, otherwise, the data stored within this file will be in an inconsistent state. An example validator state file is shown below:

{
  "height": "3968024",
  "round": 0,
  "step": 3,
  "signature": "<signature>",
  "signbytes": "<sign-bytes>"
}

If you forget to restore to the validator state file when restoring a node, or when restoring a node from snapshot, your validator will double-sign blocks it has already signed, and get jailed permanently ("tombstoned") with no way to re-establish the validator.

Upgrade height information

The software upgrades and block height they were applied at is stored in $CHEQD_HOME/data/upgrade-info.json. This file is used by Cosmovisor to track automated updates, and informs it whether it should attempt an upgrade/migration or not.

{"name":"v0.6","height":2478827,"info":"{\"binaries\":{\"linux/amd64\":\"https://github.com/cheqd/cheqd-node/releases/download/v0.6.0/cheqd-noded\"}}"}

Manual backup and restore

The simplest way to backup your validator secrets listed above is to display them in your terminal:

cat <filename>

You can copy the contents of the file displayed in terminal off the server and store it in a secure location.

To restore the files, open the equivalent file on the machine where you want to restore the files to using a text editor (e.g., nano) and paste in the contents:

nano <filename>

Backing up and restoring via HashiCorp Vault

HashiCorp Vault is an open-source project that allows server admins to run a secure, access-controlled off-site backup for secrets. You can either run a self-managed HashiCorp Vault server or use a hosted/managed HashiCorp Vault service.

Pre-requisites

Before you get started with this guide, make sure you've installed HashiCorp Vault CLI on the validator you want to run backups from.

You also need a running HashiCorp Vault server cluster you can use to proceed with this guide.

Setting up a HashiCorp Vault cluster is outside the scope of this documentation, since it can vary a lot depending on your setup. If you don't already have this set up, HashiCorp Vault documentation and Vault tutorials is the best place to get started.

Setting up Vault CLI environment

Once you have Vault CLI set up on the validator, you need to set up environment variables in your terminal to configure which Vault server the secrets need to be backed up to.

Add the following variables to your terminal environment. Depending on which terminal you use (e.g., bash, shell, zsh, fish etc), you may need to modify the statements accordingly. You'll also need to modify the values according to your validator and Vault server configuration.

export VAULT_ADDR="https://vault.example.com"
export VAULT_NAMESPACE="admin/testnet"
export VAULT_TOKEN="[VAULT_TOKEN]"
export CHEQD_HOME=/home/cheqd
export MONIKER=[NODE_MONIKER]

Backup procedure for HashiCorp Vault

Configure Vault backup script

Download the vault-backup.sh script from Github:

wget -c https://raw.githubusercontent.com/cheqd/infra/main/scripts/tools/vault-backup.sh

Make the script executable:

chmod +x vault-backup.sh

We recommend that you open the script using an editor such as nano and confirm that you're happy with the environment variables and settings in it.

Stop the cheqd service

Before backing up your secrets, it's important to stop the cheqd node service or Cosmovisor service; otherwise, the validator private state will be left in an inconsistent state and result in an incorrect backup.

If you're running via Cosmovisor (the default option), this can be stopped using:

sudo systemctl stop cheqd-cosmovisor

Or, if running as a standalone service:

sudo systemctl stop cheqd-node

Run the Vault backup script

Once you've confirmed the cheqd service is stopped, execute the Vault backup script:

./vault.sh -b true

We use HashiCorp Vault KV v2 secrets engine. Please make sure that it's enabled and mounted under cheqd path.

Restoring from HashiCorp Vault

To restore backed-up secrets from a Vault server, you can use the same script using the -r ("restore") flag:

./vault.sh -r true

Restoring secrets to a different machine

If you're restoring to a different machine than the original machine the backup was done from, you'll need to go through the pre-requisites, CLI setup step, and download the Vault backup script to the new machine as well.

In this scenario, you're also also recommended to disable the service (e.g., cheqd-cosmovisor) on the original machine. This ensures that if the (original) machine gets restarted, systemd does not try and start the node service as this can potentially result in two validators running with the same validator keys (which will result in tombstoning).

sudo systemctl disable cheqd-cosmovisor

Once you've successfully restored, you can enable the service (e.g., cheqd-cosmovisor) on the new machine:

sudo systemctl enable cheqd-cosmovisor

This document offers the information and instructions required for node operators complete an upgrade with a fresh installation.

We decided to remove the debian package as an installtion artifact and use our own installation tool. The main reason for this is to help our current and future node operators join the cheqd network or complete an upgrade in a more intuitive, simpler and less time intensive way.

For this upgrade from 0.5.0 to 0.6.0 there are 2 possible scenario:

• upgrade by installing Cosmovisor

• upgrade only cheqd-noded binary.

Cosmovisor is a tool from the cosmos-sdk team which is able to make an upgrade in a full-auto mode. It can download and exchange binary without any actions from a node operator. Beginning with version 0.6.0, and with all subsequent versions, we will leverage Cosmosvisor as a tool to handling our upgrade process.

For more information about interactive installer please see this documentation. You will find answers to common questions within this document, however of course feel free to reach out to the team on Slack or Discord.

Upgrade with installing Cosmovisor

As the installation and setting up the Cosmovisor can be difficult, and requires some additional steps for setting up the systemd service, we injected all this steps into our interactive installer.

The flow for installtion is:

Stop the systemd service

sudo systemctl stop cheqd-noded

Make sure that it was definitely stopped by using:

systemctl status cheqd-noded

The output should be:

● cheqd-noded.service - Service for running cheqd-node daemon
     Loaded: loaded (/lib/systemd/system/cheqd-noded.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Thu 2022-07-07 12:31:12 UTC; 27s ago
       Docs: https://docs.cheqd.io/node
    Process: 13427 ExecStart=/usr/bin/cheqd-noded start (code=exited, status=0/SUCCESS)
   Main PID: 13427 (code=exited, status=0/SUCCESS)

the main focus here: Active: inactive (dead)

Remove current debian package

sudo apt remove cheqd-node

Download interactive installer and run it

wget -c https://raw.githubusercontent.com/cheqd/cheqd-node/interactive_installer/installer/installer.py
sudo python3 installer.py

The next answers are needed for upgrading cheqd-noded binary with the Cosmovisor installation

IMPORTANT For running an Upgrade scenario you'll be required to setup a current home directory for a cheqd user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:. This is because the upgrade scenario will only be used if this directory exists.

1) v0.5.0
2) v0.6.0
3) v0.6.0-rc2
4) v0.6.0-rc1
5) v0.5.0-rc2
Choose list option number above to select version of cheqd-node to install [default: 1]:
2
Set the path for cheqd user's home directory [default: /home/cheqd]:

Existing cheqd-node configuration folder detected. Do you want to upgrade an existing cheqd-node installation? (yes/no) [default: no]:
y
*********  INFO: Installing cheqd-node with Cosmovisor allows for automatic unattended upgrades for valid software upgrade proposals.
Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]:
y
Overwrite existing configuration for cheqd-node logging? (yes/no) [default: yes]:
y
Overwrite existing configuration for logrotate? (yes/no) [default: yes]:
y

WARNING Please make sure that you answered yes for questions about overwriting existing configuration. It's very important when making a new installation with Cosmovisor.

Start new systemd service

sudo systemctl start cheqd-cosmovisor

Upgrade only binary

If you are updating a current installation the next steps can be used:

Stop the systemd service

sudo systemctl stop cheqd-noded

and make sure that it was really stopped by:

systemctl status cheqd-noded

Output should be like:

● cheqd-noded.service - Service for running cheqd-node daemon
     Loaded: loaded (/lib/systemd/system/cheqd-noded.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Thu 2022-07-07 12:31:12 UTC; 27s ago
       Docs: https://docs.cheqd.io/node
    Process: 13427 ExecStart=/usr/bin/cheqd-noded start (code=exited, status=0/SUCCESS)
   Main PID: 13427 (code=exited, status=0/SUCCESS)

the main focus here: Active: inactive (dead)

Remove current debian package

sudo apt remove cheqd-node

Download interactive installer and run it

wget -c https://raw.githubusercontent.com/cheqd/cheqd-node/interactive_installer/installer/installer.py
sudo python3 installer.py

Answers for interactive installer

IMPORTANT For running an Upgrade scenario you'll be required to setup a current home directory for a cheqd user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:. This is because the upgrade scenario will only be used if this directory exists.

1) v0.5.0
2) v0.6.0
3) v0.6.0-rc2
4) v0.6.0-rc1
5) v0.5.0-rc2
Choose list option number above to select version of cheqd-node to install [default: 1]:
2
Set path for cheqd user's home directory [default: /home/cheqd]:

Existing cheqd-node configuration folder detected. Do you want to upgrade an existing cheqd-node installation? (yes/no) [default: no]:
y
*********  INFO: Installing cheqd-node with Cosmovisor allows for automatic unattended upgrades for valid software upgrade proposals.
Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]:
n
Overwrite existing systemd configuration for cheqd-node? (yes/no) [default: yes]:
n
Overwrite existing configuration for cheqd-node logging? (yes/no) [default: yes]:
n
Overwrite existing configuration for logrotate? (yes/no) [default: yes]:
n

WARNING. IF you are keeping just standalone a cheqd-noded, without Cosmovisor, it's crucial you keep your systemd service files without overwriting them. Please make sure that your answers were no.

Similar to what was previously in place, for starting the service only the next command is needed

sudo systemctl start cheqd-noded

Building from source

Prerequisites:

• Install Go (currently, our builds are done for Golang v1.18)

To build the executable, run:

make proto-gen
make swagger
make build

Build using Docker

We have an in-depth guide for making custom Docker image builds.

Running a localnet using Docker Compose

We also have an in-depth guide on running a localnet with multiple nodes using Docker / Docker Compose.

Indexers, in a broad context, play a fundamental role in organising and optimising data retrieval within various systems. These tools act as navigational aids, allowing efficient access to specific information by creating structured indexes. In the realm of databases and information management, indexers enhance query performance by creating a roadmap to swiftly locate data entries.

In the context of blockchain and dApps, indexers go beyond traditional databases, facilitating streamlined access to on-chain data. This includes transaction histories, smart contract states, and event logs. In the dynamic and decentralised world of blockchain, indexers contribute to the efficiency of data queries, supporting real-time updates and ensuring the seamless functionality of diverse applications and platforms.

There are several indexer solutions available, each offering different levels of decentralisation, ease of development, and performance for you to consider. These solutions serve as intermediaries to assist in indexing Cheqd.

Context

This document provides instructions on how to run a localnet with multiple validator/non-validator nodes. This can be useful if you are developing applications to work on cheqd network, or in automated testing pipelines.

The techniques described here are used in CI/CD contexts, for example, in this repository itself in the test.yml Github workflow.

Pre-requisites

• A clone of the cheqd-node repository

• Either a pre-built Docker image downloaded from Github Container Registry, or a custom-built Docker image (the latter is mandatory if you've modified any code in the repository cline).

• Docker Engine and Docker Compose (same versions as described in configuration instructions for Docker setup)

• A cheqd-node binary to run the network config generation script below.

Instructions

Our localnet setup instructions are designed to set up a local network with the following node types:

• 3x validator nodes

• 1x non-validator/observer node

• 1x seed node

The definition for this network is described in a localnet Docker Compose file, which can be modified as required for your specific use case. Since it's not possible to cover all possible localnet setups, the following instructions describe the steps necessary to execute a setup similar to that using in our Github test workflow.

Generate localnet configuration (one-time)

Execute the bash script gen-network-config.sh to generate validator keys and node configuration for the node types above.

./docker/localnet/gen-network-config.sh

You may modify the output if you want a different mix of node types.

Import the generated keys (one-time)

Import the keys generated using the import-keys.sh bash script:

./docker/localnet/import-keys.sh

Bring up the localnet using Docker Compose

Modify the docker-compose.yml file if necessary, along with the per-container environment variables under the container-env folder.

docker compose --env-file build-latest.env up --detach --no-build

Interacting with localnet

The default Docker localnet will configure a running network with a pre-built image or custom image.

Nodes

The five nodes and corresponding ports set up by the default Docker Compose setup will be:

1. Validator nodes

   1. validator-0

      1. P2P: 26656

      2. RPC: 26657

   2. validator-1

      1. P2P: 26756

      2. RPC: 26757

   3. validator-2

      1. P2P: 26856

      2. RPC: 26857

   4. validator-3

      1. P2P: 26956

      2. RPC: 26957

2. Seed node

   1. seed-0

      1. P2P: 27056

      2. RPC: 27057

3. Observer node

   1. observer-0

      1. P2P: 27156

      2. RPC: 27157

You can tests connection to a node using browser: http://localhost:<rpc_port>. Example for the first node: http://localhost:26657.

Accounts

Key and corresponding accounts will be placed in the network config folder by the import-keys.sh script, which are used within the nodes configured above.

When connecting using CLI, provide the --home parameter to any CLI command to point to the specific home directory of the corresponding node: --home network-config/validator-x.

CLI commands

See the cheqd CLI guide to learn about the most common CLI commands.

Accepted

1. ADR 001: Payment mechanism for issuing credentials

2. ADR 002: Importing/exporting mnemonic keys from Cosmos

3. ADR 003: Command Line Interface (CLI) tools

4. ADR 004: Token fractions

5. ADR 005: Genesis parameters

6. ADR 006: Community tax

Proposed

1. ADR 007: Revocation registry

Draft

1. ADR 011: AnonCreds: Schemas and Credential Definitions

Moved

The following ADRs have been moved to the cheqd identity documentation site

1. ADR 001: did:cheqd method

2. ADR 002: On-Ledger DID-Linked Resources

SubQuery is a leading blockchain data indexer that provides developers with fast, flexible, universal, open source and decentralised APIs for web3 projects. SubQuery SDK allows developers to get rich indexed data and build intuitive and immersive decentralised applications in a faster and more efficient way. SubQuery supports 150+ ecosystems including Cheqd, Cosmos, Ethereum, Near, Polygon, Polkadot, Algorand, and Avalanche.

Another one of SubQuery's competitive advantages is the ability to aggregate data not only within a chain but across multiple blockchains all within a single project. This allows the creation of feature-rich dashboard analytics, multi-chain block scanners, or projects that index IBC transactions across zones.

Useful resources

• SubQuery Docs: SubQuery Academy (Documentation)

• Intro Quick Start Guide: 1. Create a New Project

• Starter Project

For technical questions and support reach out to us start@subquery.network

Running and Hosting your Cheqd SubQuery APIs

SubQuery is open-source, meaning you have the freedom to run it in the following three ways:

• Locally on your own computer (or a cloud provider of your choosing), view the instructions on how to run SubQuery Locally.

• You can publish it to SubQuery's enterprise-level Managed Service, where we'll host your SubQuery project in production ready services for mission critical data with zero-downtime blue/green deployments. There even is a generous free tier. Find out how.

• You can publish it to the decentralised SubQuery Network, the most open, performant, reliable, and scalable data service for dApp developers. The SubQuery Network indexes and services data to the global community in an incentivised and verifiable way and supports Cheqd from launch.

Background

Ubuntu's standard support for Ubuntu 20.04 LTS ("Long Term Support") version ends in April 2025. Ubuntu 20.04 LTS is currently the default Linux operating system used to build and run the binaries for our cheqd-node. To ensure continued stability and security, we need to upgrade to the latest Long-Term Support (LTS) version, Ubuntu 24.04.

Additionally, to ensure compatibility with Ubuntu 24.04, you'll need to upgrade to cheqd-noded v2.0.2. This upgrade will address any existing security vulnerabilities and ensure that we are running on the most up-to-date software and distribution, providing a secure and reliable environment.

Please follow the guide to transition both the operating system and our node software smoothly.

Prerequisites

• Backup critical data (e.g., keys, config files).

• Be prepared for the expected downtime of your node (approx 1 hour)

• Ensure all dependencies and software running on your node (except cheqd-node) support the latest Ubuntu LTS.

Step 1: Prepare the Current System

1. Stop and disable the cheqd-cosmovisor.service:

   Copy

   sudo systemctl stop cheqd-cosmovisor.service && sudo systemctl disable cheqd-cosmovisor.service

2. Update sources list and upgrade existing packages:

   Copy

   sudo apt update && sudo apt upgrade -y

3. You'll probably need to restart your server after this step (you'll see the message if you run the do-release-upgrade command):

   Copy

   sudo shutdown -r now

Step 2: Upgrade to the Ubuntu 22.04

1. Trigger distribution upgrade

   Copy

   sudo do-release-upgrade

2. During the process, you'll be prompted for a lot of answers, here are the most important ones:

   Copy

   Reading cache
   
   Checking package manager
   
   Continue running under SSH?
   
   This session appears to be running under ssh. It is not recommended
   to perform a upgrade over ssh currently because in case of failure it
   is harder to recover.
   
   If you continue, an additional ssh daemon will be started at port
   '1022'.
   Do you want to continue?
   
   Continue [yN] 

   Feel free to continue over ssh, since this shouldn't cause any issues for most of the cloud providers.

   Copy

   No valid mirror found
   
   While scanning your repository information no mirror entry for the
   upgrade was found. This can happen if you run an internal mirror or
   if the mirror information is out of date.
   
   Do you want to rewrite your 'sources.list' file anyway? If you choose
   'Yes' here it will update all 'jammy' to 'noble' entries.
   If you select 'No' the upgrade will cancel.
   
   Continue [yN] 

   This is required, so continue.

   Copy

   Do you want to start the upgrade? 
   
   
   1 installed package is no longer supported by Canonical. You can 
   still get support from the community. 
   
   50 packages are going to be removed. 135 new packages are going to be 
   installed. 587 packages are going to be upgraded. 
   
   You have to download a total of 1,030 M. This download will take 
   about 3 minutes with a 40Mbit connection and about 27 minutes with a 
   5Mbit connection. 
   
   Fetching and installing the upgrade can take several hours. Once the 
   download has finished, the process cannot be canceled. 
   
    Continue [yN]  Details [d]

   After you agree with this, the actual upgrade process will start.

   There will be some configuration changes and you'll probably be asked if you want to install a new version of certain software (see the screenshots and examples below). In most cases, it is completely fine to overwrite configuration changes, but be cautious if you have some custom configurations, since these actions will overwrite them:

   Copy

   Configuration file '/etc/systemd/timesyncd.conf'
    ==> Modified (by you or by a script) since installation.
    ==> Package distributor has shipped an updated version.
      What would you like to do about it ?  Your options are:
       Y or I  : install the package maintainer's version
       N or O  : keep your currently-installed version
         D     : show the differences between the versions
         Z     : start a shell to examine the situation
    The default action is to keep your current version.
   *** timesyncd.conf (Y/I/N/O/D/Z) [default=N] ? 
   
   Configuration file '/etc/sudoers'
    ==> Modified (by you or by a script) since installation.
    ==> Package distributor has shipped an updated version.
      What would you like to do about it ?  Your options are:
       Y or I  : install the package maintainer's version
       N or O  : keep your currently-installed version
         D     : show the differences between the versions
         Z     : start a shell to examine the situation
    The default action is to keep your current version.
   *** sudoers (Y/I/N/O/D/Z) [default=N] ? 

   After that, you'll be asked if you want to remove obsolete packages. It's always a good idea to check details (by pressing d ), especially if you have other software running on your node. In our case, we agreed to remove unused packages:

   Copy

   Remove obsolete packages?
   
   
   84 packages are going to be removed.
   
    Continue [yN]  Details [d]

   Finally, you'll be asked to restart your system to apply the changes. Your server should automatically reboot, but it's good to check with your cloud provider documentation and make sure this action won't cause any data loss.

   Copy

   System upgrade is complete.
   
   Restart required
   
   To finish the upgrade, a restart is required.
   If you select 'y' the system will be restarted.
   
   Continue [yN] 

   It's probable that SSH fingerprint is going to change after the upgrade, so you won't be able to ssh to your server immediately. To resolve that, you'll need to run the following command on your localhost:

   Copy

   ssh-keygen -R <host>

3. Check the distribution version:

   Copy

   sudo lsb_release -a

After you ssh again, you can check your distribution version, which should match Ubuntu 22.04 LTS if the upgrade was performed successfully.

Step 3: Upgrade to Ubuntu 24.04 LTS

1. Trigger another distribution upgrade:

   Copy

   sudo do-release-upgrade

2. The remaining steps should be the same as in Step 2, although you won't be asked the same questions as in the first upgrade.

3. Note that it's possible that you won't be able to proceed with this due to some package incompatibility:

   Copy

   Calculating the changes
   
   Calculating the changes
   
   Could not calculate the upgrade
   
   An unresolvable problem occurred while calculating the upgrade.
   
   The package 'postgresql-client-15' is marked for removal but it is in
   the removal deny list.
   
   If none of this applies, then please report this bug using the
   command 'ubuntu-bug ubuntu-release-upgrader-core' in a terminal. If
   you want to investigate this yourself the log files in
   '/var/log/dist-upgrade' will contain details about the upgrade.
   Specifically, look at 'main.log' and 'apt.log'.
   
   Restoring original system state

   On one of our nodes, it was the postgres-client-15.

   We resolved this issue by removing this package and installing it again after a successful upgrade:

   Copy

   sudo apt purge postgres-client-15

4. After you complete the upgrade and restart your node again, you should ssh to your server again and check the distribution version. If everything was successful, you should get output like this:

   Copy

   $ lsb_release -a
   No LSB modules are available.
   Distributor ID: Ubuntu
   Description:    Ubuntu 24.04.1 LTS
   Release:        24.04
   Codename:       noble

Step 4: Upgrade cheqd-node to v2.0.2

1. Download the latest version of the interactive installer:

   Copy

   wget https://raw.githubusercontent.com/cheqd/cheqd-node/main/installer/installer.py

2. Run the installer:

   Copy

   python3 installer.py

3. Select the first option UPGRADE existing installation and proceed by choosing the v2.0.2 version from the list.

4. For the remaining questions, answer based on your previous setup and complete the binary upgrade.

5. Check the version of your cheqd-node:

   Copy

   cheqd-noded version

6. Re-enable cheqd-cosmovisor.service and start your node:

   Copy

   sudo systemctl enable cheqd-cosmovisor.service && sudo systemctl start cheqd-cosmovisor.service

Step 5: Confirm your node caught up with the network

The final step would be to make sure that your node is up and running and that it managed to sync with the network.

Run cheqd-noded status and check for "catching_up":false and also check if the latest_block_height and latest_block_time looks good to you.

Status

Summary

The aim of this ADR is to define the smallest fraction for CHEQ tokens.

Context

Cosmos SDK doesn't provide native support for token fractions. The lowest denomination out-of-the-box that can be used in transactions is 1token.

To address this issue, similar Cosmos networks assume that they use N digits after the decimal point and multiply all values by 10^(-N) in UI.

Examples of lowest token denominations in Cosmos

Popular Cosmos networks were compared to check how many digits after the decimal point are used by them:

• Cosmos: 6

• IRIS: 6

• Fetch.ai: 18

• Binance: 8

Decision

It was decided to go with 10^-9 as the smallest fraction, with the whole number token being 1 CHEQ. Based on the SI prefix system, the lowest denomination would therefore be called "nanocheq".

Consequences

Backward Compatibility

• There is no backward compatibility. To adjust the number of digits after the decimal point (lowest token denomination), the network should be restarted.

Positive

• The power of 10 chosen for the lowest denomination of CHEQ tokens is more precise than for Cosmos ATOMs, which allows transactions to be defined in smaller units.

Negative

• This decision is hard to change in the future, as changes to denominations require significant disruption when a network is already up and running.

Neutral

• N/A

References

Status

Summary

Due to the nature of the cheqd project merging concepts from the and self-sovereign identity (SSI), there are two potential options for creating Command Line Interface (CLI) tools for developers to use:

1. Cosmos-based CLI: Most likely route for Cosmos projects for their node application. Most existing Cosmos node validators will be familiar with this method of managing their node.

2. VDR CLI: Traditionally, a lot of SSI networks have used and therefore the Indy CLI tool for managing and interacting with the ledger. This has now been renamed to and is the tool that most existing SSI node operators ("stewards") would be familiar with.

Ideally, the cheqd-node project would provide a consistent set of CLI tools rather than two separate tools with varying feature sets between them.

This ADR will focus on the CLI tool architecture choice for cheqd-node.

Context