Using JMESd

This guide will go over commands which are available on JMESd, the command-line interface that connects to JMES and enables you to interact with the JMES blockchain. JMESd operates as both a client and a server as every active validator and full node runs JMESd and communicates with their node via JMESd. You can use JMESd to interact with the JMES blockchain by uploading contracts, querying data, managing staking activities, working with governance proposals, and more. For more general information, run jmesd --help in your terminal. For more information about a specific JMESd command, append the -h or --help flag after the command: jmesd query --help.

Accessing a Node

To query state and send transactions, you must connect to a node, which is the access point to the entire network of peer connections. You can either run your own full node or connect to someone else's.

Running your own full node

Running your own full node is the most secure option, but it comes with relatively high resource requirements. For more information about the requirements of running your own full node and a tutorial for installing JMESd, check out the installation guide. For a tutorial that explains how to connect to an existing JMES network, see joining a network.

Connecting to a remote full node

If you don't want to run your own full node, you can connect to someone else's full node. As you consider your options for operators, it is recommended to prioritize operators that you can trust. Malicious operators might intentionally return incorrect query results or censor your transactions. You shouldn't worry about an operator being able to access your account as long as you have your private key stored in a secure location. Possible options of full node operators include validators, wallet providers, or exchanges.

To connect to the full node, you need an address in the https://<host>:<port> format, for example https://77.87.106.33:26657. This address has to be communicated by the full node operator you choose to trust. You will use this address in the following section.

If you are not running a node and would like to communicate through JMESd, lists of public nodes can be found here.

Configuring JMESd

JMESd enables you to interact with a node that runs on the JMES network, whether you run it yourself or not. To configure JMESd, edit the the config.toml file in the ~/.jmes/config/ directory.

Querying Blockchain State

To query all relevant information from the blockchain, such as account balances, amount of bonded tokens, outstanding rewards, and so on, use jmesd query. The following list shows some of the most useful commands for delegators:

# query account balances and other account-related information
jmesd query account <ACCOUNT_ADDRESS>
# Account address is of the form jmes1rEXAMPLE9tEXAMPLEf9cvEXAMPLEss
# you can find the one for your node by running `jmesd keys list`
# query the list of validators
jmesd query staking validators
# query the information of a validator given their address
jmesd query staking validator <validatorAddress>
# query all delegations made from a delegator given their address
# (note: delegator addresses are regular account addresses)
jmesd query staking delegations <delegatorAddress>
# query a specific delegation made from a delegator to a validator
jmesd query staking delegation <delegatorAddress> <validatorAddress>
# query the rewards of a delegator given a delegator address (e.g. jmes10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg)
jmesd query distr rewards <delegatorAddress>

Sending Transactions

The jmes tx command can be used to send transactions containing module messages with state-changing directives that get processed and included in blocks.

jmesd tx ...

To learn more about the different types of transactions you can issue, see the section for each module.

Simulating a transaction

To simulate a transaction without actually broadcasting it, append the --dry-run flag to the command statement:

jmesd tx bank send \
    <sender_address> \
    <recipient_address> \
    <amount_and_denomination> \
    --chain-id=<chain-id> \
    --dry-run

Example: simulate a bJMES transfer:

jmesd tx bank send \
    jmes1ru2ySENDER-EXAMPLEtf9cva9kp33h0jnsm9ss \
    jmes1rRECIPIENT-EXAMPLEtf9cva9kp33h0jnsm9ss \
    1ubJMES \
    --chain-id=pisco-1 \
    --dry-run

Generating a transaction without sending

To build a transaction and print its JSON format to STDOUT, append --generate-only to the list of the command line arguments. This allows you to separate the creation and signing of a transaction with the broadcasting.

jmesd tx bank send \
    <sender_address> \
    <recipient_address> \
    <amount_and_denomination> \
    --chain-id=<chain-id> \
    --generate-only > unsignedSendTx.json

jmesd tx sign \
    --chain-id=<chain_id> \
    --from=<address> \
    unsignedSendTx.json > signedSendTx.json

Example: Sign an unsigned transaction

jmesd tx sign \
    --chain-id=pisco-1 \
    --from=jmes1EXAMPLEy09tEXAMPLEtf9EXAMPLE3h0EXAMPLEss unsignedTx.json

A successful transaction response should look similar to the following:

