Jade Do-It-Yourself Hardware Guide

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.

Table of Contents

• Background
  • What is a Jade?
  • Motivation (Who Should Follow This Guide?)
  • Who Should NOT Follow This Guide?
  • MUST READ: Keep Your DIY Jade Secured
  • Current Limitations of Third-Party DIY Hardware
• Hardware Options
  • TTGO T-Display
  • M5Stack M5StickC PLUS
  • M5Stack Core Basic
  • M5Stack FIRE v2.6
• Set-Up Instructions
  • Use the Semi-Automated Script
  • Use a Device-Specific Script
  • Run the Commands Manually
• Acknowledgements

Background

What is a Jade?

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.

Motivation (Who Should Follow This Guide)

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.

Who Should NOT Follow This Guide?

1. You want to secure more than $100,000 (in 2023 dollars) worth of bitcoin. For larger amounts, install Linux yourself on dedicated laptops and use multisig on Bitcoin Core following a best-practices self-custody guide.

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

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

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

MUST READ: Keep Your DIY Jade Secured

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

Limitations of This Project

• No camera support. To build a DIY Jade with camera support, please refer here.
• No Secure Boot support. To mitigate the risk of not using Secure Boot, keep your DIY Jade secured. (Secure Boot is great because it prevents someone from stealing your device, flashing malicious firmware, then replacing your device without your knowledge. Secure Boot sucks for noobs because if they lose the key, they lose the ability upgrade their DIY Jades in the future.)

[back to top]

Hardware Options

Pick one of the four $8-$50 options based on your budget.

The button interfaces on the two cheaper options are annoying, so if you're planning to use the device daily, go with one of the two more expensive options.

To reduce the risk of supply chain attacks, buy your hardware directly from the manufacturer rather than through a third-party channel like Amazon or Alibaba. In many cases, it's cheaper to buy directly too.

TTGO T-Display

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.

Interface action	Button combination
Navigate menus left	Push bottom button (below the power plug)
Navigate menus right	Push top button (above the power plug)
Confirm your selection on screen	Push the top and bottom buttons simultaneously

M5Stack M5StickC PLUS

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.

Interface action	Button combination
Turn on device	Press the power button (below the screen)
Turn off device	Hold the power button for 3 seconds
Navigate menus left	Push top button (above the screen)
Navigate menus right	Push main button (beside the screen)
Confirm your selection on screen	Hold the top and main buttons simultaneously for 1 second then release

M5Stack Core Basic

MSRP: $40

Includes a built-in battery and a nice 3-button design.

Interface action	Button combination
Turn on device	Press the red power button (on the left side)
Turn off device	Hold the red power button for 10 seconds
Navigate menus left	Push left button (below the screen)
Navigate menus right	Push right button (below the screen)
Confirm your selection on screen	Push the center button (below the screen)

M5Stack FIRE v2.6

MSRP: $50

Includes a bigger built-in batter and nice 3-button design.

The button interface is the exact same as the M5Stack Core Basic.

[back to top]

Set-Up Instructions

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)

Use the Semi-Automated Script

This option is recommended for the average user who doesn't know how to read and write bash.

1. Read this section about physically securing your DIY Jade.

2. Open the Terminal.

   • On Linux, press Ctrl+Alt+T.
   • On macOS, press Command+Space, type terminal, and press return.
   • on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press 🔍 (search) on the keyboard, type terminal and press enter.

3. Run the following command (via copy-paste) in Terminal.

   /bin/bash -c "$(curl -sSL https://github.com/bitcoin-tools/diyjade/raw/master/flash_your_device)"

4. When the script asks, choose your device (#1-#4).

After the script completes, you should see the Jade initialization screen on your device.

Use a Device-Specific Script

1. Read this section about physically securing your DIY Jade.

2. Open the Terminal.

   • On Linux, press Ctrl+Alt+T.
   • On macOS, press Command+Space, type terminal, and press return.
   • on ChromeOS, install Linux under Settings -> Advanced -> Developers. Then press 🔍 (search) on the keyboard, type terminal and press enter.

3. Run one of the following commands (via copy-paste) in Terminal.

   If you have this hardware	Run this command
   TTGO T-Display	/bin/bash -c "$(curl -sSL https://github.com/bitcoin-tools/diyjade/raw/master/device_specific/flash_the_ttgo_tdisplay)"
   M5Stack M5StickC Plus	/bin/bash -c "$(curl -sSL https://github.com/bitcoin-tools/diyjade/raw/master/device_specific/flash_the_m5stack_m5stickc_plus)"
   M5Stack Core Basic	/bin/bash -c "$(curl -sSL https://github.com/bitcoin-tools/diyjade/raw/master/device_specific/flash_the_m5stack_core_basic)"
   M5Stack FIRE	/bin/bash -c "$(curl -sSL https://github.com/bitcoin-tools/diyjade/raw/master/device_specific/flash_the_m5stack_fire)"

After the script completes, you should see the Jade initialization screen on your device.

Run the Commands Manually

This options is provided for people who want to run the commands themselves.

1. Read this section about physically securing your DIY Jade.

2. Open the Terminal. On Linux, press Ctrl+Alt+T. On macOS, press Command+Space, type terminal, and press return.

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

4. Download the Jade source code. Copy-and-paste the following lines into Terminal:

   git clone -b 1.0.30 --recursive https://github.com/blockstream/jade "${HOME}"/jade
   cd "${HOME}"/jade/

5. Load the pre-built configuration file for your DIY hardware.

   If you have this hardware	Run this command
   TTGO T-Display	cp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults
   M5Stack M5StickC Plus	cp configs/sdkconfig_display_m5stickcplus.defaults sdkconfig.defaults
   M5Stack Core Basic	cp configs/sdkconfig_display_m5blackgray.defaults sdkconfig.defaults
   M5Stack FIRE	cp configs/sdkconfig_display_m5fire.defaults sdkconfig.defaults

6. 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_DEFAULT_LEVEL_NONE=y\n/' sdkconfig.defaults
   rm sdkconfig.defaults.bak

7. Build the firmware.

   idf.py build
   

8. Connect your device to your computer via USB.

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

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

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

[back to top]

Acknowledgements

Inspiration for this project came from:

• Blockstream Jade
• @YTCryptoGuide (YouTube).