Skip to main content

Node Configuration and Strategies

Node strategies allow for much more detailed and granular control over your node's behavior and its interaction with the protocol, making this feature primarily suited for advanced users. These strategies enable you to effectively manage your node by configuring settings such as the threshold for ticket aggregation, the redemption process, and more. To modify or manage these strategies, you will need to implement a configuration file.

Create and apply configuration file to your node​

Please select your platform:

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

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

(2) Feel free to customize the strategy settings to suit your specific needs. For detailed guidance, refer to the section: understanding node strategies.

(3) Navigate to the ".hopr-id-dufour" directory on your machine and upload the newly created configuration file there. Ensure that the configuration file is named "hoprd-docker.cfg.yaml".

(4) After uploading the configuration file, stop your current node.

(5) 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 -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 '<SECRET_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.

(7) Paste your Docker command into the terminal window and execute it.

(8) 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​

host​

Specifies host to listen on for the HOPR P2P protocol.

host:
  address: !IPv4 1.2.3.4 # Add your publc IP address here
  port: 9091
SettingsDefault valueDescription
addressThe public IP address of the machine where the node is running. Make sure to include !IPv4 before entering the public IP address.
port9091Listening on TCP & UDP ports.

db​

Specifies details for the database used by the HOPR node.

db:
  data: /app/hoprd-db
  initialize: true
  force_initialize: false
SettingsDescription
dataSpecifies the path to the database directory. For Docker users, the path is "/app/hoprd-db". For Dappnode users, the path is "/app/hoprd-db/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.
force_initializeDefaults to "false". If set to "true", any existing database in the specified directory will be overwritten and re-initialized.

heartbeat​

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

heartbeat:
  interval: 60
  threshold: 60
  variance: 2
SettingsDescription
intervalInterval in which the heartbeat is triggered in seconds.
thresholdThe time interval for which to consider peer heartbeat renewal in seconds.
varianceRound-to-round variance to complicate network sync in seconds.

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.2
  quality_offline_threshold: 0.5
  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
min_delayMinimum delay (seconds) will be multiplied by backoff, it will be half the actual minimum value.
max_delayMaximum delay in seconds.
quality_bad_thresholdQuality threshold since a node is considered having "bad" connectivity.
quality_offline_thresholdQuality threshold from which a node is considered available enough to be used.
quality_stepQuality step on failed/successful ping probe.
quality_avg_window_sizeSize of the quality moving average window.
ignore_timeframeIndicates how long (in seconds) a node is considered "ignored".
backoff_exponentBackoff exponent when probing nodes.
backoff_minMinimum backoff (in seconds) when probing nodes.
backoff_maxMaximum backoff (in seconds) when probing nodes.

protocol​

Configuration of various HOPR sub-protocols.

  protocol:
    ack:
      timeout: 15
    heartbeat:
      timeout: 15
    msg:
      timeout: 15
    ticket_aggregation:
      timeout: 15
SettingsDescription
ackMessage acknowledgement sub-protocol configuration.
timeoutTimeout in seconds.
heartbeatHeartbeat sub-protocol configuration.
msgMessage sub-protocol configuration.
ticket_aggregationTicket aggregation sub-protocol configuration.

chain​

Blockchain specific configuration.

chain:
    provider: https://gnosis-rpc.publicnode.com
    announce: true
    network: dufour
    check_unrealized_balance: true
SettingsDescription
providerRPC provider URL to use. You should add your own provider for better performance. Additional information can be found here.
announceIndicates whether the node should announce itself on-chain.
networkWhich blockchain network should be used by the node.
check_unrealized_balanceIndicates whether the node should check channel unrealized balance when validating acknowledged tickets. We are strongly recommended to leave this enabled.

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_transaction_service_providerThe node's safe transaction provider, such as https://safe-transaction.prod.hoprtech.net/
safe_addressNode's safe address, this must be provided by the user.
module_addressNode's module address, this must be provided by the user.

transport​

Transport related configuration.

transport:
  announce_local_addresses: false
  prefer_local_addresses: false
SettingsDescription
announce_local_addressesDetermines whether local addresses should be announced on-chain. Set to true for testing purposes only.
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: 'change_me'
  private_key: ''
SettingsDescription
fileThe path to the identity file. If no file exists at the specified location, a new one will be created.
passwordThe database password used to access the identity file. For guidance on creating a secure database password, please refer to this guide.
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 # Change to your own token
  host:
    address: !IPv4 0.0.0.0
    port: 3001
SettingsDescription
enableIndicates whether the REST API should be enabled. Possible values: "true" or "false".
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.
hostDefines the local interface host where the API should listen.
addressThe address of the local interface to listen on.
portThe REST API TCP lsiten port.

inbox​

HOPRd Message Inbox configuration

inbox:
  capacity: 512
  max_age: 900
  excluded_tags: [ 0 ]
SettingsDescription
capacityCapacity of messages in the Inbox, per message tag.
max_ageThe maximumm age of a message in the inbox in seconds.
excluded_tagsTags which are not allowed into the inbox.

