/app-flow

Primary LanguageCApache License 2.0Apache-2.0

Ledger Flow app

stability-wip License CircleCI

This repository contains:

  • Ledger Nano S/X BOLOS app
  • Specs / Documentation
  • C++ unit tests
  • Zemu 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

Download and install

Once the app is approved by Ledger, it will be available in their app store (Ledger Live). You can get builds generated by CircleCI from the release tab. THESE ARE UNVETTED DEVELOPMENT RELEASES.

Download a release from here (https://github.com/onflow/ledger-app-flow/releases). You only need zxtool.sh

If the file is not executable, run

chmod +x ./zxtool.sh

then run:

./zxtool.sh load

Development

Preconditions

  • Be sure you checkout submodules too:

    git submodule update --init --recursive

  • Install Docker CE

  • We only officially support Ubuntu. It should be possible to do app development is other OSs, but compatibility is not always ensured.

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 > v14.0. We typically recommend using n for node version management. (This is used to run emulation tests)

  • Install python 3

  • Install other dependencies running:

    • make deps

  • This project requires Ledger firmware 1.6

    • The current repository keeps track of Ledger's SDK but it is possible to override it by changing the git submodule.

Warning: Some IDEs may not use the same python interpreter or virtual enviroment 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.

How to build ?

We like clion or vscode, however, he we describe reproducible command line steps that can be used anywhere

  • Building the app itself

    If you installed all dependencies (as described above), just run:

    make

Running tests

Generating transaction test vectors

Transaction test vectors are stored in tests/testvectors.

Transaction sources are stored in the following manifest files:

  • tests/generate-transaction-tests/manifest.mainnet.json
  • tests/generate-transaction-tests/manifest.testnet.json

These manifest files are created by the flow-core-contracts repository.

To regenerate the test vectors, update the manifest files and run this:

make generate_test_vectors

Running C/C++ tests (x64)

If you installed the what is described above, just run:

make cpp_test

Running device emulation/integration tests

You can run tests on an emulated Ledger device using Zemu, a NodeJS package developed by Zondax.

NPM package here: https://www.npmjs.com/package/@zondax/zemu

Repository here: https://github.com/Zondax/zemu

First install the dependencies:

At this moment, if you change the app you will need to run make before running the test again.

make zemu_install

Then you can run JS tests:

make zemu_test

To run a single specific test:

At the moment, the recommendation is to run from the IDE. Remember to run make if you change the app.

Using a real device for integration tests

How to prepare your DEVELOPMENT! device:

You can normally use an emulated device for development purposed. This is only required if you are working on some integration that requires a physical device.

Please 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

There are a few additional steps that increase reproducibility and simplify development:

1 - Ensure your device works in your OS

2 - Set a test mnemonic

Many of our integration tests expect the device to be configured with a known test mnemonic.

  • Plug your device while pressing the right button

  • Your device will show "Recovery" in the screen

  • Double click

  • Run make dev_init. This will take about 2 minutes. The device will be initialized to:

    PIN: 5555
Mnemonic: equip will roof matter pink blind book anxiety banner elbow sun young

3 - Add a development certificate

  • Plug your device while pressing the right button

  • Your device will show "Recovery" in the screen

  • Click both buttons at the same time

  • Enter your pin if necessary

  • Run make dev_ca. The device will receive a development certificate to avoid constant manual confirmations.

Using a real device for a single test

  • Use make clean, make, and make load to load the app to the ledger device.
  • Make adjustments in js/test/transactions.spec.js if needed
  • Run yarn test in the js folder.

Loading the app

The Makefile will build the firmware in a docker container and leave the binary in the correct directory.

  • Build

    make                # Builds the app

  • Upload to a device

    The following command will upload the application to the ledger:

    Warning: The application will be deleted before uploading.

    make load          # Builds and loads the app to the device

APDU Specifications