From 647aabb39c599fc4869a19a331fd679f9c017cd3 Mon Sep 17 00:00:00 2001 From: Coline Date: Fri, 28 Jan 2022 14:59:37 +0100 Subject: [PATCH] docs(README): refactor --- README.md | 150 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 119 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 5fd6b9a..03e6438 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,118 @@ -# app-ethereum -Ethereum wallet application framework for Nano S and Nano X. -Ledger Blue is not maintained anymore, but the app can still be compiled for this target using the branch `blue-final-release`. +
+
+ + + + +

app-ethereum

+ +

+ Ethereum wallet application for Ledger Blue, Nano S and Nano X +
+ « Explore the docs » +
+
+ Report Bug + · Request Feature +

+
+
+ +
+ Table of Contents + +- [About the project](#about-the-project) +- [Documentation](#documentation) + - [Plugins](#plugins) +- [Testing](#testing) + - [Requirement](#requirement) + - [Build the applications required by the test suite](#build-the-applications-required-by-the-test-suite) + - [Running all tests](#running-all-tests) + - [With Makefile](#with-makefile) + - [With yarn](#with-yarn) + - [Running a specific tests](#running-a-specific-tests) + - [Adding tests](#adding-tests) + - [Zemu](#zemu) + - [Update binaries](#update-binaries) +- [Contributing](#contributing) + + +
+ +## About the project + +Ethereum wallet application framework for Nano S and Nano X. +Ledger Blue is not maintained anymore, but the app can still be compiled for this target using the branch [`blue-final-release`](https://github.com/LedgerHQ/app-ethereum/tree/blue-final-release). + +## Documentation This app follows the specification available in the `doc/` folder. To compile it and load it on a device, please check out our [developer portal](https://developers.ledger.com/docs/nano-app/introduction/). -# Plugins +### Plugins -This app support external plugins. More info in [doc/ethapp_plugin.asc](https://github.com/LedgerHQ/app-ethereum/blob/master/doc/ethapp_plugins.asc). If you wish to have a look at an existing plugin, feel free to check out the [Boilerplate plugin](https://github.com/LedgerHQ/app-plugin-boilerplate). +We have the concept of plugins in the ETH app. +Find the documentations here: +- [Blog Ethereum plugins](https://blog.ledger.com/ethereum-plugins/) +- [Ethereum application Plugins : Technical Specifications](https://github.com/LedgerHQ/app-ethereum/blob/master/doc/ethapp_plugins.asc) +- [Plugin guide](https://hackmd.io/300Ukv5gSbCbVcp3cZuwRQ) +- [Boilerplate plugin](https://github.com/LedgerHQ/app-plugin-boilerplate) -# Testing +## Testing Testing is done via the open-source framework [zemu](https://github.com/Zondax/zemu). -## Running tests +### Requirement -First [install yarn](https://classic.yarnpkg.com/en/docs/install/#debian-stable). -Open `tests/build_local_test_elfs.sh` and add your BOLOS SDKs path to `NANOS_SDK` and `NANOX_SDK`. -This helper script will build the applications required by the test suite and move them at the right place. -``` -cd tests -./build_local_test_elfs.sh -``` -Then you can install the project by simply running: -``` -cd .. -make test -``` -This will run `make install_tests` and `make run_tests` +- [nodeJS](https://github.com/nvm-sh/nvm) +- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable) +- [build environnement](https://github.com/LedgerHQ/ledger-app-builder/blob/master/Dockerfile) -To run a specific tests (here the send test): -``` -cd tests -jest --runInBand --detectOpenHandles src/send.test.js -``` +#### Build the applications required by the test suite -Make sure you're in the `tests` folder before running `jest` or `yarn test`. +1. Add your BOLOS SDKs path to: + - `NANOS_SDK` and `NANOX_SDK` + +2. Go to the `tests` folder and run `./build_local_test_elfs.sh` + - ```sh + cd tests + # This helper script will build the applications required by the test suite and move them at the right place. + yarn install + ./build_local_test_elfs.sh + ``` + +### Running all tests +#### With Makefile + +1. Then you can install the project by simply running on the `root` of the repo: + - ```sh + make test + ``` + - This will run `make install_tests` and `make run_tests` + +#### With yarn + +1. Go to the `tests` folder and run: + - ```sh + yarn test + ``` + +### Running a specific tests + +1. Go to the `tests` folder and run: + - ```sh + yarn jest --runInBand --detectOpenHandles {YourTestFile} + ``` +2. For example with the `send test`: + - ```sh + yarn jest --runInBand --detectOpenHandles src/send.test.js + ``` -## Adding tests +### Adding tests -### Zemu +#### Zemu To add tests, copy one of the already existing test files in `tests/src/`. You then need to adapt the `buffer` and `tx` variables to adapt to the APDU you wish to send. @@ -54,16 +125,33 @@ You then need to adapt the `buffer` and `tx` variables to adapt to the APDU you Finally make sure you adapt the expected signature! -### Update binaries +#### Update binaries Don't forget to update the binaries in the test folder. To do so, compile with those environement variables: -``` + +```sh make DEBUG=1 ALLOW_DATA=1 ``` Then copy the binary to the `tests/elfs` folder (in this case, compiled with SDK for nanoS): -``` + +```sh cp bin/app.elf tests/elfs/ethereum_nanos.elf ``` Repeat the operation for a binary compiled with nanoX SDK and change for `ethereum_nanox.elf`. + + +## Contributing + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag `enhancement`. + +1. Fork the Project +2. Create your Feature Branch (`git checkout -b feature/my-feature`) +3. Commit your Changes (`git commit -m 'feat: my new feature`) +4. Push to the Branch (`git push origin feature/my-feature`) +5. Open a Pull Request + +Please try to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).