1: Introduction

This document is a comprehensive walk-through to guide you through the process of importing your seed from the Cosmos Fundraiser, and delegating your Atoms to a validator like Chorus One.

If you are looking for the easiest way to delegate, try the delegation tool on our website, which allows you to delegate Atoms from your Ledger device requiring just a few clicks. A video tutorial explains how to use the delegation tool.

For any questions that you might have with the following guide or the delegation tool, email us at support@chorus.one, reach out to our team via telegram, or schedule a call with one of our team members to assist you in delegating. Some key features of this delegation guide are:

In order to delegate successfully, you will need to do three things correctly. Each of these three items, corresponds to a section of this document.

  1. First, you will need to import your Cosmos fundraiser mnemonic (seed) into a Ledger hardware wallet. Instructions are covered in Section 3 of this document. Read to the end of the Introductory section if you don’t have a ledger.
  2. Second, you will need to install two programs - gaiacli and gaiad - on your personal computer. These programs will coordinate both with the Cosmos Hub, and with your hardware wallet. The programs will also let you generate the delegation transactions, and have them signed by the hardware wallet. Instructions are covered in Section 4 of this document.
  3. Third, you will need to connect to a seed (full) node, then create and send delegation transactions. Chorus One is operating such a full node and makes it available to delegators. The Chorus seed node will forward your transactions to the Cosmos Hub to have them included in the blockchain. You will find instructions in Section 5 of the document.

The next section contains a table of contents. Feel free to skip to sections that are relevant to you. Sections 3, 4 and 5 cover delegation using the command line. This method requires you to have a Ledger hardware wallet.

Section 6 will cover the case where you don't have a hardware wallet, and are fine delegating via command line. Section 7 will covers the case where you don't have a hardware wallet, and want to delegate with a user-friendly GUI.

If you run into issues following this guide, refer to Section 8. We will keep this document updated with issues, and their solutions, as they emerge with delegator.

2: Table of Contents

1: Introduction

2: Table of Contents

3: Setup of Cosmos fundraiser mnemonic in a Ledger device

3.1: How to factory reset an already configured Ledger device

3.2: Setting up your mnemonic in a factory reset Ledger device

3.3: Installation of the Cosmos Ledger Application on the ledger device

4: Setup of gaiad and gaiacli on your personal computer

4.1: Setup and verification of gaiad and gaiacli for Mac OSX

4.2: Setup and verification of gaiad and gaiacli for Linux

5: Connecting to Chorus node and delegating Atoms

5.1 Understand account naming in gaiacli and save Ledger account name

5.2: Check your Atom balances from the fundraiser

5.3: Connecting gaiacli to a Seed Node

5.4: Delegating Atoms to the Chorus validator

5.5: Withdrawing rewards and re-delegating them to Chorus validator

5.6: Unbonding your Atom delegation from the Chorus validator

6: Delegating without a ledger using the command line

7: Delegating without a ledger using Voyager GUI

8. Troubleshooting issues

9: Conclusion and contact details

3: Setup of Cosmos fundraiser mnemonic in a Ledger device

We will demonstrate how to set up your Cosmos mnemonic in a Ledger Nano S. This is the first step towards delegating your Atoms, and earning interest with Chorus One on the Cosmos Network. We will cover basic principles and terms in this section. Most of the instructions that follow will also work for Ledger Blue. We will link to instructions from Ledger, when we can. If you get stuck, refer to the Ledger instructions as a backup.

First and foremost, you will have been asked to store a 12 word phrase during the Cosmos fundraiser. This 12 word phase is referred to as the mnemonic in this document. Keeping this mnemonic secure is of utmost importance - if someone else gets access to the mnemonic, then they can steal your Atoms!

As the security of the mnemonic is critical, we recommend to never enter the mnemonic on any computer that is connected to the Internet. Therefore, the procedure here will teach you how to enter the mnemonic on a Ledger hardware wallet; a security device purpose built to safeguard your mnemonic. A different section of this delegation guide will teach you how to set up the mnemonic on your PC, but we don't recommend that procedure for any significant sum of Atoms.

In order to set up the seed, you must have a factory reset Ledger device. If you bought a new Ledger device, follow the instructions in sections 3 and 4. If you have an old Ledger device that is already configured, you will need to reset the device, before you can import the Cosmos seed into the device. Follow the instructions in Section 2 to reset an already configured Ledger device, and then proceed to Sections 3 and 4.

