Node network

There are 2 different network interfaces which are covered by their respective section:

rest:
   ...
p2p:
   ...

REST interface configuration

  • listen: listen address
  • tls: (optional) enables TLS and disables plain HTTP if provided
    • cert_file: path to server X.509 certificate chain file, must be PEM-encoded and contain at least 1 item
    • priv_key_file: path to server private key file, must be PKCS8 with single PEM-encoded, unencrypted key
  • cors: (optional) CORS configuration, if not provided, CORS is disabled
    • allowed_origins: (optional) allowed origins, if none provided, echos request origin, note that an origin should include a scheme, for example: http://127.0.0.1:8080.
    • max_age_secs: (optional) maximum CORS caching time in seconds, if none provided, caching is disabled

Configuring TLS

In order to enable TLS there must be provided certificate and private key files.

Example generation of files for self-signed TLS

Generate private key

openssl genrsa -out priv.key 2048

Wrap private key in PKCS8

openssl pkcs8 -topk8 -inform PEM -outform PEM -in priv.key -out priv.pk8 -nocrypt

Generate a self-signed certificate for private key

openssl req -new -key priv.key -out cert_req.csr
openssl x509 -req -days 3650 -in cert_req.csr -signkey priv.key -out cert.crt

Use generated files in config

rest:
  tls:
    cert_file: cert.crt
    priv_key_file: priv.pk8

P2P configuration

  • trusted_peers: (optional) the list of nodes' multiaddr to connect to in order to bootstrap the p2p topology (and bootstrap our local blockchain). Note that you can use a DNS name in the following format: /dns4/node.example.com/tcp/3000. Use dns6 instead of dns4 if you want the peer to connect with IPv6.
  • public_address: multiaddr the address to listen from and accept connection from. This is the public address that will be distributed to other peers of the network that may find interest into participating to the blockchain dissemination with the node. Currently only TCP is supported.
  • public_id: (optional) This is a static identifier, 24 bytes encoded in hexadecimal. They are used to bootstrap the connection to the node if the node introduce itself as a trusted peer. Most of the user don't need to set this value and in fact we are working toward potentially removing the need for this value.
  • listen_address: (optional) multiaddr specifies the address the node will listen to to receive p2p connection. Can be left empty and the node will listen to whatever value was given to public_address.
  • topics_of_interest: (optional) the different topics we are interested to hear about:
    • messages: notify other peers this node is interested about Transactions typical setting for a non mining node: "low". For a stakepool: "high";
    • blocks: notify other peers this node is interested about new Blocks. typical settings for a non mining node: "normal". For a stakepool: "high".
  • max_connections: the maximum number of P2P connections this node should maintain. If not specified, an internal limit is used by default [default: 256]
  • max_inbound_connections: the maximum number of client P2P connections this node should keep open. [default: 192]
  • policy: (optional) set the setting for the policy module
    • quarantine_duration set the time to leave a node in quarantine before allowing it back (or not) into the fold. It is recommended to leave the default value [default: 30min].
    • quarantine_whitelist set a trusted list of peers that will not be quarantined in any circumstance. It should be a list of valid addresses, for example: ["/ip4/127.0.0.1/tcp/3000"]. By default this list is empty, [default: []].
  • layers: (optional) set the settings for some of the poldercast custom layers (see below)
  • max_unreachable_nodes_to_connect_per_event: (optional) set the maximum number of unreachable nodes to contact at a time for every new notification. Every time a new propagation event is triggered, the node will select randomly a certain amount of unreachable nodes to connect to in addition to the one selected by other p2p topology layer [default: 20]
  • gossip_interval: (optional) interval to start gossiping with new nodes, changing the value will affect the bandwidth. The more often the node will gossip the more bandwidth the node will need. The less often the node gossips the less good the resilience to node churn. [default: 10s]
  • topology_force_reset_interval: (optional) If this value is set, it will trigger a force reset of the topology layers. The default is to not do force the reset. It is recommended to let the protocol handle it.
  • max_bootstrap_attempts: (optional) number of times to retry bootstrapping from trusted peers. If not set, default behavior, the bootstrap process will keep retrying indefinitely, until completed successfully. If set to 0 (zero), the node will skip bootstrap all together -- even if trusted peers are defined. If the node fails to bootstrap from any of the trusted peers and the number of bootstrap retry attempts is exceeded, then the node will continue to run without completing the bootstrap process. This will allow the node to act as the first node in the p2p network (i.e. genesis node), or immediately begin gossip with the trusted peers if any are defined.

The trusted peers

The trusted peers is a concept that is not fully implemented yet. One of the key element for now is that this is the first node any node tries to connect in order to meet new nodes. Right now, as far as we know, only one of them is needed. IOHK provides a few others for redundancy.

Layers

Jörmungandr provides multiple additional layers to the poldercast default ones: the preferred list or the bottle in the sea.

Preferred list

this is a special list that allows to connect multiple nodes together without relying on the auto peer discovery. All entries in the preferred list are also whitelisted automatically, so they cannot be quarantined.

configuration:
  • view_max: this is the number of entries to show in the view each round the layer will randomly select up to view_max entries from the whole preferred_list.peers list of entries. [default: 20]
  • peers: the list of peers to keep in the preferred list [default: EMPTY]

Also, the preferred list will never be quarantined or blacklisted, the node will attempt to connect to (up to view_max of) these nodes every time, even if some are down, unreachable or not operated anymore.

COMPATIBILITY NOTE: in near future the peer list will be only a list of addresses and the ID part will not be necessary.

Example:
p2p:
  layers:
    preferred_list:
      view_max: 20
      peers:
        - address: '/ip4/127.0.0.1/tcp/2029'
          id: 019abc...
        - ...

Setting the public_id

This is needed to advertise your node as a trusted peer. If not set, the node will generate a random ID, which is fine for a regular user. You can generate a public id with openssl, for example: openssl rand -hex 24

topics_of_interest

This is optional an optional value to set. The default is:

messages: low
blocks: normal

These value makes sense for most of the users that are not running stake pools or that are not even publicly reachable.

However for a publicly reachable node, the recommended setting would be:

messages: normal
blocks: normal

and for a stake pool

messages: high
blocks: high