Interaction with the network: CLI

For more information on the command usage, refer to its help screen: panacead --help.

Here is a list of useful panacead commands, including usage examples.

Keys

Key Types

There are three types of key representations that are used:

• panacea

  • Derived from account keys generated by panacead keys add

  • Used to receive funds

  • e.g. panacea17kmacx3czkdnhtfueqzzxk9xqzapj453f23m5a

• panaceavaloper

  • Used to associate a validator to it's operator

  • Used to invoke staking commands

  • e.g. panaceavaloper17kmacx3czkdnhtfueqzzxk9xqzapj453wg3mgr

• panaceapub

  • Derived from account keys generated by panacead keys add

  • e.g. panaceapub1addwnpepqwk3j2j3knuyah89skh8wtn5kr4qx32nhql6hzjadzmre2xlfmvxgy39ln8

• panaceavalconspub

  • Generated when the node is created with panacead init.

  • Get this value with panacead tendermint show-validator

  • e.g. panaceavalconspub1zcjduepqktkqqsl9rchj77v9vg0crc87grp9h2u5ggpdtvcq74kxlr29lgwsa3dr66

Generate Keys

You'll need an account private and public key pair (a.k.a. sk, pk respectively) to be able to receive funds, send txs, bond tx, etc.

To generate a new secp256k1 key:

panacead keys add <account_name>

Previously, you had to enter a password to save it to disk, but you do not currently need to.

Setting up the keyring

If you check your private keys, you'll now see <account_name>:

panacead keys show <account_name>

View the validator operator's address via:

panacead keys show <account_name> --bech=val

You can see all your available keys by typing:

panacead keys list

View the validator pubkey for your node by typing:

panacead tendermint show-validator

Note that this is the Tendermint signing key, not the operator key you will use in delegation transactions.

::: danger Warning We strongly recommend NOT using the same passphrase for multiple keys. The MediBloc team will not be responsible for the loss of funds. :::

Fees & Gas

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

Validator's have a minimum gas price configuration and they use this value when determining if they should include the transaction in a block during CheckTx, where gasPrices >= minGasPrices. Note, your transaction must supply fees that are greater than or equal to minimum fee which the validator requires.

Note: With such a mechanism in place, validators may start to prioritize txs by gasPrice in the mempool, so providing higher fees or gas prices may yield higher tx priority.

e.g.

panacead tx send ... --fees=1000000umed

or

panacead tx send ... --gas-prices=5umed

Account

Query Account

To view your account information:

panacead query account <account_panacea>

Bank

Query balance

After receiving tokens to your address, you can view your account's balance by typing:

panacead query bank balances <account_panacea>

::: warning Note When you query an account balance with zero tokens, you will get this error: account <account_panacea> does not exist. This can also happen if you fund the account before your node has fully synced with the chain. These are both normal.:::

Send Tokens

The following command could be used to send coins from one account to another:

panacead tx bank send \
  <from_key_or_address> \
  <to_address> \
  <amount> \
  --chain-id <chain_id> \
  --from <from_key> \
  --fees 1000000umed

where to_address is a key matching the format: panacea1y3mhszahwatjc3023datq46a0u2fv337tes4n9

::: warning Note The <amount> accepts the format <value|coin_name> -> ex) 10000000umed. :::

::: tip Note 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 supply will be automatically estimated before executing the transaction. Gas estimate 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, whose default value is 1.0. :::

Now, view the updated balances of the origin and destination accounts:

panacead query bank balances <from_address>
panacead query bank balances <to_address>

You can also check your balance at a given block by using the --height flag:

panacead query account <account_panacea> --height=<block_height>

You can simulate a transaction without actually broadcasting it by appending the --dry-run flag to the command line:

panacead tx bank send \
  <from_key_or_address> \
  <to_address> \
  <amount> \
  --from <from_key> \
  --chain-id <chain_id> \
  --dry-run

Furthermore, you can build a transaction and print its JSON format to STDOUT by appending --generate-only to the list of the command line arguments:

panacead tx bank send \
  <from_key_or_address> \
  <to_address> \
  <amount> \
  --chain-id <chain_id> \
  --fees 1000000umed \
  --generate-only > unsignedSendTx.json

panacead tx sign \
  --chain-id <chain_id> \
  --from <key_name> \
  unsignedSendTx.json > signedSendTx.json

