Skip to main content

Node Configuration Options

Here are the available node configuration options, along with their default values and descriptions:

Application-level config

NameDefault ValueDescription
config-fileLoads configuration from a TOML file (cmd-line parameters take precedence)
protected-topicnewSeq[ProtectedTopic](0)Topics and its public key to be used for message validation, topic:pubkey. Argument may be repeated

Log config

NameDefault ValueDescription
log-levellogging.LogLevel.INFOSets the log level for process. Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL
log-formatlogging.LogFormat.TEXTSpecifies what kind of logs should be written to stdout. Supported formats: TEXT, JSON

General node config

NameDefault ValueDescription
cluster-id0Cluster id that the node is running in. Node in a different cluster id is disconnected
agent-stringnwakuNode agent string which is used as identifier in network
nodekeyP2P node private key as 64-char hex string
listen-addressdefaultListenAddress()Listening address for LibP2P (and Discovery v5, if enabled) traffic
tcp-port60000TCP listening port
ports-shift0Add a shift to all port numbers
natanySpecify method to use for determining public address. Must be one of: any, none, upnp, pmp, extip:<IP>
ext-multiaddrExternal multiaddresses to advertise to the network. Argument may be repeated
ext-multiaddr-onlyfalseOnly announce external multiaddresses
max-connections50Maximum allowed number of libp2p connections
max-relay-peersMaximum allowed number of relay peers
peer-store-capacityMaximum stored peers in the peerstore
peer-persistencefalseEnable peer persistence

DNS addrs config

NameDefault ValueDescription
dns-addrstrueEnable resolution of dnsaddr, dns4 or dns6 multiaddrs
dns-addrs-name-server["", ""]DNS name server IPs to query for DNS multiaddrs resolution. Argument may be repeated
dns4-domain-nameThe domain name resolving to the node's public IPv4 address

Relay config

NameDefault ValueDescription
relaytrueEnable relay protocol: true|false
relay-peer-exchangefalseEnable gossipsub peer exchange in relay protocol: true|false
rln-relayfalseEnable spam protection through rln-relay: true|false
rln-relay-cred-pathThe path for persisting rln-relay credential
rln-relay-membership-indexThe index of the onchain commitment to use
rln-relay-dynamicfalseEnable waku-rln-relay with on-chain dynamic group management: true|false
rln-relay-id-keyRln relay identity secret key as a Hex string
rln-relay-id-commitment-keyRln relay identity commitment key as a Hex string
rln-relay-eth-client-addressws://localhost:8540/WebSocket address of an Ethereum testnet client e.g., ws://localhost:8540/
rln-relay-eth-contract-addressAddress of membership contract on an Ethereum testnet
rln-relay-eth-private-keyPrivate key for broadcasting transactions
executefalseRuns the registration function on-chain. By default, a dry-run will occur
rln-relay-cred-passwordPassword for encrypting RLN credentials
rln-relay-tree-pathPath to the RLN merkle tree sled db (
rln-relay-bandwidth-threshold0 # to maintain backwards compatibilityMessage rate in bytes/sec after which verification of proofs should happen
staticnodePeer multiaddr to directly connect with. Argument may be repeated
keep-alivefalseEnable keep-alive for idle connections: true|false
topic["/waku/2/default-waku/proto"]Default topic to subscribe to. Argument may be repeated. Deprecated! Please use pubsub-topic and/or content-topic instead
pubsub-topicDefault pubsub topic to subscribe to. Argument may be repeated
content-topicDefault content topic to subscribe to. Argument may be repeated

Store and message store config

NameDefault ValueDescription
storefalseEnable/disable waku store protocol
storenodePeer multiaddress to query for storage
store-message-retention-policytime:172800Message store retention policy. Time retention policy: time:<seconds>. Capacity retention policy: capacity:<count>. Size retention policy: size:<xMB/xGB>. Set to none to disable
store-message-db-urlsqlite://store.sqlite3The database connection URL for persistent storage
store-message-db-vacuumfalseEnable database vacuuming at start. Only supported by SQLite database engine
store-message-db-migrationtrueEnable database migration at start

Filter config

NameDefault ValueDescription
filterfalseEnable filter protocol: true|false
filternodePeer multiaddr to request content filtering of messages
filter-timeout14400 # 4 hoursTimeout for filter node in seconds
filter-subscription-timeout300 # 5 minutesTimeout for filter subscription without ping or refresh it, in seconds. Only for v2 filter protocol
filter-max-peers-to-serve1000Maximum number of peers to serve at a time. Only for v2 filter protocol
filter-max-criteria1000Maximum number of pubsub and content topic combinations per peer at a time. Only for v2 filter protocol

Light push config

NameDefault ValueDescription
lightpushfalseEnable lightpush protocol: true|false
lightpushnodePeer multiaddr to request lightpush of published messages

JSON-RPC config

NameDefault ValueDescription
rpctrueEnable Waku JSON-RPC server: true|false
rpc-address127.0.0.1Listening address of the JSON-RPC server
rpc-port8545Listening port of the JSON-RPC server
rpc-adminfalseEnable access to JSON-RPC Admin API: true|false
rpc-privatefalseEnable access to JSON-RPC Private API: true|false

REST HTTP config

NameDefault ValueDescription
restfalseEnable Waku REST HTTP server: true|false
rest-address127.0.0.1Listening address of the REST HTTP server
rest-port8645Listening port of the REST HTTP server
rest-relay-cache-capacity30Capacity of the Relay REST API message cache
rest-adminfalseEnable access to REST HTTP Admin API: true|false
rest-privatefalseEnable access to REST HTTP Private API: true|false

Metrics config

NameDefault ValueDescription
metrics-serverfalseEnable the metrics server: true|false
metrics-server-address127.0.0.1Listening address of the metrics server
metrics-server-port8008Listening HTTP port of the metrics server
metrics-loggingtrueEnable metrics logging: true|false

DNS discovery config

NameDefault ValueDescription
dns-discoveryfalseEnable discovering nodes via DNS
dns-discovery-urlURL for DNS node list in format 'enrtree://<key>@<fqdn>'
dns-discovery-name-server["", ""]DNS name server IPs to query. Argument may be repeated

Discv5 config

NameDefault ValueDescription
discv5-discoveryfalseEnable discovering nodes via Node Discovery v5
discv5-udp-port9000Listening UDP port for Node Discovery v5
discv5-bootstrap-nodeText-encoded ENR for bootstrap node. Used when connecting to the network. Argument may be repeated
discv5-enr-auto-updatefalseDiscovery can automatically update its ENR with the IP address
discv5-table-ip-limit10Maximum amount of nodes with the same IP in discv5 routing tables
discv5-bucket-ip-limit2Maximum amount of nodes with the same IP in discv5 routing table buckets
discv5-bits-per-hop1Kademlia's b variable, increase for less hops per lookup

Waku peer exchange config

NameDefault ValueDescription
peer-exchangefalseEnable waku peer exchange protocol (responder side): true|false
peer-exchange-nodePeer multiaddr to send peer exchange requests to. (enables peer exchange protocol requester side)

WebSocket config

NameDefault ValueDescription
websocket-supportfalseEnable websocket: true|false
websocket-port8000WebSocket listening port
websocket-secure-supportfalseEnable secure websocket: true|false
websocket-secure-key-pathSecure websocket key path: '/path/to/key.txt'
websocket-secure-cert-pathSecure websocket Certificate path: '/path/to/cert.txt'

To configure your node using the provided configuration options, have a look at the Node Configuration Methods guide.