3.1: How to factory reset an already configured Ledger device
  1. Power on the device by inserting it into the USB slot of your personal computer, using the cable provided by Ledger. Insert your PIN, and navigate to device dashboard.
  2. Open the settings application, by navigating to the gear icon using the navigation buttons.
  3. Navigate to the 'Device' line, by using the navigation buttons as up or down arrows. Confirm by pressing both buttons simultaneously to open up device settings.
  4. Similar to previous step, navigate to 'Reset all' and confirm.
  5. Accept by clicking the button corresponding to the tick mark. Enter your PIN.
  6. Congratulations, your device is factory reset

If you have a Ledger Blue, you'll find the official instructions here.

3.2: Setting up your mnemonic in a factory reset Ledger device

These instructions were made using a Ledger Nano S running on firmware 1.5.5. Older devices might have slightly different workflows, please adjust as needed.

  1. Power on the device by inserting it into the USB slot of your personal computer, using the cable provided by Ledger.
  2. Follow instructions to press both buttons to begin work on the device.
  3. You should have reached a screen that asks you whether to configure this as a new device. Choose ‘No’ by clicking the button corresponding to the cross mark.
  4. Confirm that you want a restore a configuration by pressing the button corresponding to a tick mark.
  5. Press both buttons to continue on to the PIN configuration process. The PIN you set up here will be used to authenticate you to the Ledger device and access your mnemonic.
  6. Choose a secure 8 digit PIN, and enter the PIN using the buttons. Buttons function as increase or decrease navigation keys. In order to move to the next digit once a particular digit is set correctly, navigate to the tick mark symbol using the buttons, and then press both buttons. In order to move to the previous digit to make a correction, navigate to the tick mark symbol using the buttons, and then press both the buttons.
  7. The device will ask you to repeat the PIN. If the twice entered PIN codes do not match, you will need to restart at Step 5. If the PIN codes match, proceed to the next step.
  8. Press both buttons simultaneously to begin the entry of your recovery phase. The phrase 'recovery phase' has the same meaning as 'mnemonic'.
  9. The device shall give you an option of entering 12,18 or 24 word mnemonic. Select a 12-word mnemonic by browsing through the option list using the scroll buttons. Once the number 12 is magnified, click both buttons simultaneously.
  10. One by one, the device will allow you to enter the words. We will only cover the entry of the first word, since the rest follow a similar procedure. Press both buttons simultaneously.
  11. The device will show letters on the top. To enter the first letter of the first word, scroll through the alphabetical letters. Once the correct letter is enlarged, confirm by pressing both the buttons. This will move you to the next letter, which should be entered in a similar fashion.
  12. Once enough letters are entered for the first word, the device will display different options to be selected as the first word. Scroll through this list by using the buttons. Once the correct word is shown on the device, press both buttons to confirm the word. If you’d like to correct, scroll to the extreme right of the displayed word list and press when ‘clear’ is displayed.
  13. Repeat the process for all of the 12 words. The device will process your input, and will indicate its readiness when complete.

Now, we need to install the Cosmos Ledger Application on the device. Section 4 demonstrates how.

If you have a Ledger Blue, you'll find the official instructions here and here.

3.3: Installation of the Cosmos Ledger Application on the ledger device

Every network, like Cosmos or Bitcoin, has their idiosyncratic way of deriving addresses (accounts) from mnemonics and configuring the fields of a transaction. Your Ledger now needs to be "taught" the idiosyncrasies of Cosmos by the installation of the Cosmos Ledger application.

In order to download and install the Cosmos Ledger Application, we will first install Ledger Live on your personal computer. Ledger Live has an "application store" for all Ledger applications. Ledger Live can be downloaded for Linux, Windows and Mac. Follow the standard operating system workflows to install the software. When installed, run Ledger Live and follow the next series of instructions.

