Skip to main content

Command line usage

GotaBit Client​

gotabitd is the tool that enables you to interact with the node that runs on the GotaBit Hub network, whether you run it yourself or not. Let us set it up properly. In order to install it, follow the installation procedure.

Setting up gotabitd​

The main command used to set up gotabitd is the following:

gotabitd config <flag> <value>

It allows you to set a default value for each given flag.

First, set up the address of the full-node you want to connect to:

gotabitd config node <host>:<port>

If you run your own full-node, just use http://localhost:26657 as the address.

Then, let us set the default value of the --trust-node flag:

gotabitd config trust-node true
# Set to true if you trust the full-node you are connecting to, false otherwise

Finally, let us set the chain-id of the blockchain we want to interact with:

gotabitd config chain-id gotabithub-2

Keys​

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:

gotabitd keys add <account_name>

The output of the above command will contain a seed phrase. It is recommended to save the seed phrase in a safe place so that in case you forget the password of the operating system's credentials store, you could eventually regenerate the key from the seed phrase with the following command:

gotabitd keys add --recover

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

gotabitd keys show <account_name> --bech=val

You can see all your available keys by typing:

gotabitd keys list

View the validator pubkey for your node by typing:

gotabitd tendermint show-validator

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

Generate Multisig Public Keys​

You can generate and print a multisig public key by typing:

gotabitd keys add --multisig=name1,name2,name3[...] --multisig-threshold=K new_key_name

K is the minimum number of private keys that must have signed the transactions that carry the public key's address as signer.

The --multisig flag must contain the name of public keys that will be combined into a public key that will be generated and stored as new_key_name in the local database. All names supplied through --multisig must already exist in the local database. Unless the flag --nosort is set, the order in which the keys are supplied on the command line does not matter, i.e. the following commands generate two identical keys:

gotabitd keys add --multisig=foo,bar,baz --multisig-threshold=2 multisig_address
gotabitd keys add --multisig=baz,foo,bar --multisig-threshold=2 multisig_address

Multisig addresses can also be generated on-the-fly and printed through the which command:

gotabitd keys show --multisig-threshold K name1 name2 name3 [...]

For more information regarding how to generate, sign and broadcast transactions with a multi signature account see Multisig Transactions. TODO:

Tx Broadcasting​

When broadcasting transactions, gotabitd accepts a --broadcast-mode flag. This flag can have a value of sync (default), async, or block, where sync makes the client return a CheckTx response, async makes the client return immediately, and block makes the client wait for the tx to be committed (or timing out).

It is important to note that the block mode should not be used in most circumstances. This is because broadcasting can timeout but the tx may still be included in a block. This can result in many undesirable situations. Therefore, it is best to use sync or async and query by tx hash to determine when the tx is included in a block.

Fees & Gas​

Each transaction may either supply fees or gas prices, but not both.

Validator's have a minimum gas price (multi-denom) 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 any of the denominations 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.

gotabitd tx bank send ... --fees=50000ugtb
gotabitd tx bank send ... --gas-prices=0.0025ugtb

Account​

Get Tokens​

On a testnet, getting tokens is usually done via a faucet.

Query Account Balance​

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

gotabitd query account <account_gotabit>

Send Tokens​

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

gotabitd tx bank send <sender_key_name_or_address> <recipient_address> 10faucetToken \
  --chain-id my-test-chain --keyring-backend test

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

gotabitd query account <account_gotabit>
gotabitd query account <destination_gotabit>

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

gotabitd query account <account_gotabit> --block=<block_height>

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

gotabitd tx bank send <sender_key_name_or_address> <destination_gotabitaccaddr> 10faucetToken \
  --chain-id my-test-chain --keyring-backend test \
  --dry-run

gotabitd tx sign \
  --chain-id my-test-chain --keyring-backend test \
  --from=<key_name> \
  unsignedSendTx.json > signedSendTx.json
# sign validate
gotabitd tx validate-signatures signedSendTx.json
# broadcast transaction
gotabitd tx broadcast --node=<node> signedSendTx.json

You may optionally pass the --broadcast-mode flag to specify which response to receive from the node:

  • sync: the CLI waits for a CheckTx execution response only.
  • async: the CLI returns immediately (transaction might fail).

Encoding a Transaction​

In order to broadcast a transaction using the gRPC or REST endpoints, the transaction will need to be encoded first. This can be done using the CLI.

Encoding a transaction is done using the following command:

gotabitd tx encode tx_signed.json

This will read the transaction from the file, serialize it using Protobuf, and output the transaction bytes as base64 in the console.

Decoding a Transaction​

The CLI can also be used to decode transaction bytes.

Decoding a transaction is done using the following command:

gotabitd tx decode [protobuf-byte-string]

This will decode the transaction bytes and output the transaction as JSON in the console. You can also save the transaction to a file by appending > tx.json to the above command.

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.

Each event is composed by a key-value pair in the form of {eventType}.{eventAttribute}={value}. Events can also be combined to query for a more specific result using the & symbol.

You can query transactions by events as follows:

# query by sender
gotabitd query txs --events='message.sender=gio1...'
# action query param
gotabitd query txs --events='message.sender=gio1...&message.action=withdraw_delegator_reward'
# pagination
gotabitd query txs --events='message.sender=gio1...' --page=1 --limit=20
# by tx hash
gotabitd query tx [hash]

