How to Store Your Cosmos ATOMs on Your Ledger and Delegate with the Command-Line

Published in

Cryptium Labs

7 min readMar 11, 2019

In a previous guide, we have learnt about installing the Cosmos Network SDK on your device and running your local full node. Recently, with Cosmos’ launch, a new chain started:cosmoshub-1. We learnt how to upgrade your full node from a testnet to the mainnet, which is a useful exercise if you are planning to operate a full node for mainnet. While the past guides were entirely focused on gaiad, in this one we will use gaiacli: the command-line interface that will allows you interact with a Cosmos full node.

Although gaiacli supports many features, in this guide we will take the perspective of an ATOM holder who owns a Ledger, recovers the fundraiser account on the Ledger, and makes a delegation to a validator. It ends with other useful commands, such as showing how to withdraw rewards and how to send unbonding transactions.

About This Guide

Commands start with $:

$ this is a command do not copy the dollar sign!

Comments start with #:

# this is a comment make sure you read them!

Sample outputs start with an arrow:

➜ this is an example command line output useful for comparing

Requirements

Ledger

As a rule of thumb, verify and do not trust. Check the website domains and app providers. Before continuing, verify that:

You have an official Ledger, and bought it from the official store https://www.ledger.com. Do not use second-hand Ledgers or buy them from unauthorised retailers, as they could’ve been compromised.
You have Ledger Live installed: download it from https://ledger.com/pages/ledger-live and check that it’s up-to-date.

The firmware of your ledger is up-to-date. If you’re not using a fresh Ledger, make sure you have backed-up your seeds before continuing.
Note that your installed apps will be erased and you will have to re-install them. Before updating, make sure you wrote down what wallets you created with the same keys (or you might forget what assets you had).
As of 11th March 2019, the latest firmware version is 1.5.5.
You have enough space the on device for installing the Cosmos app.

Gaia from the Cosmos SDK

You will need to have gaiacli installed, which comes from successfully installing the Cosmos SDK on your machine. Check if you have it installed by running:

$ gaiacli version --long➜ cosmos-sdk: 0.33.0
git commit: 7b4104aced52aa5b59a96c28b5ebeea7877fc4f0
vendor hash: 0341b356ad7168074391ca7507f40b050e667722
build tags: netgo ledger
go version go1.11.5 darwin/amd64

If you do not have it installed, follow this guide sections: 1) Requirements and Installing Golang and 2) Installing Cosmos from Source.

Access to a Cosmos Full Node

gaiacli is the command-line interface that will enable you to interact with a Cosmos full node. You can do so by either:

Running your own full node (see how)
Using a third-party full node, whose data you can rely on

Restoring an Account from the Fundraiser

As mentioned in the Hitchhiker’s Guide to the Cosmos, Cosmos had a fundraiser event that ended on April 6th 2017. If you participated in this event, you will find your corresponding ATOMs as soon as you recover the account you generated for the fundraiser.

In order to do so, find the seed words (12 words) that you generated back in the fundraiser event through the web utility (or the cli tool).

A) If you have a fresh Ledger

Connect it to your device and follow the onscreen instructions.
Choose the “Restore Configuration” option.
At Step 3 “Enter your recovery phrase”, enter the number of words of your seed words (12 words).
Connect your Ledger to your device and unlock it. Install the Cosmos App through Ledger Live, currently version 1.1.1.

B) If you have an initialised Ledger and would like to restore your fundraiser wallet on it

Before continuing, make sure your seed words are backed-up.
Go to Ledger dashboard -> device -> reset all, choose and follow through the steps, setting it as a new ledger.
At Step 3 “Enter your recovery phrase”, enter the number of words of your seed words (12 words).

Installing the Cosmos App on Your Ledger via Ledger Live

Connect your Ledger to your device and unlock it. Install the Cosmos App through Ledger Live, currently version 1.1.1:

5. Leave the Ledger connected and open the Cosmos application on your Ledger:

6. On your command-line run the following command to import the keys from your Ledger. Remember to change <keyName> for a memorable one. For example, I have named it test_ledger:

$ gaiacli keys add <keyName> --ledger➜ NAME: TYPE: ADDRESS:     PUBKEY:
test_ledger ledger cosmos1le9666lqqfm06gc5duyp4uqxj42mtw6pff3pew cosmospub1addwnpepqd2unmsvcslvc4lzt36d6083ktf9tjd0tp37d8ngz28cenky2l0h62az70y

7. You can check all the accounts you have imported so far by running the command:

$ gaiacli keys list➜ NAME: TYPE: ADDRESS:     PUBKEY:
test_ledger ledger cosmos1le9666lqqfm06gc5duyp4uqxj42mtw6pff3pew cosmospub1addwnpepqd2unmsvcslvc4lzt36d6083ktf9tjd0tp37d8ngz28cenky2l0h62az70y

Configuring the Connection to a Trusted Full Node

