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
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
.
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.
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
You can quickly setup a convenient environment to build and test your application by using Ledger's VSCode developer tools extension which leverages the ledger-app-dev-tools docker image.
It will allow you, whether you are developing on macOS, Windows or Linux, to quickly build your apps, test them on Speculos and load them on any supported device.
- Install and run Docker.
- Make sure you have an X11 server running:
- Install VScode and add Ledger's extension.
- Open a terminal and clone
app-ethereum
withgit clone git@github.com:LedgerHQ/app-ethereum.git
. - Open the
app-ethereum
folder with VSCode. - Use Ledger extension's sidebar menu or open the tasks menu with
ctrl + shift + b
(command + shift + b
on a Mac) to conveniently execute actions:- Build the app for the device model of your choice with
Build
. - Test your binary on Speculos with
Run with Speculos
. - You can also run functional tests, load the app on a physical device, and more.
- Build the app for the device model of your choice with
The terminal tab of VSCode will show you what commands the extension runs behind the scene.
The ledger-app-dev-tools docker image contains all the required tools and libraries to build, test and load an application.
You can download it from the ghcr.io docker repository:
sudo docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest
You can then enter this development environment by executing the following command
from the root directory of the application git
repository:
sudo docker run --rm -ti --user "$(id -u):$(id -g)" --privileged -v "/dev/bus/usb:/dev/bus/usb" -v "$(realpath .):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest
sudo docker run --rm -ti --user "$(id -u):$(id -g)" --privileged -v "$(pwd -P):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest
docker run --rm -ti --privileged -v "$(Get-Location):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest
The application's code will be available from inside the docker container, you can proceed to the following compilation steps to build your app.
To easily setup a development environment for compilation and loading on a physical device, you can use the VSCode integration whether you are on Linux, macOS or Windows.
If you prefer using a terminal to perform the steps manually, you can use the guide below.
Setup a compilation environment by following the shell with docker approach.
Be sure you checkout the submodule:
git submodule update --init
From inside the container, use the following command to build the app:
make DEBUG=1 # compile optionally with PRINTF
You can choose which device to compile and load for by setting the BOLOS_SDK
environment variable to the following values:
BOLOS_SDK=$NANOS_SDK
BOLOS_SDK=$NANOX_SDK
BOLOS_SDK=$NANOSP_SDK
BOLOS_SDK=$STAX_SDK
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).
First make sure you have the proper udev rules added on your host. See udev-rules
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.
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.apdu --elfFile bin/app.elf
The Ethereum app comes with different tests:
- Functional Tests implemented with Ledger's Ragger test framework.
- Unit Tests, allowing to test basic simple functions
On Linux, you can use Ledger's VS Code extension to run the tests. If you prefer not to, open a terminal and follow the steps below.
Install the tests requirements:
pip install -r tests/ragger/requirements.txt
Then you can:
Run the functional tests (here for nanos but available for any device once you have built the binaries):
pytest tests/ragger/ --tb=short -v --device nanos
Please see the corresponding ducomentation USAGE
Or run your app directly with Speculos
speculos --model nanos build/nanos/bin/app.elf
To test your app on macOS or Windows, it is recommended to use Ledger's VS Code extension to quickly setup a working test environment.
You can use the following sequence of tasks and commands (all accessible in the extension sidebar menu):
Select build target
Build app
Then you can choose to execute the functional tests:
- Use
Run tests
.
Or simply run the app on the Speculos emulator:
Run with Speculos
.
Those tests are available in the directory tests/unit
. Please see the corresponding README
to compile and run them.
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
.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/my-feature
) - Commit your Changes (
git commit -m 'feat: my new feature
) - Push to the Branch (
git push origin feature/my-feature
) - Open a Pull Request
Please try to follow Conventional Commits.