Skip to main content

Core Configuration

Hornet uses a JSON standard format as a config file. If you are unsure about JSON syntax, you can find more information in the official JSON specs.

The default config file is 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

1. REST API#

NameDescriptionType
bindAddressThe bind address on which the REST API listens onstring
jwtAuthConfig for JWT authobject
publicRoutesthe HTTP REST routes which can be called without authorization. Wildcards using * are allowed.array of strings
protectedRoutesthe HTTP REST routes which need to be called with authorization. Wildcards using * are allowed.array of strings
powEnabledWhether the node does PoW if messages are received via APIbool
powWorkerCountThe amount of workers used for calculating PoW when issuing messages via APIinteger
limitsConfiguration for api limitsobject

JWT Auth#

NameDescriptionType
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": {    "bindAddress": "0.0.0.0:14265",    "jwtAuth": {      "salt": "HORNET"    },    "publicRoutes": [      "/health",      "/mqtt",      "/api/v1/info",      "/api/v1/tips",      "/api/v1/messages*",      "/api/v1/transactions*",      "/api/v1/milestones*",      "/api/v1/outputs*",      "/api/v1/addresses*",      "/api/v1/treasury",      "/api/v1/receipts*"    ],    "protectedRoutes": [      "/api/v1/*",      "/api/plugins/*"    ],    "powEnabled": true,    "powWorkerCount": 1,    "limits": {      "bodyLength": "1M",      "maxResults": 1000    }  },

2. Dashboard#

NameDescriptionType
bindAddressThe bind address on which the dashboard can be accessed fromstring
devWhether to run the dashboard in dev modebool
authConfiguration 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/rocksdb)string
pathThe path to the database folderstring
autoRevalidationWhether to automatically start revalidation on startup if the database is corruptedbool

Example:

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

4. Snapshots#

NameDescriptionType
depthThe depth, respectively the starting point, at which a snapshot of the ledger is generatedinteger
intervalInterval, in milestones, at which snapshot files are created (snapshots are only created if the node is synced)integer
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": {    "depth": 50,    "interval": 200,    "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
milestonesMilestones based pruningobject
sizeDatabase size based pruningobject
pruneReceiptsWhether to delete old receipts data from the databasebool

Milestones#

NameDescriptionType
enabledWhether to delete old message data from the database based on maximum milestones to keepbool
maxMilestonesToKeepMaximum amount of milestone cones to keep in the databaseinteger

Size#

NameDescriptionType
enabledWhether to delete old message data from the database based on maximum database sizebool
targetSizeTarget size of the databasestring
thresholdPercentageThe percentage the database size gets reduced if the target size is reachedfloat
cooldownTimeCool down time between two pruning by database size eventsstring

Example:

  "pruning": {    "milestones": {      "enabled": false,      "maxMilestonesToKeep": 60480    },    "size": {      "enabled": true,      "targetSize": "30GB",      "thresholdPercentage": 10.0,      "cooldownTime": "5m"    },    "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": "chrysalis-mainnet",    "bech32HRP": "iota",    "minPoWScore": 4000.0,    "milestonePublicKeyCount": 2,    "publicKeyRanges": [      {        "key": "a9b46fe743df783dedd00c954612428b34241f5913cf249d75bed3aafd65e4cd",        "start": 0,        "end": 777600      },      {        "key": "365fb85e7568b9b32f7359d6cbafa9814472ad0ecbad32d77beaf5dd9e84c6ba",        "start": 0,        "end": 1555200      },      {        "key": "ba6d07d1a1aea969e7e435f9f7d1b736ea9e0fcb8de400bf855dba7f2a57e947",        "start": 552960,        "end": 2108160      }    ]  },

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
stateFilePathThe path to the state file of the coordinatorstring
intervalThe interval milestones are issuedstring
powWorkerCountThe amount of workers used for calculating PoW when issuing checkpoints and milestonesinteger
checkpointsConfiguration for checkpointsobject
tipselConfiguration for tip selectionobject
signingConfiguration for signingobject
quorumConfiguration for quorumobject

Checkpoints#

NameDescriptionType
maxTrackedMessagesMaximum amount of known messages for milestone tip selectioninteger

Tipsel#

NameDescriptionType
minHeaviestBranchUnreferencedMessagesThresholdMinimum threshold of unreferenced messages in the heaviest branchinteger
maxHeaviestBranchTipsPerCheckpointMaximum amount of checkpoint messages with heaviest branch tipsinteger
randomTipsPerCheckpointAmount of checkpoint messages with random tipsinteger
heaviestBranchSelectionTimeoutThe maximum duration to select the heaviest branch tipsstring

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
retryAmountNumber of signing retries to perform before shutting down the nodeinteger
retryTimeoutThe timeout between signing retriesstring

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 quorum 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

Example:

  "coordinator": {    "stateFilePath": "coordinator.state",    "interval": "10s",    "powWorkerCount": 0,    "checkpoints": {      "maxTrackedMessages": 10000    },    "tipsel": {      "minHeaviestBranchUnreferencedMessagesThreshold": 20,      "maxHeaviestBranchTipsPerCheckpoint": 10,      "randomTipsPerCheckpoint": 3,      "heaviestBranchSelectionTimeout": "100ms"    },    "signing": {      "provider": "local",      "remoteAddress": "localhost:12345",      "retryAmount": 10,      "retryTimeout": "2s"    },    "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. Migrator#

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

NameDescriptionType
stateFilePathPath to the state file of the migratorstring
receiptMaxEntriesThe max amount of entries to embed within a receiptinteger
queryCooldownPeriodThe cool down period of the service to ask for new datastring

Example:

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

11. Receipts#

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

NameDescriptionType
backupConfiguration for backupobject
validatorConfiguration for validatorobject

Backup#

NameDescriptionType
enabledWhether to backup receipts in the backup folderbool
pathPath to the receipts backup folderstring

Validator#

NameDescriptionType
validateWhether to validate receiptsbool
ignoreSoftErrorsWhether to ignore soft errors and not panic if one is encounteredbool
apiConfiguration for legacy APIobject
coordinatorConfiguration for legacy Coordinatorobject

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,      "path": "receipts"    },    "validator": {      "validate": false,      "ignoreSoftErrors": false,      "api": {        "address": "http://localhost:14266",        "timeout": "5s"      },      "coordinator": {        "address": "UDYXTZBE9GZGPM9SSQV9LTZNDLJIZMPUVVXYXFYVBLIEUHLSEWFTKZZLXYRHHWVQV9MNNX9KZC9D9UZWZ",        "merkleTreeDepth": 24      }    }  },

12. Tangle#

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

Example:

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

13. 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
nonLazyConfiguration for tips from the non-lazy poolobject
semiLazyConfiguration 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    }  },

14. 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"    ]  },

15. P2P#

NameDescriptionType
bindMultiAddressesThe bind addresses for this nodearray of strings
connectionManagerConfiguration for connection managerobject
gossipConfiguration for gossip protocolobject
identityPrivateKeyprivate key used to derive the node identity (optional)string
dbConfiguration for p2p databaseobject
reconnectIntervalThe time to wait before trying to reconnect to a disconnected peerstring
autopeeringConfiguration for autopeeringobject

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

Gossip#

NameDescriptionType
unknownPeersLimitmaximum amount of unknown peers a gossip protocol connection is established tointeger
streamReadTimeoutThe read timeout for subsequent reads from the gossip streamstring
streamWriteTimeoutThe write timeout for writes to the gossip streamstring

Database#

NameDescriptionType
pathThe path to the p2p databasestring

Autopeering#

NameDescriptionType
bindAddressThe bind address on which the autopeering module listens onstring
entryNodesThe list of autopeering entry nodes to usearray of strings
entryNodesPreferIPv6Defines if connecting over IPv6 is preferred for entry nodesbool
runAsEntryNodeDefines whether the node should act as an autopeering entry nodebool

Example:

  "p2p": {    "bindMultiAddresses": [      "/ip4/0.0.0.0/tcp/15600",      "/ip6/::/tcp/15600"    ],    "connectionManager": {      "highWatermark": 10,      "lowWatermark": 5    },    "gossip": {      "unknownPeersLimit": 4,      "streamReadTimeout": "1m0s",      "streamWriteTimeout": "10s"    },    "identityPrivateKey": "",    "db": {      "path": "p2pstore"    },    "reconnectInterval": "30s",    "autopeering": {      "bindAddress": "0.0.0.0:14626",      "entryNodes": [        "/dns/lucamoser.ch/udp/14826/autopeering/4H6WV54tB29u8xCcEaMGQMn37LFvM1ynNpp27TTXaqNM",        "/dns/entry-hornet-0.h.chrysalis-mainnet.iotaledger.net/udp/14626/autopeering/iotaPHdAn7eueBnXtikZMwhfPXaeGJGXDt4RBuLuGgb",        "/dns/entry-hornet-1.h.chrysalis-mainnet.iotaledger.net/udp/14626/autopeering/iotaJJqMd5CQvv1A61coSQCYW9PNT1QKPs7xh2Qg5K2",        "/dns/entry-mainnet.tanglebay.com/udp/14626/autopeering/iot4By1FD4pFLrGJ6AAe7YEeSu9RbW9xnPUmxMdQenC"      ],      "entryNodesPreferIPv6": false,      "runAsEntryNode": false    }  },

16. 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"    ]  },

17. Warpsync#

NameDescriptionType
advancementRangeThe used advancement range per warpsync checkpointinteger

Example:

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

18. 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": "IOTA - A new dawn",    "index": "HORNET Spammer",    "indexSemiLazy": "HORNET Spammer Semi-Lazy",    "cpuMaxUsage": 0.8,    "mpsRateLimit": 0.0,    "workers": 0,    "autostart": false  },

19. Faucet#

NameDescriptionType
amountThe amount of funds the requester receivesinteger
smallAmountThe amount of funds the requester receives if the target address has more funds than the faucet amount and less than maximuminteger
maxAddressBalanceThe maximum allowed amount of funds on the target addressinteger
maxOutputCountThe maximum output count per faucet messageinteger
indexationMessageThe faucet transaction indexation payloadstring
batchTimeoutThe maximum duration for collecting faucet batchesstring
powWorkerCountThe amount of workers used for calculating PoW when issuing faucet messagesinteger
websiteConfiguration for the faucet websiteobject

Website#

NameDescriptionType
bindAddressThe bind address on which the faucet website can be accessed fromstring
enabledWhether to host the faucet websitebool

Example:

  "faucet": {    "amount": 10000000,    "smallAmount": 1000000,    "maxAddressBalance": 20000000,    "maxOutputCount": 127,    "indexationMessage": "HORNET FAUCET",    "batchTimeout": "2s",    "powWorkerCount": 0,    "website": {      "bindAddress": "localhost:8091",      "enabled": true    }  },

20. 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  },

21. Profiling#

NameDescriptionType
bindAddressThe bind address on which the profiler listens onstring

Example:

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

22. Prometheus#

NameDescriptionType
bindAddressThe bind address on which the Prometheus exporter listens onstring
fileServiceDiscoveryConfiguration 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  },

23. Debug#

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

Example:

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