ℹ️ Overview

is a public self-sovereign identity (SSI) network for building secure 🔐 and private 🤫 self-sovereign identity systems on 💫. 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 and .

▶️ Quick start for joining cheqd networks

Join our for help, questions, and support if you are looking to join our or .

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 is as simple as...

1. Install of cheqd-node software (currently v3.x.x) on a hosting platform of your choice by .

2. Once you have acquired CHEQ tokens, .

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

🚧 Testnet

Our 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 of cheqd-node software (currently v3.x.x) on a hosting platform of your choice by .

2. Acquire testnet CHEQ tokens through .

🧑‍💻 Using cheqd

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

📌 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

🛠 Developing & contributing to cheqd

cheqd-node is written in Go and built using Cosmos SDK. The explains a lot of the 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 .

Creating a local network

If you are building from source, or otherwise interested in running a local network, we have 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 and let us know.

💬 Community

Our 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

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.

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 , 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

Context

This section lists previous software upgrade proposals and specific instructions on how to execute them.

• v0.6.0 Upgrade Guide

Reporting a Vulnerability

If you think you have discovered a security issue in any of cheqd projects, we'd love to hear from you.

We take all security bugs seriously. If confirmed upon investigation, we will patch it within a reasonable amount of time and release a public security bulletin discussing the impact and credit the discoverer.

There are two ways to report a security bug:

• Email us at

• Join and post a message on the #security channel

Accepted

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 to define our software release versions. The latest software version running on chain is in the v2.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.

Building from source

Prerequisites:

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

• 100x increases in gas prices, with minimum gas price going up from 50ncheq to 5000ncheq (as )

• This change incorporates looser restrictions on DID Document properties such as assertionMethod, allowing developers to specify additional details for keys which might not necessarily be used for authentication/controller purposes (e.g., BBS+ keys for credential issuance.)

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

Example

Transferring tokens

Command

Arguments

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

Example

State Sync allows node operators to initialize their nodes quickly with much less storage consumed. This is really useful in case you don't need full (or significant) chain history and it significantly reduces costs. For comparison, our state DB snapshots published on snapshots.cheqd.net, typically have around 600GB of data, while after State Sync initialization, node consumes only around 540 MB of data.

Modifying config.toml file

In order to enable State Sync, you need to update the Comet BFT configuration file, like this:

#######################################################
###         State Sync Configuration Options        ###
#######################################################
[statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = true

# RPC servers (comma-separated) for light client verification of the synced state machine and
# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
# header hash obtained from a trusted source, and a period during which validators can be trusted.
#
# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = "https://eu-rpc.cheqd.net:443,https://ap-rpc.cheqd.net:443"
trust_height = 20748000
trust_hash = "BD43534FB20E7C163917BC1A501349C68656A9C24EE48C92BB82FFEE687EEE14"
trust_period = "168h0m0s"

As you can see, first you need to enable the State Sync module. After that, you need to provide RPC endpoints that expose and serve state sync snapshots. You can use our public RPC endpoints, as we generate and serve state sync snapshots from them. After that, you need to add the trust_height - this is usually $CURRENT_BLOCK_HEIGHT - 2000 blocks (which is the interval at we generate new snapshots on our RPC nodes). Finally, you need to add the block ID hash, as trust_hash parameter. This can be fetched via RPC, like this - https://rpc.cheqd.net/block?height=20748000. You will find block hash under .result.block_id.hash.

Reference:

You can also use this simple bash script to update your node configuration:

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

Decision

Fractions of CHEQ tokens will be referred by their , based on the power of 10 of CHEQ tokens being referred to in context. This notation system is common across other Cosmos networks as well.

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

What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

Summary

A short (~100 word) description of the issue being addressed. "If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the ADR.

Context

This section describes the forces at play, such as business, technological, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. It should clearly explain the problem and motivation that the proposal aims to resolve.

ADR-specific Details

This section describes the implementation and/or architecture approach for the proposed changes in detail.

Consequences

This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.

Backwards Compatibility

All ADRs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The ADR must explain how the author proposes to deal with these incompatibilities. ADR submissions without a sufficient backwards compatibility treatise may be rejected outright.

Positive

{positive consequences}

Negative

{negative consequences}

Neutral

{neutral consequences}

References

• {reference link}

Unresolved questions

{list of questions or action items}

This is a location to record all high-level architecture decisions for cheqd-node, the server/node portion of purpose-built network for decentralised identity.

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.

An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log.

Rationale

ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. An ADR should provide:

• Context on the relevant goals and the current state

• Proposed changes to achieve the goals

• Summary of pros and cons

Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and justification for a change in architecture, or for the architecture of something new. The spec is much more compressed and streamlined summary of everything as it stands today.

If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.

Creating new ADR

Use the when creating a new ADR.

Overview

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

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

This guide is specifically made for the the validators/node operators affected by the pruning issue encountered following our v4.x upgrade. This issue required some validators/node operators having to disable pruning entirely.

Re-enabling pruning (to default/custom from nothing) on the affected nodes will cause the nodes to halt again as the database pruning resumes its operation. To avoid this it is recommended to reset your node db and recover it using state sync or a db snapshot. The nodes that weren't affected by the pruning issue or that had recovered by the time the pruning fix was rolled out do not have to undergo this procedure.

Following this procedure will significantly reduce the disk space required for your node’s regular operations, thereby lowering operational costs (on the nodes we manage, we observed storage usage drop from 700+ GB to under 10 GB). Additionally, running a node with less disk usage will likely improve performance.

After the proposal status is marked as passed, the upgrade plan will become active. You can query the upgrade plan details using the following command:

This will return output similar to:

At block height 1000, the BeginBlocker will be triggered. At this point, the node will be out of consensus, awaiting the upgrade to the new version.

The log messages like these should be expected:

Once the new application version is installed and running and 1/3 of the voting power on the network is restored, the node will resume normal operations.

Context

We provide a pre-built cheqd-node Docker image 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

Pull a (replace latest with a different version tag if you want to pull something other than the latest version):

Modify environment variables used by Docker Compose

We provide . This is broken down into three files that need to be modified with the configuration parameters:

1. : Docker Compose file

2. : Environment variables used in docker-compose.yml

3. : Environment variables used inside the

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:

Note: The file paths above for the -f and --env-file parameter are relative to the . Please modify the file paths for the correct relative/absolute paths on the system where you are executing the commands.

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:

• to create custom images

• with multiple nodes to simulate a network

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 Cosmos SDK) use stake slashing as a mechanism of enforcing good on-chain behaviour 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).

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

