certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
cosmos-sdk/docs/sdk/clients.md

13 KiB
Raw Blame History

Clients

::: tip Note 🚧 We are actively working on documentation for SDK clients. :::

Gaia CLI

::: tip Note 🚧 We are actively working on improving documentation for Gaiacli and Gaiad. :::

gaiacli is the command line interface to manage accounts and transactions on Cosmos testnets. Here is a list of useful gaiacli commands, including usage examples.

Keys

Key Types

There are three types of key representations that are used:

  • cosmos
    • Derived from account keys generated by gaiacli keys add
    • Used to receive funds
    • e.g. cosmos15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc
  • cosmosvaloper
    • Used to associate a validator to it's operator
    • Used to invoke staking commands
    • e.g. cosmosvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah
  • cosmospub
    • Derived from account keys generated by gaiacli keys add
    • e.g. cosmospub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm
  • cosmosvalconspub
    • Generated when the node is created with gaiad init.
    • Get this value with gaiad tendermint show-validator
    • e.g. cosmosvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf

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 key default _ed25519_ elliptic curve:

gaiacli keys add <account_name>

Next, you will have to create a passphrase to protect the key on disk. The output of the above command will contain a seed phrase. Save the seed phrase in a safe place in case you forget the password!

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

gaiacli keys show <account_name>

View the validator operator's address via:

gaiacli keys show <account_name> --bech=val

You can see all your available keys by typing:

gaiacli keys list

View the validator pubkey for your node by typing:

gaiad tendermint show-validator

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

Account

Get Tokens

The best way to get tokens is from the Cosmos Testnet Faucet. If the faucet is not working for you, try asking #cosmos-validators. The faucet needs the cosmos from the account you wish to use for staking.

Query Account balance

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

gaiacli account <account_cosmos>

::: warning Note When you query an account balance with zero tokens, you will get this error: No account with address <account_cosmos> was found in the state. 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:

gaiacli tx send \
  --amount=10faucetToken \
  --chain-id=<chain_id> \
  --name=<key_name> \
  --to=<destination_cosmos>

::: warning Note The --amount flag accepts the format --amount=<value|coin_name>. :::

::: 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=simulate, the gas limit will be automatically estimated. 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:

gaiacli account <account_cosmos>
gaiacli account <destination_cosmos>

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

gaiacli account <account_cosmos> --block=<block_height>

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

gaiacli tx send \
  --amount=10faucetToken \
  --chain-id=<chain_id> \
  --name=<key_name> \
  --to=<destination_cosmosaccaddr> \
  --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:

gaiacli tx send \
  --amount=10faucetToken \
  --chain-id=<chain_id> \
  --name=<key_name> \
  --to=<destination_cosmosaccaddr> \
  --generate-only > unsignedSendTx.json

You can now sign the transaction file generated through the --generate-only flag by providing your key to the following command:

gaiacli tx sign \
  --chain-id=<chain_id> \
  --name=<key_name>
  unsignedSendTx.json > signedSendTx.json

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

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

Staking

Set up a Validator

Please refer to the Validator Setup section for a more complete guide on how to set up a validator-candidate.

Delegate to a Validator

On the upcoming mainnet, you can delegate atom to a validator. These delegators can receive part of the validator's fee revenue. Read more about the Cosmos Token Model.

Query Validators

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

gaiacli query validators

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

gaiacli query validator <account_cosmosval>

Bond Tokens

On the testnet, we delegate steak instead of atom. Here's how you can bond tokens to a testnet validator (i.e. delegate):

gaiacli tx delegate \
  --amount=10steak \
  --validator=$(gaiad tendermint show-validator) \
  --name=<key_name> \
  --chain-id=<chain_id>

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.

::: tip Note Don't use more steak thank you have! You can always get more by using the Faucet! :::

Query Delegations

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

gaiacli query delegation \
	--address-delegator=<account_cosmos> \
	--validator=<account_cosmosval>

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

gaiacli query delegations <account_cosmos>

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. You can unbond a specific shares-amount (eg:12.1) or a shares-percent (eg:25) with the corresponding flags.

gaiacli tx unbond begin \
  --validator=<account_cosmosval> \
  --shares-percent=100 \
  --from=<key_name> \
  --chain-id=<chain_id>

Later you must complete the unbonding process by using the gaiacli tx unbond complete command:

gaiacli tx unbond complete \
  --validator=<account_cosmosval> \
  --from=<key_name> \
  --chain-id=<chain_id>
Query Unbonding-Delegations

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

