From b5ef441f830ac810f259083907c883f405ace906 Mon Sep 17 00:00:00 2001 From: Ramy EL BEHEDY <32883529+RamyEB@users.noreply.github.com> Date: Tue, 17 Oct 2023 18:21:49 +0900 Subject: [PATCH 1/2] Add documentation for dynamic generation (#248) * doc: remove eth dapp browser * doc: add overrite documentation * doc: fix manifest * Update apps/docs/pages/appendix/manifest.mdx --------- Co-authored-by: Quentin Jaccarino --- apps/docs/pages/appendix/manifest.mdx | 109 ++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 16 deletions(-) diff --git a/apps/docs/pages/appendix/manifest.mdx b/apps/docs/pages/appendix/manifest.mdx index 10cc995c..2e193e15 100644 --- a/apps/docs/pages/appendix/manifest.mdx +++ b/apps/docs/pages/appendix/manifest.mdx @@ -8,10 +8,6 @@ A Manifest is a config file that allows external applications and decentralized If you have followed instructions on the [How to create a Live app(comming soon)](/) page, you should now be ready to interact with the Dapp directly from Ledger Live interface to make sure all the basic features work as expected. -### Ethereum Dapp Browser - -Your DApp will be ran inside the Ethereum Dapp Browser, which is a separate application loaded inside Ledger Live to handle interactions between a Dapp and the Ledger Live application. Don’t hesitate to have a look at this project’s Readme to have more information on how to use it and what are the currently supported RPC calls. - ### Manifest properties To test and integrate your application, you first need to write your application Manifest file. This file must contain some mandatory information, such as the app package names, the components, the permissions needed, the hardware and software features, etc. @@ -120,22 +116,13 @@ _Complete manifest.json file with default or examples values :_ { "id": "ReplaceAppName", "name": "ReplaceAppName", - "url": "http://localhost:3000/", + "url": "http://localhost:3000", "params": { - "dappUrl": "http://localhost:3000/", - "nanoApp": "ReplaceAppName", - "dappName": "ReplaceAppName", - "networks": [ - { - "currency": "ethereum", - "chainID": 1, - "nodeURL": "..." - } - ] + "exampleParam": "value" }, "homepageUrl": "http://localhost:3000/", "platform": ["ios","android","desktop"], - "apiVersion": "^1.0.0", + "apiVersion": "^2.0.0", "manifestVersion": "2", "branch": "stable", "categories": ["NFT", "Swap", "YourAppCategory"], @@ -153,3 +140,93 @@ _Complete manifest.json file with default or examples values :_ "visibility": "complete" } ``` + +## Manifest Overrides Guide + +### Introduction to Overrides + +In the context of app manifests, the **overrides** feature offers a powerful mechanism to create conditional modifications to your manifest. With this feature, you can specify different values for specific conditions, such as Ledger Live versions (`llVersion`) and device (`platform`). This ensures a tailored experience across multiple versions and platforms without the need for separate manifest files. + +### Structure of Overrides + +Inside your manifest, you can include an `overrides` section to define conditions and their corresponding modifications. Here's how you structure them: + +1. **ledgerLiveVersion Overrides**: Allows you to define variations of the manifest specific to different Ledger Live versions. + + **Example**: + ```json + "overrides": { + "ledgerLiveVersion": { + "1.0.0": { + "name": "overrided manifest" + } + } + } + ``` + In this example, users with Ledger Live version `1.0.0` will see the app name as "overrided manifest". + +2. **Platform Overrides**: Enables you to tailor the manifest for specific platforms like iOS, Android, etc. + + **Example**: + ```json + "overrides": { + "platform": { + "ios": { + "name": "overrided for iOS" + }, + "android": { + "name": "overrided for Android" + } + } + } + ``` + Depending on the user's device platform, they will see a different app name – "overrided for iOS" on Apple devices and "overrided for Android" on Android devices. + +### Depth Limitation in Overrides + +It's important to note that only the first depth of fields can be overridden. This means you can't make granular changes to nested properties. If you need to override a field with nested properties, you must redefine the entire field, including all nested properties. + +**For example**, you can't override just a nested `url` inside a `params` field like this: +```json +"overrides": { + "platform": { + "ios": { + "params": { + "url": "new-url" + } + } + } +} +``` +Instead, you need to redefine the entire `params` field: +```json +"overrides": { + "platform": { + "ios": { + "params": { + "url": "new-url", + "anotherField": "value", + "yetAnotherField": "anotherValue" + } + } + } +} +``` + +### Activating Overrides + +Overrides come into play when the manifest is requested with specific parameters. Here are the supported parameters and how they activate the overrides: + +1. **ledgerLiveVersion**: Activated by calling with the `llVersion` parameter. + - **Example**: `http://localhost:3000/api/v1/apps?llVersion=1.0.0` + +2. **Platform**: Activated by calling with the `platform` parameter. The `platforms` field inside the manifest will be replaced accordingly. + - **Example**: `http://localhost:3000/api/v1/apps?platform=ios` will generate all manifests for iOS and replace the `platforms` field in the manifest with `["ios"]`. + +3. **Combining Parameters**: You can combine multiple parameters to activate multiple overrides. + - **Example**: `http://localhost:3000/api/v1/apps?llVersion=1.0.0&platform=ios` will apply overrides for both Ledger Live version `1.0.0` and the `iOS` platform. + + +### Priority in Overrides + +In cases where both `ledgerLiveVersion` and `platform` might have overriding values for the same field, the priority is determined by their order in the manifest. Whichever is higher takes precedence. From eae3598bdc2bfcf6dfc2de789ef46e3e0df15362 Mon Sep 17 00:00:00 2001 From: Anthony Goussot <73408295+ComradeAERGO@users.noreply.github.com> Date: Wed, 18 Oct 2023 09:52:33 +0200 Subject: [PATCH 2/2] docs(tutorial): Build a live app from the ground up (#239) * docs(tutorial): Build a live app from the ground up * docs(tutorial): Add Next Scaffolding and references --- apps/docs/pages/examples/_meta.json | 3 + .../examples/live-app-creation/_meta.json | 6 + .../live-app-creation/configuration.mdx | 105 +++++++++++++++ .../examples/live-app-creation/hooking-up.mdx | 123 ++++++++++++++++++ .../examples/live-app-creation/manifest.mdx | 61 +++++++++ .../examples/live-app-creation/start.mdx | 88 +++++++++++++ 6 files changed, 386 insertions(+) create mode 100644 apps/docs/pages/examples/live-app-creation/_meta.json create mode 100644 apps/docs/pages/examples/live-app-creation/configuration.mdx create mode 100644 apps/docs/pages/examples/live-app-creation/hooking-up.mdx create mode 100644 apps/docs/pages/examples/live-app-creation/manifest.mdx create mode 100644 apps/docs/pages/examples/live-app-creation/start.mdx diff --git a/apps/docs/pages/examples/_meta.json b/apps/docs/pages/examples/_meta.json index c0dd9748..16ad16ed 100644 --- a/apps/docs/pages/examples/_meta.json +++ b/apps/docs/pages/examples/_meta.json @@ -1,4 +1,7 @@ { + "live-app-creation": { + "title": "Build a live app from scratch" + }, "test-live-app": { "title": "Test your live app" } diff --git a/apps/docs/pages/examples/live-app-creation/_meta.json b/apps/docs/pages/examples/live-app-creation/_meta.json new file mode 100644 index 00000000..7b96352c --- /dev/null +++ b/apps/docs/pages/examples/live-app-creation/_meta.json @@ -0,0 +1,6 @@ +{ + "start": "Start here", + "configuration": "Configuration", + "hooking-up": "Hooking up", + "manifest": "Import your app in Ledger Live" +} diff --git a/apps/docs/pages/examples/live-app-creation/configuration.mdx b/apps/docs/pages/examples/live-app-creation/configuration.mdx new file mode 100644 index 00000000..0b2a58a1 --- /dev/null +++ b/apps/docs/pages/examples/live-app-creation/configuration.mdx @@ -0,0 +1,105 @@ +import { Callout } from "nextra/components"; + +### 4. **Configuring Ledger's Wallet API** + +To interact with Ledger Live, you'll need to configure the Ledger's Wallet API. The first step is to install the necessary packages, and then set up the appropriate configuration through a transport layer named "Transport". This transport layer will enable communication with the Wallet API. + +- **Installing Packages**: + Install the necessary packages using npm: + + ```sh + npm install @ledgerhq/wallet-api-client @ledgerhq/wallet-api-client-react + ``` + +- **Creating Transport Provider**: + Create a file named `TransportProvider.tsx`. This file will contain a component that utilizes the Ledger Wallet API client to create a communication transport Higher Order Component (HOC). + + ```jsx + // src/TransportProvider.tsx + import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react"; + import { Transport, WindowMessageTransport } from "@ledgerhq/wallet-api-client"; + + function TransportProvider({ children }) { + function getWalletAPITransport(): Transport { + if (typeof window === "undefined") { + return { + onMessage: undefined, + send: () => {} + }; + } + + const transport = new WindowMessageTransport(); + transport.connect(); + return transport; + } + + const transport = getWalletAPITransport(); + + return ( + {children} + ); + } + + export default TransportProvider; + ``` + +- **Wrapping App with TransportProvider**: + In your root file, wrap your `` with the `TransportProvider`: + + ```jsx + // src/index.tsx or src/index.js + import React from 'react'; + import ReactDOM from 'react-dom'; + import App from './App'; + import TransportProvider from './TransportProvider'; + + ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render( + + + + + + ); + ``` + +With this setup, your entire application can access Ledger's Wallet API and communicate with it via the `TransportProvider`. + +### 5. **Setting Up The Simulator** + +During the development and testing phases, the Ledger Wallet API simulator can help you develop without requiring to run Ledger Live in parallel. +You can modify your `TransportProvider.tsx` file to use the `getSimulatorTransport` function provided by the simulator library. + +```jsx +// src/TransportProvider.tsx +import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react"; +import { getSimulatorTransport, profiles } from "@ledgerhq/wallet-api-simulator"; +import type { Transport } from "@ledgerhq/wallet-api-core"; + +function TransportProvider({ children }) { + function getWalletAPITransport(): Transport { + if (typeof window === "undefined") { + return { + onMessage: undefined, + send: () => {}, + }; + } + + // Use Simulator transport + const transport = getSimulatorTransport(profiles.STANDARD); + + return transport; + } + + const transport = getWalletAPITransport(); + + return ( + {children} + ); +} + +export default TransportProvider; +``` + + + For more informations regarding the simulator, please checkout out [the simulator subsection](/react/simulator) + \ No newline at end of file diff --git a/apps/docs/pages/examples/live-app-creation/hooking-up.mdx b/apps/docs/pages/examples/live-app-creation/hooking-up.mdx new file mode 100644 index 00000000..f161fd35 --- /dev/null +++ b/apps/docs/pages/examples/live-app-creation/hooking-up.mdx @@ -0,0 +1,123 @@ +### 6. **Fetching Account Information** + +With your environment set up, you can now start interacting with the Ledger Wallet API. Create a new file under the `/hooks` directory named `useAccounts.tsx`. This file will house a custom hook to fetch user account information using the `useAccounts` hook provided by Ledger. + +```jsx +// src/hooks/useAccounts.tsx +import { useAccounts } from "@ledgerhq/wallet-api-client-react"; + +function useUserAccounts() { + const { accounts, loading, error } = useAccounts(); + + return { + accounts, + loading, + error, + }; +} + +export default useUserAccounts; +``` + +Now, you can use this custom hook in your components to fetch and display user account information. + +### 7. **Creating Transaction Signing Functionality** + +Now that you can fetch account information, the next step is to facilitate transaction signing within your app. Create a new file under the `/hooks` directory named `useSignTransaction.tsx`. This file will contain a custom hook to sign transactions using the `useSignTransaction` hook provided by Ledger. + +```jsx +// src/hooks/useSignTransaction.tsx +import { useSignTransaction, useRequestAccount } from '@ledgerhq/wallet-api-client-react'; +import { useCallback, useState, useEffect } from 'react'; +import BigNumber from 'bignumber.js'; + +function useTransactionSigner() { + const { requestAccount, account } = useRequestAccount(); + const { signTransaction, pending, signature, error } = useSignTransaction(); + const [response, setResponse] = useState(null); + + useEffect(() => { + requestAccount(); + }, [requestAccount]); + + const handleSignTransaction = useCallback(async () => { + if (!account) return; + + const ethereumTransaction = { + family: 'ethereum', + amount: new BigNumber(1000000000000000), // 0.001 ETH in wei + recipient: '0xRecipientAddressHere', + gasPrice: new BigNumber(20000000000), // 20 Gwei + gasLimit: new BigNumber(21000), + nonce: 0, // Replace with the correct nonce + }; + + try { + const signature = await signTransaction(account.id, ethereumTransaction); + setResponse(signature); + } catch (e) { + console.error(e); + } + }, [account, signTransaction]); + + return { + handleSignTransaction, + pending, + response, + error + }; +} + +export default useTransactionSigner; +``` + +### 8. **Building User Interface** + +Now it's time to create the UI where users will interact with your app. Create a new file named `App.tsx` under the `/src` directory. + +```jsx +// src/App.tsx +import React from 'react'; +import useUserAccounts from './hooks/useAccounts'; +import useTransactionSigner from './hooks/useSignTransaction'; + +function App() { + const { accounts, loading, error } = useUserAccounts(); + const { handleSignTransaction, pending, response, error: signError } = useTransactionSigner(); + + return ( + <> +

User's Crypto Accounts

+ + {loading ? ( +

Loading...

+ ) : error ? ( +

Error: {error.message}

+ ) : ( + + )} + + + + {pending &&

Signing...

} + {signError &&

Error: {signError.toString()}

} + {response &&

Transaction signed successfully: {response.toString('hex')}

} + + ); +} + +export default App; +``` diff --git a/apps/docs/pages/examples/live-app-creation/manifest.mdx b/apps/docs/pages/examples/live-app-creation/manifest.mdx new file mode 100644 index 00000000..4495c941 --- /dev/null +++ b/apps/docs/pages/examples/live-app-creation/manifest.mdx @@ -0,0 +1,61 @@ +import { Callout } from "nextra/components"; + +### 9. **Creating a Manifest File** + +A manifest file is necessary to test your Live App inside Ledger Live. Create a `manifest.json` file at the root of your project. Here is a sample manifest you can use: + +```json +{ + "id": "SampleLiveApp", + "name": "SampleLiveApp", + "url": "http://localhost:3000/", + "params": { + "dappUrl": "http://localhost:3000/", + "nanoApp": "SampleLiveApp", + "dappName": "SampleLiveApp", + "networks": [ + { + "currency": "ethereum", + "chainID": 1, + "nodeURL": "..." + } + ] + }, + "homepageUrl": "http://localhost:3000/", + "platform": ["ios","android","desktop"], + "apiVersion": "^2.0.0", + "manifestVersion": "2", + "branch": "stable", + "categories": ["NFT", "Swap", "YourAppCategory"], + "currencies": "*", + "content": { + "shortDescription": { + "en": "Desc" + }, + "description": { + "en": "Desc" + } + }, + "permissions": [], + "domains": ["http://*"], + "visibility": "complete" +} +``` + + For more informations regarding the setting up of a manifest, please refer to [the manifest page](/appendix/manifest) + + +### 10. **Importing Manifest in Ledger Live** + +Ensure Ledger Live Desktop is installed on your computer. Enable Developer mode in Ledger Live by navigating to **Settings** -> **About**, and clicking ten times on the Ledger Live version. This will reveal a new **Developer** section in the settings menu. + +- Enable **platform dev tools**. +- Click on **Browse** next to **Add a local app** and select the manifest you created. + +Now you'll see a new row in the menu with the name of your Live App. You can now open and test your Live App within Ledger Live. + +--- + +This concludes the step-by-step guide to developing a Live App for Ledger Live from scratch. + +Have any questions or suggestions for improvement? Leave an issue in our repo or reach out to us through our Discord. \ No newline at end of file diff --git a/apps/docs/pages/examples/live-app-creation/start.mdx b/apps/docs/pages/examples/live-app-creation/start.mdx new file mode 100644 index 00000000..41c0d091 --- /dev/null +++ b/apps/docs/pages/examples/live-app-creation/start.mdx @@ -0,0 +1,88 @@ +import { FileTree } from 'nextra/components' + +# Building a Live App: A Step-by-Step Tutorial + +### 1. Introduction +A Live App is a decentralized application (DApp) that interacts with Ledger Live, a software application used for managing crypto assets on Ledger hardware wallets. By creating a Live App, developers can provide users with seamless interactions with blockchain-based applications directly through Ledger Live. This tutorial will guide you through the process of building a Live App from scratch, utilizing the Ledger Wallet API Client to facilitate interactions with the Ledger Live environment. + +### 2. Setting up the Development Environment +Before you begin building your Live App, we'll set up your development environment. This setup includes installing necessary tools and libraries that will assist in building, testing, and deploying your Live App. + +#### Scaffold a Next.js app +First, scaffold a new Next.js app using the following command: + +```sh +npx create-next-app my-app --typescript +``` +This will create a new Next.js project called my-app with TypeScript support. + +#### Node.js and npm: +Ensure that you have Node.js and npm (Node Package Manager) installed on your computer. If not, download and install the latest LTS version of Node.js from the official website, which includes npm. + +#### Text Editor: +Use a text editor of your choice. Popular choices include Visual Studio Code, Sublime Text, or Atom. + +#### Simulator: +Install the Ledger Wallet API simulator for a mock environment to ease the development and testing phases. You can install the simulator library using npm: + +```sh +npm install @ledgerhq/wallet-api-simulator +``` + +The simulator provides a mock environment with predefined responses for different Wallet API actions, allowing you to test your Live App without interacting with the real Ledger Live application. + +### 3. Creating the Project Structure +Now organize your project with a clear and manageable architecture. Here's a simple project structure to start with: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +- /src: This directory contains all your TypeScript/JavaScript files. + +- /components: This is where you’ll place your React components. + +- /hooks: This will hold custom hooks, including those for +interacting with the Ledger Wallet API. + +- /utils: Any utility functions or constant values can be stored here. + +- /assets: Place images, icons, and other static files in this directory. + +- App.tsx: This is the main file where your React application is bootstrapped. + +- /public: This directory contains public assets like the index.html file. + +- package.json: This file holds various metadata relevant to your project. + +- tsconfig.json: This is your TypeScript configuration file if you're using TypeScript. + +Now that your development environment is set up, and you have a basic project structure in place, you are ready to start building your Live App. In the next section, we'll delve into configuring the Wallet API to establish a connection with Ledger Live. \ No newline at end of file