From 48e03baa12c212199bb3ffab751292db5fec9888 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 20 Dec 2024 12:29:25 +0100 Subject: [PATCH] README: enforcing 80 characters limits for readibility --- README.md | 89 ++++++++++++++++++++++++++++++++++++++--------------- doc/api.asc | 31 +++++++++++++------ 2 files changed, 86 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index e3ded2f8..fdcad3a3 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,21 @@ # 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: @@ -16,33 +23,48 @@ 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 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 @@ -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` @@ -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 ``` @@ -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 ````` @@ -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 : @@ -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** @@ -189,7 +220,9 @@ 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** @@ -197,7 +230,9 @@ This queries the Mina blockchain for the balance of address `B62qicipYxyEHu7QjUq $ ./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** @@ -205,7 +240,11 @@ This sends a payment of 2.71821 Mina from hardware wallet account 1 (`B62qicipYx $ ./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). diff --git a/doc/api.asc b/doc/api.asc index 11f17d36..1a7bdb9d 100644 --- a/doc/api.asc +++ b/doc/api.asc @@ -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 : @@ -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 : @@ -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 @@ -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'