Understanding node strategies​

Node strategies should be in the configuration file!

strategy​

In this section, you can configure various strategies for your node, enabling you to optimize its performance and behavior to meet your specific requirements. Explore the available strategies below:

strategy:
  on_fail_continue: true
  allow_recursive: false
  strategies:
    
    - !Promiscuous
      max_channels: 10
      network_quality_threshold: 0.5
      new_channel_stake: "1000000000000000000 HOPR"
      minimum_node_balance: "1000000000000000000 HOPR"
      min_network_size_samples: 20
      enforce_max_channels: true
      minimum_peer_version: ">=2.1.0"
    
    - !AutoFunding
      funding_amount: "1000000000000000000 HOPR"
      min_stake_threshold: "1000000000000000000 HOPR"
    
    - !Aggregating
      aggregation_threshold: 100
      unrealized_balance_ratio: 0.9
      aggregation_timeout: 60
      aggregate_on_channel_close: true
    
    - !AutoRedeeming
      redeem_only_aggregated: true
      minimum_redeem_ticket_value: "30000000000000000000 HOPR"
      on_close_redeem_single_tickets_value_min: "90000000000000000 HOPR"

    - !Passive
    
    - !ClosureFinalizer
      max_closure_overdue: 3600
info

HOPR token amounts are measured with 18 decimal places. When setting a custom value, be sure to add 18 zeros to the integer value. For example, 1 HOPR Token should be entered as 1000000000000000000 HOPR.

on_fail_continue​

When set to "true," the system will stop executing the subsequent strategies if any of the previous ones fail.

allow_recursive​

Allows nesting strategies through !MultiStrategy.

strategies​

Contains a sequence of strategies to execute in the specified order. If left empty, the node will default to using only the "!Passive" strategy.

Strategy: !Promiscuous​

Defines a promiscuous strategy that automatically manages HOPR channels based on certain measured qualities of other HOPR nodes in the network.

SettingsDescription
max_channelsThe maximum number of opened channels the strategy should maintain.
network_quality_thresholdA quality threshold between 0 and 1 used to determine whether the strategy should open a channel with the peer. Only nodes above this threshold will be chosen for channels.
new_channel_stakeThe stake of tokens that should be allocated to a channel opened by the strategy.
minimum_node_balanceThe minimum token balance of the node. When reached, the strategy will not open any new channels.
min_network_size_samplesThe minimum number of network quality samples before the strategy can start making decisions.
enforce_max_channelsWhen set to "true", the strategy will forcefully close channels, even with peers that exceed the "network_quality_threshold", if the total number of opened outgoing channels (whether opened by the strategy or manually) surpasses the maximum limit.
minimum_peer_versionSpecifies minimum node version of the peer the strategy should open a channel to. Accepts semver syntax.
Strategy: !AutoFunding​

Automatically funds channels with a specified amount if the stake on any channel falls below the defined threshold.

SettingsDescription
funding_amountThe amount to automatically fund a channel when its stake drops below the threshold.
min_stake_thresholdThe minimum stake value at which the channel will be automatically funded.
Strategy: !Aggregating​

Automatically aggregates tickets when the number of unredeemed tickets in a channel exceeds the specified threshold.

SettingsDefault valueDescription
aggregation_threshold100Number of acknowledged winning tickets in a channel that triggers the ticket aggregation in that channel when exceeded.
unrealized_balance_ratio0.9The percentage of unredeemed ticket value in a channel that, when exceeded, triggers ticket aggregation for that channel.
aggregation_timeoutMaximum time to wait for the ticket aggregation to complete.
aggregate_on_channel_closetrueWhen set to "true", the strategy will automatically aggregate tickets in channels that have transitioned to the "PendingToClose" state.
Strategy: !AutoRedeeming​

Automatically aggregates tickets when the number of unredeemed tickets in a channel exceeds the specified threshold.

SettingsDefault valueDescription
redeem_only_aggregatedtrueWhen set to "true", the strategy will redeem only aggregated tickets.
minimum_redeem_ticket_value30000000000000000000 HOPRThe strategy will only redeem an acknowledged winning ticket if its value is at least this specified amount of HOPR. If the value is set to 0, the strategy will redeem tickets regardless of their value.
on_close_redeem_single_tickets_value_min90000000000000000 HOPRThe strategy will automatically redeem if there's a single ticket left when a channel transitions to "PendingToClose" and it has at least this value of HOPR.
Strategy: !Passive​

A strategy that does nothing. This is equivalent to leaving the strategies array empty.

Strategy: !ClosureFinalizer​

Monitors channels in the "PendingToClose" state whose channel closure grace period has elapsed, and issues a channel close transaction on these channels to finalize the closure.

SettingsDefault valueDescription
max_closure_overdue3600It won't attempt to finalize the closure of channels that have been overdue for more than provided amount of seconds.

Table of Contents