Ledger Flow Application

This repository contains:

• Ledger Nano S/Nano X/Nano SPlus/STAX BOLOS app
• Specs / Documentation
• Ledger ragger tests

ATTENTION

Please:

• Do not use in production
• Do not use a Ledger device with funds for development purposes.
• Have a separate and marked device that is used ONLY for development and testing

Once the app is approved by Ledger, it will be available in their app store (Ledger Live). The builds generated by this repository are for development purposes. THESE ARE UNVETTED DEVELOPMENT RELEASES.

Quick start guide

Docker

Install and run Docker.

Compilation

We develop on Ubuntu. On different system slight adjustment of the commands may be necessary (see documentation below).

He recommended way to compile the app is:

1. Pull the latest docker container.

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

2. Start terminal within the container.

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

3. Compile the app

make clean
make
make BOLOS_SDK=$NANOX_SDK
make BOLOS_SDK=$NANOSP_SDK
make BOLOS_SDK=$STAX_SDK

Stax app can be compiled in DEBUG mode for debugging purposes

make BOLOS_SDK=$STAX_SDK DEBUG=1

Note, that it is possible (although unlikely) for ledger to make a braking change in ledger-app-dev-tools:latest.

Tests

Speculos integration tests

These are the main test. These end to end test cover all app features. To run them you should compile the app in ledger-app-dev-tools:latest container. And then (in container) run

pytest tests/ --tb=short -v --device nanos
pytest tests/ --tb=short -v --device nanox
pytest tests/ --tb=short -v --device nanosp
pytest tests/ --tb=short -v --device stax

Note that in case ledger-app-dev-tools:latest is updated there is a chance that slight changes in gui happen. In that case it is necessary to re-generate the snapshots, e.g.

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

and review the changes in test/snapshots directory

Unit tests

As we want to test as close as possible to the production environment, the focus is on end to end integration test. However, certain complex parts of code, where test coverage with integration tests may be insufficient, are also tested using unit tests.

cd unit-tests/
cmake -Bbuild -H. && make -C build
CTEST_OUTPUT_ON_FAILURE=1 make -C build test

Scan build

We use scan build in ledger-app-dev-tools container (see Compilation section).

make clean
make scan-build
make scan-build BOLOS_SDK=$NANOX_SDK
make scan-build BOLOS_SDK=$NANOSP_SDK
make scan-build BOLOS_SDK=$STAX_SDK

Further information

Warning: This is standard documentation for ledger app provided by ledger developers. As we do not use all the options, we do no guarantee that everything is up to date.

General configuration

Install and run Docker.

With VSCode

You can quickly setup a convenient environment to build and test your application by using Ledger's VSCode developer tools extension which leverages 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.

• 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 and add Ledger's extension.
• Open a terminal and clone app-flow with
  • git clone git@github.com:LedgerHQ/app-flow.git.
  • git submodule update --init --recursive
• Open the app-flow folder with VSCode.
• Use Ledger extension's sidebar menu or open the tasks menu with ctrl + shift + b (command + shift + b on a Mac) to conveniently execute actions :
  • Build the app for the device model of your choice with Build.
  • Test your binary on Speculos with Run with Speculos.
  • You can also run functional tests, load the app on a physical device, and more.

ℹ️ The terminal tab of VSCode will show you what commands the extension runs behind the scene.

With a terminal

Using the ledger-app-dev-tools docker container (recommended)

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) (recommended)

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.

Outside the docker container

In Ubuntu, you should install the following packages:

sudo apt update && apt-get -y install build-essential git wget cmake \
libssl-dev libgmp-dev autoconf libtool

• Install node > v16.10.0. We typically recommend using n for node version management. (This is used to run emulation tests)
• Install python 3
• Install the required SDK (e.g. under /opt/) and select the one to use: export BOLOS_SDK=/opt/nanos-secure-sdk

Warning: Some IDEs may not use the same python interpreter or virtual environment as the one you used when running pip. If you see conan is not found, check that you installed the package in the same interpreter as the one that launches cmake.

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 

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

For Stax device you can compile

make BOLOS_SDK=$STAX_SDK DEBUG=1  # compile optionally with PRINTF

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. See udev-rules

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 flow app comes with functional tests implemented with Ledger's Ragger test framework.

Linux (Ubuntu) (recommended)

On Linux, you can use Ledger's VS Code extension 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

macOS / Windows

To test your app on macOS or Windows, it is recommended to use Ledger's VS Code extension to quickly setup a working test environment.

You can use the following sequence of tasks and commands (all accessible in the extension sidebar menu) :

• Select build target
• Build app

Then you can choose to execute the functional tests :

• Run tests.

Or simply run the app on the Speculos emulator :

• Run with Speculos.

Documentation

High level documentation such as APDU Protocol is 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