You can validate the transaction's signatures by typing the following:

panacead tx validate-signatures \
  --chain-id <chain_id> \
  signedSendTx.json

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

panacead tx broadcast --chain-id <chain_id> signedSendTx.json

Query Transactions

Matching a set of events

You can use the transaction search command to query for transactions that match a specific set of events, which are added on every transaction.

Events are implemented in the Cosmos SDK as an alias of the ABCI Event type and take the form of: {eventType}.{attributeKey}={attributeValue}. Events can also be combined to query for a more specific result using the & symbol.

The command for querying transactions using a event is the following:

panacead query txs --events 'message.module=bank'

And for using multiple events:

panacead query txs --events 'message.module=bank&tx.height=5'

The pagination is supported as well via page and limit:

panacead query txs --events 'message.module=bank' --page 1 --limit 20

::: tip Note

The action tag always equals the message type returned by the Type() function of the relevant message.

You can find a list of available tags on each module by looking at the /tags directory of each module. :::

Matching a transaction's hash

You can also query a single transaction by its hash using the following command:

panacead query tx [hash]

Slashing

Unjailing

To unjail your jailed validator

panacead tx slashing unjail \
  --from <validator-operator-addr> \
  --chain-id <chain_id> \ 
  --fees 1000000umed

Signing Info

To retrieve a validator's signing info:

panacead query slashing signing-info <validator-pubkey>

Query Parameters

You can get the current slashing parameters via:

panacead query slashing params

Staking

Create your validator

This guide assumes that you have already set up your full node by following the guide.

Your panaceavalconspub address (public key) can be used to create a new validator by staking tokens. You can find your validator public key by:

panacead tendermint show-validator

Execute the following command to create your validator:

Don't use more umed than you have!

panacead tx staking create-validator \
  --pubkey $(panacead tendermint show-validator) \
  --moniker "choose a moniker" \
  --chain-id <chain-id> \
  --commission-rate "0.10" \
  --commission-max-rate "0.20" \
  --commission-max-change-rate "0.01" \
  --min-self-delegation "1" \
  --amount 10000000umed \
  --fees 1000000umed \
  --from <key-name>

• pubkey: A public key associated with the Tendermint private key (which was generated by panacead init). The public key can be resolved by panacead tendermint show-validator in the node that you want to make as a validator. For details about various key types, please see this guide.

• moniker: A validator nickname that will be displayed publicly

• commission-rate: An initial commission rate on block rewards and fees charged to delegators

  • This shouldn't be smaller than the minimum commission rate (a genesis parameter) that can be queried by panacead query staking params.

• commission-max-rate: A maximum commission rate which this validator can charge. This cannot be changed after the create-validator transaction is processed.

• commission-max-change-rate: A maximum daily increase of the validator commission. This cannot be changed after the create-validator transaction is processed. This is used to measure % point change over the commision-rate. E.g. 1% to 2% is a 100% rate increase, but only 1% point.

• min-self-delegation: A strictly positive integer in umed that represents the minimum amount of self-delegated voting power your validator must always have. If the validator's self-delegated stake falls below this limit, their entire staking pool will unbond.

• amount: An amount of your self-delegation

Note: A minimum amount of MEDs that must be delegated to be an active validator is 1med (1000000umed). In other words, validators cannot be in the active set, if their total stake (= self-bonded stake + delegators stake) is under 1med.

You can confirm that you are in the validator set by the following command:

panacead query staking validators

Edit validator description

You can edit your validator's public description. This info is to identify your validator, and will be relied on by delegators to decide which validators to stake to. Make sure to provide input for every flag below. If a flag is not included in the command the field will default to empty (--moniker defaults to the machine name) if the field has never been set or remain the same if it has been set in the past.

The --from option specifies which validator you are editing.

panacead tx staking edit-validator \
  --moniker "choose a new moniker" \
  --website "https://example.com" \
  --details "This is a detail description" \
  --chain-id <chain_id> \
  --commission-rate "0.15" \
  --from <key_name> \
  --fees 1000000umed

Note: The --commission-rate value must adhere to the following invariants:

• Must be between the minimum commission rate (a genesis parameter) and the validator's commission-max-rate

• Must not exceed the validator's commission-max-change-rate which is maximum % point change rate per day. In other words, a validator can only change its commission once per day and within commission-max-change-rate bounds.

