https://github.com/onflow/ledger-app-flow
https://github.com/onflow/ledger-app-flow
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/onflow/ledger-app-flow
- Owner: onflow
- License: apache-2.0
- Created: 2020-09-05T03:49:18.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2025-02-14T17:20:01.000Z (10 months ago)
- Last Synced: 2025-04-09T14:09:01.683Z (8 months ago)
- Language: JavaScript
- Size: 22.7 MB
- Stars: 10
- Watchers: 41
- Forks: 12
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Ledger Flow app
[](https://opensource.org/licenses/Apache-2.0)
[](https://circleci.com/gh/onflow/ledger-app-flow)
This repository contains:
- Ledger Nano S/X/SPlus BOLOS app
- Specs / Documentation
- C++ unit tests
- Speculos tests
- Semi-automatic on-device tests for Nano S/SPlus
## 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).
The builds generated by this repository are for development purposes. THESE ARE UNVETTED DEVELOPMENT RELEASES._
# Development
## Preconditions
- Be sure you checkout submodules too:
```
git submodule update --init --recursive
```
- Install Docker CE
- Instructions can be found here: https://docs.docker.com/install/
- 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 > v16.10.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 NanoS firmware 2.1 and/pr NanoSPlus firmware 1.0.0rc5
- The requirements can be modified by changing build container (containerized build) / setting BOLOS_SDK variable (non-containerized build)
_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 ?
There are two possibilities. You may build in a build container or not. Normally, you should use build container. For this you need to have enviroment variable `BOLOS_SDK=` (that is, empty). If you want to do non-containerized build you se this variable to the directory containing `nanos-secure-sdk` (but many make targets work only with containerized approach).
> 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:
```bash
make
```
However, you may want to clean up first (e.g. if you switched branches, or target devices)
```bash
make clean
```
If you want to build NanoX binaries (do not forget `make clean` when changing device builds)
```bash
TARGET_DEVICE=NANO_X make
```
If you want to build NanoSPlus binaries (do not forget `make clean` when changing device builds)
```bash
TARGET_DEVICE=NANO_SP make
```
### Loading the app to NanoS device using zxtool
You can use `app/pkg/zxtool.sh` generated by `make` command to load the app to ledger (works only for NanoS and NanoSPlus). The file is generated by most recent build so make sure that the build targets the device you want use. For further information about device setup see
"Using a real device for integration tests" section
## 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 concadenation of several manifet files created by the
[flow-core-contracts](https://github.com/onflow/flow-core-contracts/tree/master/lib/go/templates)
repository.
To regenerate the test vectors, update the manifest files and run this:
```bash
make generate_test_vectors
```
### Running C/C++ tests (x64)
If you installed the what is described above, just run (you may need to run `make clean` first):
```bash
make cpp_test
```
### Running device emulation/integration tests
You can run tests on an emulated Ledger device using Speculos.
todo: update documentation
```bash
make speculos_install
```
Then you can run JS tests. The tests compare against saved snapshots.
```bash
make speculos_port_5001_test
make speculos_port_5002_test
```
Or for NanoX:
```bash
TARGET_DEVICE=NANO_X make speculos_port_5001_test
TARGET_DEVICE=NANO_X make speculos_port_5002_test
```
Or for NanoSPlus:
```bash
TARGET_DEVICE=NANO_SP make speculos_port_5001_test
TARGET_DEVICE=NANO_SP make speculos_port_5002_test
```
If you want to change the snapshots you can set `TEST_PNG_RE_GEN_FOR` enviroment variable. If you want to change snapshots set `TEST_PNG_RE_GEN_FOR=test`, otherwise you can set a prefix and tests with that prefix will be re-generated. Dont forget to review generated snapshot.
The 5002 test test sign transaction calls and uses the generated test vectors. Do not forget to regenerate them if you change them. The 5001 tests test all other calls.
Remember to run `make` if you change the app.
There are also backward compatibility tests, but only for Nano S. They test if JS works well with older versions of the application loaded on leder.
### Updating Build container/SDK/Speculos
When updating Build container/SDK/Speculos you want to change SDK parameter in speculos call in `deps/ledger-zxlib/dockerized_build.mk`
### Modifying the transaction list
To modify the list of transaction known by Ledger, do the following:
1. Add/modify the manifest files in `transaction_metadata` directory, modify the script to include new files.
2. Copy the resulting `txMerkleTree.js` file to `js/src`. Re-build js and re-install speculos (`make speculos_install` to include newly build js in speculos tests).
3. Take the top level hash from `txMerkleTree.js` and move it to `merkleTreeRoot` variable of `app/src/tx_metadata.c` (you need to split the hex into C array of uint8_t's).
4. Copy the resulting `txMerkleTree.js` file to `test/generate-transaction-tests` and regenerate the tests.
5. You may want to modify the manifest for integration testing to include newly added changes into integration tests. If you do this, you may need to generate and review snapshots both for NanoS and NanoX/S+.
This process will have to change slightly in the future to support backward compatibility of JS. Thus not much automation for now.
## Using a real device for integration tests (Nano S and Nano S Plus)
### 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**
- In Linux hosts it might be necessary to adjust udev rules, etc.
Refer to Ledger documentation: https://support.ledger.com/hc/en-us/articles/115005165269-Fix-connection-issues,
https://developers.ledger.com/docs/nano-app/load/
**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.
**4 - Load the app**
- see below
**5 - Run the tests**
- Run `make ledger_test` / `TARGET_DEVICE=NANO_SP make ledger_test` and follow the instructions. You might want to comment out some tests.
Note that the tests require clean app state. You can compare screens you see with Speculos snapshots.
### Loading the app
The Makefile will build the firmware in a docker container and leave the binary in the correct directory.
- Build (you might need to `make clean first')
```
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
- [APDU Protocol](docs/APDUSPEC.md)