This guide is designed for the general user who is not incompetant with computers and is looking to secure less than $100,000 (in 2023 prices) worth of bitcoin.
The Blockstream Jade is a bitcoin-only hardware wallet that runs 100% on Open Source code.
The firmware that runs Jade can also run other general purpose hardware that shares the same ESP32 microcontroller.
Why Should I Follow This Guide?
Three words: supply chain attacks.
You understand that the person who sells you hardware for your bitcoin shouldn't know you use it for bitcoin.
WARNING: Do not hold more than $100,000 (in 2023 prices) on any hardware wallet including the Jade. For large amounts, refer to the "Who Should NOT Follow This Guide?" section.
You want to learn how to use the Jade hardware wallet. Refer to the Jade's help center documentation or contact Blockstream for software support.
You can't be bothered to operate a computer through the command line. We will be using the Terminal console, which some people find scary. It's not hard, I promise.
You aren't willing to use Linux, macOS (running modern Arm-based hardware), or ChromOS. (This guide only supports Debian-based Linux, macOS, and ChromeOS for now but will eventually add support for other Linux distributions.)
tl;dr: You need to control physical access to your DIY Jade.
Evil maid attacks, such as this one done by hackers for a competitor, will become easier and cheaper to perform over time.
It's not just a risk of someone hacking or altering YOUR device. An evil maid can also swap your device with a new malicious device.
You need to control physical access to your DIY Jade hardware wallet at all times as a countermeasure. Keep your DIY Jade locked up in a safe, lockbox, or some other method of restricting access. Don't let your house cleaner see your DIY Jade.
For further reading, please see [#1], [#2], [#3], [#4].
You are better off buying the hardware directly from the hardware vendor than through a third-party channel like Amazon or Alibaba. In many cases, it's cheaper to buy direct too.
There are three options for flashing your device:
This option is recommended for the average user who doesn't know how to read and write bash.
Open the Terminal.
Ctrl+Alt+T
.Command+Space
, type terminal, and press return
.🔍 (search)
on the keyboard, type terminal and press enter
.Run the following command (via copy-paste) in Terminal.
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/flash_your_device)"
When the script asks, choose your device (#1-#4).
After the script completes, you should see the Jade initialization screen on your device.
Open the Terminal.
Ctrl+Alt+T
.Command+Space
, type terminal, and press return
.🔍 (search)
on the keyboard, type terminal and press enter
.Run one of the following commands (via copy-paste) in Terminal.
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_ttgo_tdisplay)"
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_m5stickc_plus)"
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_core_basic)"
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_fire)"
After the script completes, you should see the Jade initialization screen on your device.
This options is provided for people who want to run the commands themselves.
Open the Terminal. On Linux, press Ctrl+Alt+T
. On macOS, press Command+Space
, type terminal, and press return
.
Install the required software packages. On a slow computer, this step can take over 20 minutes. Copy-and-paste the following lines into Terminal:
sudo apt update
sudo apt install -y cmake git python3-pip python3-venv
[ -d ${HOME}/esp ] || mkdir ${HOME}/esp
git clone -b v5.1.1 --recursive https://github.com/espressif/esp-idf.git ${HOME}/esp/esp-idf
cd "${HOME}"/esp/esp-idf
./install.sh esp32
. ./export.sh
TODO: Add instructions for installing macOS dependendies.
Download the Jade source code. Copy-and-paste the following lines into Terminal:
git clone --recursive https://github.com/blockstream/jade "${HOME}"/jade
cd "${HOME}"/jade/
git checkout $(git tag | grep -v miner | sort -V | tail -1)
Load the pre-built configuration file for your DIY hardware.
cp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults
cp configs/sdkconfig_display_m5stickcplus.defaults sdkconfig.defaults
cp configs/sdkconfig_display_m5blackgray.defaults sdkconfig.defaults
cp configs/sdkconfig_display_m5fire.defaults sdkconfig.defaults
Modify the configuration file you just loaded to disable logging in debug mode (a.k.a. "research and development" mode).
sed -i.bak '/CONFIG_DEBUG_MODE/d' ./sdkconfig.defaults
sed -i.bak '1s/^/CONFIG_LOG_DEFUALT_LEVEL_NONE=y\n/' sdkconfig.defaults
rm sdkconfig.defaults.bak
Build the firmware.
idf.py build
Connect your device to your computer via USB.
Enable read-write permissions for your device.
[ -f /dev/ttyACM0 ] && sudo chmod o+rw /dev/ttyACM0
[ -f /dev/ttyUSB0 ] && sudo chmod o+rw /dev/ttyUSB0
TODO: Add macOS instructions.
Flash (install) Jade onto your device. On a slow computer, this step can take over 10 minutes. Run the following command in Terminal:
idf.py -b 115200 flash
Either disable read-write permissions for your device or disconnect it. (Default permissions will be restored when you re-connect it.)
[ -f /dev/ttyACM0 ] && sudo chmod o-rw /dev/ttyACM0
[ -f /dev/ttyUSB0 ] && sudo chmod o-rw /dev/ttyUSB0
After the build and flash process completes, you should see the Jade initialization screen on your device.
Inspiration for this project came from: