Skip to content

Commit

Permalink
README: enforcing 80 characters limits for readibility
Browse files Browse the repository at this point in the history
  • Loading branch information
dannywillems committed Dec 20, 2024
1 parent a2f2e10 commit 400d08d
Showing 1 changed file with 64 additions and 25 deletions.
89 changes: 64 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,70 @@
# ledger-app-mina

## Overview

This is the Mina app for the Ledger Nano S and Nano X hardware wallet.

## Building and installing
To build and install the app on your Ledger Nano you must set up the Ledger Nano build environments. Please follow the Getting Started instructions at [here](https://ledger.readthedocs.io/en/latest/userspace/getting_started.html).

To build and install the app on your Ledger Nano you must set up the Ledger Nano
build environments. Please follow the Getting Started instructions at
[here](https://ledger.readthedocs.io/en/latest/userspace/getting_started.html).

### With a terminal

The [ledger-app-dev-tools](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-app-dev-tools) docker image contains all the required tools and libraries to **build**, **test** and **load** an application.
The
[ledger-app-dev-tools](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-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:

```shell
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 directory of the application `git` repository:
You can then enter this development environment by executing the following
command from the directory of the application `git` repository:

**Linux (Ubuntu)**

```shell
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 "/dev/bus/usb:/dev/bus/usb" \
-v "$(realpath .):/app" \
ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest
```

**macOS**

```shell
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
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
```

**Windows (with PowerShell)**

```shell
docker run --rm -ti --privileged -v "$(Get-Location):/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.
The application's code will be available from inside the docker container, you
can proceed to the following compilation steps to build your app.

## Compilation and load

To easily setup a development environment for compilation and loading on a physical device, you can use the [VSCode integration](#with-vscode) whether you are on Linux, macOS or Windows.
To easily setup a development environment for compilation and loading on a
physical device, you can use the [VSCode integration](#with-vscode) 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.
If you prefer using a terminal to perform the steps manually, you can use the
guide below.

### Compilation

Expand All @@ -54,7 +76,8 @@ 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 :
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`
Expand All @@ -68,37 +91,43 @@ By default this variable is set to build/load for Nano S.

This step will vary slightly depending on your platform.

:information_source: Your physical device must be connected, unlocked and the screen showing the dashboard (not inside an application).
:information_source: 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 :
First make sure you have the proper udev rules added on your host:

```shell
# 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 control --reload-rules
sudo udevadm trigger
```

Then once you have [opened a terminal](#with-a-terminal) in the `app-builder` image and [built the app](#compilation-and-load) for the device you want, run the following command :
Then once you have [opened a terminal](#with-a-terminal) in the `app-builder`
image and [built the app](#compilation-and-load) for the device you want, run
the following command:

```shell
# 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](#compilation-and-load) will allow you to load on whichever supported device you want.
[Setting the BOLOS_SDK environment variable](#compilation-and-load) will allow
you to load on whichever supported device you want.

**macOS / Windows (with PowerShell)**

:information_source: It is assumed you have [Python](https://www.python.org/downloads/) installed on your computer.
:information_source: It is assumed you have
[Python](https://www.python.org/downloads/) installed on your computer.

Run these commands on your host from the app's source folder once you have [built the app](#compilation-and-load) for the device you want :
Run these commands on your host from the app's source folder once you have
[built the app](#compilation-and-load) for the device you want:

```shell
# Install Python virtualenv
python3 -m pip install virtualenv
python3 -m pip install virtualenv
# Create the 'ledger' virtualenv
python3 -m virtualenv ledger
```
Expand All @@ -110,7 +139,7 @@ Enter the Python virtual environment

```shell
# Install Ledgerblue (tool to load the app)
python3 -m pip install ledgerblue
python3 -m pip install ledgerblue
# Load the app.
python3 -m ledgerblue.runScript --scp --fileName bin/app.apdu --elfFile bin/app.elf
`````
Expand All @@ -124,7 +153,7 @@ The Mina app comes with functional tests implemented with Ledger's [Ragger](http
Install the tests requirements :
```shell
pip install -r tests/requirements.txt
pip install -r tests/requirements.txt
```
Then you can :
Expand Down Expand Up @@ -177,7 +206,9 @@ Continue? (y/N) y
Generating address (please confirm on Ledger device)... done
Received address: B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt
```
This generates the keypair corresponding to hardware wallet account 1 (BIP44 account `44'/12586'/1'/0/0`) and returns the corresponding Mina address.

This generates the keypair corresponding to hardware wallet account 1 (BIP44
account `44'/12586'/1'/0/0`) and returns the corresponding Mina address.

**Get balance**

Expand All @@ -189,23 +220,31 @@ Getting account balance... done
Address: B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt
Balance: 9792.0
```
This queries the Mina blockchain for the balance of address `B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`.

This queries the Mina blockchain for the balance of address
`B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`.

**Send payment**

```bash
$ ./utils/mina_ledger_wallet.py send-payment 1 B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g 2.71821
```

This sends a payment of 2.71821 Mina from hardware wallet account 1 (`B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`) to recipient `B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g`.
This sends a payment of 2.71821 Mina from hardware wallet account 1
(`B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`) to recipient
`B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g`.

**Delegate**

```bash
$ ./utils/mina_ledger_wallet.py delegate 1 B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g --memo "Delegation is fun!"
```

This delegates the entire balance of hardware wallet account 1 (`B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`) to delegate `B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g`.
This delegates the entire balance of hardware wallet account 1
(`B62qicipYxyEHu7QjUqS7QvBipTs5CzgkYZZZkPoKVYBu6tnDUcE9Zt`) to delegate
`B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g`.

## Documentation
This follows the specification available in the [`api.asc`](https://github.com/LedgerHQ/ledger-app-boilerplate/blob/master/doc/api.asc).

This follows the specification available in the
[`api.asc`](https://github.com/LedgerHQ/ledger-app-boilerplate/blob/master/doc/api.asc).

0 comments on commit 400d08d

Please sign in to comment.