If your node is not up to date, please

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:

From Cosmos SDk v0.50+ versions the gov module provides a draft json file for all types of proposals. These json files can be generated using the draft-proposal subcommand present within the gov module.

It provides an interactive interface and provides a json output using user submitted information. The json file can be submitted on chain for voting using the following command:

Examples of proposal.json for a few commonly submitted proposal types

1) Text proposals

The main parameters here are:

• proposal_title - name of the proposal.

• proposal_description - proposal description; limited to 255 characters; you can use json markdown to provide links.

2) Community Pool Spend

The main parameters here are:

• proposal_title - name of the proposal.

• proposal_description - proposal description; limited to 255 characters; you can use json markdown to provide links.

• recipient_address- cheqd address to which the community pool tokens should be sent.

3) Software upgrade

The main parameters here are:

• proposal_title - name of the proposal.

• proposal_name - name of proposal which will be used in UpgradeHandler in the new application,

• proposal_description

4) IBC Recover Client

The main parameters here are:

• proposal_title - name of the proposal.

• proposal_description - proposal description; limited to 255 characters; you can use json markdown to provide links.

• expired_client_id - IBC client id of the expired connection.

Expedited Proposals

Cosmos SDK v0.50+ also added support for expedited proposals. Expedited proposals have shorter a voting period and a higher tally threshold by default. If an expedited proposal fails to meet the threshold within the shorter voting period, it is then automatically converted to a regular proposal and restarts voting under regular voting conditions.

Submitting expedited proposals

Any and all proposals can be submitted as expedited proposals by switching the expedited field to true in proposal.json file. Eg;-

Context

ℹ️ We provide 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 , or .

Upgrade process includes 2 main parts:

• Sending a SoftwareUpgradeProposal to the network

• Moving to the new binary manually

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 .

This upgrade moved cheqd to support Cosmos SDK v0.50 "Eden".

Cosmos SDK v0.50 is a long-term support version bringing major improvements in performance, developer experience, and modularity. Key features include ABCI++ for more flexible and efficient consensus and IAVL 1.0 for faster and more efficient data storage. It also adds Optimistic Execution to reduce block times and Sign Mode Textual for clearer, more secure transaction signing. This release sets a solid foundation for building faster, more customizable applications on cheqd.

We also enhanced our DIDs to support a more flexible service section, enabling direct connections to did:cheqd DIDs using DIDComm. This enhancement brings full cheqd support for DIDComm endpoint discovery, making it easier for apps and SDKs like ACA-Py and Credo to integrate seamless messaging and communication.

Overview

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

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

We would love for you to contribute to cheqd and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow.

🧑‍⚖️ Code of Conduct

Help us keep cheqd open and inclusive. Please read and follow our

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 interactive installer.

Preparations

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

1. 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.

2. 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.

3. 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.

Installation

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

In general, the installer allows you to install the binary and download/extract the latest snapshot from .

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

If the installation process was successful, the next step is to get back the configurations from :

• Copy config directory to the CHEQD_HOME_DIRECTORY/.cheqdnode/

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

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)

Important notes

1. Any validators upgrading should have carried out the Ubuntu 24.04 LTS upgrade to v2.0.2 before attempting this upgrade

2. After this upgrade, Keplr Wallet unfortunately cannot support dynamic fee lookups for Cosmos SDK chains that are not natively integrated into their wallet. Therefore, we recommend users to .

Ensure your transaction fee configuration works after the upgrade

For non-identity transactions (e.g., standard transfers, staking, rewards, etc), this upgrade introduces EIP-1559 style burns, with the introduction of a feemarket module which introduces dynamic gas pricing. This might affect how you attach/calculate fees when submitting transactions.

