How to use your ledger device with hive-ledger-cli

engrave (73)in HiveDevs • 3 years ago (edited)

The purpose of this post is to fulfill Ledger documentation requirements. It is a guide for advanced users that would like to use Hive application with a CLI (Command-line interface). In the near future I will provide an updated tutorial with user-friendly wallet supporting Ledger Hive application.

Support me with your witness vote! Click on the image below:

Introduction

Hardware wallets are considered to be the most secure way to keep your crypto assets. From now on, Ledger Nano S and X can be used to protect your Hive account. This guide will help you protecting your Hive account with keys derived on your ledger device and treat is as a cold wallet. This is the ultimate protection for your account.

Quickly about Hive

Hive is different than most blockchains. It has two native assets: HIVE and HBD (Hive Backed Dollar) and usernames instead of public addresses. Those accounts have different keys associated with different roles (owner, active, posting and memo). Every role can contain different key. To ultimately protect your Hive account it is recommended to replace your Owner key with the one derived from your device - this will protect you from leaking your private key by mistake.

Requirements

Before you start, make sure you have

Initialized Ledger device with newest firmware (2.0 for S and 1.3.0 for X)
Hive application installed on your device

Install `hive-ledger-cli`

hive-ledger-cli is a npm package that can be installed globally on your system. In order to use it, you need to have NodeJS installed on your system.

To install hive-ledger-cli simply paste

sudo npm install -g hive-ledger-cli --unsafe-perm

Validate your installation with following command which should show you the CLI help

hive-ledger-cli --help

Get an account

If you already have Hive account, you can skip this part.

Hive accounts are not free - they need to be created by another user and it costs 3 HIVE. There are multiple providers of Hive accounts. Most of them requires some sort of validation (i.e phone or email) and some can utilize different crypto assets (like BTC) to pay the fee.

Visit and choose what fits you best:

https://signup.hive.io

How to validate public key

In order to validate public key derived from a specified SLIP-0048 path, you can use get-public-key command:

USAGE
  $ hive-ledger-cli get-public-key PATH

ARGUMENTS
  PATH  BIP 32 path to derive key from

OPTIONS
  -c, --confirm  Force confirmation on Ledger device
  -h, --help     show CLI help

EXAMPLE
  $ hive-ledger-cli get-public-key "m/48'/13'/0'/0'/0'"
  Establishing transport with Hive application... done
  STM5m57x4BXEePAzVNrjUqYeh9C2a7eez1Ya2wPo7ngWLQUdEXjKn

Connect your device, unlock and open Hive application.

Select SLIP-0048 path you want to generate and validate public key for. Example key valid for Hive is m/48'/13'/0'/0'/0'
Type hive-ledger-cli get-public-key "m/48'/13'/0'/0'/0'" -c

Navigate using left and right buttons to inspect public key. Make sure it's the same that in your terminal

Confirm public key by pressing both buttons on "Approve" screen.

How to associate Hive account with your Ledger device

If you already have your Hive username, you can use your ledger device to ultimately protect it by changing all your keys to the ones derived from your device.

In the example below, we will associate existing account called test.ledger with the device. You will need current owner private key in Hive supported WIF format.

USAGE
  $ hive-ledger-cli associate-account USERNAME

ARGUMENTS
  USERNAME  Account to associate

OPTIONS
  -d, --dry              dry run will only print signed transaction instead broadcasting it
  -h, --help             show CLI help
  -k, --key-gap=key-gap  [default: 5] Gap limit for unused key indexes on which the software decides that SLIP-0048 account index is not used
  -t, --testnet          use testnet configuration

EXAMPLE
  $ hive-ledger-cli associate-account test.ledger
  Found existing account:  test.ledger

  This operation will replace ALL your keys with those from your device. First, we need to find new keys for your owner, active and posting authorities.

  Press any key to continue or q to exit:
  Establishing transport with Hive application... done
  Searching for unused keys on your device... done

  New owner key:  STM7ZEBoDotbYpnyNHdARYMDBMNnLWpV7fiiGa6pvHbXhfRo9ZrDf
  Derivation path:  m/48'/13'/0'/1'/0'
  Please confirm this public key on your device... done

  New active key:  STM5zpFRqa73yFULSwUYfPSftx4fE7kha9YfkAPR9yKvNLKU2QDFu
  Derivation path:  m/48'/13'/1'/1'/0'
  Please confirm this public key on your device... done

  New posting key:  STM6YGUesBwuotbZvcfqoXfjQUrfVXGYwJZ9DCHEiFLQfxUsLK9M1
  Derivation path:  m/48'/13'/4'/1'/0'
  Please confirm this public key on your device... done

  Now you need to enter your CURRENT OWNER PRIVATE KEY in WIF format. It will be used to update your account with a new keys. Please be aware that this operation will replace ALL of your current keys

  Enter your current PRIVATE OWNER KEY for test.ledger:

