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 secure more than $100,000 (in 2023 dollars) worth of bitcoin. For large amounts, install Linux yourself on dedicated laptops and use multisig on Bitcoin Core following a best-practices self-custody guide.
- 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].
- No camera support. To build a DIY Jade with camera support, please refer here.
- Need a documented process for updating firmware.
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.
- MSRP: $8-$11, either the K164 or Q125 variant
- Does not include a battery. Either keep it plugged in or add a generic battery for a few dollars.
- DO NOT confuse this hardware with the more expensive T-Display S3 or T-Display AMOLED products.
- MSRP: $20
- Includes a built-in battery
- DO NOT confuse this hardware with the older, cheaper M5StickC. The newer PLUS verison with a larger screen is the one to buy.
- MSRP: $40
- Nice 3-button design
- MSRP: $50
- Nice 3-button design, a bigger battery, and a magnetic charging base
There are three options for flashing your device:
- Install with the Semi-Automated Script (easiest way)
- Install with a Device-Specific Script (another easy way)
- Install by Running the Code Manually (harder way)
This option is recommended for the average user who doesn't know how to read and write bash.
-
Open the Terminal.
- On Linux, press
Ctrl+Alt+T. - On macOS, press
Command+Space, type terminal, and pressreturn. - on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press
🔍 (search)on the keyboard, type terminal and pressenter.
- On Linux, press
-
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.
- On Linux, press
Ctrl+Alt+T. - On macOS, press
Command+Space, type terminal, and pressreturn. - on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press
🔍 (search)on the keyboard, type terminal and pressenter.
- On Linux, press
-
Run one of the following commands (via copy-paste) in Terminal.
- For the TTGO T-Dispay:
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_ttgo_tdisplay)" - For the M5Stack M5StickC PLUS:
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_m5stickc_plus)" - For the M5Stack Core Basic:
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_core_basic)" - For the M5Stack FIRE:
/bin/bash -c "$(curl -sSL https://github.com/epiccurious/jade-diy/raw/master/device_specific/flash_the_m5stack_fire)"
- For the TTGO T-Dispay:
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, pressCommand+Space, type terminal, and pressreturn. -
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.
- For the TTGO T-Display, run:
cp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults
- For the M5Stack M5StickC Plus, run:
cp configs/sdkconfig_display_m5stickcplus.defaults sdkconfig.defaults
- For the M5Stack Core, run:
cp configs/sdkconfig_display_m5blackgray.defaults sdkconfig.defaults
- For the M5Stack Fire, run:
cp configs/sdkconfig_display_m5fire.defaults sdkconfig.defaults
- For the TTGO T-Display, run:
-
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:
- Blockstream Jade
- @YTCryptoGuide (YouTube).