Recommended settings for CLI

Use --gas auto and --gas-adjustment (with value of 1.7 to 1.8) for optimal results. Using fixed --fees is unlikely to work if you don't look up real-time gas prices on the network.

Monitoring real-time gas prices using CLI

cheqd-noded query feemarket gas-price ncheq

Monitoring real-time gas prices using REST API

Initiating a GET request at https://api.cheqd.net/feemarket/v1/gas_price/ncheq. The result will be an object as:

Interpreting the real-time gas prices API response

Interpret the value of price.amount as the fixed fee in price.denom units, in which case 5000000000000000ncheq using --fees OR calculate the gas prices necessary by multiplying the value of price.amount by (10^4) * (10^9) = 10^13, in which case resulting in 50ncheq. Any increase in the indicative gas price or gas limit will result in greater quantities than the suggested minimum base fee.

Features

We're excited to announce the latest protocol upgrade to our community. This release brings cutting-edge features designed to enhance transaction efficiency, fee flexibility, and cross-chain interoperability. Here's what's coming your way:

🔥 EIP-1559 Feemarket Implementation

• Revolutionising the fee structure for a smoother, more efficient user experience. The advanced Additive Increase Multiplicative Decrease (AIMD) model ensures fair and efficient fee adjustments.

• Base Fee: Dynamically adjusts based on network congestion. This fee is burnt, reducing token supply and enhancing the economic value of $CHEQ.

• Priority Fee: Optional tip for validators to prioritise your transactions.

🌐 Fee Abstraction Module

• Cross-Chain Token Support: Pay transaction fees in tokens from any IBC-enabled Cosmos chain.

• IBC Hooks: Facilitate cross-chain smart contract calls, opening new use cases like multi-hop swaps.

• Fee Conversions: Automatically convert IBC-denominated tokens to native fees before final settlement.

🔄 IBC Packet Forwarding Middleware

• Streamlining cross-chain communication with robust packet forwarding:

• Atomic Multi-Hop Flows: Secure and synchronized token transfers across multiple chains.

• Asynchronous Acknowledgements: Track the outcome of multi-hop transfers from the initiating chain.

🔧 New Message Definitions for Governance and Token Management

Simplifying token minting and burning through governance-approved mechanisms mainly aimed at reducing complexity of $DOCK to $CHEQ token migration:

• MsgBurn: Allows manual burning of native tokens with full validation.

• MsgMint: Enables governance-controlled token minting and distribution to specific addresses.

🌟 What This Means for You

• Improved User Experience: Transaction fees are simpler, predictable, and wallet-friendly.

• Enhanced Token Utility: CHEQ’s role as the network’s core currency is strengthened.

• Cross-Chain Opportunities: Broader support for IBC tokens ensures a seamless multi-chain experience.

🎯 Next Steps

If the software upgrade proposal is approved, this upgrade will go live at block height 16502390, which is expected to be around Thursday, 12th December 2024, 9am UTC.

We’re excited to bring these advancements to the ecosystem and look forward to your feedback. Let’s build the future of Decentralised Identity together!

Release Notes for cheqd-node v3.0.1

What's Changed

• feat: Integrate feemarket + reworked ante, post handler decorator distinction by @vishal-kanna in

• feat!: Integrate feemarket + reworked ante, post handler decorator distinction by @Eengineer1 in

• feat: add fee abs module by @atheeshp in

Full Changelog:

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:

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.

Manual backup and restore

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

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:

Backing up and restoring via 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 or .

Pre-requisites

Before you get started with this guide, make sure you've 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, and 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.

Backup procedure for HashiCorp Vault

Configure Vault backup script

Download the from Github:

Make the script executable:

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:

Or, if running as a standalone service:

Run the Vault backup script

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

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:

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

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

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.

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 . 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

Make sure that it was definitely stopped by using:

The output should be:

the main focus here: Active: inactive (dead)

Remove current debian package

Download interactive installer and run it

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.

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

Upgrade only binary

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

Stop the systemd service

and make sure that it was really stopped by:

Output should be like:

the main focus here: Active: inactive (dead)

Remove current debian package

Download interactive installer and run it

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.

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

Our Pledge

We as members, contributors, and leaders pledge to make participation in the cheqd community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, country of origin, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behaviour that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people

• Being respectful of differing opinions, viewpoints, and experiences

• Giving and gracefully accepting constructive feedback

Examples of unacceptable behaviour include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind

• Use of inappropriate or non-inclusive language or other behaviour deemed unprofessional or unwelcome in the community

• Trolling, insulting or derogatory comments, and personal or political attacks

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behaviour and will take appropriate and fair corrective action in response to any behaviour that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, messages, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the community leaders responsible for enforcement at . All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions. Any Community Impact assessment should take into account:

1. The severity and/or number of incidents/actions

2. Non-compliance with previous private warnings from community leaders (if applicable)

Consequence: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behaviour.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the , version 2.0, available at .

Community Impact Guidelines were inspired by .

For answers to common questions about this code of conduct, see the FAQ at . Translations are available at .

Status

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.

Overview

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.

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