LedgerHQ · xchapron-ledger · Jan 11, 2023 · Jan 7, 2023 · Jan 10, 2023 · Jan 10, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,22 @@
+# Welcome
+
+We are glad you are here to help. This document goes over the process of submitting changes and making improvements.
+
+## Developer Steps
+
+Step 5 is optional. It helps avoid submiting broken PRs.
+
+1. Open an issue
+2. Create a branch for your work
+3. Make your changes. Don't forget to update app version in `Makefile`
+4. Check your changes by running [`make scan-build`](./README.md#clang-analyzer)
+5. [Run tests](docs/running-tests.md)
+6. Create a PR to merge the changes from your Branch `#2` into `main`
+
+
+## ENF Steps
+**EOS Network Foundanation** will perform the following steps   
+- Fill out [LedgerHQ Form](https://ledger.typeform.com/Nano-App?typeform-source=developers.ledger.com) to start review process
+   - we are public release
+   - review [the checklist](https://developers.ledger.com/docs/nano-app/deliverables-checklist/)
+- Submitt PR to merge `main` branch into `LedgerHQ/app-eos` on `develop` branch
diff --git a/README.md b/README.md
@@ -9,36 +9,86 @@ To use the generic wallet refer to `signTransaction.py`, `getPublicKey.py` or Le
 # How to Install developer version
 ## Configuring Ledger Environment
 
-* Install Vagrant and Virtualbox on your machine
-* Run the following
+* Install Docker on your machines
+* Checkout the app builder repository
 
+Note the `./full` path on `docker build` differentiate from the previous version now under `legacy`
 ```
-git clone https://github.com/fix/ledger-vagrant
-cd ledger-vagrant
-vagrant up
+git clone https://github.com/LedgerHQ/ledger-app-builder.git
+cd ledger-app-builder
+sudo docker build -t ledger-app-builder:latest ./full
 ```
 
 This will take a few minutes to install
 
+## Prepare to Connect Device
+Set `udev` rules to enable devices to connect with docker container. *Note:* Instructions are for linux and tested on Ubuntu 22.
+```
+wget -q -O - https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh | sudo bash
+```
+
+Download your app
+```
+git clone https://github.com/eosnetworkfoundation/ledger-app.git
+```
+
 ## Compile your ledger app
 
-* install your app under apps/ for instance:
+* go to your instance directory:
+* copy over the files and enter the docker container
+```
+cd ledger-app
+sudo docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "$(realpath .):/app" ledger-app-builder:latest
+bash-5.1# make clean
+bash-5.1# make
+```
+
+If you want to **load** and **delete** your app directly from the container image you need to provide `--privileged` access.
+
+```
+sudo docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "/dev/bus/usb:/dev/bus/usb" -v "$(realpath .):/app" --privileged ledger-app-builder:latest
+bash-5.1# make clean
+bash-5.1# make
+```
+
+## Clang Analyzer
+
 ```
-cd apps/
-git clone https://github.com/tarassh/eos-ledger
+sudo docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "$(realpath .):/app" ledger-app-builder:latest
+bash-5.1# make scan-build
+```
+
+## Ledger Variants
+
+The `BOLOS_SDK` has three varients
+- **unset**: Nanos
+- $NANOX_SDK: Nanox
+- $NANOSP_SDK: Nanosp
 
+For Nano X, specify the BOLOS_SDK environment variable before building your app:
+
+```
+sudo docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "$(realpath .):/app" ledger-app-builder:latest
+bash-5.1# make clean
+bash-5.1# BOLOS_SDK=$NANOX_SDK make
 ```
-* connect to the machine with `ssh vagrant`
-* build eos app
+
+For Nano S+, specify the BOLOS_SDK environment variable before building your app:
 
 ```
-cd apps/eos-ledger
-make clean
-make
+sudo docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "$(realpath .):/app" ledger-app-builder:latest
+bash-5.1# make clean
+bash-5.1# BOLOS_SDK=$NANOSP_SDK make
 ```
 
-* connect your ledger Nano S to your computer
-* install the app on your ledger: `make load`
-* remove the app from the ledger: `make delete`
+Instructions taken from [Ledger HQ App Builder Readme](https://raw.githubusercontent.com/LedgerHQ/ledger-app-builder/master/README.md) with modification.
+
+## Loading App
+
+- Plugin and unlock your device
+- From within your container  
+  - `make load` or `BOLOS_SDK=$NANOSP_SDK make load` for the S-Plus
+  - `make delete` or `BOLOS_SDK=$NANOSP_SDK make delete` for the S-Plus
 
-Install instruction with slight modifications has been taken from [here](https://github.com/fix/ledger-vagrant)
+## Developer Notes
+[Setup Tools, Emulator, and Testing](./docs/Ledger-Developer-Notes.md)
diff --git a/docs/Ledger-Developer-Notes.md b/docs/Ledger-Developer-Notes.md
@@ -0,0 +1,28 @@
+## Notes
+
+Setting up the Speculos emulator and Ragger test utility is highly recommended.
+
+### Setup
+Note for Mac OSx you will need to install ledgerblue to sideload apps onto your physical device.
+   - Follow instructions in [README](../README.md) to build & compile
+   - Setup the [Speculor Emulator](./speculos-emulator-setup.md)
+
+## Testing
+   - Instructions on [Running Tests](./running-tests.md)
+   - LedgerHQ notes on [Testing with Ragger](../tests/functional/usage.md)
+
+### Creating a New App
+   - [General Process](https://developers.ledger.com/docs/coin/general-process/)
+   - [Developer Portal](https://developers.ledger.com/)
+
+### Developer Notes
+   - Side Loading Apps
+      - [Linux](https://developers.ledger.com/docs/embedded-app/load-linux/)
+      - [Mac OSx](https://developers.ledger.com/docs/embedded-app/load-mac/)
+   - [Ragger Documentation](https://ledgerhq.github.io/ragger/)
+
+
+### Ledger Emmulator
+   - [Speculos Overview](https://developers.ledger.com/docs/speculos/introduction/)
+   - [Usage](https://developers.ledger.com/docs/speculos/user/usage/)
+   - [Linux](https://developers.ledger.com/docs/speculos/installation/build/)
diff --git a/docs/running-tests.md b/docs/running-tests.md
@@ -0,0 +1,76 @@
+# Running Tests
+
+## Setup
+
+General configuration for pytest is under `ledger-app/tests/functional/conftest.py`. Configuration includes useful information like the `app name`, the `devices`, and the `ragger backends`.
+
+### Ragger
+First install `ragger`. It is a python package. May be [installed via pip](https://ledgerhq.github.io/ragger/installation.html)
+
+Alternatively you can install directly from the github repo.
+
+```
+git clone https://github.com/LedgerHQ/ragger
+cd ragger
+pip install --extra-index-url https://test.pypi.org/simple/ '.[all_backends]'
+```
+
+See [Ragger Documentation](https://ledgerhq.github.io/ragger/) for addtional information.
+
+### Build The App
+
+Follow the instructions in [Readme](../README.md#compile-your-ledger-app).
+
+After each build rename the binaries from `app.elf` to `eos_<device>.elf`. Device is one of the three listed here *nano*, *nanox*, *nanosp*. You will find the binaries under `/bin` directory.
+
+### Setup Binaries
+
+Copy the compiled binaries to `tests/elfs` directory, create the directory if necessary.
+```
+mkdir -p tests/elfs/
+cd bin
+sudo mv app.elf eos_<device>.elf
+cp eos_*.elf ../tests/elfs
+cd ../
+```
+
+## Repeat
+Build and copy the binary for each device to `tests/elfs`
+
+There should be three binaries under `tests/elfs`
+- eos_nano.elf
+- eos_nanox.elf
+- eos_nanosp.elf
+
+## Run The Emulator
+
+To validate run the app via speculos. Make sure that you run your emulator to match the build. You pass the correct device in with the `-m` option.
+
+Note your path to `speculos.py` may differ.
+
+```
+cd ledger-app
+../../ledgerHQ/speculos/speculos.py -m nanosp tests/elfs/eos_naosp.elf
+```
+
+## Testing
+
+### Install Packages
+
+You will need to install several python packages
+```
+pip install pytest pycoin asn1 base58
+```
+
+### Run Tests
+
+You can run emulated tests for a specific device or for all devices. Set `--device` to `all` for all devices.
+Use `--display` to see the emulated UI as the tests are run. The default mode runs the emulator in headless mode.  
+```
+cd test/functional
+pytest -v --tb=short --device=nanox --display
+```
+
+### CleanUp
+
+remove the directory `ledger-app/tests/functional/snapshots-tmp/` to clean out the old snapshots
diff --git a/docs/speculos-emulator-setup.md b/docs/speculos-emulator-setup.md
@@ -0,0 +1,42 @@
+# Setup Emulator for Ledger Devices
+
+## Overview
+
+- Build Emulator Speculos
+
+## Emulator
+
+- Get the [Source Code](https://github.com/LedgerHQ/speculos)
+```console
+git clone https://github.com/LedgerHQ/speculos
+```
+- cd into directory `speculos`
+- [Follow Instructions](https://github.com/LedgerHQ/speculos/blob/master/docs/index.md) to build. Recommend installing with VNC option 
+  - ````
+    sudo apt install \
+    cmake gcc-arm-linux-gnueabihf libc6-dev-armhf-cross gdb-multiarch \
+    python3-pyqt5 python3-construct python3-flask-restful python3-jsonschema \
+    python3-mnemonic python3-pil python3-pyelftools python-requests \
+    qemu-user-static
+    ```
+  - `sudo apt install libvncserver-dev`
+  - `cmake -Bbuild -H. -DWITH_VNC=1 && make -C build/`
+- Look for `speculos.py`
+- Test to validate install
+  - `pip install pytest`
+  - `python3 -m pytest -s -v tests/apps/`
+- Validate by running with default BTC app
+  - run in foreground
+  - display text mode, otherwise default is QT
+```
+./speculos.py --display text ./apps/btc.elf
+```
+- You can go to `http://127.0.0.1:5000/` for another interface and more data
+
+## Clean
+The clean command is below. After cleaning you may recompile and rebuild.
+```
+make -C build/ clean
+```
+
+## Building With