Core configuration

Hornet uses a JSON standard format as a config file. If you are unsure about JSON syntax, have a look at the official specs here.

The default config file is named config.json. You can change the path or name of the config file by using the -c or --config argument while executing hornet executable.

For Example: hornet -c config_example.json.

You can always get the most up-to-date description of the config parameters by running hornet -h --full.

Table of content


1. REST API

NameDescriptionType
jwtAuthconfig for JWT authobject
permittedRoutesthe allowed HTTP REST routes which can be called from non whitelisted addressesarray of strings
whitelistedAddressesthe whitelist of addresses which are allowed to access the REST APIarray of strings
bindAddressthe bind address on which the REST API listens onstring
powEnabledwhether the node does PoW if messages are received via APIbool
powWorkerCountthe amount of workers used for calculating PoW when issuing messages via APIinteger
limitsconfig for api limitsobject
excludeHealthCheckFromAuthwhether to allow the health check route anywaysbool

JWT Auth

NameDescriptionType
enabledwhether to use JWT auth for the REST APIbool
saltsalt used inside the JWT tokens for the REST API. Change this to a different value to invalidate JWT tokens not matching this new valuestring

Limits

NameDescriptionType
bodyLengththe maximum number of characters that the body of an API call may containstring
maxResultsthe maximum number of results that may be returned by an endpointinteger

Example:

  "restAPI": {
    "authEnabled": false,
    "excludeHealthCheckFromAuth": false,
    "permittedRoutes": [
      "/health",
      "/mqtt",
      "/api/v1/info",
      "/api/v1/tips",
      "/api/v1/messages/:messageID",
      "/api/v1/messages/:messageID/metadata",
      "/api/v1/messages/:messageID/raw",
      "/api/v1/messages/:messageID/children",
      "/api/v1/messages",
      "/api/v1/transactions/:transactionID/included-message",
      "/api/v1/milestones/:milestoneIndex",
      "/api/v1/milestones/:milestoneIndex/utxo-changes",
      "/api/v1/outputs/:outputID",
      "/api/v1/addresses/:address",
      "/api/v1/addresses/:address/outputs",
      "/api/v1/addresses/ed25519/:address",
      "/api/v1/addresses/ed25519/:address/outputs",
      "/api/v1/treasury"
    ],
    "whitelistedAddresses": [
      "127.0.0.1",
      "::1"
    ],
    "bindAddress": "0.0.0.0:14265",
    "powEnabled": false,
    "powWorkerCount": 1,
    "limits": {
      "bodyLength": "1M",
      "maxResults": 1000
    }
  },

2. Dashboard

NameDescriptionType
bindAddressthe bind address on which the dashboard can be access fromstring
devwhether to run the dashboard in dev modebool
authconfig for dashboard authobject

Auth

NameDescriptionType
sessionTimeouthow long the auth session should last before expiringstring
usernamethe auth usernamestring
passwordHashthe auth password+salt as a scrypt hashstring
passwordSaltthe auth salt used for hashing the passwordstring

