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.
A cheqd-node instance can be controlled and configured using the cheqd Cosmos CLI.
This document contains the commands for account management.
from can be either key alias or address. If it's an address, corresponding key should be in keychain.
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.
Our v3.x upgrade introduced EIP-1559 style burns, and our v3.1.x upgrade bumped minimum gas price to 5000ncheq. Therefore, all wallets and applications are recommended to query real-time gas prices from the chain to ensure that they succeed.
denom: The denomination of the fee. For example, ncheq
--node: IP address or URL of node to send the request to
Note: Use
--output jsonto get the output in JSON format.
You can also query real-time gas prices on chain using the REST API, which can be useful for applications that do not use the node CLI. You can fetch this by initiating a GET reqeust to:
Mainnet: https://api.cheqd.net/feemarket/v1/gas_price/ncheq
Testnet: https://api.cheqd.network/feemarket/v1/gas_price/ncheq
There are two ways of interpreting the CLI/API response:
If specifying fees as gas x gas prices with auto gas calculation (recommended): Multiply the price.amount by 10^4 to derive the gas price in ncheq. In the example above, this results in gas price 0.5ncheq * (10^4) = 5000ncheq
Note: Consider
10^4the fee offset multiplier for gas prices. This is because cheqd network usesncheqas the base denomination for gas prices, whereas Cosmos SDK usesuatomfor this feemarket implementation. The offset factor is not related to the conversion fromncheqtouatom, but rather to the way the gas prices are calculated in Cosmos SDK.
If specifying fixed fees as --fees: The price.amount value represents the exact fee to pay in CHEQ, whereas the price.denom gives the units it should be expressed in. If the network is congested, the fee may be higher than the example value shown. Therefore, it is recommended to multiply by a factor of 2 or more to ensure the transaction is processed when using --fees, as this method does not have the benefit of auto gas calculation. In the example above, this becomes 0.5 CHEQ * 2 * 10^9 = 1,000,000,000ncheq (1 CHEQ).
The Submitting transactions section below explains further how fees can be specified with transactions.
The most fool-proof method of ensuring your transaction succeeds is by querying the on-chain gas prices as described above. This fetches the real-time gas prices on the network, based on current congestion.
If, however, your application is unable to query on-chain prices for some reason, you may be able to use the following static gas price values:
Low (minimum gas price): 5000ncheq
Medium: 7500ncheq
High: 10000ncheq
Please note that without querying the real-time prices, these ranges might not satisfy requirements during periods of peak congestion, but will likely meet the required gas prices in 90% of scenarios at the peak.
In our documentation, you will come across terms like gas and gas prices. Fees are calculated as follows:
fees = gas x gas-adjustment x gas-prices
There are important changes to particular values for gas adjustment and gas prices since the v3.x and v3.1.x upgrade, which are reflected below.
--chain-id: E.g., cheqd-mainnet-1 (for mainnet), cheqd-testnet-6 (for testnet). This parameter is typically mandatory
--gas: Either a specific value, or auto (recommended)
--gas-adjustment: Usually, the auto-calculated gas value fluctuates, so you're recommended to boost the gas value by this multiplication factor. Since our v3.x upgrade, the recommended value is 1.7 or more.
--gas-prices: From v3.1.x upgrade onwards, the minimum gas price is 5000ncheq. Recommendation is to either query real-time gas prices, or use the static values.
--node (optional): IP address or URL of node's RPC endpoint to send request to, e.g., https://rpc.cheqd.net, http:localhost:26657. This is not necessary when executing on a node itself.
Instead of using --gas, --gas-adjustment, and --gas-prices, you can also specify fixed fees for a transaction using the --fees flag, which is the maximum fee limit that is allowed for the transaction.
--fees needs to be specified in ncheq units or 10^-9 CHEQ. For example, 5000ncheq is 0.000005 CHEQ. The fee is in ncheq units. Refer to the section above for obtaining gas prices that help determine the fee amount.
Pay attention at return status code. It should be 0 if a transaction is submitted successfully. Otherwise, an error message may be returned.
For most general ledger queries, use the --help flag for any command/sub-command to understand the possible parameters and values.
--node: IP address or URL of node to send the request to
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.
Each cheqd validator node has at least two keys.
Default location is $HOME/config/node_key.json
Used for peer-to-peer communication
Default location is $HOME/config/priv_validator_key.json
Used to sign consensus messages
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.
Allows restoring a key from a previously-created BIP39 mnemonic phrase.
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.
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 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:
Validator address is a function of validator's public key. To get bech32 encoded validator address run this command on node's machine:
There are several ways to get hex-encoded validator address:
Convert from bech32
Query node using CLI:
Look for "ValidatorInfo":{"Address":"..."}
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:
Peer info is used to connect to peers when setting up a new node. It has the following format:
Example:
Using this information other participants will be able to join your node.