Skip to main content
Version: v3.0.0

Node Configuration

The node configuration file enables you to customize connectivity settings, adjust node management options such as database or identity file locations, implement custom strategies, and more.

Create and apply configuration file to your node​

Please select your platform:

  1. Download HOPRd configuration file

    Download the example file specificaly for Docker: hoprd-docker.cfg.yaml

  2. (Optional) modify configuration file

    By default, the strategy settings file is pre-configured and works well as is. However, if you have a clear understanding of the settings and their implications, you can customize them to better align with your specific needs. For detailed instructions, please refer to the section: Understanding Node Strategies.

  3. Upload configuration file

    Navigate to the hoprd directory on your machine and upload the newly created configuration file there. Ensure that the configuration file is named hoprd-docker.cfg.yaml.

  4. Launch HOPRd node

    1. After uploading the configuration file, stop your current node.

    2. Once your node is stopped, add the additional parameter --configurationFilePath '/app/hoprd-db/hoprd-docker.cfg.yaml' to link your configuration file to your current docker command.

      Docker command:

      docker run \
      --pull always \
      -d --restart on-failure \
      -m 2g \
      --security-opt seccomp=unconfined \
      --platform linux/x86_64 \
      --log-driver json-file \
      --log-opt max-size=100M \
      --log-opt max-file=5 \
      -ti \
      -v $HOME/.hoprd-db-dufour/:/app/hoprd-db \
      --name hoprd \
      -p 9091:9091/tcp \
      -p 9091:9091/udp \
      -p 3001:3001 \
      -p 1422:1422/udp \
      -p 1422:1422/tcp \
      -e RUST_LOG=info \
      europe-west3-docker.pkg.dev/hoprassociation/docker-images/hoprd:stable \
      --network dufour \
      --init \
      --api \
      --announce \
      --identity /app/hoprd-db/.hopr-id-dufour \
      --data /app/hoprd-db \
      --apiHost '0.0.0.0' \
      --apiToken '<YOUR_API_TOKEN>' \
      --password 'open-sesame-iTwnsPNg0hpagP+o6T0KOwiH9RQ0' \
      --safeAddress '<SAFE_WALLET_ADDRESS>' \
      --moduleAddress '<MODULE_ADDRESS>' \
      --host '<YOUR_PUBLIC_IP>:9091' \
      --provider '<CUSTOM_RPC_PROVIDER>' \
      --configurationFilePath '/app/hoprd-db/hoprd-docker.cfg.yaml'
      note

      If you're running multiple nodes or have changed the default ports, make the necessary port adjustments accordingly.

    3. Paste your Docker command into the terminal window and execute it.

    4. Wait for about 5 minutes, then connect to your node via the HOPR Admin UI. Navigate to the CONFIGURATION page to verify that the strategy settings have been updated. If the changes aren't visible, try performing a hard refresh of the HOPR Admin UI page.

Understanding configuration file settings​

Configuration file used by the HOPR protocol. The file is written in YAML format and contains various settings related to the operation of the HOPR node. Below is a breakdown of the example file structure and the key settings within each section:

hopr:
    host:
        address: !IPv4 1.2.3.4
        port: 9091
    db:
        data: /app/data
        initialize: true
        force_initialize: false
    strategy:
        on_fail_continue: true
        allow_recursive: true
        strategies:
            - !AutoRedeeming
            redeem_only_aggregated: false
            minimum_redeem_ticket_value: "1 wxHOPR"
            - !ClosureFinalizer
            max_closure_overdue: 300
    heartbeat:
        variance: 2
        interval: 60
        threshold: 40
        max_parallel_probes: 50
    network_options:
        min_delay: 1
        max_delay: 300
        quality_bad_threshold: 0.1
        quality_offline_threshold: 0.0
        quality_step: 0.1
        quality_avg_window_size: 25
        ignore_timeframe: 120
        backoff_exponent: 1.5
        backoff_min: 2.0
        backoff_max: 300.0
    protocol:
        outgoing_ticket_winning_prob: 1
        heartbeat:
            timeout: 6
    chain:
        announce: true
        network: dufour
        provider: https://gnosis-rpc.publicnode.com
        keep_logs: true
        fast_sync: true
        enable_logs_snapshot: false
    safe_module:
        safe_transaction_service_provider: https://safe-transaction.prod.hoprtech.net
    transport:
        announce_local_addresses: false
        prefer_local_addresses: false
identity:
    file: /app/data/hopr.id
    password: #For example: 'rjVFCcqnTNJSh_8Z3P94@M2bep&Dk#UHX$agWf'
api:
    enable: true
    host:
        address: !IPv4 0.0.0.0
        port: 3001
note

The latest version of the default configuration file for all supported platforms is available in the HOPR GitHub repository.

hopr.host​

Specifies host to listen on for the HOPR P2P protocol.

host:
    address: !IPv4 1.2.3.4
    port: 9091
SettingsDefault valueDescription
host.addressThe external IP address of the machine where the node is running. Make sure to include !IPv4 before entering the external IP address. Refer to the FAQ guide to determine if your IP address meets the requirements.
host.port9091Listening on TCP & UDP ports.

hopr.db​

Specifies details for the database used by the HOPR node.

db:
    data: /app/hoprd-db
    initialize: true
    force_initialize: false