Let’s tell gaiacli which full node to remember and connect to by default:

# if you are running your own full node
$ gaiacli config node tcp://localhost:26657# if you want to connect to a third-party full node
$ gaiacli config node 34.65.6.52:26657➜ configuration saved to /Users/<user>/.gaiacli/config/config.toml

*Note that this 34.65.6.52:26657 node is one of our (Cryptium Labs) public full nodes, currently on cosmoshub-1.

2. Let’s also tell gaiacli to remember which chain-id to connect to (currently on cosmoshub-1):

$ gaiacli config chain-id cosmoshub-1 
➜ configuration saved to /Users/<user>/.gaiacli/config/config.toml

*Note: Once mainnet launches, you will need to revisit these commands. You can change them directly on the config.toml file in the path above.

3. To test the connection, let’s try query the balance of our account, replace cosmosxxxxxxxxxx for your own address:

$ gaiacli query account cosmos1u5gppgj2heugu03m9vdt3flkzryd4l85fq34lp

4. Alternatively, you can test the connection by querying other information, such as a list of available validators:

$ gaiacli query staking validators➜ [...]
Validator 
cosmosvaloper1kj0h4kn4z5xvedu2nd9c4a9a559wvpuvu0h6qn --trust-node=true --node="34.65.6.52:26657"
Validator
  Operator Address:           cosmosvaloper1kj0h4kn4z5xvedu2nd9c4a9a559wvpuvu0h6qn
  Validator Consensus Pubkey: cosmosvalconspub1zcjduepqvc5xdrpvduse3fc084s56n4a6dhzudyzjmywjx25fkgw2fhsj70searwgy
  Jailed:                     false
  Status:                     Bonded
  Tokens:                     317142782037
  Delegator Shares:           317142782037.000000000000000000
  Description:                {Cryptium Labs 5A309B5CA189D8B3 https://cryptium.ch Secure and available validation from the Swiss Alps}
  Unbonding Height:           0
  Unbonding Completion Time:  1970-01-01 00:00:00 +0000 UTC
  Minimum Self Delegation:    1
  Commission:                 rate: 0.200000000000000000, maxRate: 1.000000000000000000, maxChangeRate: 0.010000000000000000, updateTime: 2019-03-13 23:00:00 +0000 UTC

Delegate (Bond) Your ATOMS to a Validator

Before delegating, make sure you have read and understood the economic model behind Bonded Proof-of-Stake: see Must-Know Particularities of Tendermint Consensus and Bonded Proof-of-Stake (BPoS). Just a few reminders:

Delegations in Cosmos are at stake.
When a delegation is made, you keep custody of your funds.
Delegations are locked for 3 weeks (not liquid). To unlock delegations, the delegator must send an unlocking transaction, after which the ATOMs will become liquid after 3 weeks.
The validator committing a liveness fault will get delegations slashed by 0.01% and jailed for 10 minutes, hence not earning the rewards during the jailed period.
The validator committing a safety fault will get delegations slashed by 5% and the validator will be moved to the tombstone and can never be part of the consensus set again with the same keys.

$ gaiacli tx staking delegate <validatorAddress> <amountToBond>uatom --from <delegatorKeyName>

validatorAddress is the validator’s key that starts with cosmosvaloper1
amountToBond is in nano ATOMs: 1 ATOM = 1,000,000 nano ATOMS
delegatorKeyName is the name you gave to your account when you imported it from the Ledger. In the previous example this was test_ledger

For example:

$ gaiacli tx staking delegate cosmosvaloper1kj0h4kn4z5xvedu2nd9c4a9a559wvpuvu0h6qn 10000000uatom --from test_ledger

How to Withdraw Rewards from Your Cosmos Delegation

In Cosmos, rewards are handled in a particular way: they are not sent to the validator’s account, which is the case in other protocols, such as Tezos. Instead, their custody remains with the delegator but they are only accessible once withdrawn. There are two considerations:

The delegator must withdraw them by sending a withdrawal transaction.
Until withdrawn and re-delegated, the rewards are not at stake, hence not contributing to the total staking balance and not generating rewards.

The command to withdraw all rewards is:

$ gaiacli tx distr withdraw-all-rewards --from <delegatorKeyName>

Where delegatorKeyName is the name of your imported account. E.g. test_ledger

How to Unbond Your Cosmos Delegation

Once delegated, your ATOMs will remain locked. If you wish to unlock them, you must send an unbonding transaction. It will take 3 weeks from the timestamp of your unbonding transaction until your funds are unlocked:

$ gaiacli tx staking unbond <validatorAddress> <amountToUnbond>uatom --from <delegatorKeyName>

Where validatorAddress is the validator’s key that starts with cosmosvaloper1
amountToUnbond is in nano ATOMs: 1 ATOM = 1,000,000 uatoms (nano ATOMs)
delegatorKeyName is the name of your imported account. E.g. test_ledger