Merge pull request #113 from LedgerHQ/sync-discover-doc-08-01-15-04

Merging documentation from wallet-api-08-01-15-04

pages/APIs/wallet-api/_meta.json

@@ -4,5 +4,6 @@
   "core": "Core",
   "simulator": "Simulator",
   "examples": "Examples",
-  "appendix": "Appendix"
+  "appendix": "Appendix",
+  "server": "Server"
 }

pages/APIs/wallet-api/introduction.mdx

@@ -1,5 +1,6 @@
 import { Callout } from "nextra/components";
 
+
 # Welcome to the Ledger Wallet API Client documentation
 
 This library is exclusively designed to facilitate the seamless integration of decentralized applications (DApps), termed as Live Apps, within Ledger Live. It provides a streamlined way for Live Apps to communicate with Ledger hardware wallets via the Wallet API.

pages/APIs/wallet-api/server/_meta.json

@@ -0,0 +1,20 @@
+{
+  "index": {
+    "title": "Introduction",
+    "theme": {
+      "breadcrumb": false,
+      "footer": true,
+      "sidebar": true,
+      "toc": true
+    }
+  },
+  "wallet-api-server": {
+    "title": "Wallet API Server",
+    "theme": {
+      "toc": true
+    }
+  },
+  "usage-examples": "Usage examples",
+  "handlers": "Handlers",
+  "extras": "Extras"
+}

pages/APIs/wallet-api/server/extras/rpc-node.mdx