gaiacli query unbonding-delegation \
	--address-delegator=<account_cosmos> \
	--validator=<account_cosmosval> \

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

gaiacli query unbonding-delegations <account_cosmos>

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

Redelegate Tokens

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

gaiacli tx redelegate begin \
  --address-validator-source=<account_cosmosval> \
  --address-validator-dest=<account_cosmosval> \
  --shares-percent=50 \
  --from=<key_name> \
  --chain-id=<chain_id>

Here you can also redelegate a specific shares-amount or a shares-percent with the corresponding flags.

Later you must complete the redelegation process by using the gaiacli tx redelegate complete command:

gaiacli tx unbond complete \
  --validator=<account_cosmosval> \
  --from=<key_name> \
  --chain-id=<chain_id>
Query Redelegations

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

gaiacli query redelegation \
	--address-delegator=<account_cosmos> \
	--address-validator-source=<account_cosmosval> \
	--address-validator-dest=<account_cosmosval> \

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

gaiacli query redelegations <account_cosmos>

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

Governance

Governance is the process from which users in the Cosmos Hub can come to consensus on software upgrades, parameters of the mainnet or on custom text proposals. This is done through voting on proposals, which will be submitted by Atom holders on the mainnet.

Some considerations about the voting process:

  • Voting is done by bonded Atom holders on a 1 bonded Atom 1 vote basis
  • Delegators inherit the vote of their validator if they don't vote
  • Validators MUST vote on every proposal. If a validator does not vote on a proposal, they will be partially slashed
  • Votes are tallied at the end of the voting period (2 weeks on mainnet). Each address can vote multiple times to update its Option value (paying the transaction fee each time), only the last casted vote will count as valid
  • Voters can choose between options Yes, No, NoWithVeto and Abstain At the end of the voting period, a proposal is accepted if (YesVotes/(YesVotes+NoVotes+NoWithVetoVotes))>1/2 and (NoWithVetoVotes/(YesVotes+NoVotes+NoWithVetoVotes))<1/3. It is rejected otherwise

For more information about the governance process and how it works, please check out the Governance module specification.

Create a Governance proposal

In order to create a governance proposal, you must submit an initial deposit along with the proposal details:

  • title: Title of the proposal
  • description: Description of the proposal
  • type: Type of proposal. Must be of value Text (types SoftwareUpgrade and ParameterChange not supported yet).
gaiacli tx submit-proposal \
  --title=<title> \
  --description=<description> \
  --type=<Text/ParameterChange/SoftwareUpgrade> \
  --proposer=<account_cosmos> \
  --deposit=<40steak> \
  --from=<name> \
  --chain-id=<chain_id>
Query proposals

Once created, you can now query information of the proposal:

gaiacli query proposal \
  --proposal-id=<proposal_id>

Or query all available proposals:

gaiacli query proposals

You can also query proposals filtered by voter or depositer by using the corresponding flags.

Increase deposit

In order for a proposal to be broadcasted to the network, the amount deposited must be above a minDeposit value (default: 10 steak). If the proposal you previously created didn't meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:

gaiacli tx deposit \
  --proposal-id=<proposal_id> \
  --depositer=<account_cosmos> \
  --deposit=<200steak> \
  --from=<name> \
  --chain-id=<chain_id>

NOTE: Proposals that don't meet this requirement will be deleted after MaxDepositPeriod is reached.

Vote on a proposal

After a proposal's deposit reaches the MinDeposit value, the voting period opens. Bonded Atom holders can then cast vote on it:

gaiacli tx vote \
  --proposal-id=<proposal_id> \
  --voter=<account_cosmos> \
  --option=<Yes/No/NoWithVeto/Abstain> \
  --from=<name> \
  --chain-id=<chain_id>
Query vote

Check the vote with the option you just submitted:

gaiacli query vote \
  --proposal-id=<proposal_id> \
  --voter=<account_cosmos>

Query Parameters

You can get the current parameters that define high level settings for staking:

gaiacli query parameters

With the above command you will get the values for:

  • Maximum and minumum Inflation rate
  • Maximum annual change in inflation rate,
  • Goal of bonded tokens (%)
  • Unbonding time
  • Maximum numbers of validators
  • Coin denomination for staking

All this values can be updated though a governance process by submitting a parameter change proposal.

Query Pool

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

gaiacli query pool

With the pool command you will get the values for:

  • Loose and bonded tokens
  • Token supply
  • Current anual inflation and the block in which the last inflation was processed
  • Last recorded bonded shares

Gaia-Lite

::: tip Note 🚧 We are actively working on documentation for Gaia-lite. :::