app-ethereum

Ethereum wallet application for Ledger Blue, Nano S, Nano S Plus and Nano X
« Explore the docs »

Report Bug · Request Feature · Request New Network

Table of Contents

• About the project
• Documentation
  • Plugins
• Testing
  • Requirements
    • Build the applications required by the test suite
  • Running all tests
    • With Makefile
    • With yarn
  • Running a specific test
  • Adding tests
    • Zemu
    • Update binaries
• Contributing

About the project

Ethereum wallet application framework for Nano S, Nano S Plus 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.

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.

Plugins

We have the concept of plugins in the ETH app. Find the documentations here:

• Blog Ethereum plugins
• Ethereum application Plugins : Technical Specifications
• Plugin guide
• Boilerplate plugin

Testing

Testing is done via the open-source framework zemu.

Requirements

• nodeJS == 16
• yarn
• build environment

Build the applications required by the test suite

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

   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 and run tests by simply running on the root of the repo:

   make test
   # This will run `make install_tests` and `make run_tests`

With yarn

1. Go to the tests folder and run:

   yarn test

Running a specific test

1. Go to the tests folder and run:

   yarn jest --runInBand --detectOpenHandles {YourTestFile}

2. For example with the send test:

   yarn jest --runInBand --detectOpenHandles src/send.test.js

Adding tests

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.

• Adapt the expected screen flow. Please create a folder under tests/snapshots with the name of the test you're performing.
• Then adapt the ORIGINAL_SNAPSHOT_PATH_PREFIX with the name of the folder you just created.
• To create the snapshots, modify the SNAPSHOT_PATH_PREFIX and set it to be equal to ORIGINAL_SNAPSHOT_PATH_PREFIX.
• Run the tests once, this will create all the snapshots in the folder you created.
• Put back your SNAPSHOT_PATH_PREFIX to snapshots/tmp/.

Finally make sure you adapt the expected signature!

Update binaries

Don't forget to update the binaries in the test folder. To do so, compile with those environment variables:

make DEBUG=1 ALLOW_DATA=1

Then copy the binary to the tests/elfs folder (in this case, compiled with SDK for nanoS):

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 makes 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.

Loading wanchain app and ethereum app on a physical device

This step will vary slightly depending on your platform.

ℹ️ Your physical device must be connected, unlocked and the screen showing the dashboard (not inside an application).

Linux (Ubuntu)

First make sure you have the proper udev rules added on your host :

Run these commands on your host, from the app's source folder.

sudo cp .vscode/20-ledger.ledgerblue.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger Then once you have opened a terminal in the app-builder image and built the app for the device you want, run the following command :

Run this command from the app-builder container terminal.

make load # load the app on a Nano S by default Setting the BOLOS_SDK environment variable will allow you to load on whichever supported device you want.

macOS / Windows (with PowerShell)

ℹ️ It is assumed you have Python installed on your computer.

Run these commands on your host from the app's source folder once you have built the app for the device you want :

Install Python virtualenv

python3 -m pip install virtualenv

Create the 'ledger' virtualenv

python3 -m virtualenv ledger Enter the Python virtual environment

macOS : source ledger/bin/activate Windows : .\ledger\Scripts\Activate.ps1

Install Ledgerblue (tool to load the app)

python3 -m pip install ledgerblue

Load the app.

python3 -m ledgerblue.runScript --scp --fileName bin/app_eth.apdu --elfFile bin/app_eth.elf #please replace the "bin/app_eth.apdu" with your app path

python3 -m ledgerblue.runScript --scp --fileName bin/app_wan.apdu --elfFile bin/app_wan.elf