@@ -0,0 +1,63 @@
+## RPCNode
+
+**WalletAPIServer extends the abstract class RPCNode**, so let's first dig into what RPCNode is:
+
+<details>
+<summary>Class diagram overview 📝</summary>
+
+![diagram](../assets/server-rpc-node-classdiagram.png)
+
+</details>
+
+[source code](https://github.com/LedgerHQ/wallet-api/blob/main/packages/core/src/JSONRPC/RpcNode.ts)
+
+## properties
+
+- transport: allows our server to communicate with the webview
+  - receives message from webview with `transport.onMessage` being set to this.handleMessage
+  - sends message to webview with `transport.send` on error / response.
+
+## methods
+
+- requests: ignore it, used only by WalletAPIClient
+- handleMessage: forwards RPC message to handleRequest or handleResponse
+  - if handleRequest is called, it calls `onRequest` method of the WalletAPIServer
+
+### notify
+
+sends a message to the app using `this.transport.send`
+
+---
+
+## RPC Requests
+
+```js filename="packages/core/src/JSONRPC/types.ts"
+/**
+ * A rpc call is represented by sending a Request object to a Server.
+ */
+type RpcRequest<MParam = string, TParam = unknown> = {
+  /**
+   * A String specifying the version of the JSON-RPC protocol. **MUST** be exactly "2.0".
+   */
+  jsonrpc: "2.0";
+
+  /**
+   * A String containing the name of the method to be invoked.
+   */
+  method: MParam;
+
+  /**
+   * A Structured value that holds the parameter values
+   * to be used during the invocation of the method.
+   */
+  params?: TParam;
+
+  /**
+   * An identifier established by the Client that **MUST** contain a `String`, `Number`,
+   * or `NULL` value if included.
+   * If it is not included it is assumed to be a notification.
+   * The value **SHOULD** normally not be Null and Numbers **SHOULD NOT** contain fractional parts
+   */
+  id?: string | number | null;
+};
+```

pages/APIs/wallet-api/server/extras/rxjs.mdx

@@ -0,0 +1,72 @@
+# RXJS
+
+WalletAPIServer uses a bit of rxjs (version 7) to handle data coming in from ledger live.  
+You should be familiar with it (if not, start here https://www.learnrxjs.io/#brand-new-to-rxjs).
+In case you just need a refresher, you'll find below all the different rxjs operators and functions used in wallet-api-server.
+
+## map
+
+https://rxjs.dev/api/operators/map
+
+## observable
+
+https://rxjs.dev/guide/observable
+
+## BehaviorSubject
+
+https://www.learnrxjs.io/learn-rxjs/subjects/behaviorsubject
+
+> Requires an initial value and emits the current value to new subscribers
+
+```js
+// RxJS v6+
+import { BehaviorSubject } from "rxjs";
+
+const subject = new BehaviorSubject(123);
+
+// two new subscribers will get initial value => output: 123, 123
+subject.subscribe(console.log);
+subject.subscribe(console.log);
+
+// two subscribers will get new value => output: 456, 456
+subject.next(456);
+
+// new subscriber will get latest value (456) => output: 456
+subject.subscribe(console.log);
+
+// all three subscribers will get new value => output: 789, 789, 789
+subject.next(789);
+
+// output: 123, 123, 456, 456, 456, 789, 789, 789
+```
+
+## combineLatest
+
+https://www.learnrxjs.io/learn-rxjs/operators/combination/combinelatest
+
+> When any observable emits a value, emit the last emitted value from each.
+
+let's look at this function
+
+```js
+const allowedCurrencies$ = new BehaviorSubject([]);
+
+combineLatest(
+  [this.allCurrencies$, this.permissions.currencyIds$],
+  matchCurrencies
+).subscribe(allowedCurrencies$);
+```
+
+Here, allowedCurrencies emit first an empty array, then it emits a new value:
+anytime, `this.allCurrencies$` or `this.permissions.currencyIds$` changes
+Those two values are passed to a projection function (which simply finds the currencies we have defined [here](/core/modules/currency))
+
+[![](https://markdown-videos-api.jorgenkh.no/youtube/jI8GSJgPrpI)](https://youtu.be/jI8GSJgPrpI)
+
+## firstValueFrom
+
+https://rxjs.dev/api/index/function/firstValueFrom
+
+> Converts an observable to a promise by subscribing to the observable, and returning a promise that will resolve as soon as the first value arrives from the observable. The subscription will then be closed.
+
+[![](https://markdown-videos-api.jorgenkh.no/youtube/Pqfc7xa0QTg)](https://youtu.be/Pqfc7xa0QTg)

pages/APIs/wallet-api/server/handlers/_meta.json

@@ -0,0 +1,8 @@
+{
+  "account": {
+    "title": "Account",
+    "theme": {
+      "toc": true
+    }
+  }
+}

pages/APIs/wallet-api/server/handlers/account.mdx

@@ -0,0 +1,44 @@
+## overview
+
+The Account handlers allows the server to interact with the user's accounts.  
+It can list accounts, request an account, and verify account addresses on a Ledger device through Ledger Live.
+
+## request handlers:
+
+### "account.list" - List Accounts
+
+| parameter (in req.params) | required? | note                                                                  |
+| ------------------------- | --------- | --------------------------------------------------------------------- |
+| _currencyIds_             | ❌        | An array of strings specifying the currency IDs to filter accounts by |
+
+- Retrieve the list of accounts added by the user on the connected wallet.
+- Filters those accounts using `req.params.currencyIds` parameter.
+- **Returns**: A promise that resolves with an array of Account objects
+
+### "account.request" - Request Account
+
+| parameter (in req.params) | required? | note                                                                  |
+| ------------------------- | --------- | --------------------------------------------------------------------- |
+| _currencyIds_             | ❌        | An array of strings specifying the currency IDs to filter accounts by |
+
+| walletHandler used | note                                                                                                                           |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| _account.request_  | Should prompt the user to select an account from the connected wallet. Accounts shown are filtered by _currencyIds_ parameter. |
+
+- Gets an account with _account.request_ walletHandler
+- **Returns**: A promise that resolves with the selected Account object.
+
+### "account.receive" - Verify Account Address
+
+| parameter (in req.params) | required? | note                                                     |
+| ------------------------- | --------- | -------------------------------------------------------- |
+| _accountId_               | ✅        | The ID of the account whose address needs to be verified |
+
+| walletHandler used | note                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| _account.receive_  | Allows the user to verify an account's address on their Ledger device through Ledger Live. |
+
+Allows the user to verify an account's address on their Ledger device through Ledger Live.
+
+- Let's the user verify an account with _account.receive_ walletHandler
+- **Returns**: A promise that resolves with the verified address as a string.

pages/APIs/wallet-api/server/handlers/bitcoin.mdx

@@ -0,0 +1,20 @@
+## overview
+
+The Bitcoin handler allows the server to interact with Bitcoin accounts.  
+Specifically, you can retrieve the extended public key (xPub) of a Bitcoin account.  
+This is useful for deriving Bitcoin addresses without revealing the private key.
+
+## request handlers:
+
+### "bitcoin.getXPub" - Get Extended Public Key (xPub)
+
+| parameter (in req.params) | required? | note                                                                 |
+| ------------------------- | --------- | -------------------------------------------------------------------- |
+| _accountId_               | ✅        | The ID of the Bitcoin account for which the xPub is to be retrieved. |
+
+| walletHandler used | note                                                     |
+| ------------------ | -------------------------------------------------------- |
+| _bitcoin.getXPub_  | Should retrieve the xPub of a particular bitcoin account |
+
+- Gets the xPub of a bitcoin account with _bitcoin.getXPub_ walletHandler
+- **Returns**: A promise that resolves with the xPub as a string.

pages/APIs/wallet-api/server/handlers/currency.mdx

@@ -0,0 +1,16 @@
+## overview
+
+The Currency handlers enables interaction with various cryptocurrencies that are supported by the connected wallet.  
+The server can list the cryptocurrencies and apply filters by name or ticker.
+
+## request handlers:
+
+### "currency.list" - List Cryptocurrencies
+
+| parameter (in req.params) | required? | note                                                                            |
+| ------------------------- | --------- | ------------------------------------------------------------------------------- |
+| _currencyIds_             | ❌        | An array of strings specifying the currency IDs to filter the cryptocurrencies. |
+
+- Start with all currencies (available in [context.currencies](../wallet-api-server#walletcontextcurrencies))
+- Filter those against the parameter _currencyIds_
+- **Returns**: A promise that resolves with an array of Currency objects.

pages/APIs/wallet-api/server/handlers/device.mdx

@@ -0,0 +1,80 @@
+## overview
+
+The Device handlers provides methods for handling the physical device,
+including opening low-level transport and selecting a device in the connected wallet.
+
+## request handlers:
+
+### "device.close" - Close Device
+
+{/* TODO: document this one better */}
+
+Close a device in the connected wallet.
+
+| parameter (in req.params) | required? | note                     |
+| ------------------------- | --------- | ------------------------ |
+| _transportId_             | ✅        | A device's transport id. |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _device.close_     |      |
+
+- **Returns**: A promise that resolves the transport id.
+
+### "device.exchange" -
+
+{/* TODO: document this one better */}
+
+| parameter (in req.params) | required? | note |
+| ------------------------- | --------- | ---- |
+| _transportId_             | ✅        |      |
+| _apduHex_                 | ✅        |      |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _device.exchange_  |      |
+
+- **Returns**: A promise that resolves with _responseHex_
+
+### "device.open" - Open Device
+
+Open a device in the connected wallet.
+
+| parameter    | required? | note                                                    |
+| ------------ | --------- | ------------------------------------------------------- |
+| _req.params_ | ✅        | An object containing the parameters to open the device. |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _device.open_      |      |
+
+- **Returns**: A promise that resolves with a _transportId_
+
+### "device.select" - Select Device
+
+Select a device in the connected wallet.
+
+| parameter | required? | note                                                                |
+| --------- | --------- | ------------------------------------------------------------------- |
+| params    | ✅        | An object containing the parameters to select and check the device. |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _device.select_    |      |
+
+- **Returns**: A promise that resolves with a `deviceId` which can be used with the `device.open` method.
+
+### "device.transport" - Open Low-Level Transport
+
+Open low-level transport in the connected wallet.
+
+| parameter    | required? | note                                                   |
+| ------------ | --------- | ------------------------------------------------------ |
+| _req.params_ | ✅        | An object containing the parameters for the transport. |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _device.transport_ |      |
+
+- Calls the wallet handler _device.transport_
+- **Returns**: **Returns**: A promise that resolves with an instance of Transport compatible with `@ledgerhq/hw-transport`.

pages/APIs/wallet-api/server/handlers/exchange.mdx

@@ -0,0 +1,48 @@
+## overview
+
+The Exchange handlers facilitates various exchange operations such as starting the exchange process,
+completing swap, sell, and fund transactions using Ledger Live.
+
+## request handlers:
+
+### "exchange.start" - Start Exchange
+
+{/* TODO: document this one better */}
+
+Start the exchange process by generating a nonce on Ledger device. This method is typically called before completing the exchange process.
+
+| parameter (in req.params) | required? | note                                       |
+| ------------------------- | --------- | ------------------------------------------ |
+| _exchangeType_            | ✅        | Type of exchange, "SWAP", "SELL" or "FUND" |
+
+| walletHandler used | note |
+| ------------------ | ---- |
+| _exchange.start_   |      |
+
+- **Returns**: A promise that resolves with an object containing the `transactionId` which is used to complete the exchange process.
+
+### "exchange.complete" - Complete Exchange
+
+{/* TODO: document this one better */}
+
+Complete an exchange process (swap, sell, or fund) by passing the exchange content and its signature.
+
+| parameter (in req.params) | required? | note                                                                                                                                 |
+| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| _provider_                | ✅        | A string used to verify the signature.                                                                                               |
+| _fromAccountId_           | ✅        | Identifier of the account used as a source for the transaction.                                                                      |
+| _rawTransaction_          | ✅        | A RawTransaction object containing the transaction details.                                                                          |
+| _hexBinaryPayload_        | ✅        | Hexadecimal string representing the blueprint of the data that will be allowed for signing.                                          |
+| _hexSignature_            | ✅        | Hexadecimal string ensuring the source of the payload.                                                                               |
+| _feeStrategy_             | ✅        | A string representing the fee strategy (`"SLOW"`, `"MEDIUM"`, or `"FAST"`).                                                          |
+| _exchangeType_            | ✅        | A string specifying the type of exchange operation (`"SWAP"`, `"SELL"`, or `"FUND"`).                                                |
+| _toAccountId_             | ❌        | Identifier of the account used as a destination (required for `"SWAP"`).                                                             |
+| _swapId_                  | ❌        | Identifier of the backend swap used (required for `"SWAP"`).                                                                         |
+| _rate_                    | ❌        | Swap rate used in the transaction (required for `"SWAP"`).                                                                           |
+| _tokenCurrency_           | ❌        | Swap tokenCurrency is used when we want point a new token, as id does not exists in wallet-api (optional for `"SWAP"` and `"FUND"`). |
+
+| walletHandler used  | note |
+| ------------------- | ---- |
+| _exchange.complete_ |      |
+
+- **Returns**: A promise that resolves with an object containing the `transactionHash` of the broadcasted transaction.