Skip to main content

Hathor full node configuration

The full node default configuration sets, among other parameters, the maximum number of subscribed addresses per connection and the maximum number of empty addresses subscribed per connection. These configurations address the gap limit considered by the node and they directly impact memory consumption. Hence, any change in the variable values related to these configurations must be seriously evaluated.

There are two configuration parameters that should be changed in the full node to support the GAP_LIMIT increase:

  • WS_MAX_SUBS_ADDRS_CONN: It defines the number of subscribed addresses per websocket connection. By default, its value is set as 200,000.
  • WS_MAX_SUBS_ADDRS_EMPTY: It also defines the number of subscribed addresses per websocket connection, but with the difference that the addresses do not have any outputs. The default value is 100.

To change the full node default behavior, you must start by creating a new .py configuration file (e.g. myconf.py). Depending on the network (testnet or mainnet) the full node will connect to, the first line of this file will accordingly change:

  1. Testnet: from hathor.conf import testnet as base
  2. Mainnet: from hathor.conf import mainnet as base

Next, the two gap limit parameters must be defined as key-value pairs to a variable SETTINGS. An example of a configuration file is:

from hathor.conf import testnet as base
SETTINGS = base.SETTINGS._replace(
    WS_MAX_SUBS_ADDRS_CONN=200000,
    WS_MAX_SUBS_ADDRS_EMPTY=40000
)
info

If this file is not in the path where python would search for modules, PYTHONPATH env var should be updated to include this path. Besides that, HATHOR_CONFIG_FILE environment variable must be set to load this configuration file.

For running the full node in a docker container, you must add the custom configuration to the command line. Here, a complete command for connecting to the testnet considering myconf.py file stored in the folder ~/hathor-data on the host:

docker run --env PYTHONPATH=/data --env HATHOR_CONFIG_FILE=myconf -ti -p 8080:8080 -p 8081:8081 -v ~/hathor-data:/data:consistent hathornetwork/hathor-core run_node --cache --status 8080 --stratum 8081 --data /data --testnet

To run the full node locally (outside a container), you must export both variables used by the custom configuration instead of passing them as --env parameters. Hence, the configuration file can be created in any folder on the file system. Considering the file is in the folder ~/hathor-custom-config, you should the following commands for connecting the full node to the testnet:

export PYTHONPATH=~/hathor-custom-config
export HATHOR_CONFIG_FILE=myconf
poetry run hathor-cli run_node --cache --cache-size 100000 --wallet-index --status 8080 --data ~/data-test --testnet

Configuration Checking​

To check the configuration file the full node has loaded, look at the first line of the log generated by it. The full node prints some information about the execution environment in the key-value format. The key "settings" indicates the configuration file being used. In the example below, the full node loaded a myconf.py file located in the /tmp/hathor/full-node-config directory.