Guide CLI

Delegator Guide (CLI)

This document contains all the necessary information for delegators to interact with the GotaBit Hub through the Command-Line Interface (CLI).

It also contains instructions on how to manage accounts, restore accounts from the fundraiser and use a ledger nano device.

Overview

GotaBit Accounts
Restoring Accounts
Creating an Account
Setting Up gotabitd
Querying the State
Sending Transactions
Signing Transactions From an Offline Computer

GotaBit Accounts

At the core of every GotaBit account, there is a seed, which takes the form of a 12 or 24-words mnemonic. From this mnemonic, it is possible to create any number of GotaBit accounts, i.e. pairs of private key/public key. This is called an HD wallet (see BIP32 for more information on the HD wallet specification).The funds stored in an account are controlled by the private key. This private key is generated using a one-way function from the mnemonic. If you lose the private key, you can retrieve it using the mnemonic. However, if you lose the mnemonic, you will lose access to all the derived private keys. Likewise, if someone gains access to your mnemonic, they gain access to all the associated accounts. The address is a public string with a human-readable prefix (e.g. gio1knrqvl059ymv0qytxac02e6n4sm8dwh94y6mgq) that identifies your account. When someone wants to send you funds, they send it to your address. It is computationally infeasible to find the private key associated with a given address.

Restoring Account

To restore an account using a fundraiser mnemonic and store the associated encrypted private key on a computer, use the following command:

gotabitd keys add <yourKeyName> --recover

<yourKeyName> is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
You can add the optional --account flag to specify the path (0, 1, 2, ...) you want to use to generate your account. By default, account 0 is generated. The private key of account 0 will be saved in your operating system's credentials storage. Each time you want to send a transaction, you will need to unlock your system's credentials store. If you lose access to your credentials storage, you can always recover the private key with the mnemonic.

❗ You may not be prompted for password each time you send a transaction since most operating systems unlock user's credentials store upon login by default. If you want to change your credentials store security policies please refer to your operating system manual.

Creating an Account

To create an account, you just need to have gotabitd installed. Before creating it, you need to know where you intend to store and interact with your private keys. The best options are to store them in an offline dedicated computer or a ledger device. Storing them on your regular online computer involves more risk, since anyone who infiltrates your computer through the internet could exfiltrate your private keys and steal your funds. Then, to create an account, use the following command:

gotabitd keys add <yourAccountName> --ledger

<yourKeyName> is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
You can add the optional --account flag to specify the path (0, 1, 2, ...) you want to use to generate your account. By default, account 0 is generated.

To generate an account, just use the following command:

gotabitd keys add <yourKeyName>

❗After you have secured your mnemonic (triple check!), you can delete bash history to ensure no one can retrieve it:

history -c
rm ~/.bash_history

You can generate more accounts from the same mnemonic using the following command:

gotabitd keys add <yourKeyName> --recover --account 1

This command will prompt you to input a passphrase as well as your mnemonic. Change the account number to generate a different account.

Setting Up gotabitd

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 set up gotabitd, use the following command:

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

# example: gotabitd config node https://rpc-testnet.gotabit.dev (note: this is a placeholder)

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

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

gotabitd config chain-id gotabit-test-1

Querying the State

gotabitd lets you query all relevant information from the blockchain, like account balances, amount of bonded tokens, outstanding rewards, governance proposals and more. Next is a list of the most useful commands for delegator.

# query account balances and other account-related information
gotabitd query account <yourAddress>
# query the list of validators

gotabitd query staking validators
# query the information of a validator given their address (e.g. gio1sw4y6cqqxywk3zw4e6wv9pj85epdjlr7pegsw8)
gotabitd query staking validator <validatorAddress>

# query all delegations made from a delegator given their address (e.g. gio1knrqvl059ymv0qytxac02e6n4sm8dwh94y6mgq)
gotabitd query staking delegations <delegatorAddress>

# query a specific delegation made from a delegator (e.g. gio1qk5kp54unexsk8ddeq8scmcvzfgdp6rzypl96e) to a validator (e.g. gio1rgq5d4ps0tz2rwqhtrtyw95lympwvfnfg49hfe) given their addresses
gotabitd query staking delegation <delegatorAddress> <validatorAddress>