If you already have Ledger Live configured on your personal computer, directly start at Step 5.

  1. After clicking 'Get Started', your face options around device set up. Since we have already set up the device with the Cosmos mnemonic, click the ‘use an initialized device’ option. Select your device type.
  2. Complete the security checklist. You can check for the genuineness of your device in this section.
  3. Set up an optional password lock with Ledger Live. This password secures your financial privacy if you step away from your personal computer while working with Ledger Live. It does not secure your financial assets. Once the device is ready, click 'Open Device'.
  4. The standard Ledger Live interface should have appeared. This interface has menu and account sections in a left pane. In the right pane, which covers the majority of the screen, there might be a portfolio of your assets; or a blank screen advising you to install applications or add accounts. The next step will enable developer mode on ledger live. Developer mode is necessary for the installation of the Cosmos ledger app on your device.
  5. Below the title bar, on the top right of Ledger Live, you will find a small gear icon that controls the settings of Ledger Live. Click that icon.
  6. Scroll right to the bottom of the different settings to 'Developer Mode'. Toggle the switch on the right to change it from uncolored to blue.
  7. Navigate and click on the 'Manager' link on the left pane. Connect and unlock your ledger device by entering the PIN.
  8. Navigate to the dashboard. This dashboard appears directly once the PIN is entered. It might only contain a single icon with a gear, corresponding to 'Settings'.
  9. After a pause of a few seconds, and option to ‘Allow Ledger Manager’ will appear on the screen of your device. Confirm yes, by clicking the button corresponding to the tick mark.
  10. The display at Ledger Live will update to show an app catalog. Enter 'cosmos' in the search bar of the app catalog.
  11. Click the install button corresponding to the displayed Cosmos application. Once the application is installed, you’ll find an additional Cosmos icon on the screen of your device (in additions to the settings app).
  12. Now, here’s a key gotcha. The Cosmos application you just installed has different versions. An earlier version of the app produces a lot of errors when delegation. Ensure that you have version 1.0.2
  13. Navigate using the buttons to make the Cosmos application the largest icon on the device screen. Press both buttons simultaneously to open the application. Now, your device is ready to do delegation transactions!

If you possess a Ledger Blue, the instructions are the same.

Here is a key point to remember: Whenever you want to perform any transactions on the Cosmos Hub, you will need to navigate to the current state, with Cosmos application open, on your Ledger Device. For example, if your device is turned off; you will need to turn it on, enter the PIN correctly, navigate to the Cosmos application and open the application. Once the application is open, the device is ready to accept signature requests from your personal computer.

Congratulations! You’ve completed the setup of your Cosmos mnemonic on a secure hardware wallet; and are ready to wire it up to gaiacli.

4: Setup of gaiad and gaiacli on your personal computer

We will demonstrate how to install the requisite programs for OSX Linux. Post installation, you will be able to verify that a genuine copy of the software has been installed. In order to complete delegation, you will require the following two programs:

Sections 4.1 and 4.2 covers installation (and software verification) for OSX and Linux respectively.

4.1: Setup and verification of gaiad and gaiacli for Mac OSX

Getting gaiad and gaiacli to run on your command line

Verification of gaiad and gaiacli

Until this point, you've trusted the delegation guide in downloading a piece of software from the Internet. Before making any financial transactions, you should verify that the software you got is the one that was released by the Tendermint team. This section accomplishes the task of verification.

4.2: Setup and verification of gaiad and gaiacli for Linux

Verification of gaiad and gaiacli

Until this point, you've trusted the delegation guide in downloading a piece of software from the Internet. Before making any financial transactions, you should verify that the software you got is the one that was released by the Tendermint team. This section accomplishes the task of verification.

5: Connecting to a node and delegating Atoms

In this section, we will cover a few related topics:

  1. Understand how account naming works in gaiacli. This is a major source of confusion in creating the correct delegation transactions.
  2. Finding out your Cosmos account from the fundraiser and checking its balance in the Genesis file, and on the blockchain.
  3. Connecting to a seed node. This node will receive your delegation transactions, and have them confirmed.
  4. Delegating your Atoms to the Chorus validator.
  5. Withdrawing your rewards and re-delegating them to Chorus validator.
  6. Unbonding your Atom delegation from the Chorus validator.

The same steps can be used with any other validator provided you have their details. For the section in particular, it does not matter which platform you are using - OSX, Windows, or Linux - as long as you completed Section 4 correctly. Hence, this section is written in a platform-independent fashion. Prior to executing this section, you should have a Ledger Nano S configured (Section 3). Unlock the device, and open the Tendermint/Cosmos application before running commands, or when you encounter an error. Gaiad and Gaiacli should be set up as per Section 4.

5.1 Understand account naming in gaiacli and save Ledger account name

