Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: enforcing 80 characters limits for readibility #25

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

README: enforcing 80 characters limits for readibility #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 64 additions & 25 deletions README.md
View file
Open in desktop
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).
31 changes: 22 additions & 9 deletions doc/api.asc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@ boilerplate application : Common Technical Specifications

## About

This application describes the APDU messages interface to communicate with the boilerplate application.
This application describes the APDU messages interface to communicate with the
boilerplate application.

The application covers the following functionalities :

Expand Down Expand Up @@ -87,7 +88,9 @@ The address can be optionally checked on the device before being returned.

### General transport description

Ledger APDUs requests and responses are encapsulated using a flexible protocol allowing to fragment large payloads over different underlying transport mechanisms.
Ledger APDUs requests and responses are encapsulated using a flexible protocol
allowing to fragment large payloads over different underlying transport
mechanisms.

The common transport header is defined as follows :

Expand All @@ -100,11 +103,15 @@ The common transport header is defined as follows :
| Payload | var
|==============================================================================================================================

The Communication channel ID allows commands multiplexing over the same physical link. It is not used for the time being, and should be set to 0101 to avoid compatibility issues with implementations ignoring a leading 00 byte.
The Communication channel ID allows commands multiplexing over the same
physical link. It is not used for the time being, and should be set to 0101 to
avoid compatibility issues with implementations ignoring a leading 00 byte.

The Command tag describes the message content. Use TAG_APDU (0x05) for standard APDU payloads, or TAG_PING (0x02) for a simple link test.
The Command tag describes the message content. Use TAG_APDU (0x05) for standard
APDU payloads, or TAG_PING (0x02) for a simple link test.

The Packet sequence index describes the current sequence for fragmented payloads. The first fragment index is 0x00.
The Packet sequence index describes the current sequence for fragmented
payloads. The first fragment index is 0x00.

### APDU Command payload encoding

Expand Down Expand Up @@ -146,21 +153,27 @@ APDU Response payloads are encoded as follows :

### USB mapping

Messages are exchanged with the dongle over HID endpoints over interrupt transfers, with each chunk being 64 bytes long. The HID Report ID is ignored.
Messages are exchanged with the dongle over HID endpoints over interrupt
transfers, with each chunk being 64 bytes long. The HID Report ID is ignored.

### BLE mapping

A similar encoding is used over BLE, without the Communication channel ID.

The application acts as a GATT server defining service UUID D973F2E0-B19E-11E2-9E96-0800200C9A66
The application acts as a GATT server defining service UUID
D973F2E0-B19E-11E2-9E96-0800200C9A66

When using this service, the client sends requests to the characteristic D973F2E2-B19E-11E2-9E96-0800200C9A66, and gets notified on the characteristic D973F2E1-B19E-11E2-9E96-0800200C9A66 after registering for it.
When using this service, the client sends requests to the characteristic
D973F2E2-B19E-11E2-9E96-0800200C9A66, and gets notified on the characteristic
D973F2E1-B19E-11E2-9E96-0800200C9A66 after registering for it.

Requests are encoded using the standard BLE 20 bytes MTU size

## Status Words

The following standard Status Words are returned for all APDUs - some specific Status Words can be used for specific commands and are mentioned in the command description.
The following standard Status Words are returned for all APDUs - some specific
Status Words can be used for specific commands and are mentioned in the command
description.

'Status Words'

Expand Down