# query the rewards of a delegator given a delegator address (e.g. gio1r4rzuyt2a4rarlcqjcmzlk4rlea2rsd0e4d9z3)
gotabitd query distribution rewards <delegatorAddress>

# query all proposals currently open for depositing
gotabitd query gov proposals --status deposit_period

# query all proposals currently open for voting
gotabitd query gov proposals --status voting_period

# query a proposal given its proposalID
gotabitd query gov proposal <proposalID>

For more commands, just type:

gotabitd query

For each command, you can use the -h or --help flag to get more information.

Sending Transactions

Sending Tokens

# Send a certain amount of tokens to an address
# Ex value for parameters (do not actually use these values in your tx!!): <to_address>=gio1tseh0grt8j8klrdunpudflvy9lfn3rl50zdpu8 <amount>=1000000ugtb
# Ex value for flags: <gasPrice>=0.0025ugtb

gotabid tx bank send $MY_VALIDATOR_ADDRESS [from_key_or_address] [to_address] [amount] [flags]

Bonding Gtbs and Withdrawing Rewards

# Bond a certain amount of Gtbs to a given validator
# ex value for flags: <validatorAddress>=gio1qk5kp54unexsk8ddeq8scmcvzfgdp6rzypl96e, <amountToBound>=10000000ugtb, <gasPrice>=0.0025ugtb

gotabitd tx staking delegate <validatorAddress> <amountToBond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>

# Redelegate a certain amount of Gtbs from a validator to another
# Can only be used if already bonded to a validator
# Redelegation takes effect immediately, there is no waiting period to redelegate
# After a redelegation, no other redelegation can be made from the account for the next 3 weeks
# ex value for flags: <stcValidatorAddress>=gio1qk5kp54unexsk8ddeq8scmcvzfgdp6rzypl96e, <amountToRedelegate>=100000000ugtb, <gasPrice>=0.0025ugtb

gotabitd tx staking redelegate <srcValidatorAddress> <destValidatorAddress> <amountToRedelegate> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>

# Withdraw all rewards
# ex value for flag: <gasPrice>=0.0025ugtb

gotabitd tx distribution withdraw-all-rewards --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>


# Unbond a certain amount of Gtbs from a given validator
# You will have to wait 3 weeks before your Gtbs are fully unbonded and transferrable
# ex value for flags: <validatorAddress>=gio1qk5kp54unexsk8ddeq8scmcvzfgdp6rzypl96e, <amountToUnbound>=10000000ugtb, <gasPrice>=0.0025ugtb

gotabitd tx staking unbond <validatorAddress> <amountToUnbond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>

To confirm that your transaction went through, you can use the following queries:

# your balance should change after you bond Gtbs or withdraw rewards
gotabitd query account

# you should have delegations after you bond Gtb
gotabitd query staking delegations <delegatorAddress>

# this returns your tx if it has been included
# use the tx hash that was displayed when you created the tx
gotabitd query tx <txHash>

Double check with a block explorer if you interact with the network through a trusted full-node.

Participating in Governance

Primer on Governance

The GotaBit Hub has a built-in governance system that lets bonded Gtb holders vote on proposals. There are three types of proposal:

Text Proposals: These are the most basic type of proposals. They can be used to get the opinion of the network on a given topic.
Parameter Proposals: These are used to update the value of an existing parameter.
Software Upgrade Proposal: These are used to propose an upgrade of the Hub's software.

Any Gtb holder can submit a proposal. In order for the proposal to be open for voting, it needs to come with a deposit that is greater than a parameter called minDeposit. The deposit need not be provided in its entirety by the submitter. If the initial proposer's deposit is not sufficient, the proposal enters the deposit_period status. Then, any Gtb holder can increase the deposit by sending a depositTx.

Once the deposit reaches minDeposit, the proposal enters the voting_period, which lasts 2 weeks. Any bonded Gtb holder can then cast a vote on this proposal. The options are Yes, No, NoWithVeto and Abstain. The weight of the vote is based on the amount of bonded Gtbs of the sender. If they don't vote, delegator inherit the vote of their validator. However, delegators can override their validator's vote by sending a vote themselves.