SettingsDescription
db.dataSpecifies the path to the database directory. For Docker users, the path is /app/hoprd-db. For Dappnode users, the path is /app/hoprd/data.
db.initializeDefaults to true, meaning the database will be created if it doesn't already exist. If set to false and the database is missing, the node will not start.
db.force_initializeDefaults to false. If set to true, any existing database in the specified directory will be overwritten and re-initialized.

hopr.heartbeat​

Configuration of the heartbeat mechanism for probing other nodes in the HOPR network.

heartbeat:
    max_parallel_probes: 50
    interval: 60
    threshold: 40
    variance: 2
SettingsDescription
heartbeat.max_parallel_probesThe maximum number of concurrent heartbeat probes.
heartbeat.intervalInterval in which the heartbeat is triggered in seconds.
heartbeat.thresholdThe time interval for which to consider peer heartbeat renewal in seconds.
heartbeat.varianceRound-to-round variance to complicate network sync in seconds.

hopr.network_options​

Defines how the quality of nodes in the HOPR network is evaluated.

network_options:
    min_delay: 1
    max_delay: 300
    quality_bad_threshold: 0.1
    quality_offline_threshold: 0.0
    quality_step: 0.1
    quality_avg_window_size: 25
    ignore_timeframe: 600
    backoff_exponent: 1.5
    backoff_min: 2.0
    backoff_max: 300.0
SettingsDescription
network_options.min_delayMinimum delay (seconds) will be multiplied by backoff, it will be half the actual minimum value.
network_options.max_delayMaximum delay in seconds.
network_options.quality_bad_thresholdQuality threshold since a node is considered having bad connectivity.
network_options.quality_offline_thresholdQuality threshold from which a node is considered available enough to be used.
network_options.quality_stepQuality step on failed/successful ping probe.
network_options.quality_avg_window_sizeSize of the quality moving average window.
network_options.ignore_timeframeIndicates how long (in seconds) a node is considered ignored.
network_options.backoff_exponentBackoff exponent when probing nodes.
network_options.backoff_minMinimum backoff (in seconds) when probing nodes.
network_options.backoff_maxMaximum backoff (in seconds) when probing nodes.

hopr.protocol​

Configuration of various HOPR sub-protocols.

protocol:
    outgoing_ticket_winning_prob: 1
    heartbeat:
        timeout: 7
SettingsDescription
protocol.outgoing_ticket_winning_probOutgoing ticket winning probability. Default value is 1.
protocol.heartbeat.timeoutHeartbeat sub-protocol configuration, with the timeout specified in seconds.

hopr.chain​

Blockchain specific configuration.

chain:
    provider: https://gnosis-rpc.publicnode.com
    announce: true
    network: dufour
SettingsDescription
chain.announceIndicates whether the node should announce itself on-chain.
chain.networkWhich blockchain network should be used by the node.
chain.providerRPC provider URL to use. You should add your own provider for better performance. Additional information can be found here. If you're using a local RPC endpoint, ensure the URL includes the http:// prefix followed by the IP address or localhost.
chain.keep_logsConfigures the node to retain RPC logs after processing, using more disk space but enabling future chain-node state reconciliation.
chain.fast_syncConfigures whether to use fast synchronization during node startup. This process can take anywhere from 10 to 20 minutes, depending on your hardware specifications.
chain.enable_logs_snapshotSpecifies the URL for downloading a publicly accessible tar.xz file containing SQLite logs database files.

hopr.safe_module​

Configuration of node's Safe.

safe_module:
    safe_transaction_service_provider: https://safe-transaction.prod.hoprtech.net
    safe_address: '0x0000000000000000000000000000000000000000'
    module_address: '0x0000000000000000000000000000000000000000'
SettingsDescription
safe_module.safe_transaction_service_providerThe node's safe transaction provider, such as https://safe-transaction.prod.hoprtech.net/
safe_module.safe_addressNode's safe address, this must be provided by the user.
safe_module.module_addressNode's module address, this must be provided by the user.

hopr.transport​

Transport related configuration.

transport:
    announce_local_addresses: false
    prefer_local_addresses: false
SettingsDescription
transport.announce_local_addressesDetermines whether local addresses should be announced on-chain. Set to true for testing purposes only.
transport.prefer_local_addressesDetermines whether local addresses should be preferred when connecting to a peer. Set to true for testing purposes only.

identity​

The main node's identity, defining it's on-chain and off-chain keys.

identity:
    file: /app/hoprd-db/.hopr-id-dufour
    password: 'rjVFCcqnTNJSh_8Z3P94@M2bep&Dk#UHX$agWf'
    private_key: ''
SettingsDescription
identity.fileThe path to the identity file. If no file exists at the specified location, a new one will be created.
identity.passwordThe database password used to access the identity file. For guidance on creating a secure database password, please refer to this guide.
identity.private_keyA private key that the node can use instead of an identity file. If provided, this will override the identity file.

api​

The configuration of the REST API.

api:
    enable: true
    auth: !Token YOUR_SECURITY_TOKEN
    host:
        address: !IPv4 0.0.0.0
        port: 3001
SettingsDescription
api.enableIndicates whether the REST API should be enabled. Possible values: true or false.
api.authAuthentication of the REST API. When using custom secret token, it is necessary to use !Token before secret token. Example: !Token My#S3cur1ty#Token. For guidance on creating a secret token, please refer to this guide.
api.hostDefines the local interface host where the API should listen.
api.host.addressThe address of the local interface to listen on.
api.host.portThe REST API TCP lsiten port.

Table of Contents