Core (full node)

Introduction

This article is the central reference for teams operating a Hathor full node. It covers installation, configuration, monitoring, upgrade, CLI usage, and the HTTP and WebSocket APIs.

:::tip Do you need to run your own full node? Most integrations and DApps need to operate their own full node rather than relying on a public endpoint. See Why do organizations need to run a full node? if you're not sure. :::

Releases

• Latest version:
• Deprecated versions: v0.59 and earlier
• Release notes at GitHub

Description

Hathor core is the official and reference client for operating a full node in Hathor Network.

Functionalities

• Full node — i.e., full blockchain (ledger) and network routing
• Tools for development of Hathor system
• Support for integration of external systems with Hathor Network

info

It does not provide wallet and miner. There are specific components of Hathor system for these functionalities, which are used alongside it.

Interfaces

• CLI: for full node operation and development of Hathor.
• P2P: for communication between network nodes.
• HTTP API: for full node operation and communication with network clients (wallets, explorers, miners, etc.).
• WebSocket API: for asynchronous communication with network clients.

Installation

• Install from source code: for the development environment of Hathor core, derived clients, and blueprints.

• Install using Docker: for production environment or for the development of other software.

• Install alongside headless wallet using Docker compose: for production environment or for the development of other software, when it is necessary to run the headless wallet together.

Configuration

• Highlighted configurations: detailed explanations and additional steps for configurations that go beyond what --help covers.

• Bootstrap the full node with a snapshot of the ledger: skip waiting for full sync by bootstrapping from a ledger snapshot.

For all available configuration flags, run hathor-cli run_node --help (see CLI section).

Troubleshooting

See Core (full node) troubleshooting.

Monitoring

• Monitoring — main reference: to consult about monitoring while operating full nodes.

• Metrics: reference material regarding metrics tracked by Hathor core.

• Install a monitoring system: step-by-step to install a Prometheus-based monitoring system.

• Monitoring system — PoC: example of a Prometheus-based monitoring solution.

Upgrade

See Upgrade Hathor core.

CLI

The Hathor core CLI runs the full node and provides tools for Hathor system development. List all available subcommands:

From source code

poetry run hathor-cli help

Using Docker

docker run hathornetwork/hathor-core help

List all configuration flags for running a full node:

From source code

poetry run hathor-cli run_node --help

Using Docker

docker run hathornetwork/hathor-core run_node --help

P2P interface

The P2P interface handles communication between Hathor network nodes using a custom protocol over TLS and TCP. It is managed internally by the full node and is not directly called by external systems or DApps — no integration work is required on your side.

HTTP API

The HTTP API is the main integration point for external systems: wallets, explorers, miners, DApps, and any other software that needs to read from or interact with the Hathor Network.

See HTTP API reference.

Websocket API

Websocket API is used for asynchronous communication with network clients, complementing the HTTP API. At the moment, it supports the following use cases:

• Mining: full node notifies miners when a new block was found in the network; and miners send blocks they find to full node.
• Ledger events: full node notifies clients about ledger (blockchain) events — i.e., any change in the state of the ledger, such as new transactions, new blocks, voided inputs, and reorganizations of the best blockchain.
• Transactions history streaming: provides faster loading for wallet applications.

note

A dedicated Websocket API reference is not yet published in this documentation. For current protocol details, refer to the Hathor core repository on GitHub.

What's next?

• Integrate an external system: use the full node as part of a system integration with Hathor Network.
• Headless wallet pathway: add wallet capabilities alongside the full node.
• Build a DApp: deploy a decentralized application on Hathor.
• Public networks: connect to Hathor testnet or mainnet.

Miscellaneous

• Repository at GitHub

• Official images at Docker Hub

• Report a bug or request a feature: open an issue at Hathor core repository at GitHub.

• Ask for support: post in the #development channel on Hathor Discord for help from the Hathor team and community.