At the end of the voting period, the proposal is accepted if there are more than 50% Yes votes (excluding Abstain votes) and less than 33.33% of NoWithVeto votes (excluding Abstain votes).

# Submit a Proposal
# <type>=text/parameter_change/software_upgrade
# ex value for flag: <gasPrice>=0.0025ugtb

gotabitd tx gov submit-proposal tx gov submit-proposal path/to/proposal.json --chain-id my-test-chain --keyring-backend test

// Where proposal.json contains:

{
  // array of proto-JSON-encoded sdk.Msgs
  "messages": [
    {
      "@type": "/cosmos.bank.v1beta1.MsgSend",
      "from_address": "gio...",
      "to_address": "gio...",
      "amount":[{"denom": "stake","amount": "10"}]
    }
  ],
  // metadata can be any of base64 encoded, raw text, stringified json, IPFS link to json
  // see below for example metadata
  "metadata: "4pIMOgIGx1vZGU=",
  "deposit": "10stake"
  "title: "My proposal"
  "summary": "A short summary of my proposal"
}

// metadata example:
{
 "title": "",
 "authors": [""],
 "summary": "",
 "details": "",
 "proposal_forum_url": "",
 "vote_option_context": "",
}

# Increase deposit of a proposal
# Retrieve proposalID from $gotabitd query gov proposals --status deposit_period
# ex value for parameter: <deposit>=10000000ugtb

gotabitd tx gov deposit <proposalID> 10stake --chain-id my-test-chain --keyring-backend test --from mykey

# Vote on a proposal
# Retrieve proposalID from $gotabitd query gov proposals --status voting_period
# <option>=yes/no/no_with_veto/abstain

gotabitd tx gov vote <proposalID> yes --chain-id my-test-chain --keyring-backend test --from mykey

Signing Transactions From an Offline Computer

If you do not have a ledger device and want to interact with your private key on an offline computer, you can use the following procedure. First, generate an unsigned transaction on an online computer with the following command (example with a bonding transaction):

// Bond Gtbs
// ex value for flags: <amountToBound>=10000000ugtb, <bech32AddressOfValidator>=giovaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, <gasPrice>=0.0025ugtb, <delegatorAddress>=gio1tseh0grt8j8klrdunpudflvy9lfn3rl50zdpu8

gotabitd tx staking delegate <validatorAddress> <amountToBond> \
  --from <delegatorAddress> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> \
  --chain-id my-test-chain --keyring-backend test --from mykey \
  --generate-only > unsignedTX.json

In order to sign, you will also need the chain-id, account-number and sequence. The chain-id is a unique identifier for the blockchain on which you are submitting the transaction. The account-number is an identifier generated when your account first receives funds. The sequence number is used to keep track of the number of transactions you have sent and prevent replay attacks.

Get the chain-id from the genesis file (gotabithub-2), and the two other fields using the account query:

gotabitd query account <yourAddress> --chain-id gotabithub-2

Generating a transaction can simply be done by appending the --generate-only flag on any tx command, e.g.:

gotabitd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id gotabithub-2 --generate-only

Then, copy unsignedTx.json and transfer it (e.g. via USB) to the offline computer. If it is not done already, create an account on the offline computer. For additional security, you can double check the parameters of your transaction before signing it using the following command:

cat unsignedTx.json

Now, sign the transaction using the following command. You will need the chain-id, sequence and account-number obtained earlier:

gotabitd tx sign unsignedTx.json --from <delegatorKeyName> --offline \
  --sequence <sequence> --account-number <account-number> \
  --chain-id my-test-chain --keyring-backend test > signedTx.json

Copy signedTx.json and transfer it back to the online computer. Finally, use the following command to broadcast the transaction:

gotabitd tx broadcast signedTx.json

Delegator Guide (CLI)​

Overview​

GotaBit Accounts​

Restoring Account​

Creating an Account​

Setting Up gotabitd​

Querying the State​

Sending Transactions​

Sending Tokens​

Bonding Gtbs and Withdrawing Rewards​

Participating in Governance​

Primer on Governance​

Signing Transactions From an Offline Computer​