diff --git a/pages/APIs/wallet-api/_meta.json b/pages/APIs/wallet-api/_meta.json index 7bb3f7c3..a695c845 100644 --- a/pages/APIs/wallet-api/_meta.json +++ b/pages/APIs/wallet-api/_meta.json @@ -4,5 +4,6 @@ "core": "Core", "simulator": "Simulator", "examples": "Examples", - "appendix": "Appendix" + "appendix": "Appendix", + "server": "Server" } diff --git a/pages/APIs/wallet-api/introduction.mdx b/pages/APIs/wallet-api/introduction.mdx index deddbc0d..b45b71ba 100644 --- a/pages/APIs/wallet-api/introduction.mdx +++ b/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. diff --git a/pages/APIs/wallet-api/server/_meta.json b/pages/APIs/wallet-api/server/_meta.json new file mode 100644 index 00000000..e728bba6 --- /dev/null +++ b/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" +} diff --git a/pages/APIs/wallet-api/server/assets/diagram-permissions-1-light.png b/pages/APIs/wallet-api/server/assets/diagram-permissions-1-light.png new file mode 100644 index 00000000..69e6a174 Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-permissions-1-light.png differ diff --git a/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-dark.png b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-dark.png new file mode 100644 index 00000000..d88b64ac Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-dark.png differ diff --git a/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-light.png b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-light.png new file mode 100644 index 00000000..0bb39a93 Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-1-light.png differ diff --git a/pages/APIs/wallet-api/server/assets/diagram-request-handlers-2-light.png b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-2-light.png new file mode 100644 index 00000000..e7604591 Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-request-handlers-2-light.png differ diff --git a/pages/APIs/wallet-api/server/assets/diagram-transport-1-light.png b/pages/APIs/wallet-api/server/assets/diagram-transport-1-light.png new file mode 100644 index 00000000..63ecb92e Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-transport-1-light.png differ diff --git a/pages/APIs/wallet-api/server/assets/diagram-wallet-handlers-1-light.png b/pages/APIs/wallet-api/server/assets/diagram-wallet-handlers-1-light.png new file mode 100644 index 00000000..9027beb8 Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/diagram-wallet-handlers-1-light.png differ diff --git a/pages/APIs/wallet-api/server/assets/server-rpc-node-classdiagram.png b/pages/APIs/wallet-api/server/assets/server-rpc-node-classdiagram.png new file mode 100644 index 00000000..9f5b5c01 Binary files /dev/null and b/pages/APIs/wallet-api/server/assets/server-rpc-node-classdiagram.png differ diff --git a/pages/APIs/wallet-api/server/extras/rpc-node.mdx b/pages/APIs/wallet-api/server/extras/rpc-node.mdx new file mode 100644 index 00000000..e270f131 --- /dev/null +++ b/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: + +
+Class diagram overview ๐Ÿ“ + +![diagram](../assets/server-rpc-node-classdiagram.png) + +
+ +[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 = { + /** + * 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; +}; +``` diff --git a/pages/APIs/wallet-api/server/extras/rxjs.mdx b/pages/APIs/wallet-api/server/extras/rxjs.mdx new file mode 100644 index 00000000..6cdb990d --- /dev/null +++ b/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) diff --git a/pages/APIs/wallet-api/server/handlers/_meta.json b/pages/APIs/wallet-api/server/handlers/_meta.json new file mode 100644 index 00000000..575e1c8a --- /dev/null +++ b/pages/APIs/wallet-api/server/handlers/_meta.json @@ -0,0 +1,8 @@ +{ + "account": { + "title": "Account", + "theme": { + "toc": true + } + } +} diff --git a/pages/APIs/wallet-api/server/handlers/account.mdx b/pages/APIs/wallet-api/server/handlers/account.mdx new file mode 100644 index 00000000..b8f3d9b9 --- /dev/null +++ b/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. diff --git a/pages/APIs/wallet-api/server/handlers/bitcoin.mdx b/pages/APIs/wallet-api/server/handlers/bitcoin.mdx new file mode 100644 index 00000000..1f67ad8a --- /dev/null +++ b/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. diff --git a/pages/APIs/wallet-api/server/handlers/currency.mdx b/pages/APIs/wallet-api/server/handlers/currency.mdx new file mode 100644 index 00000000..50acde93 --- /dev/null +++ b/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. diff --git a/pages/APIs/wallet-api/server/handlers/device.mdx b/pages/APIs/wallet-api/server/handlers/device.mdx new file mode 100644 index 00000000..2ce3c7fa --- /dev/null +++ b/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`. diff --git a/pages/APIs/wallet-api/server/handlers/exchange.mdx b/pages/APIs/wallet-api/server/handlers/exchange.mdx new file mode 100644 index 00000000..7b351bed --- /dev/null +++ b/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. diff --git a/pages/APIs/wallet-api/server/handlers/message.mdx b/pages/APIs/wallet-api/server/handlers/message.mdx new file mode 100644 index 00000000..58e9da6a --- /dev/null +++ b/pages/APIs/wallet-api/server/handlers/message.mdx @@ -0,0 +1,22 @@ +## overview + +The Message handler enables users to sign messages using Ledger Live. +In the Ethereum context, the messages can be [EIP-191](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-191.md) or [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) messages. + +## request handlers: + +### "message.sign" - Sign Message + +Allow the user to sign the provided message. This method is used to get a signature for a given message, which proves that the owner of the account has agreed to the message content. + +| parameter (in req.params) | required? | note | +| ------------------------- | --------- | ------------------------------------------------------------------------------------------------ | +| _accountId_ | โœ… | A string representing the Ledger Live ID of the account that should be used to sign the message. | +| _hexMessage_ | โœ… | A Buffer containing the message that should be signed. | +| _meta_ | โŒ | An object with additional data associated with the message. | + +| walletHandler used | note | +| ------------------ | ---- | +| _message.sign_ | | + +- **Returns**: A promise that resolves with a Buffer containing the signed message in hexadecimal format. diff --git a/pages/APIs/wallet-api/server/handlers/storage.mdx b/pages/APIs/wallet-api/server/handlers/storage.mdx new file mode 100644 index 00000000..04b581ea --- /dev/null +++ b/pages/APIs/wallet-api/server/handlers/storage.mdx @@ -0,0 +1,42 @@ +## overview + +The Storage handlers provides a way to interact with Ledger Live's internal storage. +The server can store and retrieve data using key-value pairs. + +## request handlers: + +### "storage.set" - Set Data + +{/* TODO: document this one better, could it be generalized for all wallets? */} + +Store data in Ledger Live's internal storage. You can specify a key and value, and optionally provide a store ID to store data in a specific store. + +| parameter (in req.params) | required? | note | +| ------------------------- | --------- | --------------------------------------------------------------------------- | +| _key_ | โœ… | A string representing the key under which you want to store the data. | +| _value_ | โœ… | A string representing the data you want to store. | +| _storeId_ | โŒ | A string representing the ID of the store where you want to store the data. | +| | + +| walletHandler used | note | +| ------------------ | ---- | +| _storage.set_ | | + +- **Returns**: A promise that resolves when the data is successfully stored. There is no return value. + +### "storage.get" - Get Data + +{/* TODO: dig over multi store documentaire */} + +Retrieve data from Ledger Live's internal storage by specifying a key. You can also specify a store ID to retrieve data from a particular store. + +| parameter (in req.params) | required? | note | +| ------------------------- | --------- | ------------------------------------------------------------------------------- | +| _key_ | โœ… | A string representing the key of the data you want to retrieve. | +| _storeId_ | โŒ | A string representing the ID of the store from which you want to retrieve data. | + +| walletHandler used | note | +| ------------------ | ---- | +| _storaget.get_ | | + +- **Returns**: A promise that resolves with the value as a string or `undefined` if the key does not exist. diff --git a/pages/APIs/wallet-api/server/handlers/transaction.mdx b/pages/APIs/wallet-api/server/handlers/transaction.mdx new file mode 100644 index 00000000..6b1dd92a --- /dev/null +++ b/pages/APIs/wallet-api/server/handlers/transaction.mdx @@ -0,0 +1,41 @@ +## overview + +The Transaction handlers allows the server to interact with user transactions. +It enables the server to let the user sign a transaction and also allows the server to sign and broadcast a transaction through Ledger Live. + +## request handlers: + +### "transaction.sign" - Sign Transaction + +Let the user sign a transaction without broadcasting it. This is useful if you want to sign a transaction for later use. + +| parameter (in req.params) | required? | note | +| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `accountId` | โœ… | The ID of the account where the transaction will be made. | +| `rawTransaction` | โœ… | The raw [transaction object](../../appendix/transaction) in the currency family-specific format. | +| `options` | โŒ | Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsign-type) for more information. | +| `meta` | โŒ | Metadata for the transaction. | +| | + +| walletHandler used | note | +| ------------------ | ---- | +| _transaction.sign_ | | + +- **Returns**: A promise that resolves with the raw signed transaction as a Buffer. + +### "transaction.signAndBroadcast" - Sign and Broadcast Transaction + +Let the user sign a transaction and broadcast it to the network. + +| parameter (in req.params) | required? | note | +| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `accountId` | โœ… | The ID of the account where the transaction will be made. | +| `rawTransaction` | โœ… | The raw [transaction object](../../appendix/transaction) in the currency family-specific format. | +| `options` | โŒ | Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsign-type) for more information. | +| `meta` | โŒ | Metadata for the transaction. | + +| walletHandler used | note | +| ------------------------------ | ---- | +| _transaction.signAndBroadcast_ | | + +- **Returns**: A promise that resolves with the transaction hash as a string. diff --git a/pages/APIs/wallet-api/server/handlers/wallet.mdx b/pages/APIs/wallet-api/server/handlers/wallet.mdx new file mode 100644 index 00000000..71e6646c --- /dev/null +++ b/pages/APIs/wallet-api/server/handlers/wallet.mdx @@ -0,0 +1,26 @@ +## overview + +The Wallet handlers allows you to interact with the user's wallet. +This includes retrieving the user's ID, fetching wallet information, and listing the capabilities of the wallet. + +## request handlers: + +### "wallet.capabilities" + +List the method IDs that are implemented by the wallet. (ie. the [walletHandlers](../wallet-api-server#wallethandlers) method names) + +- **Returns**: A promise that resolves with an array of strings representing the method IDs. + +### "wallet.userId" + +Retrieve the user ID of the connected wallet. + +- Fetches the user ID stored in [walletContext.config](../wallet-api-server#walletcontextconfig) +- **Returns**: A promise that resolves with the user ID as a string. + +### "wallet.info" + +Retrieve information about the connected wallet. + +- Fetches the wallet info stored in [walletContext.config](../wallet-api-server#walletcontextconfig) +- **Returns**: A promise that resolves with an object containing information about the connected wallet. diff --git a/pages/APIs/wallet-api/server/index.mdx b/pages/APIs/wallet-api/server/index.mdx new file mode 100644 index 00000000..6bd03d9b --- /dev/null +++ b/pages/APIs/wallet-api/server/index.mdx @@ -0,0 +1,52 @@ +import { Steps } from 'nextra/components' + +The WalletAPIServer is **a bi-directonnal JSON-RPC 2.0 server** + +These docs aim to explain the design of the WalletAPIServer and how to use it. + +There are a few ways you can go about reading it, depending on your use case: + +## How to grasp what it does + + + ### Start of with the [visual introduction](./server/wallet-api-server/diagrams#slideshow) + + ### Look at the reference page [here](./server/wallet-api-server) + +### Check out [this example](./server/usage-examples/with-constructor) + +shows how a server can be used, instantiating it via its constructor + + + +## How to use walletAPIServer + + + +### Use [this page](./server/wallet-api-server) as your reference + +### Check out [here](./server/wallet-api-server#constructor) + +how to instantiate a server via its constructor + +### Check out [here](./server/wallet-api-server/react-hook) + +(optional, useful if using react) how to instantiate a server via a react hook + +### Check out [this example](./server/usage-examples/with-constructor) + +shows how a server can be used, instantiating it via its constructor + +### Check out [the usage of a server made within Ledger Live](./server/usage-examples/within-ledger-live) + +shows how a server can be used, instantiating it via the react hook + + + +## Additional resources living outside of these docs + +- Source code: https://github.com/LedgerHQ/wallet-api/tree/main/packages/server +- Main file: https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/WalletAPIServer.ts +- Wallet API README: https://github.com/LedgerHQ/wallet-api/blob/main/README.md +- Spec: https://github.com/LedgerHQ/wallet-api/blob/main/spec/server/README.md +- Package name: **@ledgerhq/wallet-api-server** diff --git a/pages/APIs/wallet-api/server/usage-examples/with-constructor.mdx b/pages/APIs/wallet-api/server/usage-examples/with-constructor.mdx new file mode 100644 index 00000000..46fff358 --- /dev/null +++ b/pages/APIs/wallet-api/server/usage-examples/with-constructor.mdx @@ -0,0 +1,81 @@ +## Example usage of the walletAPIServer + +Here's how you can instantiate a new `WalletAPIServer` using its [constructor](../wallet-api-server#constructor) + +### instantiation + +```ts {21} +const transport: Transport = { + onMessage: undefined, + send: (message: string) => { + if (wapiView) { + wapiView.webContents.postMessage("message", message); + } + }, +}; + +const config = { + appId: "fake-manifest-id", // should be the real manifest id, used in the storage handler code + wallet: { + name: "browserview-wallet", + version: "0.1.0", + }, + tracking: false, + userId: "fake", +}; + +const wapiServer = new WalletAPIServer(transport, config); +``` + +two required arguments are passed, [transport](../wallet-api-server#transport) and [config](../wallet-api-server#walletcontextconfig). + +### setup accounts, currencies and permissions via setters + +```ts +wapiServer.setAccounts(accounts); +wapiServer.setCurrencies(currencies); +wapiServer.setPermissions({ + currencyIds: ["**"], + methodIds: ["account.list", "account.receive", "account.request"], +}); +``` + +Call setters to set the [accounts](../wallet-api-server#allaccounts), +[currencies](../wallet-api-server#allcurrencies), +and [permissions](../wallet-api-server#permissions) + +### set wallet handlers + +```ts + wapiServer.setHandler("account.request", async ({ accounts$, currencies$ }) => { + return new Promise((resolve, reject) => { + uiAccountRequest({ + accounts$, + currencies: currencies.map({id} => id), + onSuccess: (account: AccountLike, parentAccount: Account | undefined) => { + resolve(accountToWalletAPIAccount(account, parentAccount)); + }, + onCancel: () => { + reject(new Error("Canceled by user")); + }, + }); + }); + }) + +``` + +Set a [walletHandler](../wallet-api-server#wallethandlers) to handle +actions that would request an account from the wallet. + +### wire up transport + +```ts {3} +import { ipcMain } from "electron"; +ipcMain.on("walletAPI:postMessage", (_, data) => { + transport.onMessage?.(data); +}); +``` + +Set up the transport's `onMessage` value, which will allow _APP -> SERVER_ communication. + +More on transport [here](../wallet-api-server#transport). diff --git a/pages/APIs/wallet-api/server/usage-examples/within-ledger-live.mdx b/pages/APIs/wallet-api/server/usage-examples/within-ledger-live.mdx new file mode 100644 index 00000000..abdc9711 --- /dev/null +++ b/pages/APIs/wallet-api/server/usage-examples/within-ledger-live.mdx @@ -0,0 +1,211 @@ +import { Callout } from "nextra/components"; +import { Steps } from "nextra/components"; + +## Usage of the walletAPIServer in Ledger Live + +The react hook [useWalletAPIServer](../wallet-api-server/react-hook) +is used within [Ledger Live](https://github.com/LedgerHQ/ledger-live/) +to create a walletAPIServer + +It is used in _ledger-live-common_ here +**ledger-live-common/src/wallet-api/react.ts** +In this file, a walletAPIServer +is created, and exposed through another hook (also called +`useWalletAPIServer`) + +This (LLC hook) is in turn used in both +[LLD](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-desktop/src/renderer/components/Web3AppWebview/WalletAPIWebview.tsx#L10) +and [LLM](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-mobile/src/components/Web3AppWebview/helpers.ts#L8) + +## useWebview() + + +### useWebView() gets called + +Both LLD and LLM, when creating live apps, use the hook `useWebView`, +with the main arguments being: + +- [manifest](../../appendix/manifest) +- [customHandlers](../wallet-api-server#requesthandlers) +- webviewRef + +```ts filename="apps/ledger-live-desktop/src/renderer/components/Web3AppWebview/WalletAPIWebview.tsx" +const WalletAPIWebview => { + ({ manifest customHandlers} ) => { + const { webviewRef } = useWebviewState(); + + useWebView({ manifest, customHandlers}, webviewRef); + return + } +}; +``` + +### Prepares transport + +Will allow communication with the webview. + +```ts filename="simplified" +const webviewHook = { + return { + postMessage: (message) => { + webviewRef.current.contentWindow?.postMessage(message); + }, + }; +}; +``` + +### Prepares uiHooks + +They will allow walletHandlers to trigger ui actions + +
+ more on uiHooks + +uiHooks are created in useWebView and sent to LLC useWalletAPIServer +`uiHook` is an object that maps a method like `"account.request"` to an action in LLD / LLM +here's a list of actions it triggers in LLD: + +- opening a drawer to select an account, start an exchange process +- opening modals to sign transactions, messages, start an exchange process, connect a device +- store data / update account data +- display toaster + +
+ +### LLC useWalletAPIServer() gets called + +The goal of LLC's `useWalletAPIServer` is simply to call the walletAPIServer hook (also called `useWalletAPIServer`) + +Before doing so it: + +- Extracts [permissions](../wallet-api-server#permissions) From the manifest + +- Converts accounts sent from [useWebView](./within-ledger-live#usewebview) (coming from redux store) to [a format readable by walletAPIServer](../wallet-api-server#allaccounts) + +- Fetches and filters currencies (coming from `libs/ledger-live-common/src/currencies/helpers.ts` `listCurrencies`) + +- Converts filtered currencies to a format readable by wallet-api-server. More on that format [here](../wallet-api-server/react-hook#currencies) + +- Creates a [transport](../wallet-api-server#transport) + +```js +function useTransport(postMessage: (message: string) => void | undefined): Transport { + return useMemo(() => { + return { + onMessage: undefined, + send: postMessage, // will allow WALLETAPISERVER -> LIVEAPP communication (via postMessage) + }; + }, [postMessage]); +} + + const transport = useTransport(webviewHook.postMessage); +``` + +### walletAPIServer gets instantiated + +via the react hook [useWalletAPIServer](../wallet-api-server/react-hook) + +### post-instantiation transport setup + +walletAPIServer sends back its `onMessage` callback, the webview will use +it to send message to it. + +```ts {1,12-13, 20} +const { onMessage } = useWalletAPIServer({ + manifest, + accounts, + config, + webviewHook, + uiHook, + customHandlers, +}); + +const handleMessage = useCallback( + (event: Electron.IpcMessageEvent) => { + if (event.channel === "webviewToParent") { + onMessage(event.args[0]); + } + }, + [onMessage] +); + +useEffect(() => { + webviewRef.current.addEventListener("ipc-message", handleMessage); +}, [handleMessage, onLoad]); +``` + +### post-instantiation setup of wallet handlers + +[server.setHandler](../wallet-api-server#wallethandlers) is called +to setup Ledger Live Wallet/UI/Store callbacks. + +
+ Simplified example of setHandler() call + +```js filename="libs/ledger-live-common/src/wallet-api/react.ts" + server.setHandler("account.request", async ({ accounts$, currencies$ }) => { + const currencies = await firstValueFrom(currencies$); + return new Promise((resolve, reject) => { + let currencyList = currencyList = allCurrenciesAndTokens.filter(({ id }) => currencyIds.includes(id)); + uiAccountRequest({ + accounts$, + currencies: currencyList, + onSuccess: (account: AccountLike, parentAccount: Account | undefined) => { + resolve(accountToWalletAPIAccount(account, parentAccount)); + }, + onCancel: () => { + reject(new Error("Canceled by user")); + }, + }); + }); + }); + }, [manifest, server, tracking, uiAccountRequest]); +``` + +those handlers are saved in the property `WalletAPIServer.walletHandlers` + +To recap: + +- `WalletAPIServer.walletHandlers` -> callbacks defined in LLC, trigger modals / drawers / update redux store, etc. +- `WalletAPIServer.requestHandlers` -> internalHandlers + customHandlers, can call `walletHandlers` inside of them + +
+ + + +```mermaid +flowchart TD + A{LLD/LLM useWebView} -->| + SENDS: + + manifest + accounts + uiHooks: so server can trigger LL ui + webviewHook: so server can communicate TO the webview + customHandlers + | B{LLC useWalletAPIServer} + B --> | + GETS BACK: + + onMessage: so webview can communicate TO server + |A +``` + +```mermaid +flowchart TD + A{LLC useWalletAPIServer} -->| + SENDS: + + transport: so server can communicate TO webview + accounts + currencies + permissions + customHandlers + | B{wallet-api-server useWalletAPIServer} + B --> | + GETS BACK: + + server: WalletAPIServer, a RPC Node + onMessage: so webview can communicate TO server + |A +``` diff --git a/pages/APIs/wallet-api/server/wallet-api-server/_meta.json b/pages/APIs/wallet-api/server/wallet-api-server/_meta.json new file mode 100644 index 00000000..7784da0d --- /dev/null +++ b/pages/APIs/wallet-api/server/wallet-api-server/_meta.json @@ -0,0 +1,16 @@ +{ + "index": { + "title": "Wallet API Server", + "theme": { + "sidebar": true, + "toc": true + } + }, + "diagrams": { + "title": "Diagrams", + "theme": { + "sidebar": true, + "toc": false + } + } +} diff --git a/pages/APIs/wallet-api/server/wallet-api-server/diagrams.mdx b/pages/APIs/wallet-api/server/wallet-api-server/diagrams.mdx new file mode 100644 index 00000000..b152a946 --- /dev/null +++ b/pages/APIs/wallet-api/server/wallet-api-server/diagrams.mdx @@ -0,0 +1,35 @@ +import { Callout } from "nextra/components"; +import { Bleed } from "nextra-theme-docs"; +import Image from "next/image"; + +## Slideshow + +A slideshow introducing the different part of the server is available [here](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4) + +## Diagrams + + + Those diagrams come from this introductory + [slideshow](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4) and + are slightly reworked to be understood as standalone diagrams. + + +### 1. a basic way to allow wallet-application interaction + +![diagram](../assets/diagram-request-handlers-1-light.png) + +### 2. process requests with requestHandlers + +![diagram](../assets/diagram-request-handlers-2-light.png) + +### 3. ask wallet for data / actions with walletHandlers + +![diagram](../assets/diagram-wallet-handlers-1-light.png) + +### 4. handle bidirectional communication + +![diagram](../assets/diagram-transport-1-light.png) + +### 4. data passed from wallet to the server (accounts, currencies, config) and permissions + +![diagram](../assets/diagram-permissions-1-light.png) diff --git a/pages/APIs/wallet-api/server/wallet-api-server/index.mdx b/pages/APIs/wallet-api/server/wallet-api-server/index.mdx new file mode 100644 index 00000000..3cf2d988 --- /dev/null +++ b/pages/APIs/wallet-api/server/wallet-api-server/index.mdx @@ -0,0 +1,343 @@ +import { Callout } from "nextra/components"; + +## properties + +### allAccounts$ + +Represents all available wallet accounts + +`Account` is a slightly modified subject of the Account type used by the Ledger Live platform + +
+ details of the Account type + +```js +export type Account = { + /** + * The unique identifier of this account used internally by Ledger Live software + */ + id: string; + /** + * The accountโ€™s name set by the user. + */ + name: string; + /** + * The "next" public address where a user should receive funds. In the context of Bitcoin, the address is "renewed" each time funds are received in order to allow some privacy. In other blockchains, the address might never change + */ + address: string; + /** + * The associated cryptocurrency id of the Account + */ + currency: string; + /** + * The total amount of assets that this account holds + */ + balance: BigNumber; + /** + * The amount of the balance that can be spent. Most of the time it will be equal to the balance, but this can vary in some blockchains + */ + spendableBalance: BigNumber; + /** + * Tracks the current blockchain block height + */ + blockHeight: number | undefined; + /** + * The date of the last time a synchronization was performed. In other words, tracks how up-to-date the Account data is + */ + lastSyncDate: Date; +}; +``` + +
+ +| Created via | name | +| ----------- | --------------- | +| _setter_ | **setAccounts** | + +### allCurrencies$ + +All available currencies that supported by the wallet. + +
+ details of the Currency type + +```js +type Currency = { + type: "CryptoCurrency"; + name: string; + id: string; + color: string; + ticker: string; + decimals: number; + family: "bitcoin" | "ethereum" | "algorand" | "crypto_org" | "ripple" | "cosmos" | "celo" | ... 10 more ... | "solana"; +} + +``` + +
+ +| Created via | name | +| ----------- | ----------------- | +| _setter_ | **setCurrencies** | + +--- + +### permissions + +Permissions are a set of two lists: + +1. The first restricting the [currencies](./wallet-api-server#allcurrencies) that can be used, +2. The second restricting the [requestHandlers](./wallet-api-server#requesthandlers) method that can be used, + this list also restricts the calls that the [sendMessage](./wallet-api-server#sendmessage) method can make + +| Created via | name | +| ----------- | ------------------ | +| _setter_ | **setPermissions** | + +#### permissions.currencyIds$ + +- a list of currencies ids an application can interact with + +```js filename="example" +permissions.currencyIds$ = ["ethereum", "bitcoin"]; +``` + +- โ„น๏ธ it is possible to allow all currencies available in [allCurrencies](../wallet-api-server#allcurrencies) by setting this value to `["**"]` + +```js filename="example with glob" +permissions.currencies$ = ["**"], +``` + +#### permissions.methodIds$ + +- a list of methods a live app can call, corresponds to a [requestHandler's name](./wallet-api-server#requesthandlers) +- this list is also checked against when _SERVER -> APP_ communication is done (in [sendMessage](./wallet-api-server#sendmessage)) + +```js filename="example" +permissions.methodIds$ = [ + "account.request", + "currency.list", + "account.list", + "transaction.signAndBroadcast", + "transaction.sign", + "message.sign", + "account.receive", + "wallet.capabilities", + "storage.set", + "storage.get", + "wallet.userId", + "wallet.info", + "bitcoin.getXPub", + "exchange.start", + "exchange.complete", +]; +``` + +--- + +### walletContext + +#### walletContext.currencies$ + +The allowed currencies: + +[allCurrencies](./wallet-api-server#allcurrencies) filtered against the currencies listed in [permissions.currencyIds](./wallet-api-server#permissionscurrencyids) + +| Created via | name | note | +| ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _observable_ | | set in constructor, updates anytime `allAccounts` or `allowedCurrencies` changes, more info on how it does this using rxjs [here](./extras/rxjs#combinelatest) | + +#### walletContext.accounts$ + +The allowed accounts: + +[allAccounts](./wallet-api-server#allaccounts) filtered against the allowedCurrencies computed above + +| Created via | name | note | +| ------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _observable_ | | set in constructor, updates anytime `allAccounts` or `walletContext.allowedCurrencies` changes, more info on how it does this using rxjs [here](./extras/rxjs#combinelatest) | + +#### walletContext.config + +An object of this form + +```js +ServerConfig = { + userId: string; // used in internal handler wallet.userID + tracking: boolean; + appId: string; // used in internal handler storage.ts, to store data in this fashion: object[app.id] + wallet: { // used in internal handler wallet.info + name: string; + version: string; + }; +}; +``` + +| Created via | name | +| ------------- | ------------- | +| _constructor_ | **config** | +| _setter_ | **setConfig** | + +--- + +### transport + +A transport protocol used to communicate with an application + +
+Show diagram + +![diagram](../assets/diagram-transport-1-light.png) + +
+ +```js +type Transport = { + // A function to handle messages coming from the application + onMessage: MessageHandler + + // A function to send messages to the application + send(message: string): void; +}; + +``` + +| Created via | name | +| ------------- | ------------- | +| _constructor_ | **transport** | + +--- + +### requestHandlers + +
+Show diagram + +![diagram](../assets/diagram-request-handlers-2-light.png) + +
+ +More on RpcRequest [here](./extras/rpc-node#rpc-requests). + +A handler is a function of type `RPCHandler` + +```js filename="packages/server/src/types.ts" + type RPCHandler = ( + request: RpcRequest, + context: WalletContext, + handlers: Partial, +) => Promisable; + +``` + +requestHandlers is an object of this type, mapping method ids (handlers name) to their RPCHandlers: + +```js +{ + 'handlerName': RPCHandler, + 'handlerName2': RPCHandler, + 'handlerName3': RPCHandler, + ... +} +``` + +A default set of handlers will always be present, those are the `internalHandlers`. + + + You can find a comprehensive list of those internalHandlers + [here](./handlers/account). + + +Additionally, you can pass `customHandlers` to the constructor. + +To put it simply: `requestHandlers = internalHandlers + customHandlers {:js}` + +| Created via | name | +| ------------- | --------------------- | +| _constructor_ | **customHandlers** | +| _setter_ | **setCustomHandlers** | + +--- + +### walletHandlers + +
+Show diagram + +![diagram](../assets/diagram-wallet-handlers-1-light.png) + +
+ +wallets using the wallet-api-server must implements this spec: +https://github.com/LedgerHQ/wallet-api/blob/main/spec/rpc/README.md + +those functions will allow requestHandlers to interact with the wallet +most requestHandlers use one or more walletHandlers internally, to request / send data to the wallet +on top of that, request handlers will use permissions set above to filter out what's show / operated on (allowed accounts, allowed currencies) + +| Created via | name | note | +| ----------- | --------------- | ------------------------------------------------------- | +| _setter_ | **setHandler** | | +| _setter_ | **setHandlers** | _sets in bulk, overriding all existing wallet handlers_ | + +## methods + +### handleMessage + +A function to handle messages coming from the application + +Used in conjonction with the transport property. + +the `server.transport.onMessage` value is set to this function. + +Parse json to either a [rpcRequest](./extras/rpc-node#rpc-requests) or rpcResponse object + +Will then call `handleRpcRequest` + +### handleRpcRequest + +calls .onrequest, then creates an `RpcResponse` with the result and sends that +response back to the application (using `this.transport.send`) + +### onRequest + +call the appropriate [requestHandler](./wallet-api-server#requesthandlers) for that request + +1. check if method exists by looking up [requestHandlers](./wallet-api-server#requesthandlers) +2. check if [permissions](./wallet-api-server#permissionsmethodids) allows for it to be called +3. calls it, with the following parameters : + +- request ([RpcRequest](./extras/rpc-node#rpc-requests)) +- [walletContext](./wallet-api-server#walletcontext) +- [walletHandlers](./wallet-api-server#wallethandlers) + +### sendMessage + +1. checks if it can send a message to the server by checking permissions. +2. then calls [notify](./wallet-api-server#notify) + +## constructor + +```js filename="packages/server/src/WalletAPIServer.ts" +class WalletAPIServer{ + constructor( + transport: Transport, + config: ServerConfig, + logger = defaultLogger, + customHandlers: CustomHandlers = {}, + ) {...} +} + +``` + +| Parameter | required? | note | +| ---------------- | --------- | ------------------------------------------------------------------------------ | +| _transport_ | โœ… | sets the [transport](./wallet-api-server#transport) | +| _config_ | โœ… | sets the [walletContext.config](./wallet-api-server#walletcontextconfig) value | +| _logger_ | โŒ | (optional) sets the logger | +| _customHandlers_ | โŒ | (optional) sets [customHandlers](./wallet-api-server#walletcontextconfig) | + + + It is how a WalletAPIServer is created in the example + [here](./usage-examples/with-constructor) + diff --git a/pages/APIs/wallet-api/server/wallet-api-server/react-hook.mdx b/pages/APIs/wallet-api/server/wallet-api-server/react-hook.mdx new file mode 100644 index 00000000..d11ada5f --- /dev/null +++ b/pages/APIs/wallet-api/server/wallet-api-server/react-hook.mdx @@ -0,0 +1,62 @@ +import { Callout } from "nextra/components"; + +## useWalletAPIServer + +[source code](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/react.ts) + +For convenience in a react environment, the hook `useWalletAPIServer`, is available. + +It is used to setup a WalletAPIServer + + + [It is how wallet API Server are created in ledger + live](../usage-examples/within-ledger-live) + + +```js filename="packages/server/src/WalletAPIServer.ts" + +export function useWalletAPIServer({ + transport, + config, + logger, + accounts, + currencies, + permission, + customHandlers, +}){...} + +``` + +| Parameter (destructured from single object) | required? | note | +| ------------------------------------------- | --------- | ------------------------------------------------------------------------------- | +| _transport_ | โœ… | sets the [transport](../wallet-api-server#transport) | +| _config_ | โœ… | sets the [walletContext.config](../wallet-api-server#walletcontextconfig) value | +| _logger_ | โŒ | (optional) sets the logger | +| _accounts_ | โœ… | sets the [accounts](../wallet-api-server#allaccounts) | +| _currencies_ | โœ… | sets the [currencies](../wallet-api-server#allcurrencies) | +| _permissions_ | โœ… | sets the [permissions](../wallet-api-server#permissions) | +| _customHandlers_ | โŒ | (optional) sets [customHandlers](../wallet-api-server#walletcontextconfig) | + +Once instantiated, it + +- Sets custom handlers, in all cases (even if no custom handlers are sent from LLC), + it will be called to set the [requestHandlers](../wallet-api-server#requesthandlers) +- Sets config, permissions, currencies and accounts. + +Then, it returns: + +```ts +return { + server, + onMessage, +}; +``` + +`server` is our walletAPIServer instance. +`onMessage`, which will allow _APP -> SERVER_ communication. + + + Note that WalletAPIServer is instantiated as a ref + [useRef](https://react.dev/reference/react/useRef) we actually return + ```server: server.current``` +