The IOTA network is a distributed network. It uses a gossip protocol to broadcast data among IOTA nodes. To participate in a network, each node has to establish a secure connection to other nodes in the network (to its peer neighbors), and mutually exchange messages.
Each node can be uniquely identified by a
Peer identity (also called
PeerId) is represented by a public
and private key pair. Since
PeerId is a cryptographic hash of a peer's public key, the
PeerId represents a verifiable link between the given peer and its public key. It enables individual peers to establish a secure communication channel as the hash can be used to verify an identity of the peer.
When Hornet is started for the first time, it will automatically generate a
PeerId and save the identity's private key in the
./p2pstore/identity.key file. Hornet will keep the generated identity between subsequent restarts.
Each time Hornet starts, the
PeerId is written to stdout:
2021-08-23T17:17:50Z INFO P2P WARNING: never share your "p2pstore" folder as it contains your node's private key!
2021-08-23T17:17:50Z INFO P2P stored new private key for peer identity under "p2pstore/identity.key"
2021-08-23T17:17:50Z INFO P2P peer configured, ID: 12D3KooWQPA5woZRTT9ExAsq6gRrcPqf3bVn5M5taopJ5Uvhw4iz
PeerId is an essential part of your
multiaddr used to configure neighbors. For example,
12D3KooWHiPg9gzmy1cbTFAUekyLHQKQKvsKmhzB7NJ5xnhK4WKq corresponds to your
PeerId is also visible on the start page of the dashboard.
However, you can pre-generate the identity if you want. This way, you can pre-communicate it to your peers before you even start your node.
You can use the
p2pidentity-gen CLI tool to generate a
PeerId which generates a private key file and logs the output to stdout:
./hornet tools p2pidentity-gen
Your p2p private key (hex): 64166cc2627c369283cb1dd8412b6259232653611a3ae5cfb52398c23cfaead76af7a3cb775895046b9f28f2cf2b4150a9fd5dfd0ecf5c8d94529818578f40a2
Your p2p public key (hex): 6af7a3cb775895046b9f28f2cf2b4150a9fd5dfd0ecf5c8d94529818578f40a2
Your p2p public key (base58): 8CZELJwB3aBzxJgnLMvvt1FirAwNN6jif9LavYTNHCty
Your p2p PeerID: 12D3KooWH1vQ5SWtEUTVNCCCxxgGeoLZLVz1PnpCcjhcJXcGB9cu
Always take care of your
./p2pstore/identity.key file, since it contains the private key to your node's identity.
You can find more information on the
PeerId in the libp2p docs page.
Addressing Peer Neighbors
To communicate to your peer neighbors, you will need an address to reach them. For that, Hornet uses the
MultiAddresses format (also known as
multiAddr is a convention on how to encode multiple layers of addressing information into a single path structure that is future-proof. Basically,
multiaddr combines several pieces of information in a single human-readable and machine-optimized string, including network protocol and
For example, a node is reachable using IPv4
TCP on port
15600 and its
multiaddr encoding of this information would look like this:
ip4 is used. A common mistake is to use
If a node is reachable using a DNS name (for example
node01.iota.org), then the given
multiaddr would be:
You will need to find out your own
multiaddr to give to your peers for neighboring. To do so, combine the
peerId you received
from the stdout when the Hornet node started up (or which was shown via the
p2pidentity-gen CLI tool), and your
p2p.bindAddress. Replace the
/dns/<hostname> segments with the actual information.
You can find more information about
multiaddr at the libp2p docs page.
Adding Node Peers
Once you know your node's own
multiaddr, it can be exchanged with other node owners to establish a mutual peer connection. We recommended several peer neighbors between 4-6 to get some degree of redundancy.
You can join the official IOTA Discord server and the
#nodesharing channel. There, you will be able to describe your node location (Europe,
Germany, Asia, etc.), with your allocated high watermark resources and ask for neighbors.
Do not publicly disclose your node
multiaddr to all readers but wait for an individual direct chat.
You can change the path or name of the
peering.json file by using the
--peeringConfig argument while
peering.json example, with
Hornet also supports automatically finding peers through the autopeering module. To minimize service distribution in case your autopeered peers are flaky, we recommend you only use autopeering if you have at least four static peers.
Autopeering is disabled by default. If you want to enable it, add
The autopeering plugin will disclose your public IP address to possibly all nodes and entry points. Do not enable this plugin if you do not want this to happen!
Your node will use the specified entry nodes under
p2p.autopeering.entryNodes to find new peers.
entryNodes are also encoded as
/autopeering portion defines the base58 encoded Ed25519 public key.
By default, Hornet will peer up to four autopeered peers and initiate a gossip protocol with them. Autopeered peers are not subject to connection trimming, the same way as mutually tethered peers are not either.
If you want to run your own node as an autopeering entry node, you should enable
p2p.autopeering.runAsEntryNode. The base58 encoded public key is in the output of the
p2pidentity-gen Hornet tool. Alternatively, if you already have an identity in a
./p2pstore, you can use the
p2pidentity-extract Hornet tool to extract it.
p2p.connectionManager.lowWatermark configuration options define "watermark" points. Watermark points can be considered like a filling basin where if the
highWatermark is reached, water will be drained until it reaches the
lowWatermark again. Similarly, the connection manager within Hornet will start trimming away connections to peers if
highWatermark peers are connected until it reaches
lowWatermark count of peers. These watermarks exist for a certain buffer number of peers to be connected, which will not necessarily be targeted by the gossip protocol.