Delegate to a Validator

You can delegate umed to a validator. These delegators can receive part of the validator's fee revenue.

Query Validators

You can query the list of all validators of a specific chain:

panacead query staking validators

If you want to get the information of a single validator you can check it with:

panacead query staking validator <account_panaceaval>

Bond Tokens

Here's how you can bond tokens to a validator (i.e. delegate):

panacead tx staking delegate \
  <validator address> \
  10000000umed \
  --from <key_name> \
  --chain-id <chain_id>

<validator> is the operator address of the validator to which you intend to delegate. If you are running a local testnet, you can find this with:

panacead keys show [name] --bech val

where [name] is the name of the key you specified when you initialized panacead.

While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.

Query Delegations

Once submitted a delegation to a validator, you can see it's information by using the following command:

panacead query staking delegation <delegator_addr> <validator_addr>

Or if you want to check all your current delegations with distinct validators:

panacead query staking delegations <delegator_addr>

You can also get previous delegation(s) status by adding the --height flag.

Unbond Tokens

If for any reason the validator misbehaves, or you just want to unbond a certain amount of tokens, use this following command.

panacead tx staking unbond \
  <account_panaceaval> \
  10000umed \
  --from <key_name> \
  --chain-id <chain_id>

The unbonding will be automatically completed when the unbonding period has passed.

Query Unbonding-Delegations

Once you begin an unbonding-delegation, you can see it's information by using the following command:

panacead query staking unbonding-delegation <delegator_addr> <validator_addr>

Or if you want to check all your current unbonding-delegations with disctinct validators:

panacead query staking unbonding-delegations <account_panacea>

Additionally, as you can get all the unbonding-delegations from a particular validator:

panacead query staking unbonding-delegations-from <account_panaceaval>

To get previous unbonding-delegation(s) status on past blocks, try adding the --height flag.

Redelegate Tokens

A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another:

panacead tx staking redelegate \
  <src validator address> \
  <dst validator address> \
  10000umed \
  --from <key_name> \
  --chain-id <chain_id>

The redelegation will be automatically completed when the unbonding period has passed.

Query Redelegations

Once you begin an redelegation, you can see it's information by using the following command:

panacead query staking redelegation <delegator_addr> <src_val_addr> <dst_val_addr>

Or if you want to check all your current unbonding-delegations with disctinct validators:

panacead query staking redelegations <account_panacea>

Additionally, as you can get all the outgoing redelegations from a particular validator:

panacead query staking redelegations-from <account_panaceaval>

To get previous redelegation(s) status on past blocks, try adding the --height flag.

Query Parameters

Parameters define high level settings for staking. You can get the current values by using:

panacead query staking params

With the above command you will get the values for:

• Unbonding time

• Maximum numbers of validators

• Maximum entries

• Coin denomination for staking

Query Pool

A staking Pool defines the dynamic parameters of the current state. You can query them with the following command:

panacead query staking pool

With the pool command you will get the values for:

• Not-bonded and bonded tokens

Fee Distribution

Query distribution parameters

To check the current distribution parameters, run:

panacead query distribution params

Query validator commission

To check the current outstanding commission for a validator, run:

panacead query distribution commission <validator_address>

Query validator slashes

To check historical slashes for a validator, run:

panacead query distribution slashes <validator_address> <start_height> <end_height>

Query delegator rewards

To check current rewards for a delegation (were they to be withdrawn), run:

panacead query distribution rewards <delegator_address> <validator_address>

Query all delegator rewards

To check all current rewards for a delegation (were they to be withdrawn), run:

panacead query distribution rewards <delegator_address>

Multisig transactions

Multisig transactions require signatures of multiple private keys. Thus, generating and signing a transaction from a multisig account involve cooperation among the parties involved. A multisig transaction can be initiated by any of the key holders, and at least one of them would need to import other parties' public keys into their Keybase and generate a multisig public key in order to finalize and broadcast the transaction.

For example, given a multisig key comprising the keys p1, p2, and p3, each of which is held by a distinct party, the user holding p1 would require to import both p2 and p3 in order to generate the multisig account public key:

panacead keys add \
  p2 \
  --pubkey '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AhExixh..."}'

panacead keys add \
  p3 \
  --pubkey '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A3ntuPW..."}'