Slashing​

Unjailing​

To unjail your jailed validator

gotabitd tx slashing unjail --from <validator-operator-addr>

Signing Info​

To retrieve a validator's signing info:

gotabitd query slashing signing-info <validator-pubkey>

Query Parameters​

You can get the current slashing parameters via:

gotabitd query slashing params

Staking​

Query Validators​

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

gotabitd query staking validators

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

gotabitd query staking validator <account_gotabitval>

Bond Tokens​

On the gotabit Hub mainnet, we delegate ugtb, where 1gtb = 1000000ugtb. Here's how you can bond tokens to a testnet validator (i.e. delegate):

gotabitd tx staking delegate <validator_addr> 1000gtb \
  --from=<key_name> \
  --chain-id my-test-chain --keyring-backend test

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

gotabitd keys show [name] --bech val

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

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.

gotabitd query staking delegation <delegator_addr> <validator_addr>
# check all your current delegations with distinct validators
gotabitd query staking delegations <delegator_addr>

Unbond Tokens​

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

gotabitd tx staking unbond <validator_addr> 1000gtb \
  --from=<key_name> \
  --chain-id my-test-chain --keyring-backend test

Query Unbonding-Delegations​

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

gotabitd query staking unbonding-delegation <delegator_addr> <validator_addr>
# all your current unbonding-delegations with disctinct validators
gotabitd query staking unbonding-delegations <account_gotabit>
# get all the unbonding-delegations from a particular validator
gotabitd query staking unbonding-delegations-from <account_gotabitval>

Redelegate Tokens​

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

gotabitd tx staking redelegate \
  <src-validator-operator-addr> \
  <dst-validator-operator-addr> \
  10gtb \
  --from=<key_name> \
  --chain-id my-test-chain --keyring-backend test

Query Redelegations​

Once you begin a redelegation, you can see its information by using the following command:

gotabitd query staking redelegation <delegator_addr> <src_val_addr> <dst_val_addr>
# all your current unbonding-delegations with distinct validators
gotabitd query staking redelegations <account_gotabit>
# all the outgoing redelegations from a particular validator
gotabitd query staking redelegations-from <account_gotabitval>

Query staking Parameters​

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

gotabitd query staking params

With the above command you will get the values for:

  • Unbonding time
  • Maximum numbers of validators
  • Coin denomination for staking All these values will be subject to updates through a governance process by ParameterChange proposals.

Query Pool​

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

gotabitd query staking pool

With the pool command you will get the values for:

  • Not-bonded and bonded tokens
  • Token supply
  • Current annual inflation and the block in which the last inflation was processed
  • Last recorded bonded shares

Query Delegations To Validator

gotabitd query delegations-to <account_gotabitval>

Governance​

A complete example can be found here

Fee Distribution​

Query Distribution Parameters​

gotabitd query distribution params

Query distribution Community Pool​

gotabitd query distribution community-pool

Query outstanding rewards​

gotabitd query distribution outstanding-rewards

Query Validator Commission​

gotabitd query distribution commission <validator_address>

Query Validator Slashes​

gotabitd query distribution commission <validator_address>

Query Delegator Rewards​

gotabitd query distribution rewards <delegator_address> <validator_address>

Query All Delegator Rewards​

gotabitd 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:

gotabitd keys add \
  p2 \
  --pubkey=`{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+h9HPxCnJyRleArqjgfRXyl9M4+EsuVCrO//T+7yVDS"}`

gotabitd keys add \
  p3 \
  --pubkey=`{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+h8HPxCnJyRleArqjgfRXyl9M4+EsuVCrO//T+7yVDS"}`

gotabitd 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:

gotabitd 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:

gotabitd keys show p1p2p3 -o json

gotabitd keys show p1p2p3 --show-multisig

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

gotabitd tx bank send  $MY_VALIDATOR_ADDRESS 1000000ugtb \
  --from=<multisig_address> \
  --chain-id my-test-chain --keyring-backend test \
  --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:

gotabitd tx sign \
  unsignedTx.json \
  --multisig=<multisig_address> \
  --from=p1 \
  --chain-id my-test-chain --keyring-backend test \
  --output-document=p1signature.json

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:

gotabitd tx sign \
  unsignedTx.json \
  --multisig=<multisig_address> \
  --from=p2 \
  --chain-id my-test-chain --keyring-backend test \
  --output-document=p2signature.json

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:

gotabitd tx multisign \
  unsignedTx.json \
  p1p2p3 \
  p1signature.json p2signature.json \
  --chain-id my-test-chain --keyring-backend test > signedTx.json

The transaction can now be sent to the node:

gotabitd tx broadcast signedTx.json

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

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

# bash/sh
gotabitd completion > gotabitd_completion
gotabitd completion > gotabitcli_completion
# zsh
gotabitd completion --zsh > gotabitd_completion
gotabitd completion --zsh > gotabitcli_completion

Rosetta Command​

To run Rosetta in your application CLI, use the following command:

gotabitd rosetta --help

To test and run Rosetta API endpoints for applications that are running and exposed, use the following command:

gotabitd rosetta
     --blockchain "gotabit"
     --network "testnet-1"
     --tendermint "localhost:26657"
     --grpc "localhost:9090"
     --addr ":8080"