Full node highlighted configurations

Introduction

This article complements the full node configuration reference. It does not cover all possible configurations. Instead, it only details configurations that require further explanations and/or additional steps, namely:

• Select network instance
• Enable ledger events producer

Each of the following sections covers one of these configurations. Now, For all possible configurations, see Hathor core CLI.

Select network instance

By default, the full node connects to Hathor Network mainnet. At the time of writing (Jul 26, 2025), Hathor Network has three official public instances:

• mainnet
• testnet
• nano-testnet

mainnet

If you do not specify any option/environment variable for a different network instance, the full node will start and attempt to connect to the mainnet. However, at the time of writing (Jul 26, 2025), mainnet operates with a whitelist — i.e., only peers whose id is on the whitelist can connect to the network.

To add your full node to the whitelist, follow this procedure:

1. Start a shell session.
2. Change the working directory to where you installed your full node.
3. Use hathor-cli to generate file peer_id.json:

Source code

cd hathor-core && poetry run hathor-cli gen_peer_id > ../peer_id.json

Docker

docker run \
  hathornetwork/hathor-core \
  gen_peer_id > peer_id.json

peer_id.json contains your node’s identity on the network. For example:

peer_id.json

{
    "id": "c35b69ef2a5a528c221b6923bcaaf538f03a8cecd87bd155e0d2f6fd4f932362",
    "entrypoints": [],
    "pubKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAspy7i+lCrpzSrErQmRqFzpkundR35O9qbw85/KEjGFgl3xOV/iKk72thTm5LCfZHQoO6/38gATycWwiXZCBYufKjIMd0dxLCt6omAfqogGxc/iccVSuFuwh1VMHt3mBLeVXVAZ2aYrWfENAUVZEbRT5yZVlkhkGiGK28wCWUJayaNUUpkDJ5EBaKGmX9mezz3L3F+lhdKMuYCbUfmT33GY52/bTR7zyjytAjJjzTnzOWGkFLYewJgNqMsGr1yqFfF1vS3fAFw8K1OL9CzXYszvC8HUpjUTScNg1iMqfC7D9igfRNH/5PeVvtjWIWlvCpRPPVthX1bKuHwB2oq4zOdwIDAQAB",
    "privKey": "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCynLuL6UKunNKsStCZGoXOmS6d1Hfk72pvDzn8oSMYWCXfE5X+IqTva2FObksJ9kdCg7r/fyABPJxbCJdkIFi58qMgx3R3EsK3qiYB+qiAbFz+JxxVK4W7CHVUwe3eYEt5VdUBnZpitZ8Q0BRVkRtFPnJlWWSGQaIYrbzAJZQlrJo1RSmQMnkQFooaZf2Z7PPcvcX6WF0oy5gJtR+ZPfcZjnb9tNHvPKPK0CMmPNOfM5YaQUth7AmA2oywavXKoV8XW9Ld8AXDwrU4v0LNdizO8LwdSmNRNJw2DWIyp8LsP2KB9E0f/k95W+2NYhaW8KlE89W2FfVsq4fAHairjM53AgMBAAECggEACvOuUklmw9Ms3dCmksS8EKt23smg4mJFyfKKkTGGN99rzw5h45fXOjEA4fDEXCOEQhFWvYTbfwfq5HAV7FdJaXl1xDRGsWhulRlzRCrM+zbpytG2HIjTJeFCZISRo9GOvy1iprs1tLjDPKItpQOFQw0tsYY2Mj9DA7Vfff6v41FkLb5+mRjmC1H3aQQ5fsFx/4phKw45Due7GrbyS+uXL5Nvij28cnD4v0evozH11BF1BbJ/QUFXQLOKPQXmODMUgZaHBGaF6PL8eczZ8pxhOAUTsB98ZsXEAe4x447SJw45ZJ8LQ1qouyUnYBTITq/gWkKgvAs4GzPAYtR+5FP6fQKBgQDvOfKyWn5jNcr0apuLiu+C9zCWqLW37uzrfRDq2AeKdupInWRoZXGc5Jvj1fAZB8XKkXRa5BtKcKcCp0xAvQo0j5mZPd0knZBGaSPS9ff9vUVvUwovBSIMUxMpjB+9OvaJM/Eil9iCQHj6GaMZPxt6ExNm4XgNAuMSMW2Plfg2MwKBgQC/IsbNPO8pvyf1b9qYF4fC0ptguf3dPyu5nMmZtFHHb8v1MHxTOuYvboGG9ToHpC8B9fVdD6mpn63TUxrelSsTrmTTisMBSlMWLbYEoMfvBQlhKbvrJZ2c7wllCXv38KW8Cr5XATFb1tHH9VANx/FGoTP7m8NC8YxY+vZySHUarQKBgD3+7n56JTbgwfAFkLnhD6EJHnZs0msQaCW/C5tQ0ON5Xc3jvBmx8HeQZzXsQ4S5FvEgMN89LjVkbGOrp38/fl2QuWWVOrI6gyE8LiSFyfbgDhaDlqgI1IINJXIm9jK8DRgRdfRZFarrum5WJoZsbFp+hxCqbcoxbVdRp+sGGoUxAoGABSjCJv4TEpRnVrerNdnEv1yB9y1uDc/LtVnnEzAL2Q9KeRbS9EgtuHAKLQNnipdC8ZGbCuUGVl7KCV8/5WwvWnulmxQuyVUhQwL+28cfPnNrWmUO/nzocTj+juyfnQSw5I+BrcWJeIom5XfYrlaMS7TEO3Fr5t2wRSKZDmKoTo0CgYACyAMJaEI0cpEJVuX8Gdv8v2Z72oROM2zmas61I2a1SUOvpIx/0c2EGT/3S8cNeVo60UZu1wlEyTGblOF9PGhAbE8UQkNdH2YrEemKS9ISmia32ZPswVGdWqbV/jrj/uRccWCNfXvLipRFfZrmowWxKLPzp4CCC0lmk78wYJKW3Q=="
}