gaiacli is a tool designed to allow you to work with multiple mnemonics (those 12 word phrases), not just the fundraiser mnemonic. Another fact is that one can derive infinite numbers of Cosmos accounts from the same mnemonic. The mnemonic is like a "starter password". By mathematically transforming this starter password in predefined ways, new passwords for new Cosmos accounts are easily generated. In principle, one mnemonic should be enough to cover all your needs for all the crypto networks. But, some people choose to store funds across different mnemonics.

Gaiacli enables one to work with multiple mnemonics, and multiple accounts derived from these mnemonics. This guide will focus on your fundraiser mnemonic, but the principles generalise quite well.

One of the user challenges is that each Cosmos account is really long. Suppose, you have Atoms spread across five different accounts, and want to delegate from each of them. To create each transaction, you will need to type in the account addresses to tell gaiacli which account to delegate from. Gaiacli offers a shortcut - it allows you to name your different accounts. Any name you give in gaiacli to any of your accounts will be local to that particular machine.

Enough theory, run the command "./gaiacli keys add ledgeraccount0 --ledger", and inspect the output.

This command makes gaiacli communicate with the Ledger, and asks the ledger to calculate one Cosmos account from the mnemonic. Once calculated, the ledger forwards the account address (not the private key) to gaiacli, and gaiacli prints that data on the command line. Tendermint team allocated your Atoms to this particular account. You’ll be able to verify balances using Section 5.2.

You will be displayed a table with columns name, type, address and pubkey. The value corresponding to Address, that starts with 'cosmos..' is your Cosmos address. Note it down. The command also named this particular account ledgeraccount0. You can verify this by reading under the name column.

If you run the command "./gaiacli keys add itinerantgoat --ledger", it will name the same account itinerant goat as well. In later commands, whenever you specify ledgeraccount0 or itinerantgoat, gaiacli know which particular Cosmos address to work with. This simplifies your need to keep typing in long account strings. Tweak the commands that follow as per this understanding, and delegate from all of your accounts.

5.2: Check your Atom balances from the fundraiser

This section will help you check whether you were allotted the correct balance in the Cosmos ICO.

Once the cosmos mainnet is live, you will be able to query balances and delegation transactions using the same (or different) address on the different blockchain explorers: Stargazer, Hubble and Forbole.

5.3: Connecting gaiacli to a Seed Node

This section will connect your gaiacli instance to the Chorus seed node. You do not really need to trust this node - it serves the purpose of broadcasting your transactions to the blockchain.

Note: Try this step only after the Cosmos Hub main network is live.

Congratulations, your computer is now correctly configured to delegate Atoms to Chorus One.

5.4: Delegating Atoms to the Chorus validator

This command will require the following parameters:

  1. Address of the Chorus validator <validator_address>: cosmosvaloper15urq2dtp9qce4fyc85m6upwm9xul3049e02707
  2. Amount to Bond, represented as <amount_to_bond>: This is the amount of items you would like to delegate, in microAtoms. Suppose you want to delegate 2 Atoms. <amount_to_bond> then equals 2000000. We recommend you to not delegate your full balance. Save a few Atoms for the payment of future transaction fees.
  3. Address you would like to delegate from <address_name>: You can specify any address that you name as per Section 5.1 that controls some Atoms. In this walk-through, we assume that you are delegating from the ledger - ledgeraccount0. In case you have a different account to delegate from, replace "ledgeraccount0" in the commands that follow with the name of the account you are delegating from.
  4. Fees you would like to send in microAtoms, <fee_amount>: Transaction fees for the delegation operation in units of 10^-6 Atom. We recommend setting transaction fees to 200000. In other words, <fee_amount> should equal 200000 as per our recommendation.
  5. The address of your account, <account_address>: This is the long “cosmos…” address corresponding to your account. Some commands do not work with <address_name>, and <account_address> must be fully specified.

Let's make the delegation now! Make sure to leave a small portion of your Atom balance to be able to cover for transaction costs of reward withdrawals.

5.5: Withdrawing rewards and re-delegating them to Chorus validator

Post delegation, the delegating account will start accumulating rewards. The delegator must withdraw these rewards by sending a withdrawal transaction. When the withdrawal transaction succeeds, rewards are attributed to the cosmos account. These rewards can then be delegated again to enable them to compound. This process is called "withdrawal and re-delegation" and must be done periodically (the optimal frequency depends on the size of your stake) to achieve the best compounding returns on your Atom stash. This section will explain how to withdraw and re-delegate rewards.

