Skip to main content

DApp-wallet integration architecture

Introduction​

This article explains the architecture for integrating a DApp with Hathor official desktop and mobile wallet applications. By the end, you will have a clear understanding of how to design your DApp’s integration with these wallets.

TL;DR: see section key takeaways.

Overview​

The way DApps integrate with wallets depends on the support provided by each wallet application. Nonetheless, a two-layer integration architecture has become the de facto industry standard, with variations occurring only in the protocols chosen to implement the outer layer. For example, the Uniswap web application integrates with "MetaMask" via a web3 injector, and with the "Trust Wallet" mobile application via WalletConnect. The following diagram presents this two-layer integration architecture:

High-level view DApp-wallet integration architecture

In the inner layer, wallets expose a JSON-RPC API to be consumed by DApps. The message exchange in the inner layer is encapsulated by an external transport protocol. At the time of writing (Oct 10, 2024), there are two widely used transport protocol options in the web3 industry:

  • Web3 injector
  • WalletConnect

The web3 injector provides an object (web3 provider) within a JavaScript context of a browser that exposes the wallet’s JSON-RPC API. This approach is used when both wallet and DApp front end run in the browser — specifically, wallet as an extension and DApp front end as a web application. For example, MetaMask connecting to Uniswap web application.

The WalletConnect protocol establishes a session between DApp and wallet to enable secure, remote JSON-RPC message exchange. WalletConnect is used when wallet and DApp front end do not run together within the same browser environment. In this case, wallet and DApp front end may even be running on different devices. For example, Trust Wallet on an iPhone connecting to Uniswap in a browser on a MacBook (both devices operated by the same person).

Hathor official desktop and mobile wallets expose a JSON-RPC API as their inner layer and support the WalletConnect protocol 1 for DApp integration. In the following sections, we will detail the two layers for the specific case of Hathor official wallet applications.

Inner layer: JSON-RPC API​

The following diagram presents the inner layer of the integration:

DApp-wallet integration inner layer

Credits: icons created by rendicon, and Ralf Schmitzer from the Noun Project; and smashingstocks from Flaticon.

To load data into the UI, the DApp needs to read Hathor blockchain. To achieve this, the DApp must implement an HTTP client that establishes a direct connection with a full node of the network. Developers accustomed to integrating DApps with browser extension wallets like MetaMask may find this direct connection unusual. With wallet and front end running on the browser, only the wallet connects to the network, and the DApp accesses this connection via the web3 provider. However, when the outer layer is WalletConnect, the DApp does not obtain the connection from the wallet.

In a nutshell, (1) the DApp connects to a full node of the network (via HTTP API); (2) the DApp front end connects to the wallet via WalletConnect protocol; and (3) the wallet establishes its own connection to another full node of the network.

Inner layer flow​

To implement the inner layer integration, developers should consider the following flow:

  1. DApp and wallet establish a connection at the outer layer.
  2. User interacts with DApp UI, triggering a need to read blockchain data.
  3. DApp sends read request to its connected full node.
  4. Full node responds DApp’s request.
  5. DApp UI uses the data to display functionality to user.
  6. User initiates an operation.
  7. DApp begins processing user's requested operation.
  8. DApp requests specific data from wallet — e.g., address, UTXO, balance, etc.
  9. Wallet returns requested data.
  10. DApp uses the data to prepare a nano contract call for the operation.
  11. DApp requests wallet to create a transaction for the nano contract call.
  12. Wallet assembles a raw transaction for the nano contract call.
  13. Wallet prompts user to authorize the transaction.
  14. User authorizes wallet to sign the transaction.
  15. Wallet signs the transaction.
  16. Wallet submits the signed transaction to its full node.
  17. Full node confirms the transaction and responds to wallet.
  18. Wallet informs DApp that of transaction confirmation.
  19. DApp notifies user that the operation was successfully confirmed.

A single user operation may require multiple interactions with the wallet and several blockchain reads. The following sequence diagram illustrates this flow:

DApp-wallet integration inner layer

Outer layer: WalletConnect protocol​

The following diagram presents the outer layer of the integration:

DApp-wallet integration outer layer

Credits: icons created by rendicon from the Noun Project; and smashingstocks from Flaticon.

The WalletConnect protocol acts as the transport layer for RPC calls, providing a secure communication channel for message exchange. The payload of the exchanged messages consists of JSON-RPC requests/responses. DApp and wallet do not communicate directly. Instead, message exchange is mediated by a relay mechanism following a PubSub (publisher-subscriber) pattern 2.

At the time of writing (Oct 10, 2024), the only available relay for use with the WalletConnect protocol is the centralized relay service provided by Reown Cloud 3. Communication between DApp and wallet occurs over a secure channel, with messages encrypted using symmetric cryptography based on a shared key between the two.

The communication channel is identified by a unique topic shared exclusively between wallet and DApp. Messages are labeled with this topic, and both DApp and wallet subscribe to listen to it. This setup enables WalletConnect to function as a secure transport layer over websocket protocol.

This establishes a session for message exchange between DApp and wallet. The communication channel remains active for the duration of the session. If the session is terminated or expires, the associated channel is closed, and communication on the corresponding topic ceases.

In summary, establishing a session requires the DApp and wallet to use WalletConnect clients to connect to the relay service provided by Reown Cloud.

Outer layer flow​

To implement the outer layer integration, developers should consider the following flow:

  1. User initializes DApp.
  2. DApp creates a WalletConnect client.
  3. WalletConnect client connects to Reown Cloud relay service and generates a topic.
  4. DApp displays the URI (as a QR code and deep link) for pairing with the wallet.
  5. User initializes Hathor desktop/mobile wallet.
  6. Using the wallet, user scans the QR code or copies/pastes the deep link.
  7. Wallet connects to relay service and subscribes to the topic.
  8. DApp receives a notification that the wallet has paired.

From this point on, the DApp and wallet can exchange messages, with the payload consisting of RPC requests/responses. The following sequence diagram represents this flow:

DApp-wallet integration inner layer

Key takeaways​

The integration between DApps and Hathor official wallets (mobile and desktop) occurs in two layers. In the inner layer, the wallets expose a JSON-RPC API to the DApps. To enable secure and remote exchange of RPC messages between DApps and wallets, the WalletConnect protocol 1 is used as an outer layer. This protocol is part of the Reown solution. By using it, the DApp and wallet establish a session mediated by the relay service provided by Reown Cloud.

Finally, the described flows provide an overview of how the connection is established and the basic interactions between the DApp and the wallet.

Footnotes​

  1. Hathor's official desktop and mobile applications support WalletConnect protocol v2. ↩ ↩2

  2. PubSub according to Reown docs: "PubSub (also known as Publish-Subscribe) is a messaging pattern where senders of messages (publishers) do not send messages directly to receivers but instead label messages with a topic that can be listened to by subscribers. Subscribers only receive messages matching the topics that have expressed interest on." ↩

  3. Reown has plans to provide a decentralized alternative for the relay server called WalletConnect Network. To know more about it see WalletConnect Network official website. ↩