Stellar app for the Ledger Nano S and Ledger Blue

Introduction

This is the wallet app for the Ledger Nano S and Ledger Nano X that makes it possible to store Stellar-based assets on those devices and generally sign any transaction for the Stellar network.

A companion Javascript library is available to communicate with this app. To learn how to use this library and generate a browserified version of it you can take look at the demo project.

Building and installing

To build and install the app on your Nano S or X you must set up the Ledger Nano S or X build environments. Please follow the Getting Started instructions at the Ledger Nano S github repository.

Additionaly, install this dependancy:

sudo apt install libbsd-dev

Alternatively, you can set up the Vagrant Virtualbox Ledger environment maintained here. This sets up an Ubuntu virtual machine with the Ledger build environment already set up.

The command to compile and load the app onto the device is:

make load

To remove the app from the device do:

make delete

Testing

The ./test directory contains files for testing the xdr transaction parser and the screen formatter.

They require the cmocka unit testing framework, CMake and libbsd to be installed:

sudo apt install libcmocka-dev cmake

To build and execute the tests, run the following commands:

mkdir test/build
cd test/build
cmake ..
make && make test

XDR parsing

When a transaction is to be signed it is sent to the device as an XDR serialized binary object. To show the transaction details to the user on the device this binary object must be read. This is done by a purpose-built parser shipped with this app.

Due to memory limitations the transaction maximum size is set to 1kb. This should be sufficient for most usages, including multi-operation transactions up to 15 operations depending on the size of the operations.

Alternatively the user can enable hash signing. In this mode the transaction XDR is not sent to the device but only the hash of the transaction, which is the basis for a valid signature. In this case details for the transaction cannot be displayed and verified which is why this is not the preferred mode of operation. In fact, setting hash signing mode is not persistent and needs be set again whenever the user needs it.

Key pair validation

The operation to retrieve the public key implements an optional keypair verification method. Along with the request to retrieve the public key a small message is sent that is to be signed by the device. Back on the host the returned signature can be checked against the returned public key. This is to guard against incompatibility between the keypairs generated by the Ledger device and the ones expected by the Stellar network, whatever the reason for this might be. The extra precaution prevents users from sending funds to an address they are not able to sign transactions for.

Building on Mac OS

Currently there are some tweaks that need to be made to the Makefile in order to be able to build and load the app on Mac OS. I added the following before the line include $(BOLOS_SDK)/Makefile.rules:

GLYPH_SRC_DIR = /Users/lenondupe/Code/ledger/ledger-app-stellar/src
SOURCE_PATH += $(BOLOS_SDK)/lib_stusb
SOURCE_PATH += $(BOLOS_SDK)/lib_u2f
INCLUDES_PATH += $(BOLOS_ENV)/gcc-arm-none-eabi-5_3-2016q1/lib/gcc/arm-none-eabi/5.3.1/include-fixed
INCLUDES_PATH += $(BOLOS_ENV)/gcc-arm-none-eabi-5_3-2016q1/arm-none-eabi/include