To withdraw:

To delegate the rewards:

5.6: Unbonding your Atom delegation from the Chorus validator

To un-bond and make your Atoms liquid again (so that they can be moved and sold), one needs to submit an unbonding transaction. It takes three weeks for an un-bonding transaction to complete, and unlock funds.

To unbond:

6: Delegating without a ledger using the command line

So, you don't have a Ledger yet; but do not want to miss out on the high interest rate of the early days. We've got you covered.

Go through Section 4, and have gaiacli and gaiad setup on your personal computer. Read section 5.1 to understand account naming, but don’t run any of the commands from there. Now, we will import your fundraiser mnemonic:

Importing fundraiser mnemonic:

Now, execute Sections 5.2 - 5.6 as usual. Congratulations, you’ve delegated without using a Ledger!

7: Delegating without a ledger using Voyager GUI

 

Coming up as soon as there is a stable Voyager release.

8. Troubleshooting issues

Issue # 1: When attempting to delegate, or configure the node as per Section 5.3; I get an error similar to: “ERROR: while parsing config (3,1): unexpected token”

Diagnosis of Issue # 1: The user tried to configure the node once, and then reconfigured the node again. Some data from the previous configuration was saved in the configuration file, and gaiacli is having trouble decoding that data. This likely happened because Chorus needed to alter our seed node early on as the chain went live and thus necessitated the delegators to configure the seed node twice.

How to resolve Issue # 1: We will need to edit the configuration file, and make sure the file reads as such after the added. There is likely a third line that we need to be deleted:

<START_OF_FILE>

chain-id = "cosmoshub-1"

node = "18.194.218.14:26657"

<END_OF_FILE>

In order to edit the file, type “vim /Users/<your_username>/.gaiacli/config/config.toml”. This opens us the Vim editor. Press letter i on your keyboard to edit the file. Scroll to the right places using the cursor and delete what’s needed. Once the file looks like indicated, press Escape. Type wq! And Enter. Your problem should be fixed.

Issue # 2: When attempting to have something signed by the Ledger, such as a delegation or a withdrawal transaction, I get: “ERROR: [APDU_CODE_OUTPUT_BUFFER_TOO_SMALL] Authentication method blocked”.

Diagnosis of Issue # 2: This error occurs when the user runs an older version of Ledger Firmware, or an older version of the Ledger Cosmos Application. This issue was detected by the creator of the Cosmos Ledger Application, and he fixed it in version 1.0.1. The error exists in version 1.0.0 and older. Now, if the user is running older firmware on the ledger, Ledger Live does not show the newest version (1.0.1) in the Application store.

How to resolve Issue # 2: First, make sure you are running the latest version of Ledger firmware - version 1.5.5. The process to update the firmware can be found here. Then, install the Cosmos application version 1.0.1 following the instructions in Section 3.3.  Retry whatever it was that caused the error - it should be fixed.

Issue # 3: When attempting to send a delegation or withdrawal transaction, everything goes fine inside the Ledger but then this (or similar) error appears: “ERROR: broadcast_tx_commit: Response error: RPC error -32603 - Internal error: Timed out waiting for tx to be included in a block”

Diagnosis of Issue # 3: This is not an error - it’s rather a pseudoerror. The way gaiacli broadcasts transactions is it send to the seed node, and waits for ~30 seconds to receive a confirmation from the node that the transaction was included in a block. If the transaction is included in that time frame, it shows the transaction data. If however, the network is slow (for some reason), and the transaction is not confirmed in ~30 seconds, gaiacli shows this error. This does not mean your transaction failed, it just means the transaction is sitting in the memory pool of validators waiting for a proposer to include your transaction in their proposed block. Most likely, your transaction will complete in a few minutes.

How to resolve Issue # 3: Don’t do anything - just wait and you should be okay.

9: Conclusion and contact details

This guide has covered methods for delegating Atoms in the Cosmos Hub mainnet. We welcome feedback on the guide. Please feel free to add comments on the corresponding Google Doc, and we shall be pleased to improve the guide.

If you’d like hands-on F2F support with a Chorus One team member, schedule a call with us here. We are a validator with a vision, and would be happy to discuss our company, values and community with you.

For email based support, write to us at  support@chorus.one

If you want to discuss Cosmos further, stop by our Chorus One Telegram and say hi. And, of course, we’re happy to answer any questions about delegating to Chorus One.