@ledgerhq/device-signer-kit-ethereum 1.1.0 → 1.3.0

package/README.md

@@ -1,6 +1,4 @@
-# Ledger Ethereum Signer Implementation
-
-## Introduction
+# Ledger Ethereum Signer
 
 This module provides the implementation of the Ledger Ethereum signer of the Device Management Kit. It enables interaction with the Ethereum application on a Ledger device including:
 
@@ -9,11 +7,24 @@ This module provides the implementation of the Ledger Ethereum signer of the Dev
 - Signing a message displayed on a Ledger device;
 - Signing an [EIP-712](https://eips.ethereum.org/EIPS/eip-712) specified message.
 
-### How it works
+## 🔹 Index
+
+1. [How it works](#-how-it-works)
+2. [Installation](#-installation)
+3. [Initialisation](#-initialisation)
+4. [Use Cases](#-use-cases)
+   - [Get Address](#use-case-1-get-address)
+   - [Sign Transaction](#use-case-2-sign-transaction)
+   - [Sign Message](#use-case-3-sign-message)
+   - [Sign Typed Data](#use-case-4-sign-typed-data)
+5. [Observable Behavior](#-observable-behavior)
+6. [Example](#-example)
+
+## 🔹 How it works
 
 The Ledger Ethereum Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations, including signing transactions. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.
 
-### Installation
+## 🔹 Installation
 
 > **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.
 
@@ -23,31 +34,31 @@ To install the `device-signer-kit-ethereum` package, run the following command:
 npm install @ledgerhq/device-signer-kit-ethereum
 ```
 
-## Usage
-
-### Setting up
+## 🔹 Initialisation
 
-To initialize an Ethereum signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerEthBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:
+To initialise an Ethereum signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerEthBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:
 
 ```typescript
-// Initialize an Ethereum signer instance using default context module
+// Initialise an Ethereum signer instance using default context module
 const signerEth = new SignerEthBuilder({ sdk, sessionId }).build();
 ```
 
 You can also configure the context module yourself:
 
 ```typescript
-// Initialize an Ethereum signer instance using customized context module
+// Initialise an Ethereum signer instance using customized context module
 const signerEth = new SignerEthBuilder({ sdk, sessionId })
   .withContextModule(customContextModule)
   .build();
 ```
 
-### Use Cases
+## 🔹 Use Cases
 
 The `SignerEthBuilder.build()` method will return a `SignerEth` instance that exposes 4 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.
 
-#### Use Case 1: Get Address
+---
+
+### Use Case 1: Get Address
 
 This method allows users to retrieve the Ethereum address according to given `derivationPath`.
 
@@ -55,7 +66,7 @@ This method allows users to retrieve the Ethereum address according to given `de
 const { observable, cancel } = signerEth.getAddress(derivationPath, options);
 ```
 
-**Parameters**
+#### **Parameters**
 
 - `derivationPath`
 
@@ -78,104 +89,23 @@ const { observable, cancel } = signerEth.getAddress(derivationPath, options);
   - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).
   - `returnChainCode`: An optional boolean indicating whether the chain code should be returned (`true`) or not (`false`).
 
-**Returns**
-
-- `observable`
-
-  - An [Observable](https://rxjs.dev/guide/observable) object that contains the [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts) derived instance, which reprensents the operation's state. For example:
-
-    ```typescript
-    observable.subscribe({
-      next: (state: DeviceActionState) => {
-        switch (state.status) {
-          case DeviceActionStatus.NotStarted: {
-            console.log("The action is not started yet.");
-            break;
-          }
-          case DeviceActionStatus.Pending: {
-            const {
-              intermediateValue: { requiredUserInteraction },
-            } = state;
-            // Access the intermediate value here, explained below
-            console.log(
-              "The action is pending and the intermediate value is: ",
-              intermediateValue,
-            );
-            break;
-          }
-          case DeviceActionStatus.Stopped: {
-            console.log("The action has been stopped.");
-            break;
-          }
-          case DeviceActionStatus.Completed: {
-            const { output } = state;
-            // Access the output of the completed action here
-            console.log("The action has been completed: ", output);
-            break;
-          }
-          case DeviceActionStatus.Error: {
-            const { error } = state;
-            // Access the error here if occured
-            console.log("An error occured during the action: ", error);
-            break;
-          }
-        }
-      },
-    });
-    ```
-
-  - When the action status is `DeviceActionStatus.Pending`, the state will include an `intermediateValue` object that provides useful information for interaction:
-
-    ```typescript
-    const { requiredUserInteraction } = intermediateValue;
+#### **Returns**
 
-    switch (requiredUserInteraction) {
-      case UserInteractionRequired.VerifyAddress: {
-        // User needs to verify the address displayed on the device
-        console.log(
-          "User needs to verify the address displayed on the device.",
-        );
-        break;
-      }
-      case UserInteractionRequired.None: {
-        // No user action required
-        console.log("No user action needed.");
-        break;
-      }
-      case UserInteractionRequired.UnlockDevice: {
-        // User needs to unlock the device
-        console.log("The user needs to unlock the device.");
-        break;
-      }
-      case UserInteractionRequired.ConfirmOpenApp: {
-        // User needs to confirm on the device to open the app
-        console.log("The user needs to confirm on the device to open the app.");
-        break;
-      }
-      default:
-        // Type guard to ensure all cases are handled
-        const uncaughtUserInteraction: never = requiredUserInteraction;
-        console.error(
-          "Unhandled user interaction case:",
-          uncaughtUserInteraction,
-        );
-    }
-    ```
+- `observable` Emits DeviceActionState updates, including the following details:
 
-  - When the action status is `DeviceActionStatus.Completed`, the execution result can be accessed through the `output` property in the state. The `output` property is of type `GetAddressCommandResponse`, which has the following structure:
+```typescript
+type GetAddressCommandResponse = {
+  publicKey: string; // Public key derived from the given path
+  address: `0x${string}`; // Ethereum address in hex format
+  chainCode?: string; // Optional chain code
+};
+```
 
-    ```typescript
-    type GetAddressCommandResponse = {
-      publicKey: string;
-      address: `0x${string}`;
-      chainCode?: string;
-    };
-    ```
+- `cancel` A function to cancel the action on the Ledger device.
 
-- `cancel`
-  - The function without a return value to cancel the action on the Ledger device.
+---
 
-#### Use Case 2: Sign Transaction
+### Use Case 2: Sign Transaction
 
 This method enables users to securely sign transactions using clear signing on Ledger devices.
 
@@ -187,7 +117,7 @@ const { observable, cancel } = signerEth.signTransaction(
 );
 ```
 
-**Parameters**
+#### **Parameters**
 
 - `derivationPath`
 
@@ -198,8 +128,8 @@ const { observable, cancel } = signerEth.signTransaction(
 - `transaction`
 
   - **Required**
-  - **Type:**`Transaction` (compatible with [ethers v5](https://docs.ethers.org/v5/) or [ethers v6](https://docs.ethers.org/v6/))
-  - The transaction object that needs to be signed.
+  - **Type:**`Uint8Array`
+  - The transaction buffer that needs to be signed.
 
 - `options`
 
@@ -214,104 +144,23 @@ const { observable, cancel } = signerEth.signTransaction(
 
   - `domain` An optional string representing the domain present in the transaction. Currently, only ENS domains are supported.
 
-**Returns**
-
-- `observable`
+#### **Returns**
 
-  - An [Observable](https://rxjs.dev/guide/observable) object that contains the [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts) derived instance which reprensents the operation's state. For example:
-
-    ```typescript
-    observable.subscribe({
-      next: (state: SignTransactionDAState) => {
-        switch (state.status) {
-          case DeviceActionStatus.NotStarted: {
-            console.log("The action is not started yet.");
-            break;
-          }
-          case DeviceActionStatus.Pending: {
-            const {
-              intermediateValue: { requiredUserInteraction },
-            } = state;
-            // Access the intermediate value here, explained below
-            console.log(
-              "The action is pending and the intermediate value is: ",
-              intermediateValue,
-            );
-            break;
-          }
-          case DeviceActionStatus.Stopped: {
-            console.log("The action has been stopped.");
-            break;
-          }
-          case DeviceActionStatus.Completed: {
-            const { output } = state;
-            // Access the output of the completed action here
-            console.log("The action has been completed: ", output);
-            break;
-          }
-          case DeviceActionStatus.Error: {
-            const { error } = state;
-            // Access the error here if occured
-            console.log("An error occured during the action: ", error);
-            break;
-          }
-        }
-      },
-    });
-    ```
-
-  - When the action status is `DeviceActionStatus.Pending`, the state will include an `intermediateValue` object that provides useful information for interaction:
-
-    ```typescript
-    const { requiredUserInteraction } = intermediateValue;
+- `observable` Emits DeviceActionState updates, including the following details:
 
-    switch (requiredUserInteraction) {
-      case UserInteractionRequired.SignTransaction: {
-        // User needs to sign the transaction displayed on the device
-        console.log(
-          "User needs to sign the transaction displayed on the device.",
-        );
-        break;
-      }
-      case UserInteractionRequired.None: {
-        // No user action required
-        console.log("No user action needed.");
-        break;
-      }
-      case UserInteractionRequired.UnlockDevice: {
-        // User needs to unlock the device
-        console.log("The user needs to unlock the device.");
-        break;
-      }
-      case UserInteractionRequired.ConfirmOpenApp: {
-        // User needs to confirm on the device to open the app
-        console.log("The user needs to confirm on the device to open the app.");
-        break;
-      }
-      default:
-        // Type guard to ensure all cases are handled
-        const uncaughtUserInteraction: never = requiredUserInteraction;
-        console.error(
-          "Unhandled user interaction case:",
-          uncaughtUserInteraction,
-        );
-    }
-    ```
-
-  - When the action status is `DeviceActionStatus.Completed`, the execution result can be accessed through the `output` property in the state. This property is a `Signature` object with the following structure:
+```typescript
+type Signature = {
+  r: `0x${string}`; // R component of the signature
+  s: `0x${string}`; // S component of the signature
+  v: number; // Recovery parameter
+};
+```
 
-    ```typescript
-    type Signature = {
-      r: `0x${string}`;
-      s: `0x${string}`;
-      v: number;
-    };
-    ```
+- `cancel` A function to cancel the action on the Ledger device.
 
-- `cancel`
-  - The function without a return value to cancel the action on the Ledger device.
+---
 
-#### Use Case 3: Sign Message
+### Use Case 3: Sign Message
 
 This method allows users to sign a text string that is displayed on Ledger devices.
 
@@ -319,7 +168,7 @@ This method allows users to sign a text string that is displayed on Ledger devic
 const { observable, cancel } = signerEth.signMessage(derivationPath, message);
 ```
 
-**Parameters**
+#### **Parameters**
 
 - `derivationPath`
 
@@ -333,102 +182,23 @@ const { observable, cancel } = signerEth.signMessage(derivationPath, message);
   - **Type:** `string`
   - The message to be signed, which will be displayed on the Ledger device.
 
-**Returns**
+#### **Returns**
 
-- `observable`
+- `observable` Emits DeviceActionState updates, including the following details:
 
-  - An [Observable](https://rxjs.dev/guide/observable) object that contains the [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts) derived instance which reprensents the operation's state. For example:
-
-    ```typescript
-    observable.subscribe({
-      next: (state: SignPersonalMessageDAState) => {
-        switch (state.status) {
-          case DeviceActionStatus.NotStarted: {
-            console.log("The action is not started yet.");
-            break;
-          }
-          case DeviceActionStatus.Pending: {
-            const {
-              intermediateValue: { requiredUserInteraction },
-            } = state;
-            // Access the intermediate value here, explained below
-            console.log(
-              "The action is pending and the intermediate value is: ",
-              intermediateValue,
-            );
-            break;
-          }
-          case DeviceActionStatus.Stopped: {
-            console.log("The action has been stopped.");
-            break;
-          }
-          case DeviceActionStatus.Completed: {
-            const { output } = state;
-            // Access the output of the completed action here
-            console.log("The action has been completed: ", output);
-            break;
-          }
-          case DeviceActionStatus.Error: {
-            const { error } = state;
-            // Access the error here if occured
-            console.log("An error occured during the action: ", error);
-            break;
-          }
-        }
-      },
-    });
-    ```
-
-  - When the action status is `DeviceActionStatus.Pending`, the state will include an `intermediateValue` object that provides useful information for interaction:
-
-    ```typescript
-    const { requiredUserInteraction } = intermediateValue;
-
-    switch (requiredUserInteraction) {
-      case UserInteractionRequired.SignPersonalMessage: {
-        // User needs to sign the message displayed on the device
-        console.log("User needs to sign the message displayed on the device.");
-        break;
-      }
-      case UserInteractionRequired.None: {
-        // No user action required
-        console.log("No user action needed.");
-        break;
-      }
-      case UserInteractionRequired.UnlockDevice: {
-        // User needs to unlock the device
-        console.log("The user needs to unlock the device.");
-        break;
-      }
-      case UserInteractionRequired.ConfirmOpenApp: {
-        // User needs to confirm on the device to open the app
-        console.log("The user needs to confirm on the device to open the app.");
-        break;
-      }
-      default:
-        // Type guard to ensure all cases are handled
-        const uncaughtUserInteraction: never = requiredUserInteraction;
-        console.error(
-          "Unhandled user interaction case:",
-          uncaughtUserInteraction,
-        );
-    }
-    ```
-
-  - When the action status is `DeviceActionStatus.Completed`, the execution result can be accessed through the `output` property in the state. This property is a `Signature` object with the following structure:
+```typescript
+type Signature = {
+  r: `0x${string}`; // R component of the signature
+  s: `0x${string}`; // S component of the signature
+  v: number; // Recovery parameter
+};
+```
 
-    ```typescript
-    type Signature = {
-      r: `0x${string}`;
-      s: `0x${string}`;
-      v: number;
-    };
-    ```
+- `cancel` A function to cancel the action on the Ledger device.
 
-- `cancel`
-  - The function without a return value to cancel the action on the Ledger device.
+---
 
-#### Use Case 4: Sign TypedData
+### Use Case 4: Sign Typed Data
 
 This method enables users to sign an Ethereum message following the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) specification.
 
@@ -439,7 +209,7 @@ const { observable, cancel } = signerEth.signTypedData(
 );
 ```
 
-**Parameters**
+#### **Parameters**
 
 - `derivationPath`
 
@@ -476,101 +246,122 @@ const { observable, cancel } = signerEth.signTypedData(
 
   - The typed data as defined at [EIP-712](https://eips.ethereum.org/EIPS/eip-712).
 
-**Returns**
+#### **Returns**
 
-- `observable`
+- `observable` Emits DeviceActionState updates, including the following details:
 
-  - An [Observable](https://rxjs.dev/guide/observable) object that contains the [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts) derived instance which reprensents the operation's state. For example:
+```typescript
+type Signature = {
+  r: `0x${string}`; // R component of the signature
+  s: `0x${string}`; // S component of the signature
+  v: number; // Recovery parameter
+};
+```
 
-    ```typescript
-    observable.subscribe({
-      next: (state: SignTypedDataDAState) => {
-        switch (state.status) {
-          case DeviceActionStatus.NotStarted: {
-            console.log("The action is not started yet.");
-            break;
-          }
-          case DeviceActionStatus.Pending: {
-            const { intermediateValue } = state;
-            // Access the intermediate value here, explained below
-            console.log(
-              "The action is pending and the intermediate value is: ",
-              requiredUserInteraction,
-            );
-            break;
-          }
-          case DeviceActionStatus.Stopped: {
-            console.log("The action has been stopped.");
-            break;
-          }
-          case DeviceActionStatus.Completed: {
-            const { output } = state;
-            // Access the output of the completed action here, explained below
-            console.log("The action has been completed: ", output);
-            break;
-          }
-          case DeviceActionStatus.Error: {
-            const { error } = state;
-            // Access the error here if occured
-            console.log("An error occured during the action: ", error);
-            break;
-          }
-        }
-      },
-    });
-    ```
+- `cancel` A function to cancel the action on the Ledger device.
 
-  - When the action status is `DeviceActionStatus.Pending`, the state will include an `intermediateValue` object that provides useful information for interaction:
+## 🔹 Observable Behavior
 
-    ```typescript
-    const { requiredUserInteraction } = intermediateValue;
+Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation’s progress and status:
+
+- **NotStarted**: The operation hasn’t started.
+- **Pending**: The operation is in progress and may require user interaction.
+- **Stopped**: The operation was canceled or stopped.
+- **Completed**: The operation completed successfully, with results available.
+- **Error**: An error occurred.
 
-    switch (requiredUserInteraction) {
-      case UserInteractionRequired.SignTypedData: {
-        // User needs to sign the typed data displayed on the device
+**Example Observable Subscription:**
+
+```typescript
+observable.subscribe({
+  next: (state: DeviceActionState) => {
+    switch (state.status) {
+      case DeviceActionStatus.NotStarted: {
+        console.log("The action is not started yet.");
+        break;
+      }
+      case DeviceActionStatus.Pending: {
+        const {
+          intermediateValue: { requiredUserInteraction },
+        } = state;
+        // Access the intermediate value here, explained below
         console.log(
-          "User needs to sign the typed data displayed on the device.",
+          "The action is pending and the intermediate value is: ",
+          intermediateValue,
         );
         break;
       }
-      case UserInteractionRequired.None: {
-        // No user action required
-        console.log("No user action needed.");
+      case DeviceActionStatus.Stopped: {
+        console.log("The action has been stopped.");
         break;
       }
-      case UserInteractionRequired.UnlockDevice: {
-        // User needs to unlock the device
-        console.log("The user needs to unlock the device.");
+      case DeviceActionStatus.Completed: {
+        const { output } = state;
+        // Access the output of the completed action here
+        console.log("The action has been completed: ", output);
         break;
       }
-      case UserInteractionRequired.ConfirmOpenApp: {
-        // User needs to confirm on the device to open the app
-        console.log("The user needs to confirm on the device to open the app.");
+      case DeviceActionStatus.Error: {
+        const { error } = state;
+        // Access the error here if occurred
+        console.log("An error occurred during the action: ", error);
         break;
       }
-      default:
-        // Type guard to ensure all cases are handled
-        const uncaughtUserInteraction: never = requiredUserInteraction;
-        console.error(
-          "Unhandled user interaction case:",
-          uncaughtUserInteraction,
-        );
     }
-    ```
+  },
+});
+```
 
-  - When the action status is `DeviceActionStatus.Completed`, the execution result can be accessed through the `output` property in the state. This property is a `Signature` object with the following structure:
+**Intermediate Values in Pending Status:**
 
-    ```typescript
-    type Signature = {
-      r: `0x${string}`;
-      s: `0x${string}`;
-      v: number;
-    };
-    ```
+When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:
 
-- `cancel`
-  - The function without a return value to cancel the action on the Ledger device.
+```typescript
+const { requiredUserInteraction } = intermediateValue;
+
+switch (requiredUserInteraction) {
+  case UserInteractionRequired.SignPersonalMessage: {
+    // User needs to sign the message displayed on the device
+    console.log("User needs to sign the message displayed on the device.");
+    break;
+  }
+  case UserInteractionRequired.SignTypedData: {
+    // User needs to sign the typed data displayed on the device
+    console.log("User needs to sign the typed data displayed on the device.");
+    break;
+  }
+  case UserInteractionRequired.SignTransaction: {
+    // User needs to sign the transaction displayed on the device
+    console.log("User needs to sign the transaction displayed on the device.");
+    break;
+  }
+  case UserInteractionRequired.VerifyAddress: {
+    // User needs to verify the address displayed on the device
+    console.log("User needs to verify the address displayed on the device.");
+    break;
+  }
+  case UserInteractionRequired.None: {
+    // No user action required
+    console.log("No user action needed.");
+    break;
+  }
+  case UserInteractionRequired.UnlockDevice: {
+    // User needs to unlock the device
+    console.log("The user needs to unlock the device.");
+    break;
+  }
+  case UserInteractionRequired.ConfirmOpenApp: {
+    // User needs to confirm on the device to open the app
+    console.log("The user needs to confirm on the device to open the app.");
+    break;
+  }
+  default:
+    // Type guard to ensure all cases are handled
+    const uncaughtUserInteraction: never = requiredUserInteraction;
+    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
+}
+```
 
-## Example
+## 🔹 Example
 
 We encourage you to explore the Ethereum Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

package/lib/cjs/api/SignerEth.js

@@ -1,2 +1,2 @@
-"use strict";var i=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var o=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var y=(e,t,a,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of o(t))!p.call(e,n)&&n!==a&&i(e,n,{get:()=>t[n],enumerable:!(r=s(t,n))||r.enumerable});return e};var d=e=>y(i({},"__esModule",{value:!0}),e);var g={};module.exports=d(g);
+"use strict";var i=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var o=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var y=(e,t,a,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of o(t))!p.call(e,r)&&r!==a&&i(e,r,{get:()=>t[r],enumerable:!(n=s(t,r))||n.enumerable});return e};var d=e=>y(i({},"__esModule",{value:!0}),e);var g={};module.exports=d(g);
 //# sourceMappingURL=SignerEth.js.map