From bf02455ab7b11ffba929d9399fbeec646abffaa6 Mon Sep 17 00:00:00 2001 From: Charles-Edouard de la Vergne Date: Tue, 26 Sep 2023 17:21:13 +0200 Subject: [PATCH] Fix doc formatting and rendering --- README.md | 95 +++++++++++++++++++++++++++++++------------------- doc/xrpapp.asc | 33 +++++++++--------- 2 files changed, 77 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 430cf139..327c1e77 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,55 @@ -# XRP Wallet App for Ledger Nano S and Ledger Nano X +# XRP Wallet App for Ledger devices + +[![Ensure compliance with Ledger guidelines](https://github.com/LedgerHQ/app-flow/actions/workflows/guidelines_enforcer.yml/badge.svg)](https://github.com/LedgerHQ/app-flow/actions/workflows/guidelines_enforcer.yml) + +[![Build and run functional tests using ragger through reusable workflow](https://github.com/LedgerHQ/app-flow/actions/workflows/build_and_functional_tests.yml/badge.svg)](https://github.com/LedgerHQ/app-flow/actions/workflows/build_and_functional_tests.yml) ## Introduction -This repository contains the source code for the XRP wallet app that makes it possible to securely store XRP and assets issued on the XRP Ledger using Ledger Nano S and Ledger Nano X devices. + +This repository contains the source code for the XRP wallet app +that makes it possible to securely store XRP and assets issued +on the XRP Ledger using Ledger Nano devices. To add Ledger Nano S and Ledger Nano X support in your application, please see the NPM package [hw-app-xrp](https://www.npmjs.com/package/@ledgerhq/hw-app-xrp) -and the examples below. +and the examples below. ## Features + The XRP wallet app comes with the following features: - - Support for all transaction types: - - AccountSet - - AccountDelete - - CheckCancel - - CheckCash - - CheckCreate - - DepositPreauth - - EscrowCancel - - EscrowCreate - - EscrowFinish - - OfferCancel - - OfferCreate - - Payment - - PaymentChannelClaim - - PaymentChannelCreate - - PaymentChannelFund - - SetRegularKey - - SignerListSet - - TrustSet - - Support for all transaction common fields such as memos - - Support for issued assets such as SOLO, stocks and ETFs - - Support for signing on behalf of others - - Support for multi-signing - - Unified UI across Ledger Nano S and Ledger Nano X +- Support for all transaction types: + - AccountSet + - AccountDelete + - CheckCancel + - CheckCash + - CheckCreate + - DepositPreauth + - EscrowCancel + - EscrowCreate + - EscrowFinish + - OfferCancel + - OfferCreate + - Payment + - PaymentChannelClaim + - PaymentChannelCreate + - PaymentChannelFund + - SetRegularKey + - SignerListSet + - TrustSet +- Support for all transaction common fields such as memos +- Support for issued assets such as SOLO, stocks and ETFs +- Support for signing on behalf of others +- Support for multi-signing +- Unified UI across Ledger Nano devices ## User Interface + The user interface primarily consists of the idle menu and the transaction review menu. ### Idle Menu + Upon starting the app on your device you are immediately greeted by the idle menu. This menu, as the name implies, is used when the device is in its idle state. At this point, an external application may initiate a @@ -48,6 +58,7 @@ transaction, which opens up the review menu. ![Idle menu](img/idle-menu.png) ### Review Menu + When reviewing a transaction the entire UI is dedicated to displaying the transaction details. You can page through all the details by using the left and right buttons on your device, as indicated by arrows on the screen. @@ -64,17 +75,20 @@ that path. See example below. ![Path field in review menu](img/review-path.png) -In order to take action on the transaction, you must first page through and review all transaction details. The last two items in the review menu are 'Sign transaction' and 'Reject'. +In order to take action on the transaction, you must first page through and review all transaction details. +The last two items in the review menu are 'Sign transaction' and 'Reject'. ![Approval menu](img/approval-menu.png) Page to either 'Sign transaction' or 'Reject' and press both buttons simultaneously to confirm your action. ## Usage + In order to initiate transactions from NodeJS or a browser client, the library [hw-app-xrp](https://www.npmjs.com/package/@ledgerhq/hw-app-xrp) can be used. An example of a basic payment transaction using this library is shown below: + ```javascript import Transport from "@ledgerhq/hw-transport-node-hid"; // import Transport from "@ledgerhq/hw-transport-u2f"; // for browser @@ -126,11 +140,13 @@ establishConnection() ``` ### Advanced Usage + #### Multi-signing a Transaction -It is also possible to perform parallel multi-signing using the XRP wallet + +It is also possible to perform parallel multi-signing using the XRP wallet app. This is done by sourcing a list of signatures for the transaction -and appending them to the `Signers` field of the transaction before submitting -it for processing. An example of combining a couple of externally sourced signatures +and appending them to the `Signers` field of the transaction before submitting +it for processing. An example of combining a couple of externally sourced signatures with a signature of the Ledger device is shown below (uses imports and functions declared in previous example). ```javascript @@ -196,9 +212,10 @@ retrieveSignerData(transactionJSON) ``` ### Additional Notes + From version 2.0.0 of the XRP wallet app it is possible to sign larger -transactions than in previous versions. In order to enable support for larger transactions -there have been slight modifications to the transport protocol, which is used to +transactions than in previous versions. In order to enable support for larger transactions, +there have been slight modifications to the transport protocol, which is used to communicate between the client and the device. The protocol changes are fully backwards-compatible with previous versions of @@ -206,10 +223,12 @@ The protocol changes are fully backwards-compatible with previous versions of to sign larger transactions you must use version 5.12.0 or above of [hw-app-xrp](https://www.npmjs.com/package/@ledgerhq/hw-app-xrp). ### Limitations + Because of resource constraints the following limits apply for the respective hardware wallet: #### Ledger Nano S + - Maximum fields per transaction: 24 fields - Maximum displayed field value length: 128 characters - Maximum transaction size: 800 bytes @@ -217,6 +236,7 @@ hardware wallet: - Multi-sign support: Parallel only #### Ledger Nano X + - Maximum fields per transaction: 60 fields - Maximum displayed field value length: 1024 characters - Maximum transaction size: 10 000 bytes @@ -224,21 +244,26 @@ hardware wallet: - Multi-sign support: Parallel only ## Building + Make sure that you have configured a development environment as outlined in [the development documentation](https://ledger.readthedocs.io/en/latest/userspace/getting_started.html) -for Ledger devices. Then run make from the repository root to build the app: +for Ledger devices. Then run make from the repository root to build the app: + ```sh make ``` ## Installing + To upload the app to your device, run the following command: + ```sh make load ``` ## Testing -Manual testing can be conducted with the help of the testing utility + +Manual testing can be conducted with the help of the testing utility [TowoLabs/ledger-tests-xrp](https://github.com/TowoLabs/ledger-tests-xrp). Make sure that your device is running the latest firmware and then follow the instructions in the test repository. diff --git a/doc/xrpapp.asc b/doc/xrpapp.asc index 77c28eb9..3e7f4887 100644 --- a/doc/xrpapp.asc +++ b/doc/xrpapp.asc @@ -1,4 +1,4 @@ -XRP application : Common Technical Specifications +XRP application : Common Technical Specifications ======================================================= Ledger Firmware Team Application version 2.0 - January 2020 @@ -6,6 +6,7 @@ Application version 2.0 - January 2020 Copyright (c) 2020 Towo Labs == 2.0 + - Support for all transaction types: - AccountSet - AccountDelete @@ -31,14 +32,14 @@ Copyright (c) 2020 Towo Labs - Support for multi-signing - Unified UI across Ledger Nano S and Ledger Nano X -== 1.0 +== 1.0 - Initial release == About -This application describes the APDU messages interface to communicate with the XRP application. +This application describes the APDU messages interface to communicate with the XRP application. -The application covers the following functionalities, either on secp256k1 or ed25519 : +The application covers the following functionalities, either on secp256k1 or ed25519 : - Retrieve a public XRP address given a BIP 32 path - Sign a basic XRP Payment transaction given a BIP 32 path @@ -62,7 +63,7 @@ The address can be optionally checked on the device before being returned. [width="80%"] |============================================================================================================================== -| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* +| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* | E0 | 02 | 00 : return address 01 : display address and confirm before returning @@ -114,7 +115,7 @@ The input data is the serialized according to XRP internal serialization protoco [width="80%"] |============================================================================================================================== -| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* +| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* | E0 | 04 | 00 : first and only transaction data block 01 : last transaction data block @@ -122,7 +123,7 @@ The input data is the serialized according to XRP internal serialization protoco 80 : first of many transaction data blocks 81 : intermediate transaction data block (neither first nor last) - | + | 40 : use secp256k1 curve (bitmask) 80 : use ed25519 curve (bitmask) | variable | variable @@ -155,7 +156,7 @@ The input data is the serialized according to XRP internal serialization protoco |============================================================================================================================== | *Description* | *Length* | DER encoded signature (secp256k1) or EDDSA signature (ed25519) | variable -|====================================================================================================== +|============================================================================================================================== === GET APP CONFIGURATION @@ -169,7 +170,7 @@ This command returns specific application configuration [width="80%"] |============================================================================================================================== -| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* +| *CLA* | *INS* | *P1* | *P2* | *Lc* | *Le* | E0 | 06 | 00 | 00 | 00 | 04 |============================================================================================================================== @@ -182,8 +183,8 @@ None [width="80%"] |============================================================================================================================== | *Description* | *Length* -| Flags - +| Flags + RFU | 01 @@ -197,9 +198,9 @@ None === 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 : +The common transport header is defined as follows : [width="80%"] |============================================================================================================================== @@ -232,7 +233,7 @@ APDU Command payloads are encoded as follows : | Optional APDU data | var |============================================================================================================================== -APDU payload is encoded according to the APDU case +APDU payload is encoded according to the APDU case [width="80%"] |======================================================================================= @@ -264,11 +265,11 @@ 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 -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 +== 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.