The identity of peers on the mainnet is established through a public key cryptographic scheme. pubKey and privKey are your public and private key pair, respectively. Do not share your private key. id is the digest (hash) of the public key, which identifies your peer and must be added to the whitelist.

4. Send a message to the #development channel on Hathor Discord server requesting that your node be added to the whitelist. Provide the name/value "id": "<your_full_node_peer_id>" from your peer_id.json file. For example:

   Hello, I need to operate a new full node on Hathor Network mainnet. I request the addition of peer "id": "<your_full_node_peer_id>" to the whitelist.

5. After confirmation that your peer id has been added to the whitelist, start your full node using the option/environment variable --peer peer_id.json. For example:

Source code

poetry run hathor-cli run_node --peer ../peer_id.json --data ../data --status 8080 --wallet-index

Docker container

docker run \
  -it -p 8080:8080 -v ${PWD}/data:/data \
  hathornetwork/hathor-core \
  run_node --peer peer_id.json --data /data --status 8080 --wallet-index

Docker compose

<working_directory>/docker-compose.yml

...
services:
  full-node:
    image: hathornetwork/hathor-core
    ports:
      - "8080:8080"
    volumes:
      - ${PWD}/data:/data
    environment:
      - HATHOR_PEER=peer_id.json
      - HATHOR_DATA=/data
      - HATHOR_STATUS=8080
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
    networks:
      hathor:
        aliases:
          - full-node
    command: run_node
  ...

testnet

To connect to testnet, start your full node using the option/environment variable --testnet. For example:

Source code

poetry run hathor-cli run_node --testnet --data ../data --status 8080 --wallet-index

Docker container

docker run \
  -it -p 8080:8080 -v ${PWD}/data:/data \
  hathornetwork/hathor-core \
  run_node --testnet --data /data --status 8080 --wallet-index

