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.

Building 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.

As such, this article does not aim to cover the entire development of a DApp. Instead, it focuses on the specificities of Hathor that you need to address, organized into a sequence of proposed milestones for your journey.

note

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

Milestones​

On Hathor, DApps follow the same architectural pattern as those on conventional public blockchain platforms. If you are not familiar with this architecture, see:
DApp architecture

In its simplest form, a DApp comprises:

  • Nano contract(s) (one or more)
  • Front end

There may also be a centralized back-end service to address non-functional requirements. When developing these components, the main aspects to consider involve how to leverage nano contracts, and how to interact with the Hathor system. The following milestones outline and organize in sequence all Hathor-specifics your project team 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), develop your DApp front end and complementary services, and deploy and operate your DApp 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:

After completing unit tests for your blueprint, it’s time to perform integration tests. Alternatively, if you plan to only instantiate contracts from existing blueprints or use contracts already deployed on chain, it’s appropriate to test the behavior of these contracts before implementing your DApp's blockchain interactions and user interface. In either case, to perform these tests, you will need to run a local development environment.

To know how to launch it, see:
Launch a local development environment

Within your local environment, you can use the headless wallet to instantiate contracts from registered blueprints (i.e., create contracts), and simulate the behavior of contract users. To know how to use the headless wallet, see:
Headless wallet pathway

Integrating DApp with Hathor Network​

Now that we have covered nano contracts, let's move on to the two integrations that your DApp must have. 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. Alternatively, it can provide only the UI and delegate the connection to a centralized back-end service. In the latter case, the centralized DApp back-end service acts as a middleman between front end and blockchain. This 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:
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 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

Finally, to perform integration tests for the entire DApp, you should use the same development local environment you launched during the milestone "leveraging nano contracts". This time, add the desktop wallet to test user interactions with your DApp.

Operating DApp infrastructure​

After completing integration testing in the local development environment, you can deploy your DApp to testnet and then to mainnet. 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

Currently, the test environment for nano contracts (and therefore DApps) is nano-testnet. Nano contracts (and therefore DApps) are not yet supported in (primary) testnet and mainnet environments. To deploy your DApp on nano-testnet, use the following URLs:

tip

Example of 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​

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.