Building a Ledger Nano S Application on MacBook and Docker

7 min readJan 31, 2021

Overview

There are many kinds of cryptocurrency wallets, one of them is a hardware wallet. A hardware wallet is a special type of wallet which stores the user’s private keys in a secure hardware device. You can read my other post here to know more about wallets.

A hardware wallet is a small device, it can only sign transactions, for other functions such as preparing transactions, broadcasting transactions it needs other software that runs on a computer or smartphone. We need to connect the hardware wallet to our computer.

Hardware wallets have major advantages over standard software wallets:

private keys are often stored in a protected area of the microcontroller, and cannot be transferred out of the device in plaintext.
Immune to computer viruses that steal from software wallets
can be used securely and interactively, private keys never need to touch potentially-vulnerable software
much of the time, the software is open-source, allowing a user to validate the entire operation of the device.

Here are pictures of some hardware wallets: Coldcardwallet, Ledger, KeepKey, and Tezor, each produced by a different company.

Ledger Nano S

Ledger Nano S is a product that is produced by Ledger SAS company in Paris. Other products are Ledger Blue, Ledger Nano X.

When you buy a Ledger Nano in the box there will be a user guide, paper for writing seed phrases, a USB cable, and the Ledger device itself.

Ledger Nano package, image: buybitcoinworldwide.com

Ledger Nano uses BOLOS (Blockchain Open Ledger Operating System) as their OS. This is the architecture of BOLOS. On Ledger devices, we can install more than one application, but only one application can run at the same time.

As described above, Ledger Nano is a small device and it needs other software that acts as a bridge to communicate with it. To manage the app inside Ledger Nano we need an app namely Ledger live.

Nowadays most cryptos such as Bitcoin and Altcoins have developed apps for Ledger Nano devices.

Do you want to make one? Yes, let’s start learning from the basic one.

Requirements

Setting up the built environment

The official website here said only Linux is supported as a development OS. For Windows and macOS users, a Linux VM is recommended.

I am using Macbook Early 2016 with macOS Catalina version 10.15.5, with RAM 8 GB to develop the Ledger Nano application in this tutorial. I need a Virtual Machine or Container that can install Linux Ubuntu. There are several options: VMWare, VirtualBox, Docker. Luckily someone or company created a Docker image nbasim/ledger-blue-sdk that supports Ledger Nano.

Install Docker

Docker provides the ability to package and run an application in a loosely isolated environment called a container. We can install Ubuntu on Mac OS using Docker. Download and install Docker from this link: https://docs.docker.com/docker-for-mac/install

Download Docker Image

A Docker image is a file, consisting of several layers, that is used to execute code in a Docker container. Someone created a Docker image for the Ledger Nano device.

Open the terminal on your Macbook, download the image with this command.

docker pull nbasim/ledger-blue-sdk

Please wait until the download process is finished. Here is the screenshot.

After the download process ends, create a folder on your MacBook with the name ledger_experiment.

mkdir ledger_experiment

On my computer, the full path is /Volumes/Data/ledger_experiment.

Now let’s start the Docker image, do this command in one line.

docker run -t -i --mount type=bind,source='/Volumes/Data/ledger_experiment',target=/home nbasim/ledger-blue-sdk /bin/bash

Ubuntu started successfully, let’s check the Ubuntu version, execute this command on the Ubuntu box, not in Macbook.

lsb_release -a

Now let’s update and install some packages on our Ubuntu 14.0 box. Execute these commands:

apt-get update
apt-get install nano
apt-get install libc6-dev-i386
apt-get install gcc-arm-none-eabi
apt-get install software-properties-common
apt-get install apt-transport-https

Update Clang

By default the Ubuntu on docker uses CLang 3.9.0, we need to update it to CLang 4.0

apt-add-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain
                    trusty-4.0 main"
apt-get update
apt-get install clang-4.0 lldb-4.0

Download Ledger Nano SDK

Make sure the ledger-blue environment is available in the folder /opt/ledger-blue. Make sure the ledger-blue environment is available in the
/opt/ledger-blue folder. I didn’t download it, it was there before.

ls /opt/ledger-blue

Next, download the nanos-secure-sdk into the folder /opt.

cd /opt
git clone https://github.com/LedgerHQ/nanos-secure-sdk.git

Your /opt folder should have two folders: ledger-blue and nano-secure-sdk.

Download Example Source Code

Download the sample source code from the git repository: https://github.com/LedgerHQ/ledger-sample-apps

cd /home
git clone https://github.com/LedgerHQ/ledger-sample-apps.git
cd ledger-sample-apps/blue-app-helloworld
ls

Edit Makefile

We need to modify the Makefile to use CLang-4.0, on the 48th line it should be set to: CLANGPATH := /usr/bin/ and the 60th line should be set to: CC := $(CLANGPATH)clang-4.0

cd /home/ledger-sample-apps/blue-app-helloworld
nano Makefile

Compiling the Source Code

Our environment is mostly ready to compile ledger nano app source code. Let’s compile the example app that we have downloaded into /home folder. We are still in the Ubuntu box, execute this command.

cd /home/ledger-sample-apps/blue-app-helloworld
make BOLOS_ENV=/opt/ledger-blue/ BOLOS_SDK=/opt/nanos-secure-sdk

The computer will compile the source code, it takes a few seconds until it finishes. Finally, it will produce app.hex file in the bin folder.

Installing apps into the device

To install the app, we need virtualenv , this module provides support for creating lightweight “virtual environments” with their own site directories, optionally isolated from system site directories.

Left Ubuntu, now back to Macbook terminal.

We need a python3 virtual environment, execute these commands on the Macbook terminal to install it.

sudo apt install python3-pip
pip3 install virtualenv

We will install the app on the hardware wallet Ledger Nano S. Take Ledger Nano S with its cable and plug it into the MacBook.

cd /Volumes/Data/ledger_experiment/ledger-sample-apps/blue-app-helloworld/bin

Run virtulenv

We’re still in the folder /Volumes/Data/ledger_experiment/ledger-sample-apps/blue-app-helloworld/bin, execute this command.

virtualenv -p python3 ledger
source ledger/bin/activate
pip3 install ledgerblue

This the screenshot

Now it's time to deploy the binary file app.hex into the Ledger device.

python -m ledgerblue.loadApp --targetId 0x31100004 --apdu --tlv --fileName app.hex --appName Hello --appFlags 0x00 --icon ""

While the process is running, see the screen of Ledger Nano, you need to do some task.

Yes, finally app running and displaying ‘HelloWorld’ on the screen. Congratulation, you success compiling and deploying HelloWorld app into Ledger Nano S.

Uninstall App

To uninstall the app, you need to connect the device to the laptop, input the pin and then execute this command.

python -m ledgerblue.deleteApp --targetId 0x31100004 --appName "Hello"

You need to complete some tasks on the Ledger Nano screen.

Edit Source Code

To edit the source code you need an Editor. Open Visual Studio Code and modify the “Hello World” with your name.

Recompile the code and redeploy the binary app.hex into the device, follow the same instructions above.

How do you feel? Happy? Yes, you already know how to compile source code, upload the app, delete the app, and modify the source code.

Video Tutorial

Are you confused about following my tutorial? Don’t worry, please watch this video tutorial.

Conclusion

The official website recommended using Linux OS as an environment to develop the Ledger Nano app. What if you don’t have one?, you can use MacBook and Ubuntu on Docker containers.

Hopefully, this short tutorial is useful for those who want to learn how to create apps on the Ledger Nano device with MacBook.

Thank you for reading this tutorial, if you are happy with this tutorial, please leave a comment, share with your friends, and click the clap icon at the bottom.