{
  "body": {
    "messages": [
      {
        "@type": "/cosmos.bank.v1beta1.MsgSend",
        "from_address": "jmes1ru2ySENDER-EXAMPLEtf9cva9kp33h0jnsm9ss",
        "to_address": "jmes1rRECIPIENT-EXAMPLEtf9cva9kp33h0jnsm9ss",
        "amount": [
          {
            "denom": "ubJMES",
            "amount": "1"
          }
        ]
      }
    ],
    "memo": "",
    "timeout_height": "0",
    "extension_options": [],
    "non_critical_extension_options": []
  },
  "auth_info": {
    "signer_infos": [
      {
        "public_key": {
          "@type": "/cosmos.crypto.secp256k1.PubKey",
          "key": "A3Z50zDpCEXAMPLEG5Ru+DGOFEXAMPLEm0EXAMPLEKtxd"
        },
        "mode_info": {
          "single": {
            "mode": "SIGN_MODE_DIRECT"
          }
        },
        "sequence": "0"
      }
    ],
    "fee": {
      "amount": [],
      "gas_limit": "200000",
      "payer": "",
      "granter": ""
    }
  },
  "signatures": [
    "dclBjQ9IsPPkOlcFMsBlQqkx7yqRl0oPBnRuEXAMPLEwlSQTGndiJtZMXI7j5MZ+5JEZI0X3MOg0cr72sq11lA=="
  ]
}

You can validate the transaction's signatures by executing the following command:

jmesd tx sign --validate-signatures signedSendTx.json

You can broadcast the signed transaction to a node by providing the JSON file to the following command:

jmesd tx broadcast --node=<node> signedSendTx.json

Fees

Transactions on the JMES Protocol network must include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. To calculate fees, use the following formula:

$fees = gas * gasPrices$

The value of gas is dependent on the transaction. Different transactions require different amounts of gas. The gas amount for a transaction is calculated as it is being processed, but there is a way to estimate it beforehand by using the auto value for the gas flag. Of course, this only gives an estimate. You can adjust this estimate with the flag --gas-adjustment (default 1.0) if you want to be sure you provide enough gas for the transaction to successfully process.

The gasPrice is the price of each unit of gas. Each validator sets a min-gas-price value and will only include transactions that have a gasPrice greater than their min-gas-price.

The transaction fees are the product of gas and gasPrice. As a user, you can specify a desired gasPrice or fee value for a transaction. The higher the value given for gasPrice or fee, the higher the chance that your transaction will get included in a block.

Setting Fees

Each transaction may either supply fees or gas prices, but not both. Most users will typically provide fees as this is the final cost you will end up incurring for the transaction being included in the ledger, where as gas prices will be dynamically calculated depending on the validator.

Validators specify a minimum gas price that they use to determine whether or not to include a transaction. The stipulation gasPrices >= minGasPrices is checked during the CheckTx process. Note, your transaction must supply fees that are greater than or equal to any of the denominations the validator requires.

To directly use fees:

jmesd tx send ... --fees=100000ubJMES

If you use fees, validators will calculate the implied minGasPrices by dividing your fee with the estimated gas consumption.

To use gas prices:

jmesd tx send ... --gas-prices=0.05ubJMES

Automatic Fee Estimation

You may want to cap the maximum gas that can be consumed by the transaction via the --gas flag. If you pass --gas=auto, the gas will be automatically estimated before executing the transaction.

Gas estimates might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction, thus an adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully.

The adjustment can be controlled via the --gas-adjustment flag, which defaults to the value of 1.0.

To get a direct fee estimation from JMESd:

jmesd tx estimate-fee ...\
    --gas-prices=0.01ubJMES
    --gas-adjustment=1.4

To create and send transactions using fee-estimation, use the template below as a format:

jmesd tx send ... \
    --gas-prices=0.01ubJMES
    --gas=auto
    --gas-adjustment=1.4

Shell Autocompletion

Auto-completion scripts for popular UNIX shell interpreters such as bash and zsh can be generated using the completion command. This makes interacting with JMES Core endpoints when using the command-line more convenient.

If you want to generate bash completion scripts run the following command:

jmesd completion > jmesd_completion

If you want to generate zsh completion scripts run the following command:

jmesd completion --zsh > jmesd_completion

On most UNIX systems, such scripts may be loaded in .bashrc or .bash_profile to enable Bash autocompletion.

echo '. jmesd_completion' >> ~/.bashrc

Refer to the user's manual of your operating system's interpreter for information on how to enable shell autocompletion.

Using JMESd

Accessing a Node​

Running your own full node​

Connecting to a remote full node​

Configuring JMESd​

Querying Blockchain State​

Sending Transactions​

Simulating a transaction​

Generating a transaction without sending​

Fees​

Setting Fees​

Automatic Fee Estimation​

Shell Autocompletion​