Connect to account with direct navigation parameters (#902)

Closes: AENG-51

To ensure users are directed to the correct LiveApp page for specific
actions (such as staking/unstaking) triggered from Ledger Live, the Acre
dapp must implement URL parameters to support direct navigation.

We want to connect to the account passed via URL. The Ledger Live App
passes the `accountId` parameter in URL when redirecting to Acre dapp.
This parameter has the following pattern
`js:2:bitcoin_testnet:<xpub>:<address_type>`. To connect to a given
account we need to get the extended public key from this parameter.

To connect to a given account by xpub we define the new option in the
provider: `tryConnectToAccountByXpub`. The Ledger Live Bitcoin provider
will try to find this account and connect.

dapp/manifests/ledger-live/ledger-live-manifest-development.json

@@ -23,6 +23,7 @@
     "account.list",
     "bitcoin.getAddress",
     "bitcoin.getPublicKey",
+    "bitcoin.getXPub",
     "transaction.signAndBroadcast",
     "custom.acre.messageSign",
     "custom.acre.transactionSignAndBroadcast"

dapp/manifests/ledger-live/ledger-live-manifest-mainnet.json

@@ -23,6 +23,7 @@
     "account.list",
     "bitcoin.getAddress",
     "bitcoin.getPublicKey",
+    "bitcoin.getXPub",
     "transaction.signAndBroadcast",
     "custom.acre.messageSign",
     "custom.acre.transactionSignAndBroadcast"

dapp/manifests/ledger-live/ledger-live-manifest-testnet.json

@@ -23,6 +23,7 @@
     "account.list",
     "bitcoin.getAddress",
     "bitcoin.getPublicKey",
+    "bitcoin.getXPub",
     "transaction.signAndBroadcast",
     "custom.acre.messageSign",
     "custom.acre.transactionSignAndBroadcast"

dapp/manifests/ledger-live/ledger-manifest-template.json

@@ -23,6 +23,7 @@
     "account.list",
     "bitcoin.getAddress",
     "bitcoin.getPublicKey",
+    "bitcoin.getXPub",
     "transaction.signAndBroadcast",
     "custom.acre.messageSign",
     "custom.acre.transactionSignAndBroadcast"

dapp/src/utils/orangekit/index.ts

@@ -107,6 +107,33 @@ async function verifySignInWithWalletMessage(
   return result.data
 }
 
+/**
+ * Finds the extended public key (xpub) of the user's account from URL. Users
+ * can be redirected to the exact app in the Ledger Live application. One of the
+ * parameters passed via URL is `accountId` - the ID of the user's account in
+ * Ledger Live.
+ * @see https://developers.ledger.com/docs/ledger-live/exchange/earn/liveapp#url-parameters-for-direct-navigation
+ *
+ * @param {string} url Request url
+ * @returns The extended public key (xpub) of the user's account if the search
+ *          parameter `accountId` exists in the URL. Otherwise `undefined`.
+ */
+function findXpubFromUrl(url: string): string | undefined {
+  const parsedUrl = new URL(url)
+
+  const accountId = parsedUrl.searchParams.get("accountId")
+
+  if (!accountId) return undefined
+
+  // The fourth value separated by `:` is extended public key. See the
+  // account ID template: `js:2:bitcoin_testnet:<xpub>:<address_type>`.
+  const xpubFromAccountId = accountId.split(":")[3]
+
+  if (!xpubFromAccountId) return undefined
+
+  return xpubFromAccountId
+}
+
 export default {
   getWalletInfo,
   isWalletInstalled,
@@ -119,4 +146,5 @@ export default {
   isWalletConnectionRejectedError,
   verifySignInWithWalletMessage,
   getOrangeKitLedgerLiveConnector,
+  findXpubFromUrl,
 }

dapp/src/utils/orangekit/ledger-live/bitcoin-provider.ts

@@ -58,9 +58,12 @@ function numberToValidHexString(value: number): string {
   return `0x${hex}`
 }
 
-export type AcreLedgerLiveBitcoinProviderOptions = {
-  tryConnectToAddress: string | undefined
-}
+export type AcreLedgerLiveBitcoinProviderOptions =
+  | {
+      tryConnectToAddress?: string
+      tryConnectToAccountByXpub?: never
+    }
+  | { tryConnectToAddress?: never; tryConnectToAccountByXpub?: string }
 
 /**
  * Ledger Live Wallet API Bitcoin Provider.
@@ -90,6 +93,7 @@ export default class AcreLedgerLiveBitcoinProvider
     network: BitcoinNetwork,
     options: AcreLedgerLiveBitcoinProviderOptions = {
       tryConnectToAddress: undefined,
+      tryConnectToAccountByXpub: undefined,
     },
   ) {
     const windowMessageTransport = new WindowMessageTransport()
@@ -115,6 +119,7 @@ export default class AcreLedgerLiveBitcoinProvider
     walletApiClient: WalletAPIClient,
     options: AcreLedgerLiveBitcoinProviderOptions = {
       tryConnectToAddress: undefined,
+      tryConnectToAccountByXpub: undefined,
     },
   ) {
     this.#network = network
@@ -140,12 +145,24 @@ export default class AcreLedgerLiveBitcoinProvider
         currencyIds,
       })
 
-      if (this.#options.tryConnectToAddress) {
+      if (
+        this.#options.tryConnectToAddress ||
+        this.#options.tryConnectToAccountByXpub
+      ) {
         for (let i = 0; i < accounts.length; i += 1) {
           const acc = accounts[i]
+          if (
+            this.#options.tryConnectToAccountByXpub &&
+            // eslint-disable-next-line no-await-in-loop
+            (await this.#walletApiClient.bitcoin.getXPub(acc.id)) ===
+              this.#options.tryConnectToAccountByXpub
+          ) {
+            this.#account = acc
+            break
+          }
+
           // eslint-disable-next-line no-await-in-loop
           const address = await this.#getAddress(acc.id)
-
           if (address === this.#options.tryConnectToAddress) {
             this.#account = acc
             break

dapp/src/wagmiConfig.ts

@@ -5,6 +5,7 @@ import { env } from "./constants"
 import { getLastUsedBtcAddress } from "./hooks/useLastUsedBtcAddress"
 import referralProgram, { EmbedApp } from "./utils/referralProgram"
 import { orangeKit } from "./utils"
+import { AcreLedgerLiveBitcoinProviderOptions } from "./utils/orangekit/ledger-live/bitcoin-provider"
 
 const isTestnet = env.USE_TESTNET
 const CHAIN_ID = isTestnet ? sepolia.id : mainnet.id
@@ -34,12 +35,19 @@ async function getWagmiConfig() {
   let createEmbedConnectorFn
   const embeddedApp = referralProgram.getEmbeddedApp()
   if (referralProgram.isEmbedApp(embeddedApp)) {
+    const lastUsedBtcAddress = getLastUsedBtcAddress()
+    const xpub = orangeKit.findXpubFromUrl(window.location.href)
+    const ledgerLiveConnectorOptions: AcreLedgerLiveBitcoinProviderOptions =
+      xpub
+        ? { tryConnectToAccountByXpub: xpub }
+        : {
+            tryConnectToAddress: lastUsedBtcAddress,
+          }
+
     const orangeKitLedgerLiveConnector =
       orangeKit.getOrangeKitLedgerLiveConnector({
         ...connectorConfig,
-        options: {
-          tryConnectToAddress: getLastUsedBtcAddress(),
-        },
+        options: ledgerLiveConnectorOptions,
       })
 
     const embedConnectorsMap: Record<