Skip to main content

Build a DApp on Hathor

Introduction​

This article is the pathway for developers on their journey to build a DApp on Hathor platform.

To do this, we will follow this flow:

  • first, we present the definition of DApp;
  • then, we outline the DApp architecture that will be considered;
  • after, we propose a sequence of milestones for your journey; and
  • finally, we detail each of these milestones that you will need to achieve.
note

DApps on Hathor leverage nano contracts. If you are not familiar with this feature, see Everything about nano contracts.

Context​

Decentralized application (DApp) is an application that runs on a blockchain system.

An application is considered decentralized when the core part of its business logic is implemented as smart contracts, and users submit blockchain transactions to perform operations on it. Not all components of a DApp need to be decentralized. Usually, the DApp team provides the front end as a web application hosted on a central server and/or as a native application published on major mobile application stores (e.g., Google Play and Appstore).

DApp architecture​

On Hathor, DApps follow the same architectural pattern as those on conventional public blockchain platforms. The following diagram presents the typical architecture of DApps on Hathor platform:

DApp architecture

Credits: icons created by annisa luthfiasari, Trevor Dsouza, rendicon, Juicy Fish, and Ralf Schmitzer from the Noun Project; and smashingstocks and, Ahmad Roaayala from Flaticon.

(1) The DApp front end comprises the application(s) (web and native) provided to users by the project (DApp) team. (2) The DApp back end comprises Hathor Network and complementary services. (3) The core business logic of the DApp is implemented as one or more nano contracts. (4) Hathor Network acts as the main part of the back end, running the core business logic, whereas its ledger (blockchain) act as the main database.

(5) Complementary services encompass all the DApp’s needs outside the scope of blockchain control. These may include meeting functional requirements, such as off-chain storage, and non-functional requirements, such as blockchain indexers. Complementary services can be decentralized, such as the indexing solution "The Graph", or centralized, such as the back-end service used in many DApps.

(6) A person accesses the DApp front end via a browser or by installing a native application on their device. The DApp front end can be provided in a centralized manner — via conventional web servers and application stores — or in a decentralized manner — e.g., IPFS and Filecoin.

Once initialized on the user's platform (web browser or native), the DApp front end establishes two connections. (7) (8) The first connection is with the back end. The connection with the back end can be made directly to Hathor Network or mediated by a centralized back-end component.

(7) In its simplest form, the DApp back end does not have a centralized service, and the front end connects directly to Hathor Network. In this case, the DApp front end alone reads the blockchain and provides functionalities to the user.

(8) For reasons such as user experience and scalability, many DApps use centralized back-end services. In this case, the DApp front end provides only the UI and connects to a centralized back-end service (9) that mediates all interactions with the blockchain.

(10) The second connection is with the user’s wallet. (11) Since it does not have access to the user’s private key, the DApp front end relies on this connection to enable the user to perform operations.

(10) Additionally, the type of connection between DApp front end and wallet depends on the user’s environment. Specifically, whether both use a web browser as a platform — e.g., DApp front end as a web application and wallet as a browser extension (like MetaMask) — or are autonomous processes, and whether or not they are on the same device — e.g., DApp front end running on a desktop web browser whereas wallet on a mobile device.

Milestones​

To build your DApp on Hathor following the presented architecture, the main specifics that your project team will need to consider are:

  • Nano contract(s)
  • Interactions with Hathor system

The following milestones outline and organize in sequence all Hathor-specifics you will need to take into account:

  1. Leveraging nano contracts
  2. Integrating DApp with Hathor Network
  3. Integrating DApp with wallets
  4. Operating DApp infrastructure

In the following sections, we will describe in detail how to leverage nano contracts (i.e., use, create, and develop them), and develop your DApp front end and complementary services on Hathor platform, within the scope of these milestones.

Leveraging nano contracts​

In any blockchain platform, smart contracts implement the core business logic of a DApp. A DApp can use one or more smart contracts, which may be created by the (DApp) project team itself or by third parties — and may already be deployed on chain. For example, "1inch" is a DEX aggregator that uses various smart contracts created by third parties.