Docker compose

<absolute_path_hathor_installation>/docker-compose.yml

...
services:
  full-node:
    image: hathornetwork/hathor-core
    ports:
      - "8080:8080"
    volumes:
      - ${PWD}/data:/data
    environment:
      - HATHOR_TESTNET=true
      - HATHOR_DATA=/data
      - HATHOR_STATUS=8080
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
    networks:
      hathor:
        aliases:
          - full-node
    command: run_node
    ...

nano-testnet

To connect to nano-testnet, start your full node using the option/environment variable --nano-tesnet. For example:

Source code

poetry run hathor-cli run_node --nano-testnet --data ../data --status 8080 --wallet-index

Docker container

docker run \
  -it -p 8080:8080 -v ${PWD}/data:/data \
  hathornetwork/hathor-core \
  run_node --nano-testnet --data /data --status 8080 --wallet-index

Docker compose

<absolute_path_hathor_installation>/docker-compose.yml

...
services:
  full-node:
    image: hathornetwork/hathor-core
    ports:
      - "8080:8080"
    volumes:
      - ${PWD}/data:/data
    environment:
      - HATHOR_TESTNET=true
      - HATHOR_DATA=/data
      - HATHOR_STATUS=8080
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
    networks:
      hathor:
        aliases:
          - full-node
    command: run_node
    ...

Enable ledger events producer

As the name suggests, ledger events producer is a feature for the full node to notify subscribed applications about changes in the ledger (blockchain) — e.g., new transactions, new blocks, best blockchain reorganizations, voided transactions, etc. Client applications connect and subscribe as consumers of ledger events via an asynchronous API exposed by the full node.

By default, the full node bootstraps with the ledger events producer disabled. To enable it, start your full node using the option/environment variable --enable-event-queue. For example:

Source code

poetry run hathor-cli run_node --testnet --data ../data --status 8080 --wallet-index --enable-event-queue

Docker container

docker run \
  -it -p 8080:8080 -v ${PWD}/data:/data \
  hathornetwork/hathor-core \
  run_node --testnet --data /data --status 8080 --wallet-index --enable-event-queue

Docker compose

<absolute_path_hathor_installation>/docker-compose.yml

...
services:
  full-node:
    image: hathornetwork/hathor-core
    ports:
      - "8080:8080"
    volumes:
      - ${PWD}/data:/data
    environment:
      - HATHOR_TESTNET=true
      - HATHOR_DATA=/data
      - HATHOR_STATUS=8080
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
      - HATHOR_ENABLE_EVENT_QUEUE=true
    networks:
      hathor:
        aliases:
          - full-node
    command: run_node
    ...

Events are stored in the full node's database along with the ledger. When you enable the ledger events producer on a full node synchronizing from scratch with the network, events are generated concurrently with synchronization. Now, when you enable the ledger events producer for the first time on a full node that already has an extensive ledger, it will need to generate all corresponding events during bootstrap, which typically takes a few minutes.

Note that enabling and disabling the ledger events producer can only be done when starting the full node. Additionally, if you enable the feature and then restart the full node with it disabled, an error will be triggered. To learn more about this, see Initialization failure: event queue disabled at Full node troubleshoot.

warning

If the full node discards its ledger events database and starts a new one, client applications must do the same. Otherwise, they will no longer receive new event notifications.

For example, suppose your full node operated with the ledger events producer enabled. During this period, several client applications connected to your full node’s async API and subscribed to be notified of these events. However, after a full node failure, it was necessary to sync from scratch with the network. As a result, the full node generated a new ledger event database from scratch. To receive event notifications again, client applications need to discard their event database and restart from scratch to sync with the full node’s new event database.

What's next?

• Bootstrap the full node with a snapshot of the ledger: to expedite the synchronization of the full node with its peers.

• Hathor core CLI: for the comprehensive documentation on how to configure your full node.

• Full node pathway: for how to operate this application.