Example:

  "dashboard": {
    "bindAddress": "localhost:8081",
    "dev": false,
    "auth": {
      "sessionTimeout": "72h",
      "username": "admin",
      "passwordHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "passwordSalt": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  },

3. DB

NameDescriptionType
enginethe used database engine (pebble/bolt/rocksdb)string
paththe path to the database folderstring
autoRevalidationwhether to automatically start revalidation on startup if the database is corruptedbool
debugignore the check for corrupted databases (should only be used for debug reasons)bool

Example:

  "db": {
    "engine": "rocksdb",
    "path": "mainnetdb",
    "autoRevalidation": false,
    "debug": false,
  },

4. Snapshots

NameDescriptionType
intervalinterval, in milestones, at which snapshot files are created (snapshots are only created if the node is synced)integer
depththe depth, respectively the starting point, at which a snapshot of the ledger is generatedinteger
fullPathpath to the full snapshot filestring
deltaPathpath to the delta snapshot filestring
deltaSizeThresholdPercentagecreate a full snapshot if the size of a delta snapshot reaches a certain percentage of the full snapshot (0.0 = always create delta snapshot to keep ms diff history)float
downloadURLsURLs to load the snapshot files from.array of objects

DownloadURLs

NameDescriptionType
fulldownload link to the full snapshot filestring
deltadownload link to the delta snapshot filestring

Example:

"snapshots": {
    "interval": 50,
    "depth": 50,
    "fullPath": "snapshots/mainnet/full_snapshot.bin",
    "deltaPath": "snapshots/mainnet/delta_snapshot.bin",
    "deltaSizeThresholdPercentage": 50.0,
    "downloadURLs": [
      {
        "full": "https://source1.example.com/full_snapshot.bin",
        "delta": "https://source1.example.com/delta_snapshot.bin"
      },
      {
        "full": "https://source2.example.com/full_snapshot.bin",
        "delta": "https://source2.example.com/delta_snapshot.bin"
      }
    ]
  },

5. Pruning

NameDescriptionType
enabledwhether to delete old message data from the databasebool
delayamount of milestone cones to keep in the databaseinteger
pruneReceiptswhether to delete old receipts data from the databasebool

Example:

  "pruning": {
    "enabled": true,
    "delay": 60480,
    "pruneReceipts": false
  },

6. Protocol

NameDescriptionType
networkIDthe network ID on which this node operates onstring
bech32HRPthe HRP which should be used for Bech32 addressesstring
minPoWScorethe minimum PoW score required by the networkfloat
milestonePublicKeyCountthe amount of public keys in a milestoneinteger
publicKeyRangesList of public key ranges from the coordinatorarray of objects

PublicKeyRanges

NameDescriptionType
keypublic keystring
startMilestone start indexinteger
endMilestone end indexinteger

Example:

  "protocol": {
    "networkID": "mainnet1",
    "bech32HRP": "iota",
    "minPoWScore": 4000,
    "milestonePublicKeyCount": 2,
    "publicKeyRanges": [
      {
        "key": "7205c145525cee64f1c9363696811d239919d830ad964b4e29359e6475848f5a",
        "start": 0,
        "end": 0
      },
      {
        "key": "e468e82df33d10dea3bd0eadcd7867946a674d207c39f5af4cc44365d268a7e6",
        "start": 0,
        "end": 0
      },
      {
        "key": "0758028d34508079ba1f223907ac3bb5ce8f6bdccc6b961c7c85a2f460b30c1d",
        "start": 0,
        "end": 0
      }
    ]
  },

7. Proof of Work

NameDescriptionType
refreshTipsIntervalinterval for refreshing tips during PoW for spammer messages and messages passed without parents via APIstring

Example:

  "pow": {
    "refreshTipsInterval": "5s"
  },

8. Requests

NameDescriptionType
discardOlderThanthe maximum time a request stays in the request queuestring
pendingReEnqueueIntervalthe interval the pending requests are re-enqueuedstring

Example:

  "requests": {
    "discardOlderThan": "15s",
    "pendingReEnqueueInterval": "5s"
  },

9. Coordinator

NameDescriptionType
checkpointsconfig for checkpointsobject
intervalthe interval milestones are issuedstring
powWorkerCountthe amount of workers used for calculating PoW when issuing checkpoints and milestonesinteger
quorumconfig for quorumobject
signingconfig for signingobject
stateFilePaththe path to the state file of the coordinatorstring
tipselconfig for tip selectionobject

Checkpoints

NameDescriptionType
maxTrackedMessagesmaximum amount of known messages for milestone tipselectioninteger

Quorum

NameDescriptionType
enabledwhether the coordinator quorum is enabledbool
groupsthe quorum groups used to ask other nodes for correct ledger state of the coordinatorArray of object arrays
timeoutthe timeout until a node in the quorum must have answeredstring

Groups

NameDescriptionType
{GROUP_NAME}the qourum group used to ask other nodes for correct ledger state of the coordinatorArray of objects
{GROUP_NAME}
NameDescriptionType
aliasalias of the quorum client (optional)string
baseURLbaseURL of the quorum clientstring
userNameusername for basic auth (optional)string
passwordpassword for basic auth (optional)string

Signing

NameDescriptionType
providerthe signing provider the coordinator uses to sign a milestone (local/remote)string
remoteAddressthe address of the remote signing provider (insecure connection!)string

Tipsel

NameDescriptionType
heaviestBranchSelectionTimeoutthe maximum duration to select the heaviest branch tipsstring
maxHeaviestBranchTipsPerCheckpointmaximum amount of checkpoint messages with heaviest branch tipsinteger
minHeaviestBranchUnreferencedMessagesThresholdminimum threshold of unreferenced messages in the heaviest branchinteger
randomTipsPerCheckpointamount of checkpoint messages with random tipsinteger

Example:

  "coordinator": {
    "stateFilePath": "coordinator.state",
    "interval": "10s",
    "powWorkerCount": 15,
    "checkpoints": {
      "maxTrackedMessages": 10000
    },
    "tipsel": {
      "minHeaviestBranchUnreferencedMessagesThreshold": 20,
      "maxHeaviestBranchTipsPerCheckpoint": 10,
      "randomTipsPerCheckpoint": 3,
      "heaviestBranchSelectionTimeout": "100ms"
    },
    "signing": {
      "provider": "local",
      "remoteAddress": "localhost:12345"
    },
    "quorum": {
      "enabled": false,
      "groups": {
        "hornet": [
          {
            "alias": "hornet1",
            "baseURL": "http://hornet1.example.com:14265",
            "userName": "",
            "password": ""
          }
        ],
        "bee": [
          {
            "alias": "bee1",
            "baseURL": "http://bee1.example.com:14265",
            "userName": "",
            "password": ""
          }
        ]
      },
      "timeout": "2s"
    }
  },

10. Tangle

NameDescriptionType
milestoneTimeoutthe interval milestone timeout events are fired if no new milestones are receivedstring

Example:

  "tangle": {
    "milestoneTimeout": "30s"
  },

11. Tipsel

NameDescriptionType
maxDeltaMsgYoungestConeRootIndexToCMIthe maximum allowed delta value for the YCRI of a given message in relation to the current CMI before it gets lazyinteger
maxDeltaMsgOldestConeRootIndexToCMIthe maximum allowed delta value between OCRI of a given message in relation to the current CMI before it gets semi-lazyinteger
belowMaxDepththe maximum allowed delta value for the OCRI of a given message in relation to the current CMI before it gets lazyinteger
nonLazyconfig for tips from the non-lazy poolobject
semiLazyconfig for tips from the semi-lazy poolobject

NonLazy

NameDescriptionType
retentionRulesTipsLimitthe maximum number of current tips for which the retention rules are checked (non-lazy)integer
maxReferencedTipAgethe maximum time a tip remains in the tip pool after it was referenced by the first message (non-lazy)string
maxChildrenthe maximum amount of references by other messages before the tip is removed from the tip pool (non-lazy)integer
spammerTipsThresholdthe maximum amount of tips in a tip-pool (non-lazy) before the spammer tries to reduce theseinteger

SemiLazy

NameDescriptionType
retentionRulesTipsLimitthe maximum number of current tips for which the retention rules are checked (semi-lazy)integer
maxReferencedTipAgethe maximum time a tip remains in the tip pool after it was referenced by the first message (semi-lazy)string
maxChildrenthe maximum amount of references by other messages before the tip is removed from the tip pool (semi-lazy)integer
spammerTipsThresholdthe maximum amount of tips in a tip-pool (semi-lazy) before the spammer tries to reduce theseinteger

Example:

  "tipsel": {
    "maxDeltaMsgYoungestConeRootIndexToCMI": 8,
    "maxDeltaMsgOldestConeRootIndexToCMI": 13,
    "belowMaxDepth": 15,
    "nonLazy": {
      "retentionRulesTipsLimit": 100,
      "maxReferencedTipAge": "3s",
      "maxChildren": 30,
      "spammerTipsThreshold": 0
    },
    "semiLazy": {
      "retentionRulesTipsLimit": 20,
      "maxReferencedTipAge": "3s",
      "maxChildren": 2,
      "spammerTipsThreshold": 30
    }
  },

12. Node

NameDescriptionType
aliasthe alias to identify a nodestring
profilethe profile the node runs withstring
disablePluginsa list of plugins that shall be disabledarray of strings
enablePluginsa list of plugins that shall be enabledarray of strings

Example:

  "node": {
    "alias": "Mainnet",
    "profile": "auto",
    "disablePlugins": [
      "Warpsync"
    ],
    "enablePlugins": [
      "Prometheus",
      "Spammer"
    ]
  },

13. P2P

NameDescriptionType
bindMultiAddressesthe bind addresses for this nodearray of strings
connectionManagerconfig for connection managerobject
gossipUnknownPeersLimitmaximum amount of unknown peers a gossip protocol connection is established tointeger
identityPrivateKeyprivate key used to derive the node identity (optional)string
peerStoreconfig for peer storeobject
reconnectIntervalthe time to wait before trying to reconnect to a disconnected peerstring

ConnectionManager

NameDescriptionType
highWatermarkthe threshold up on which connections count truncates to the lower watermarkinteger
lowWatermarkthe minimum connections count to hold after the high watermark was reachedinteger

PeerStore

NameDescriptionType
paththe path to the peer storestring

Example:

  "p2p": {
    "bindMultiAddresses": [
      "/ip4/127.0.0.1/tcp/15600"
    ],
    "connectionManager": {
      "highWatermark": 10,
      "lowWatermark": 5
    },
    "gossipUnknownPeersLimit": 4,
    "identityPrivateKey": "",
    "peerStore": {
      "path": "./p2pstore"
    },
    "reconnectInterval": "30s"
  },

14. Logger

NameDescriptionType
levelthe minimum enabled logging level. Valid values are: "debug", "info", "warn", "error", "dpanic", "panic", "fatal"string
disableCallerstops annotating logs with the calling function's file name and line numberbool
encodingsets the logger's encoding. Valid values are "json" and "console"string
outputPathsa list of URLs, file paths or stdout/stderr to write logging output toarray of strings

Example:

  "logger": {
    "level": "info",
    "disableCaller": true,
    "encoding": "console",
    "outputPaths": [
      "stdout",
      "hornet.log"
    ]
  },

15. Warpsync

NameDescriptionType
advancementRangethe used advancement range per warpsync checkpointinteger

Example:

  "warpsync": {
    "advancementRange": 150,
  }

16. Spammer

NameDescriptionType
messagethe message to embed within the spam messagesstring
indexthe indexation of the messagestring
indexSemiLazythe indexation of the message if the semi-lazy pool is used (uses "index" if empty)string
cpuMaxUsageworkers remains idle for a while when cpu usage gets over this limit (0 = disable)float
mpsRateLimitthe rate limit for the spammer (0 = no limit)float
workersthe amount of parallel running spammersinteger
autostartautomatically start the spammer on node startupbool

Example:

  "spammer": {
    "message": "Binary is the future.",
    "index": "HORNET Spammer",
    "indexSemiLazy": "HORNET Spammer Semi-Lazy",
    "cpuMaxUsage": 0.5,
    "mpsRateLimit": 0,
    "workers": 1,
    "autostart": false
  },

17. MQTT

NameDescriptionType
bindAddressbind address on which the MQTT broker listens onstring
wsPortport of the WebSocket MQTT brokerinteger
workerCountnumber of parallel workers the MQTT broker uses to publish messagesinteger

Example:

  "mqtt": {
    "bindAddress": "localhost:1883",
    "wsPort": 1888,
    "workerCount": 100
  },

18. Profiling

NameDescriptionType
bindAddressthe bind address on which the profiler listens onstring

Example:

  "profiling": {
    "bindAddress": "localhost:6060"
  },

19. Prometheus

NameDescriptionType
bindAddressthe bind address on which the Prometheus exporter listens onstring
fileServiceDiscoveryconfig for file service discoveryobject
databaseMetricsinclude database metricsbool
nodeMetricsinclude node metricsbool
gossipMetricsinclude gossip metricsbool
cachesMetricsinclude caches metricsbool
restAPIMetricsinclude restAPI metricsbool
migrationMetricsinclude migration metricsbool
coordinatorMetricsinclude coordinator metricsbool
debugMetricsinclude debug metricsbool
goMetricsinclude go metricsbool
processMetricsinclude process metricsbool
promhttpMetricsinclude promhttp metricsbool

FileServiceDiscovery

NameDescriptionType
enabledwhether the plugin should write a Prometheus 'file SD' filebool
paththe path where to write the 'file SD' file tostring
targetthe target to write into the 'file SD' filestring

Example:

  "prometheus": {
    "bindAddress": "localhost:9311",
    "fileServiceDiscovery": {
      "enabled": false,
      "path": "target.json",
      "target": "localhost:9311"
    },
    "databaseMetrics": true,
    "nodeMetrics": true,
    "gossipMetrics": true,
    "cachesMetrics": true,
    "restAPIMetrics": true,
    "migrationMetrics": true,
    "coordinatorMetrics": true,
    "debugMetrics": false,
    "goMetrics": false,
    "processMetrics": false,
    "promhttpMetrics": false
  }

20. Gossip

NameDescriptionType
streamReadTimeoutthe read timeout for reads from the gossip streamstring
streamWriteTimeoutthe write timeout for writes to the gossip streamstring

Example:

  "gossip": {
    "streamReadTimeout": "1m",
    "streamWriteTimeout": "10s",
  }

21. Debug

NameDescriptionType
whiteFlagParentsSolidTimeoutdefines the the maximum duration for the parents to become solid during white flag confirmation API callstring

Example:

  "debug": {
    "whiteFlagParentsSolidTimeout": "2s",
  }

22. Legacy

This is part the config used in the migration from IOTA 1.0 to IOTA 1.5 (Chrysalis)

22.1 Migrator

NameDescriptionType
queryCooldownPeriodthe cooldown period of the service to ask for new datastring
receiptMaxEntriesthe max amount of entries to embed within a receiptinteger
stateFilePathpath to the state file of the migratorstring

Example:

  "migrator": {
    "queryCooldownPeriod": "5s",
    "receiptMaxEntries": 110,
    "stateFilePath": "migrator.state",
  }

22.2 Receipts

NameDescriptionType
backupconfig for backupobject
validatorconfig for validatorobject

Backup

NameDescriptionType
enabledwhether to backup receipts in the backup folderbool
folderpath to the receipts backup folderstring

Validator

NameDescriptionType
apiconfig for legacy APIobject
coordinatorconfig for legacy Coordinatorobject
ignoreSoftErrorswhether to ignore soft errors and not panic if one is encounteredbool
validatewhether to validate receiptsbool

Api

NameDescriptionType
addressaddress of the legacy node APIstring
timeouttimeout of API callsstring

Coordinator

NameDescriptionType
addressaddress of the legacy coordinatorstring
merkleTreeDepthdepth of the Merkle tree of the coordinatorinteger

Example:

  "receipts": {
    "backup": {
      "enabled": false,
      "folder": "receipts",
    },
    "validator": {
      "api": {
        "address": "http://localhost:14266",
        "timeout": "5s",
      },
      "coordinator": {
        "address": "JFQ999DVN9CBBQX9DSAIQRAFRALIHJMYOXAQSTCJLGA9DLOKIWHJIFQKMCQ9QHWW9RXQMDBVUIQNIY9GZ",
        "merkleTreeDepth": 18,
      },
      "ignoreSoftErrors": false,
      "validate": false,
    },
  }