Build a DApp
Introduction
This article is the pathway for developers building a DApp (Decentralized Application) on Hathor. It focuses exclusively on the Hathor-specific decisions — the smart contract layer (nano contracts), the two required integrations (Hathor Network + wallet), and the infrastructure you'll need to operate.
Your existing web3 knowledge transfers directly. The technology stack, libraries, and architectural patterns are the same. The Hathor-specific parts are what this pathway covers.
Prerequisites
Before starting, you should:
- Understand nano contracts — Hathor's approach to smart contracts. See Everything about nano contracts if you are not already familiar.
- Have a working development environment with Node.js (or your preferred web3 stack).
- Be familiar with REST API consumption and basic blockchain concepts (transactions, wallets, UTXOs).
- If using wallet integration: a Reown (WalletConnect) project ID and access to a Hathor full node or testnet endpoint.
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:
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:
- Using nano contracts
- Integrating DApp with Hathor Network
- Integrating DApp with wallets
- Operating DApp infrastructure
In the following sections, we will describe in detail how to use nano contracts, develop your DApp front end and complementary services, and deploy and operate your DApp on Hathor platform, within the scope of these milestones.
Using 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:
To create new contracts you can use blueprints created by third parties. See:
If the existing blueprints do not meet your use case requirements, you can develop your own blueprint. See:
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:
The second required integration is with wallet applications, which will be covered in the next section.
Integrating DApp with wallets
Hathor official wallet applications (desktop and mobile) expose a JSON-RPC API using the Reown (WalletConnect) protocol. There is no browser extension wallet — all DApp-wallet communication goes through WalletConnect.
| Resource | What it covers |
|---|---|
| DApp-wallet integration architecture | Two-layer architecture (JSON-RPC + WalletConnect), connection flows, sequence diagrams |
| DApp-wallet integration development | Step-by-step implementation with code: sign client, session, listeners, RPC requests |
| Hathor wallet-to-DApp API reference | Full list of JSON-RPC methods (htr_sendNanoContractTx, htr_getAddress, etc.) |
| Reown docs | WalletConnect SDK documentation (sign client, modal, session management) |
For E2E testing, set up a localnet to run a self-contained Hathor network locally before going to testnet.
Operating DApp infrastructure
After completing E2E tests in your 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.
For how to operate a full node, see:
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:
For how to connect your full node to a public network, see:
What’s next?
- Develop a blueprint: if you need to build a custom nano contract blueprint for your DApp.
- Full node pathway: comprehensive reference for operating the full node your DApp depends on.
- Headless wallet pathway: if your DApp needs to programmatically create or manage contracts on-chain.
- Public networks: connect your infrastructure to testnet for staging, then to mainnet for production.
- Miscellaneous: support channels, security disclosure, and community resources.