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

in HiveDevs3 months 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:

banner_engrave 100.png

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

  1. Connect your device, unlock and open Hive application.

  1. 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'
  2. Type hive-ledger-cli get-public-key "m/48'/13'/0'/0'/0'" -c

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

  1. 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:
  1. Connect your device, unlock and open Hive application.

  1. Type in your terminal (replace test.ledger with your own username) and follow the instruction
hive-ledger-cli associate-account test.ledger
  1. Software will derive a new set of public keys and will make sure those are unused by searching in blockchain for those keys.

  2. Validate and approve three keys from on your device.

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

  1. Repeat this step for next two keys.

  2. Enter your current owner private key in WIF format

  3. 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).

  1. Connect your device, unlock and open Hive application.

  1. Type in your terminal
hive-ledger-cli discover-accounts
  1. 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

  1. Connect your device, unlock and open Hive application.

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

  1. You can see two accounts connected with this ledger: acronyms and test.ledger. Both can be used to receive funds.

  2. 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:

  1. Connect your device, unlock and open Hive application.

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

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

  1. 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
  1. Connect your device, unlock and open Hive application.

  1. Type in your terminal
hive-ledger-cli transfer-to-vesting "m/48'/13'/0'/2'/0'" test.ledger test.ledger "0.001 HIVE"
  1. Use left and right keys to verify transaction on your hardware wallet

  1. 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


Originally posted on Hive Ledger Support. Hive blog powered by ENGRAVE.

Sort:  

Thank you for your hard work!

I saw how much time and effort it took.
And a lot of sacrifices (such as absence on meetups! ;-) )

Well done!

This comment has 100% beneficiary set to @engrave so if anyone wish to double the prize, be my guest :-)

Thanks, I appreciate this :)

After reading your post I am tempted to buy a hardware wallet. Too bad I'm broke...

Keep posting in Hive and you will be able to buy a few after a while

Thank you for your work!

It's really amazing.

Excellent!
Can we have an option in the CLI to add authority instead of replacing existing ones?

Sure, I'm going to add more features. I just wanted to add required things and submit the app. Now I will have more time to fine tune it ;)

awesome work

Great work that I think required a few boxes of paracetamol. Thank you for your contribution to the HIVE ecosystem 👍

Excellent work friend, congratulations and success, perseverance always bears good results.

Awesomeness! Bookmarked this valuable and exciting post for when I have time and the peace of mind to actually understand this. Recently ordered a new Ledger ( Nano X ) after having used the Ledger Nano S for a couple of years.

Just wait for the app to be easily accessible via Ledger Live and for a new wallet :)

Will do. cheers! :^)

Now this is development! So proud of this community

I've just ordered a new Ledger Nano X because of this post.

I had multiple of the old school HW1 Ledger wallets, Black Friday 2015 special edition. I haven't really used them in years because I no longer hold Bitcoin. Now I finally have a good reason to have a hardware wallet again.

Let me know when the not for advanced users is released. I have a Ledger and had no idea I could hold HBD on there, that would be optimum! But I have no idea what I just read.

Soon :) You won't miss it, I promise ;)

Best response I read all am.

Thanks for that Infos!
Greets
@schmidi

If only I had a Ledger, they look awesome and very versatile!

But I used the money I had to buy crypto. Guess I will sabe this post for a next opportunity

Beware. Ledger had a huge information dump in 2019. One guy in Mexico said he lost $10,000 because of it. I, at the time living in France, was considering buying it. Then changed my mind. I trust their food more than I trust their crypto wallets. Macron is rotten to the core🤮

Indeed their e-commerce data leaked some time ago (addresses, phone numbers etc) but there is no way that it could lead to a device compromise other than social engineering or another kind of manipulation/phishing. So the statement that someone lost $10k because of this is not true.

No it is true. Because of the leak of address they broke into his apartment in Mexico and took everything he had, ledger and computers included. They also stole his key phrases. So a leak like that is extremely dangerous indeed. All they need is your address. The Tresor is safer from data leaks. As we say in France...merde in France😏

good stuff!!!

Congratulations @engrave! Your post has been a top performer on the Hive blockchain and you have been rewarded with the following badge:

Post with the highest payout of the day.

You can view your badges on your board and compare yourself to others in the Ranking
If you no longer want to receive notifications, reply to this comment with the word STOP

Check out the last post from @hivebuzz:

The new HiveFest⁶ attendee badge is waiting for you

Awesome! Do you plan to add support for all active authority operations?

The ledger hw app supports 37 operations that can be performed by the user (I believe it's a complete set). I haven't had time to add it to the CLI. Most of those will be available in a GUI wallet.

Great! Ledger integration will be one of our priorities once we finish our refactor and the Ledger App is available. Thanks for your work!

i wish to buy hardware wallet to connect my hive aacount..but unfortunately it is not available in India..😐 but soon it will be for Indian user too... always hope for the best.....

Does the app work for android or mobile users?
Direct connection from Android to general ledger device?

Current solution (CLI) works only for PC but future wallet might be mobile compatible.

Yeah, maybe if it happened soon it would be even more perfect, but for now, it's so much better progress.
I salute 😍🥰🤗🤗

Woah! This is good tech stuff!

Let me know when they offer the user-friendly wallet supporting Ledger Hive application!!!

This post is crazy informative! I have been considering ledger and now know exactly how to use it when I have made the leap. I am extremely new to trading cryptocurrency and crypto gaming and have been having so much fun learning about all of this. It's a brave new world that, apparently, has already been here for some years. I am finally catching up. Thank you for this post!

This is huge help! Added to my bookmarks and favorited this. Thanks a huge ton 🙌😃
!PIZZA !LUV

<><

<><

LUV

Connect

Trade


@engrave, you've been given LUV from @d-zero.

Check the LUV in your H-E wallet. (1/1)

PIZZA!

PIZZA Holders sent $PIZZA tips in this post's comments:
@d-zero(1/10) tipped @engrave (x1)

Learn more at https://hive.pizza.

This is sooo cool, thank you so much! I always wondered why I couldn't add Hive to my hardware wallet and now I can! Epic!!

Very very interesting this post... Thanks for share!

Thanks for taking so much time to write this tutorial, @engrave.

Congratulations @engrave! Your post has been a top performer on the Hive blockchain and you have been rewarded with the following badge:

Post with the highest payout of the week.

You can view your badges on your board and compare yourself to others in the Ranking
If you no longer want to receive notifications, reply to this comment with the word STOP