Skip to content

Instantly share code, notes, and snippets.

@hschoenburg

hschoenburg/ledgerTutorialDraft.md

Last active May 6, 2019 22:44
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save hschoenburg/2f3fe0ce36fbfb8405f5cd4bde258ef3 to your computer and use it in GitHub Desktop.
Save hschoenburg/2f3fe0ce36fbfb8405f5cd4bde258ef3 to your computer and use it in GitHub Desktop.
Download ZIP
Ledger tutorial Draft
Raw
ledgerTutorialDraft.md

(tutorial to be hosted by Cosmos and linked to from the Ledger Live store.

Using the Cosmos Ledger app

Using a hardware wallet to store your keys greatly improves the security of your crypto assets. The following is a short tutorial on using the Cosmos Ledger app to sign transactions with either the Gaia CLI or the Lunie.io web wallet.

At the core of a Ledger device, there is a mnemonic that is used to generate private keys. When you initialize you Ledger, a mnemonic is generated. This mnemonic is compatible with Cosmos accounts.

The tool used to generate addresses and transactions on the Cosmos Hub network is called gaiacli, which supports derivation of account keys from a Ledger seed. Note that the Ledger device acts as an enclave of the seed and private keys, and the process of signing transaction takes place within it. No private information ever leaves the Ledger device.

Do not lose or share your 24 words with anyone. To prevent theft or loss of funds, it is best to keep multiple copies of your mnemonic stored in safe, secure places. If someone is able to gain access to your mnemonic, they will fully control the accounts associated with them.

Gaia CLI

The gaiacli tool supports transaction signing with Ledger Nano S. Here is how to get started. If using a CLI tool is unfamiliar to you, scroll down and use the Lunie.io web wallet instead.

Before you Begin

Verify that gaiacli is installed correctly with the following command

$ gaiacli version --long

➜ cosmos-sdk: 0.34.3
git commit: 67ab0b1e1d1e5b898c8cbdede35ad5196dba01b2
vendor hash: 0341b356ad7168074391ca7507f40b050e667722
build tags: netgo ledger
go version go1.11.5 darwin/amd64

Add your Ledger key

  • Connect and unlock your Ledger device.
  • Open the Cosmos app on your Ledger.
  • Create an account in gaiacli from your ledger key. NOTE: Be sure to change the keyName parameter to be a meaningful name. The ledger flag tells gaiacli to use your Ledger to seed the account.
$ gaiacli keys add <keyName> --ledger

➜ NAME: TYPE: ADDRESS:     PUBKEY:
myLedger ledger cosmos1le9666lqqfm06gc5duyp4uqxj42mtw6pff3pew cosmospub1addwnpepqd2unmsvcslvc4lzt36d6083ktf9tjd0tp37d8ngz28cenky2l0h62az70y

Confirm your address

Run this command to display your address on the device. Use the keyName you gave your ledger key. The -d flag is supported in version 1.5 and higher.

$ gaiacli keys show <keyName> -d

Confirm that the address displayed on the device matches that displayed when you added the key. To review the address again run $ gaiacli keys list.

Note the gaiacli help commands are nested. So $ gaiacli will output docs for the top level commands (status, config, query, and tx. You can access documentation for sub commands with further help commands. $ gaiacli query --help $ gaiacli tx --help

Connect to a fullnode

Next, you need to configure gaiacli with the URL of a Cosmos fullnode and the appropriate chain_id. In this example we connect to the public load balanced fullnode operated by Chorus One on the cosmoshub-2 chain. But you can point your gaiacli to any Cosmos fullnode. Be sure that the chain_id is set to the same chain as the fullnode.

$ gaiacli config node https://cosmos.chorus.one:26657

$ gaiacli config chain_id cosmoshub-2

Test your connection with a query such as:

$ gaiacli query staking validators

NOTE: You can choose to run your own fullnode locally read more here..

Sign a transaction

You are now ready to start signing and sending transactions. Send a transaction with gaiacli using the tx send command. $ gaiacli tx send --help to see all available options.

NOTE: Be sure to unlock your device with the PIN and open the Cosmos app before trying to run these commands

Use the keyName you set for your Ledger key and gaia will connect with the Cosmos Ledger app to then sign your transaction.

$ gaiacli tx send <keyName> <desinationAddress> <amount><denomination>

When prompted with confirm transaction before signing, Answer Y.

Next you will be prompted to review and approve the transaction on your Ledger device. Be sure to inspect the transaction JSON displayed on the screen. You can scroll through each field and each message. Scroll down to read more about the data fields of a standard transaction object.

Receive funds

To receive funds to the Cosmos account on your Ledger device, retrieve the address for your Ledger account with this command:

$ gaiacli keys list

NAME:   TYPE:   ADDRESS:                                        PUBKEY:
myLedger ledger  cosmos1tsewe9jf93hvp2n7wdkw52d3etgtyz3ahfq5fh   cosmospub1addwnpepqw430audr4ulaaaymh4u2up7q89p3la9l2tf5lak4mfjrct2xh48qee70l7

Further documentation

Not sure what gaiacli can do? Simply run the command without arguments to output documentation for the commands in supports. $ gaiacli

Lunie.io

The Lunie web wallet supports signing with Ledger Nano S. Here is a short intro to using your Ledger with Lunie.io.

Connect your device

  • Connect your Ledger device to your computer, unlock it with the PIN and open the Cosmos app.
  • Open https://lunie.io in your web browser (latest version of Google Chrome preferred)
  • Click “Sign in”.
  • Choose “Sign in with Ledger Nano S”

Confirm your address

Run this command to display your address on the device. Use the keyName you gave your ledger key. The -d flag is supported in version 1.5 and higher.

$ gaiacli keys show <keyName> -d

Confirm that the address displayed on your Ledger matches that shown on Lunie.io before proceeding. Now you can use your Ledger key to sign transctions on Lunie.

To learn more about using Lunie, here is a tutorial on staking and delegating ATOMs using the Lunie web wallet.

The Cosmos Standard Transaction

Transactions in Cosmos embed the Standard Transaction type from the cosmos-sdk. The Ledger device displays a serialized JSON representation of this object for you to review before signing the transaction. Here are the fields and what they mean

  • chain-id The chain to which you are broadcasting the tx, such as the gaia-13003 testnet or cosmoshub-2 mainnet.
  • account_number The global id of the sending account assigned when the account recieves funds for the first time.
  • sequence The nonce for this account, incremented with each transaction.
  • fee JSON object describing the transaction fee, its gas amount and coin denomination
  • memo optional text field used in various ways to tag transactions.
  • msgs_<index>/<field> The array of messages included in the transaction. Double click to drill down into nested fields of the JSON.

Support

For further support, start by looking over the posts in cosmos.network forum

Feel welcome to reach out in our Telegram channel to ask for help.

Here are a few relevant and helpful tutorials from the wonderful Cosmos community:

@jackzampolin
Copy link

Need to have spaces before your ## or they won't render properly

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment