Ledger Boilerplate Application

This is a boilerplate application which can be forked to start a new project for the Ledger Nano S/X/SP and Stax.

Quick start guide

With VSCode

You can quickly setup a convenient environment to build and test your application by using the vscode integration and the ledger-app-dev-tools docker image.

It will allow you, whether you are developing on macOS, Windows or Linux to quickly build your apps, test them on Speculos and load them on any supported device.

• Install and run Docker.
• Make sure you have an X11 server running :
  • On Ubuntu Linux, it should be running by default.
  • On macOS, install and launch XQuartz (make sure to go to XQuartz > Preferences > Security and check "Allow client connections").
  • On Windows, install and launch VcXsrv (make sure to configure it to disable access control).
• Install VScode
• Open a terminal and clone app-boilerplate with git clone git@github.com:LedgerHQ/app-boilerplate.git.
• Open the app-boilerplate folder with VSCode.
• Open the vscode tasks with ctrl + shift + b (command + shift + b on a Mac) and run the following actions :
  • Pull and run the ledger-app-dev-tools docker image by selecting Run dev-tools image (select the task for your platform).
  • Build the for the device model of your choice with Build app.
  • Test your binary on Speculos with Run Speculos.

ℹ️ The VsCode tasks also allow you to perform the following actions :

• Install functional tests Python requirements (mandatory before executing functional tests),
• Execute functional tests,
• Open a terminal in your docker container,
• Clean build files,
• Load the app on a physical device.

You can find all the available tasks definitions in .vscode/tasks.json.

With a terminal

The ledger-app-dev-tools docker image contains all the required tools and libraries to build, test and load an application.

You can download it from the ghcr.io docker repository:

sudo docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest

You can then enter this development environment by executing the following command from the directory of the application git repository:

Linux (Ubuntu)

sudo docker run --rm -ti --user "$(id -u):$(id -g)" --privileged -v "/dev/bus/usb:/dev/bus/usb" -v "$(realpath .):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest

macOS

sudo docker run  --rm -ti --user "$(id -u):$(id -g)" --privileged -v "$(pwd -P):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest

Windows (with PowerShell)

docker run --rm -ti --privileged -v "$(Get-Location):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest

The application's code will be available from inside the docker container, you can proceed to the following compilation steps to build your app.

Compilation and load

To easily setup a development environment for compilation and loading on a physical device, you can use the VSCode integration whether you are on Linux, macOS or Windows.

If you prefer using a terminal to perform the steps manually, you can use the guide below.

Compilation

Setup a compilation environment by following the shell with docker approach.

From inside the container, use the following command to build the app :

make DEBUG=1  # compile optionally with PRINTF

You can choose which device to compile and load for by setting the BOLOS_SDK environment variable to the following values :

• BOLOS_SDK=$NANOS_SDK
• BOLOS_SDK=$NANOX_SDK
• BOLOS_SDK=$NANOSP_SDK
• BOLOS_SDK=$STAX_SDK

By default this variable is set to build/load for Nano S.

Loading on a physical device

This step will vary slightly depending on your platform.

ℹ️ Your physical device must be connected, unlocked and the screen showing the dashboard (not inside an application).

Linux (Ubuntu)

First make sure you have the proper udev rules added on your host :

# Run these commands on your host, from the app's source folder.
sudo cp .vscode/20-ledger.ledgerblue.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules 
sudo udevadm trigger

Then once you have opened a terminal in the app-builder image and built the app for the device you want, run the following command :

# Run this command from the app-builder container terminal.
make load    # load the app on a Nano S by default

Setting the BOLOS_SDK environment variable will allow you to load on whichever supported device you want.

macOS / Windows (with PowerShell)

ℹ️ It is assumed you have Python installed on your computer.

Run these commands on your host from the app's source folder once you have built the app for the device you want :

# Install Python virtualenv
python3 -m pip install virtualenv 
# Create the 'ledger' virtualenv
python3 -m virtualenv ledger

Enter the Python virtual environment

• macOS : source ledger/bin/activate
• Windows : .\ledger\Scripts\Activate.ps1

# Install Ledgerblue (tool to load the app)
python3 -m pip install ledgerblue 
# Load the app.
python3 -m ledgerblue.runScript --scp --fileName bin/app.apdu --elfFile bin/app.elf

Test

The boilerplate app comes with functional tests implemented with Ledger's Ragger test framework.

macOS / Windows

To test your app on macOS or Windows, it is recommended to use the VSCode integration to quickly setup a working test environment.

You can use the following VsCode sequence of tasks (open the menu with ctrl + shift + b or command + shift + b on a Mac) :

• Run dev-tools image and select the task for your platform,
• Build app and select a device model.

Then you can choose to execute the functional tests :

• Install tests requirements to be executed once after you have run the dev-tools image, followed by,
• Run functional tests and select the model you just built the app for.

Or simply run the app on the Speculos emulator :

• Test app with Speculos and select the correct device model.

Linux (Ubuntu)

On Linux, you can use the VSCode integration to run the tests. If you prefer not to, open a terminal and follow the steps below.

Install the tests requirements :

pip install -r tests/requirements.txt 

Then you can :

Run the functional tests (here for nanos but available for any device once you have built the binaries) :

pytest tests/ --tb=short -v --device nanos

Or run your app directly with Speculos

speculos --model nanos build/nanos/bin/app.elf

Documentation

High level documentation such as APDU, commands and transaction serialization are included in developer documentation which can be generated with doxygen

doxygen .doxygen/Doxyfile

the process outputs HTML and LaTeX documentations in doc/html and doc/latex folders.

Continuous Integration

The flow processed in GitHub Actions is the following:

• Ledger guidelines enforcer which verifies that an app is compliant with Ledger guidelines. The successful completion of this reusable workflow is a mandatory step for an app to be available on the Ledger application store. More information on the guidelines can be found in the repository ledger-app-workflow
• Code formatting with clang-format
• Compilation of the application for all Ledger hardware in ledger-app-builder
• Unit tests of C functions with cmocka (see unit-tests/)
• End-to-end tests with Speculos emulator and ragger (see tests/)
• Code coverage with gcov/lcov and upload to codecov.io
• Documentation generation with doxygen

It outputs 3 artifacts:

• compiled_app_binaries within binary files of the build process for each device
• code-coverage within HTML details of code coverage
• documentation within HTML auto-generated documentation

Are you developing a Nano S, S Plus, X application?

If so, This boilerplate will help you get started.

For a smooth and quick integration:

• See the developers’ documentation on the Developer Portal, and
• Go on Discord to chat with developer support and the developer community.