Set up to automatically pop up Chrome extensions

Added a new parameter to the `DAppConnector` constructor that allows
defining the extension IDs that automatically pop up when pairing or
sending requests to the wallet.

This contribution includes additional functions that allow for checking
whether a specific extension is installed and responding. The available
extensions are listed under the `extensions` property of the
`DAppConnector` class. To establish a session that will automatically
activate the extension, use the `connectExtension` method instead of the
`connect` method.

Signed-off-by: Fran Fernandez <fran@kabila.app>

README.md

@@ -150,13 +150,16 @@ const dAppMetadata = {
   icons: ['<Image url>'],
 }
 
+const extensionIds = ['<Extension ID>']
+
 const dAppConnector = new DAppConnector(
   dAppMetadata,
   LedgerId.TESTNET,
   projectId,
   Object.values(HederaJsonRpcMethod),
   [HederaSessionEvent.ChainChanged, HederaSessionEvent.AccountsChanged],
   [HederaChainId.Testnet],
+  extensionIds,
 )
 await dAppConnector.init()
 ```
@@ -285,6 +288,85 @@ dAppConnector.disconnectSession(session.topic)
 dAppConnector.disconnectAllSessions()
 ```
 
+#### Extension popup
+
+By default, it is not possible to directly pop up an extension with Wallet Connect. However, to
+allow this possibility, the dAppConnector accepts a list of extension IDs. If you create the
+AppConnector with an extension ID, it will automatically send a message to the extension to
+detect if it is installed. In case the extension is installed, it will be added to the available
+extensions and its data can be found at the extensions property of dAppConnector.
+
+To connect an available extension, use the method `connectExtension(<extensionId>)`. This will
+link the extension to the signer and session. Whenever you use the signer created for this
+session, the extension will automatically open. You can find out if the extension is available
+by checking the `extensions` property.
+
+```javascript
+const dAppConnector = new DAppConnector(
+  dAppMetadata,
+  LedgerId.TESTNET,
+  projectId,
+  Object.values(HederaJsonRpcMethod),
+  [HederaSessionEvent.ChainChanged, HederaSessionEvent.AccountsChanged],
+  [HederaChainId.Testnet],
+  ['<Extension ID 1>, <Extension ID 2>'],
+)
+
+[...]
+
+dAppConnector?.extensions?.forEach((extension) => {
+  console.log(extension)
+})
+
+const extension = dAppConnector?.extensions?.find((extension) => extension.name === '<Extension name>')
+if (extension.available) {
+  await dAppConnector!.connectExtension(extension.id);
+  const signer = dAppConnector.getSigner(AccountId.fromString('0.0.12345'))
+
+  // This request will open the extension
+  const response = await signer.signAndExecuteTransaction(transaction)
+}
+```
+
+Wallets that are compatible should be able to receive and respond to the following messages:
+
+- `"hedera-extension-query-<extesnionId>"`: The extension is required to respond with
+  `"hedera-extension-response"` and provide the next set of data in the metadata property.
+  ```javascript
+  let metadata = {
+    id: '<extesnionId>',
+    name: '<Wallet name>',
+    url: '<Wallet url>',
+    icon: '<Wallet con>',
+    description: '<Wallet url>',
+  }
+  ```
+- `"hedera-extension-open-<extensionId>"`: The extension needs to listen to this message and
+  automatically open.
+- `"hedera-extension-connect-<extesnionId>"`: The extension must listen to this message and
+  utilize the `pairingString` property in order to establish a connection.
+
+This communication protocol between the wallet and web dApps requires an intermediate script to
+use the Chrome API. Refer to the
+[Chrome Extensions documentation](https://developer.chrome.com/docs/extensions/develop/concepts/messaging)
+
+To enable communication between the extension and a web dApp embedded in an iframe, the wallet
+must support the following messages:
+
+- `"hedera-iframe-query"`:The extension is required to respond with `"hedera-iframe-response"`
+  and provide the next set of data in the metadata property.
+  ```javascript
+  let metadata = {
+    id: '<extesnionId>',
+    name: '<Wallet name>',
+    url: '<Wallet url>',
+    icon: '<Wallet con>',
+    description: '<Wallet url>',
+  }
+  ```
+- `"hedera-iframe-connect"`: The extension must listen to this message and utilize the
+  `pairingString` property in order to establish a connection.
+
 ## Demo & docs
 
 This repository includes a vanilla html/css/javascript implementation with a dApp and wallet

src/lib/dapp/DAppSigner.ts

@@ -45,6 +45,7 @@ import {
   transactionBodyToBase64String,
   transactionToBase64String,
   transactionToTransactionBody,
+  extensionOpen,
 } from '../shared'
 
 export class DAppSigner implements Signer {
@@ -60,6 +61,7 @@ export class DAppSigner implements Signer {
     private readonly accountId: AccountId,
     public readonly topic: string,
     private readonly ledgerId: LedgerId = LedgerId.MAINNET,
+    public readonly extensionId?: string,
   ) {
     this.signerAccountId = `${ledgerIdToCAIPChainId(ledgerId)}:${accountId.toString()}`
     this.nodesAccountIds = [AccountId.fromString('0.0.3')]
@@ -79,6 +81,8 @@ export class DAppSigner implements Signer {
   }
 
   request<T>(request: { method: string; params: any }): Promise<T> {
+    if (this.extensionId) extensionOpen(this.extensionId)
+
     return DAppSigner.signClient.request<T>({
       topic: this.topic,
       request,

src/lib/dapp/index.ts

@@ -51,6 +51,9 @@ import {
   isSignAndExecuteTransactionParams,
   isSignTransactionParams,
   isSignAndExecuteQueryParams,
+  ExtensionData,
+  extensionConnect,
+  findExtensions,
 } from '../shared'
 import { DAppSigner } from './DAppSigner'
 import { JsonRpcResult } from '@walletconnect/jsonrpc-types'
@@ -67,6 +70,8 @@ export class DAppConnector {
   supportedEvents: string[] = []
   supportedChains: string[] = []
 
+  extensions: ExtensionData[] = []
+
   walletConnectClient: SignClient | undefined
   walletConnectModal: WalletConnectModal
   signers: DAppSigner[] = []
@@ -80,6 +85,7 @@ export class DAppConnector {
    * @param methods - Array of supported methods for the DApp (optional).
    * @param events - Array of supported events for the DApp (optional).
    * @param events - Array of supported chains for the DApp (optional).
+   * @param extensions - Array of Chrome extensions enabled to be popup when sending requests (optional).
    */
   constructor(
     metadata: SignClientTypes.Metadata,
@@ -88,18 +94,44 @@ export class DAppConnector {
     methods?: string[],
     events?: string[],
     chains?: string[],
+    extensionIds?: string[],
   ) {
     this.dAppMetadata = metadata
     this.network = network
     this.projectId = projectId
     this.supportedMethods = methods ?? Object.values(HederaJsonRpcMethod)
     this.supportedEvents = events ?? []
     this.supportedChains = chains ?? []
+    this.extensions =
+      extensionIds?.map((id) => ({
+        id,
+        available: false,
+      })) ?? []
 
     this.walletConnectModal = new WalletConnectModal({
       projectId: projectId,
       chains: chains,
     })
+
+    if (extensionIds?.length) {
+      findExtensions(
+        this.extensions.map((ext) => ext.id),
+        (metadata) => {
+          this.extensions = this.extensions.map((ext) => {
+            if (metadata.id === ext.id) {
+              return {
+                ...ext,
+                available: true,
+                name: metadata.name,
+                url: metadata.url,
+                icon: metadata.icon,
+              }
+            }
+            return ext
+          })
+        },
+      )
+    }
   }
 
   get accountIds(): AccountId[] {
@@ -197,21 +229,55 @@ export class DAppConnector {
   /**
    * Initiates the WallecConnect connection flow using URI.
    * @param pairingTopic - The pairing topic for the connection (optional).
+   * @param extensionId - The id for the extension used to connect (optional).
    * @returns A Promise that resolves when the connection process is complete.
    */
   public async connect(
     launchCallback: (uri: string) => void,
     pairingTopic?: string,
-  ): Promise<void> {
+    extensionId?: string,
+  ): Promise<SessionTypes.Struct> {
     return this.abortableConnect(async () => {
       const { uri, approval } = await this.connectURI(pairingTopic)
       if (!uri) throw new Error('URI is not defined')
       launchCallback(uri)
       const session = await approval()
+      if (extensionId) {
+        const sessionProperties = {
+          ...session.sessionProperties,
+          extensionId,
+        }
+        session.sessionProperties = sessionProperties
+        await this.walletConnectClient?.session.update(session.topic, {
+          sessionProperties,
+        })
+      }
       await this.onSessionConnected(session)
+      return session
     })
   }
 
+  /**
+   * Initiates the WallecConnect connection flow sending a message to the extension.
+   * @param extensionId - The id for the extension used to connect.
+   * @param pairingTopic - The pairing topic for the connection (optional).
+   * @returns A Promise that resolves when the connection process is complete.
+   */
+  public async connectExtension(
+    extensionId: string,
+    pairingTopic?: string,
+  ): Promise<SessionTypes.Struct> {
+    const extension = this.extensions.find((ext) => ext.id === extensionId)
+    if (!extension || !extension.available) throw new Error('Extension is not available')
+    return this.connect(
+      (uri) => {
+        extensionConnect(extension.id, uri)
+      },
+      pairingTopic,
+      extensionId,
+    )
+  }
+
   private abortableConnect = async <T>(callback: () => Promise<T>): Promise<T> => {
     return new Promise(async (resolve, reject) => {
       const pairTimeoutMs = 480_000
@@ -222,6 +288,8 @@ export class DAppConnector {
 
       try {
         return resolve(await callback())
+      } catch (error) {
+        reject(error)
       } finally {
         clearTimeout(timeout)
       }
@@ -282,7 +350,7 @@ export class DAppConnector {
     const allNamespaceAccounts = accountAndLedgerFromSession(session)
     return allNamespaceAccounts.map(
       ({ account, network }: { account: AccountId; network: LedgerId }) =>
-        new DAppSigner(account, session.topic, network),
+        new DAppSigner(account, session.topic, network, session.sessionProperties?.extensionId),
     )
   }
 

src/lib/shared/extensionController.ts

@@ -0,0 +1,49 @@
+export enum EVENTS {
+  extensionQuery = 'hedera-extension-query-',
+  extensionConnect = 'hedera-extension-connect-',
+  extensionOpen = 'hedera-extension-open-',
+  extensionResponse = 'hedera-extension-response',
+}
+
+export type ExtensionData = {
+  id: string
+  name?: string
+  icon?: string
+  url?: string
+  available: boolean
+}
+
+export const findExtensions = (
+  ids: string[],
+  onFound: (_metadata: ExtensionData) => void,
+): void => {
+  if (typeof window === 'undefined') return
+
+  window.addEventListener(
+    'message',
+    (event): void => {
+      if (event?.data?.type == EVENTS.extensionResponse && event.data.metadata) {
+        onFound(event.data.metadata)
+      }
+    },
+    false,
+  )
+
+  setTimeout(() => {
+    ids.forEach((id) => {
+      extensionQuery(id)
+    })
+  }, 200)
+}
+
+export const extensionQuery = (id: string) => {
+  window.postMessage({ type: EVENTS.extensionQuery + id }, '*')
+}
+
+export const extensionConnect = (id: string, pairingString: string) => {
+  window.postMessage({ type: EVENTS.extensionConnect + id, pairingString }, '*')
+}
+
+export const extensionOpen = (id: string) => {
+  window.postMessage({ type: EVENTS.extensionOpen + id }, '*')
+}

src/lib/shared/index.ts

@@ -24,3 +24,4 @@ export * from './events'
 export * from './methods'
 export * from './payloads'
 export * from './utils'
+export * from './extensionController'