In Hathor, smart contracts are referred to as nano contracts. Nano contracts are Hathor's approach to smart contracts. Your DApp may use one or more nano contracts, created by your team or by third parties.

To start creating and using nano contracts, you need to understand how they work. See:
Nano contracts: how it works

To develop a new blueprint see:

To perform integration tests for blueprints or test your nano contracts, see:
Set up the development environment

To know how to deploy a blueprint on chain, see:
Deploy an on-chain blueprint

Integrating DApp with Hathor Network​

Now that we have covered nano contracts, let's move on to the DApp front end. The front end can be developed similarly to how it would be on any other conventional blockchain platform. You may use the same technology stack used to develop DApp front ends on other platforms. In this regard, two integrations are required. The first is with Hathor Network.

The DApp needs to read the ledger (blockchain), especially the state of the contracts it interacts with, to provide functionalities to users. To do this, your DApp needs to integrate with Hathor Network.

The implementation of this integration may vary depending on the DApp’s architecture. The DApp front end may connect directly to a full node of Hathor Network or delegate the connection to a complementary service. The latter may be chosen to meet non-functional requirements such as user experience and scalability — for example, by using indexing services for faster blockchain queries.

It is up to your project team to decide which alternative of integration with Hathor Network will be used. Regardless, the same API should be consumed. Hathor full nodes expose an HTTP API for consumption by external systems, such as your DApp. See:
Hathor full node HTTP API reference

The second required integration is with wallet applications, which will be covered in the next section.

Integrating DApp with wallets​

The way DApps integrate with wallets depends on the support provided by each wallet application. With this in mind, this section will guide you on integrating your DApp front end specifically with Hathor’s official wallet applications (desktop and mobile). In a nutshell, Hathor official wallet applications (desktop and mobile) expose a JSON-RPC API that uses the Reown solution (formerly known as WalletConnect) as the transport protocol.

For the reference documentation of the JSON-RPC API exposed by the wallets, see:
Hathor wallet-to-DApp API reference

To know how to use the Reown solution, see:
WalletConnect sign protocol at Reown docs

Operating DApp infrastructure​

Just like a DApp on any other conventional blockchain platform, your team will need to operate the following infrastructure:

  • Central server, to host the web application, if necessary.
  • A Hathor full node instance.

To know how to operate a full node, see:
Operate full node

To understand why you need to operate a full node, see:
Why do organizations need to run a full node?

If your DApp requires multiple on-chain contracts to be created over time, you may need to operate a headless wallet. If that’s the case, see:
Use the headless wallet

To perform integration tests on Hathor nano-testnet, use the following URLs:

Public full node in nano-testnet:
https://node1.nano-testnet.hathor.network/v1a/

Tx mining service in nano-testnet:
https://txmining.nano-testnet.hathor.network/

Explorer in nano-testnet:
https://explorer.alpha.nano-testnet.hathor.network/

Command to run a local full node on nano-testnet:

./hathor-cli run_node --wallet-index --status 8080 --nano-testnet --nc-history-index --data ./data/

Additional considerations​

About your journey​

This article does not aim to cover and describe the entire development of a DApp. The milestones only address aspects specific to Hathor. Beyond these specifics, developing a DApp on Hathor is no different than it would be on other conventional public blockchain platforms. You may use the same technology stack you are already familiar with, as well as many of the libraries, SDKs, and frameworks widely used in web3 development.

Alternative DApp architectures​

The suggested journey refers to the most common DApp architecture. However, alternative architectures do exist — for example, headless DApps, where the interaction logic with the blockchain is decoupled from the user interface (UI). If this applies to you and you need assistance identifying the appropriate Hathor specifications and milestones, see the next subsection for guidance on obtaining support.

Technical support​

If you encounter any difficulties while building your DApp, please send a message to the #development channel on Hathor Discord server for assistance from the team and community members.