The Heritage wallet CLI, a Bitcoin Taproot wallet managing on-chain inheritance of bitcoins.
Explore the Heritage wallet service »
Report Bug
Table of Contents
The heritage-cli project provides a CLI tool to manages Bitcoin wallets.
It can interact with the btcherit.com service or manage everything locally. On the private keys front, it can either manage them localy, or with the help of a Ledger hardware-wallet device.
Here is the basic workflow between the Bitcoin blockchain, the btcherit.com service and the heritage-cli:
This PNG can be edited using Draw.io
- The btcherit.com service synchronize permanently with the Bitcoin blockchain;
- From the service, you can see and manage your wallet, and create new unsigned transactions;
- The
heritage-clisign those transactions using your private key(s), preferably managed on a Ledger device; - From the service, you can broadcast the signed transactions.
If you don't have a Ledger device, installing the heritage-cli on an air-gapped computer will give you a very secure setup because your private keys never need to "touch" the Internet, but on the other-hand making transactions is burdensome because you need to transfer them in and out of the air-gapped computer to sign them then broadcast them.
Another advantage of this setup is that you only have to verify/trust the heritage-cli: the btcherit.com service does not know your private keys and cannot steal your coin!
And I understand: the CLI is able to work independently of the service! Provide it a custom Bitcoin Core or Electrum node for synchronization, and manage your Heritage wallet entirely on your own!
Beware though that you SHOULD make sure you understand what are the caveat of this mode of operation, most importantly that you HAVE TO backup your descriptors: it is even more important than to backup you seed.
Using Taproot Bitcoin scripts to manage inheritance is only good as long as you don't forget to move your coins to "reset" the dead-man switch. The service is here to remind you of that, as well as making the operation easy or even seemless (for example, if you spend coins few months before the expiration of your deadman switch, the service will automatically use this transaction to "reset" it).
Also, if you are dead, your heirs should be notified and helped to retrieve the coins you left behind for them, the service is also handling this part.
Of course you can take steps to do all that on your own, the service is simply here to ease the burden.
The software provided is working and can be safely used for Bitcoin's holdings.
We are using Semantic Versioning (MAJOR.MINOR.PATCH).
Everything is still in the initial-development stage (version 0.x.x). While you can expect every new version to be in working order, you SHOULD NOT expect the CLI arguments and usage to be stable. That being said, new features and breaking changes will only happen on MINOR version increment, not on PATCH version increment.
You can find precompiled binaries for the major platforms in the Release section of the repo:
If you wish to install the v0.6.0-beta for Linux, you can run:
version="v0.6.0-beta"
wget https://github.com/crypto7world/heritage-cli/releases/download/${version}/heritage-cli-${version}-x86_64-unknown-linux-gnu.tar.gz
tar xvzf heritage-cli-${version}-x86_64-unknown-linux-gnu.tar.gz
./heritage-cli # to verify it worked, should display usage instructionsNote: If you are on Linux and plan on using a Ledger device, you need to install UDEV rules, go to the official Ledger repository: https://github.com/LedgerHQ/udev-rules
To install the heritage-cli from sources, make sure you have Rust installed. You can use any method, just make sure to have the Minimum Supported Rust Version. Using rustup.rs is generally a winner:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shOn Linux, you need to install the libudev package, for example on Ubuntu:
sudo apt-get install -y libudev-devThen clone this repo, cd into it and run cargo install:
git clone https://github.com/crypto7world/heritage-cli
cd heritage-cli
cargo install --bin heritage-cli --path .
export PATH="$PATH:$HOME/.cargo/bin" # Make sure cargo installation path is in your PATH
heritage-cli # to verify it worked, should display usage instructionsAlternatively you can just use cargo build -r and then copy the heritage-cli binary from the target directory to wherever you like.
You can get help simply by running
heritage-cli helpOr, to get help about a specific command heritage-cli help <command>, for example:
heritage-cli help wallet createCreates a new Heritage wallet with the chosen online-wallet and key-provider
An Heritage wallet has two functional components:
- The "key-provider" is the component dedicated to key management.
It will be use mainly when creating a new wallet and each time you need to sign a Bitcoin transaction.
Its security is critical and using a Ledger device is recommended.
- The "online-wallet" is the component on which you can declare your Heritage Configuration, generate new Bitcoin addresses, synchronize with the blockchain and create new Unsigned transactions.
Usage: heritage-cli wallet create [OPTIONS]
Options:
[CLIP]
Assuming you use the btcherit.com service as the online-wallet, the CLI will need to be authenticated.
heritage-cli service loginIt will open a web-browser tab so you can login to the service and grant access to the CLI.
It is not per-say a mandatory step, but it will make your life MUCH easier.
Note: If you are on Linux, you need to install UDEV rules in order for your Ledger device to be found, go to the official Ledger repository: https://github.com/LedgerHQ/udev-rules
Create a new wallet named default that will use the btcherit.com service as online-wallet and a Ledger as key-provider by simply running:
heritage-cli wallet createMake sure your Ledger device in plugged in and unlocked!
Note: If you are on Linux, you need to install UDEV rules in order for your Ledger device to be found, go to the official Ledger repository: https://github.com/LedgerHQ/udev-rules
Create a new wallet named default that will use a local bitcoin node as online-wallet and a Ledger as key-provider by running:
heritage-cli wallet create -o localMake sure your Ledger device in plugged in and unlocked!
If you already have a mnemonic you would like to restore, for example abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about:
heritage-cli wallet create --kp local --seed abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about⛔ OBVIOUSLY DO NOT USE THAT MNEMONIC TO CREATE YOUR BITCOIN WALLET ⛔
First create 2 wallets:
heritage-cli heir backup create --email <your-own-email>
heritage-cli heir wife create --email <your-wife-email>Then set the Heritage Configuration of your wallet. As an example, this tells "after 360 days without the coins moving, I want my backup wallet to be able to spend the coins, then 30 days later, I want my wife's wallet to be able to spend":
heritage-cli wallet heritage-config set --sh backup:360 --sh wife:390As you can see, there is nothing really special about a backup-access. It is just a regular heir that happen to be yourself.
At this point, you can create addresses and start receiving coins:
heritage-cli wallet new-addressLast but not least, don't forget to save the seeds of the backup and wife heirs!!
heritage-cli heir backup backup-mnemonic
heritage-cli heir wife backup-mnemonicThe information provided by these commands is all your heirs need to be able to spend your coins if the deadman switch is not reset. You can put those in sealed paper envelopes. It is safe, because as long as you don't loose your main access (and don't die), there is absolutely nothing anyone can do with these enveloppes.
The Heritage wallet architecture makes it rely mostly on its internal database, which need to be synchronized with the blockchain when you receive new coins:
heritage-cli wallet syncIf you are NOT USING the btcherit.com service, the CLI will attempt to connect to a local Bitcoin Core node by default. You can change this behavior, for example to use a local Electrum node:
heritage-cli blockchain --set --electrum-uri tcp://localhost:50001See the Blockchain provider options for more:
Blockchain Provider options:
--electrum-uri <ELECTRUM_URI>
Set the Electrum server RPC endpoint URI to use when broadcasting a transaction or synchronizing a local wallet
--bitcoincore-url <BITCOINCORE_URL>
Set the Bitcoin Core server RPC endpoint URL to use when broadcasting a transaction or synchronizing a local wallet
--auth-cookie <AUTH_COOKIE>
Use the specified cookie-file to authenticate with Bitcoin Core
--username <USERNAME>
Use the specified username to authenticate with Bitcoin Core
--password <PASSWORD>
Use the specified password to authenticate with Bitcoin Core
You can spend coins like this, in one line:
heritage-cli wallet send-bitcoin -r <address>:<amount> --sign --broadcastThe CLI will create a new transaction, show it to you, ask you if you want to sign it and then broadcast it. And that's it.
You can also decompose thoses steps. For reference, here is a Bash script doing the same thing as the previous one-liner:
unsigned=$(heritage-cli wallet send-bitcoin -r <address>:<amount>)
signed=$(heritage-cli wallet sign $unsigned)
heritage-cli wallet broadcast $signedThis binary compile with Rust 1.79.0
Distributed under the MIT License. See LICENSE for more information.
And based upon 3 Rust projects without which I would not have gotten that far:
Thanks.
John Galt - @Crypto7W - john@crypto7.world
Though my real name is Jérémie Rodon (LinkedIn, GitHub), I operate this project under the pseudonym John Galt in reference to the character of Ayn Rand novel Atlas Shrugged (and, yes, I obviously embrace John Galt philosophy).
Project Link: https://github.com/crypto7world/heritage-cli