Connect your device, unlock and open Hive application.

Type in your terminal (replace test.ledger with your own username) and follow the instruction

hive-ledger-cli associate-account test.ledger

Software will derive a new set of public keys and will make sure those are unused by searching in blockchain for those keys.
Validate and approve three keys from on your device.

Confirm public key by pressing both buttons on "Approve" screen.

Repeat this step for next two keys.
Enter your current owner private key in WIF format
Your account is now associated with your device. You can validate it with "How to find accounts associated with your device" tutorial.

How to find accounts associated with your device

You can quickly check which accounts are associated with your device (those will have owner authority derived from your device).

Connect your device, unlock and open Hive application.

Type in your terminal

hive-ledger-cli discover-accounts

Wait for the result with your accounts listed in a table

How to receive HIVE or HBD

If you know your account username, you can use it as a receiver address from any other wallet or exchange for HIVE or HBD. If you don't remember it, use hive-ledger-cli to determine account names associated with your device.

USAGE
  $ hive-ledger-cli discover-accounts [ROLE]

ARGUMENTS
  ROLE  (owner|active|memo|posting) [default: owner] Role to check for

OPTIONS
  -a, --account-gap=account-gap  [default: 5] Gap limit for unused account indexes after which the software decides that device is not used
  -d, --dry                      dry run will only print signed transaction instead broadcasting it
  -h, --help                     show CLI help
  -k, --key-gap=key-gap          [default: 5] Gap limit for unused key indexes on which the software decides that device is not used
  -t, --testnet                  use testnet configuration

EXAMPLE
  $ hive-ledger-cli discover-accounts

Connect your device, unlock and open Hive application.

Type hive-ledger-cli discover-accounts and wait for process to finish

You can see two accounts connected with this ledger: acronyms and test.ledger. Both can be used to receive funds.
You can validate path and public key with "How to validate public key" tutorial

How to transfer HIVE or HBD to another account

You can send liquid tokens (HIVE or HBD) withing 3 seconds to any other existing Hive account.

USAGE
  $ hive-ledger-cli transfer PATH FROM TO AMOUNT [MEMO]

ARGUMENTS
  PATH    BIP 32 (SLIP-0048) path to derive key from and use to sign the transaction
  FROM    sender
  TO      receiver
  AMOUNT  amount to send
  MEMO    optional transfer memo

To send 0.001 HIVE from test.ledger to engrave account:

Connect your device, unlock and open Hive application.

Type in your terminal

hive-ledger-cli transfer "m/48'/13'/0'/2'/0'" test.ledger engrave "0.001 HIVE" "Sent using ledger device!"

Use left and right buttons to verify transaction on your hardware wallet.

Accept the transaction by pressing both buttons on "Approve" screen.

How to stake HIVE

To gain more governance power over Hive blockchain, you can convert your HIVE into Hive Power. We call it "powering up" and other blockchains calls it "staking". Underneath, your tokens are converted to VESTS. Withdrawal of your staked HIVE (converting it back to liquid HIVE) will take 13 weeks.

To convert HIVE into HP (Hive Power), use hive-ledger-cli.

USAGE
  $ hive-ledger-cli transfer-to-vesting PATH FROM TO AMOUNT

ARGUMENTS
  PATH    BIP 32 (SLIP-0048) path to derive key from and use to sign the transaction
  FROM    source account
  TO      target account
  AMOUNT  amount to stake

OPTIONS
  -d, --dry      dry run will only print signed transaction instead broadcasting it
  -h, --help     show CLI help
  -t, --testnet  use testnet configuration

Connect your device, unlock and open Hive application.

Type in your terminal

hive-ledger-cli transfer-to-vesting "m/48'/13'/0'/2'/0'" test.ledger test.ledger "0.001 HIVE"

Use left and right keys to verify transaction on your hardware wallet

Accept the transaction by pressing both buttons on "Approve" screen.

Where to find account balance

You can use hive-ledger-cli package to check any account balance:

$ hive-ledger-cli balance test.ledger

Will produce

Balances for @test.ledger account
----------------
Liquid:  0.998 HIVE, 0.001 HBD
Savings: 0.000 HIVE, 0.000 HBD
Staked:  0.001 HP
----------------
Pending rewards: 0.000 HP, 0.000 HIVE, 0.000 HBD

You can view your account balance on multiple block explorer and Hive powered social media frontends. Most of them support /@username standard. For example:

https://hiveblocks.com/@test.ledger
https://hiveblockexplorer.com/@test.ledger
https://hive.ausbit.dev/@test.ledger
https://peakd.com/@test.ledger/wallet
https://wallet.hive.blog/@test.ledger