panacead keys add \
  p1p2p3 \
  --multisig-threshold 2 \
  --multisig p1,p2,p3

A new multisig public key p1p2p3 has been stored, and its address will be used as signer of multisig transactions:

panacead keys show --address p1p2p3

You may also view multisig threshold, pubkey constituents and respective weights by viewing the JSON output of the key or passing the --show-multisig flag:

panacead keys show p1p2p3 --output json

The first step to create a multisig transaction is to initiate it on behalf of the multisig address created above:

panacead tx bank send <multisig_address> <recipient> 10umed \
  --from <multisig_address> \
  --chain-id <chain_id> \
  --generate-only > unsignedTx.json

The file unsignedTx.json contains the unsigned transaction encoded in JSON. p1 can now sign the transaction with its own private key:

panacead tx sign \
  unsignedTx.json \
  --multisig <multisig_address> \
  --from p1 \
  --output-document p1signature.json \
  --chain-id <chain_id>

Once the signature is generated, p1 transmits both unsignedTx.json and p1signature.json to p2 or p3, which in turn will generate their respective signature:

panacead tx sign \
  unsignedTx.json \
  --multisig <multisig_address> \
  --from p2 \
  --output-document p2signature.json \
  --chain-id <chain_id>

p1p2p3 is a 2-of-3 multisig key, therefore one additional signature is sufficient. Any the key holders can now generate the multisig transaction by combining the required signature files:

panacead tx multisign \
  unsignedTx.json \
  p1p2p3 \
  p1signature.json p2signature.json \
  --output-document signedTx.json \
  --chain-id <chain_id>

The transaction can now be sent to the node:

panacead tx broadcast signedTx.json \
  --chain-id <chain_id>

Shells completion scripts

Completion scripts for popular UNIX shell interpreters such as Bash and Zsh can be generated through the completion command, which is available for both panacead.

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

panacead completion > panacead_completion

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

panacead completion --zsh > panacead_completion

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

echo '. panacead_completion' >> ~/.bashrc

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

AOL

Create Topic

You can create topic with this:

panacead tx aol create-topic \
   --from <key_name> \
   <topic>

List Topics

You can query the list of topics belong to specific account:

panacead query aol list-topics <owner_panacea>

You can get the detail information of the topic with this:

panacead query aol get-topic <owner_panacea> <topic>

Add Writer

You can add writer to the specific topic. the list of all validators of a specific chain:

panacead tx aol add-writer \
   --from <key_name> \
   <topic> \
   <writer_panacea>

::: tip Note that the topic owner is not a writer as default. You need to add your self to the topic as a writer. :::

List Writers

You can query the list of writers to the topic:

panacead query aol list-writers <owner_panacea> <topic>

You can get the detail information of the writer with this:

panacead query aol get-writer <owner_panacea> <topic> <writer_panacea>

where [name] is the name of the key you specified when you initialized panacead.

While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.

Delete Writer

Owner can delete writer from the topic. After owner delete the writer, writer can not add record to the topic anymore.

panacead tx aol delete-writer \
   --from <key_name> \
   <topic> \
   <writer_panacea>

::: Note that only owner can delete writer from the topic :::

Add Record

Writer can add record to the topic with this:

panacead tx aol add-record \
  --from <key_name> \
  <owner_panacea> <topic> <key> <value>

Get Record

You can query the record with this:

panacead query aol get-record <owner_panacea> <topic> <offset>

DID

Create(Issue) a DID

panacead tx did create-did \
  --chain-id <chain-id> \
  --from <address>

This doesn't require any parameter except chain-id and from. That is, it generates a Secp256k1 key-pair and derive a DID and a DID Document. The DID Document is stored in Panacea.

To store the key-pair safely in your local, the command will prompt you to enter a passphrase. The encrypted key-pair file will be stored in your ~/did_keystore directory.

Resolve a DID

panacead query did get-did <did>

This returns a DID Document in JSON corresponding to that DID. If the DID doesn't exist, or was already deactivated, an error will be returned.

Update a DID

panacead tx did update-did <did> <key-id> <did-doc-path> \
  --chain-id <chain-id> \
  --from <address>

A DID Document will be replaced to the new one written in a JSON file: <did-doc-path>. To prove that you are the DID owner, you must pass a <key-id> that is one of verificationMethods in the DID Document. Also, that command will prompt you to enter a passphrase of that key if the key-pair is stored in your keystore: ~/did_keystore. The key-pair will be used to make a signature so that Panacea can verify that you are the DID owner.

Deactivate a DID

panacead tx did deactivate-did <did> <key-id> \
  --chain-id <chain-id> \
  --from <address>

Like updating a DID, a <key-id> must be specified and the corresponding key-pair should be used to make a signature so that Panacea can verify that you are the DID owner.

Deactivating a DID is not the same as deleting a DID. DIDs cannot be deleted permanently. They can just be deactivated. And DIDs cannot be reused to create another DID Documents forever.

PNFT

Creating a Denom

To issue an NFT, you first need to create a Denom. The --denom-id value is optional; if left empty, a random UUID will be generated.

panacead tx pnft create-denom \
  --denom-id <your_denom_id> \
  --denom-name <your_denom_name> \
  --denom-description <your_denom_description> \
  --denom-symbol <your_denom_symbol> \
  --denom-uri <your_denom_uri> \
  --denom-uri-hash <your_denom_hash> \
  --denom-data <your_denom_data> \
  --from <key or address> \
  --chain-id <chain-id> \
  --fees 1000000umed

You can confirm the creation of the denom with the following query:

panacead q pnft get-denom <denom_id>

## Response
denom:
  data: This is panacea denom data
  description: panacea denom detail
  id: 6a0e781a-c4a8-43ff-b15f-1a885adda8e3
  name: panacea denom
  owner: panacea1a392sz78y3hx72aegsczuu29v3rx7l8p9vxgqk
  symbol: panacea
  uri: https://medibloc.org
  uri_hash: hash...

Updating a Denom

You can update a denom. All fields except the id are updatable.

panacead tx pnft update-denom <denom_id> \
  --denom-name <update_denom_name> \
  --denom-description <update_denom_description> \
  --denom-symbol <update_denom_symbol> \
  --denom-uri <update_denom_uri> \
  --denom-uri-hash <update_denom_hash> \
  --denom-data <update_denom_data> \
  --from <key or address> \
  --chain-id <chain-id> \
  --fees 1000000umed

Transferring a Denom

You can change the owner of a denom. Only the current owner (sender_address) can initiate this transfer.

panacead tx pnft transfer-denom <denom_id> <sender_address> <receiver_address> \
  --from <sender_key or sender_address> \
  --chain-id <chain-id> \
  --fees 1000000umed

Deleting a Denom

A denom can be deleted. Only the current owner (remover_address) can initiate this deletion.

panacead tx pnft delete-denom <denom_id> \
  --from <remover_address> \
  --chain-id <chain-id> \
  --fees 1000000umed

Minting PNFT

You can mint an NFT, but only the owner of the corresponding Denom has the right to do so.

panacead tx pnft mint-pnft <denom_id> <id> \
  --pnft-name <your_nft_name> \
  --pnft-description <your_nft_description> \
  --pnft--uri <your_nft_uri> \
  --pnft-uri-hash <your_nft_uri_hash> \
  --pnft-data <your_nft_data> \
  --from <key or address> \
  --chain-id <chain-id> \
  --fees 1000000umed

The NFT can be queried with the following:

panacead q pnft get-pnf <denom_id> <id>

# Response
pnft:
  created_at: "2024-03-20T00:27:12.970988074Z"
  creator: panacea1a392sz78y3hx72aegsczuu29v3rx7l8p9vxgqk
  data: ""
  denom_id: 6a0e781a-c4a8-43ff-b15f-1a885adda8e3
  description: ""
  id: token1
  name: med
  owner: panacea1a392sz78y3hx72aegsczuu29v3rx7l8p9vxgqk
  uri: ""
  uri_hash: ""

Transferring PNFT

You can transfer the ownership of an NFT to another account.

panacead tx pnft transfer-pnft <denom_id> <id> <receiver> \
  --from <key or address> \
  --chain-id <chain-id> \
  --fees 1000000umed

Burning PNFT

An NFT can be burned, which is an action that can only be performed by the owner. This command permanently removes the specified PNFT from the blockchain. Once an NFT is burned, it cannot be recovered, so this action should be considered final and irreversible.

panacead tx pnft burn-pnft <denom_id> <id> \
  --from <key or address> \
  --chain-id <chain-id> \
  --fees 1000000umed