Cardano Development Update

Cardano's Peer-to-Peer (P2P) feature is coming closer

Longly waited for, it is finally coming closer: The Peer-to-Peer (P2P) feature which many stake pool operators have been waiting for is currently in testnet. The P2P feature will drive ever greater network decentralization. Working with a small group of SPOs, IOHK has now implemented automated peer-to-peer components – to make network node connections smoother & more seamless.

Update 2021-12-20: P2P Feature included in cardano-node 1.32.1

In the current release of Cardano-Node, for the first time, a preview of the P2P feature is included. However, it is not yet recommended to use it for production.

At the moment one major feature is still missing at Cardano-Node: Automated Peer-to-Peer Connectivity

Up to now, a major feature is still missing at Cardano Node: The P2P feature. Cardano nodes still establish connections with peers by looking up the topology.json that describes the static configuration of the cardano ecosystem. The system also relies on nodes set up by IOG that help to establish network connectivity. Typically, a topology.json includes connection data of the relays of 10-20 other stake pools which were looked up by the stake pool operator herself/himself and entered manually in this json-file. Since connection data might change, for example due to a change of DNS hostname or IP address of another relay, the stake pool operator is required to do regular maintenance tasks to check the validity and reliability of the topology.json file.

To provide a little help at this point, to increase automated decentralization and in order to simplify node communications, the topologyUpdater was developed by the Cardano Community. A small tool which helps stake pool operators to connect their nodes to other nodes in the network automatically and which renders new topology.json files every 24 hours. This way, the developers of the tool give the possibility that the nodes in Cardano network connect to a huge diversity of other nodes spread accross the globe and have some randomness in their selection of other nodes they connect to. It also helps to save time since no more manual maintenance tasks about finding and selecting other nodes for the topology.json are required.

A major drawback of topologyUpdater is that the cardano-node process needs to get restarted to apply the changes of the automatically rendered topology.json. Many stake pools in Cardano have therefore set a timer which restarts their relay nodes every 24 hours. This leads to a short unresponsive state of each node. From perspective of IT, there is one additional drawback at topologyUpdater: It is a centralized service which in fact contradicts the idea of decentralization. The developers know about this and therefore highly recommend to not use topologyUpdater on core nodes, but on relay nodes only. Anyway, a failure of this centralized topologyUpdater service would lead to failure of all topologyUpdaters on the relay nodes. In general, the developers of topologyUpdater have done a great job to do the best what was possible for them! On their github repository, the developers mentioned:

"This "TopologyUpdater" service, which is far from being perfect due to its centralization factor, is intended to be a temporary solution to allow everyone to activate their relay nodes without having to postpone and wait for manual topology completion requests. - You should NOT set up topologyUpdater for your block producing nodes."

As you can see, the time was urgent to solve this problem and add an automated P2P feature to cardano-node itself. The upcoming P2P feature makes the topologyUpdater and topology.json partly obsolete. As soon as the P2P feature goes live, it is no longer necessary to define static relays of other pools as targets. The only peers a SPO would define is his/her own block producer / core node! The testing of the P2P feature began already many months ago.

How is Peer-to-Peer network compared to the older federated and hybrid network connectivities?

In the old Byron federated system, nodes were - as mentioned above - connected to other nodes by a static configuration that was defined in the topology.json file.


Since the introduction of Shelley, the system has been functioning in a hybrid mode. Moving from the federated state of network connectivity to the hybrid one, CF / IOHK added a manually constructed peer-to-peer (P2P) network of stake pool operator (SPO) relay nodes. This means that SPO core nodes can connect to both federated relay nodes and to other SPO-run relay nodes.


To ensure efficient communication between nodes, it is essential to enable automated connections of SPO relays to each other, so that less static configuration is needed. This is currently being accomplished through upgrades to the network stack, which will ultimately enable a full P2P topology for all Cardano nodes. P2P communication will enhance the flow of information between nodes, thus reducing (and ultimately removing) the network’s reliance on the federated nodes or the centralized service of topologyUpdater, and enabling true and complete decentralization of the Cardano network.


One main advantage of the P2P feature is that all features get incorporated into the single cardano-node service itself. Once the P2P feature is published and live, it is no longer required to run additional topologyUpdater services like the restart-timer of your cardano node, the push-service which sends alive-messages to the centralized server, or the fetch-service which grabs the updated topology.json at that moment when your cardano-node gets restarted every 24 hours. A lot of stake pool operators are looking for this P2P feature to get live! Let's take a closer look at the technica ldetails of the new P2P feature.

Looking at the technical details of the the new P2P functionality

The Cardano network consists of multiple peer nodes. Some peer nodes are more active than others, some have established connections, and some should be promoted to ensure the best system performance. In future, each node will maintain a set of peers mapped into three categories:

  • cold peers ‒ existing peers without an established network connection
  • warm peers ‒ peers with an established bearer connection, which is only used for network measurements without implementing any of the node-to-node mini-protocols.
  • hot peers ‒ peers that have a connection, which is being used by all three node-to-node mini-protocols

Newly discovered peers will initially be added to the cold peer set. The P2P governor is then responsible for peer connection management: it defines which peers are beneficial for connection purposes, and which should be promoted or demoted between cold, warm, or hot sets.

The primary goal of the P2P governor is to maintain the target number of cold, warm, and hot peers. This builds and maintains a connectivity map of the entire network, and simplifies the process of connection definitions by handling them automatically.

To establish connectivity between nodes, the P2P governor will engage in the following activities:

  • the random gossip used to discover a higher number of cold peers
  • promotion of cold peers to warm peers
  • demotion of warm peers to cold peers
  • promotion of warm peers to hot peers
  • demotion of hot peers to warm peers

The P2P governor needs to establish and maintain:

  • a target number of cold peers (for example, 100)
  • a target number of hot peers (for example, between 2–20)
  • a target number of warm peers (for example, between 10–50)
  • a set of warm peers that are sufficiently diverse in terms of hop distance and geographic locations
  • a target churn frequency for hot or warm changes
  • a target churn frequency for warm or cold changes
  • a target churn frequency for cold or unknown changes


Using 2–20 hot peers is cost-efficient, as peers exchange only their block headers. The block body, in turn, is typically requested only once, and it tends to follow the shortest path through the connectivity graph.

The purpose of warm peers is to provide access to those peers that can be quickly promoted to hot ones (in case any of the warm peers fail), and also provide candidates for the churn of hot peers.

The policy for selecting which warm peers to promote to hot relies on the upstream measurements. The purpose of a degree of churn between cold and warm peers is, in part, to discover the network distance between more peers and to allow potentially better warm peers to take over from existing hot peers. This enables further optimization and adjustments. Maintaining diversity in hop distances contributes to better block distribution times across the globally distributed network.

Overall, this approach follows a common pattern for probabilistic search or optimization that uses a balance of local optimization with some elements of higher-order disruption to avoid becoming trapped in a poor local optimum.

Peers maintain a limited set of information, which is based on their previous direct interactions. Cold peers, for instance, may not maintain any data, as they have not established interactions yet. Such data can be compared to ‘reputation’ property, however, these details are purely local and are not shared among other nodes. Local peer reputation information is also updated when peer connections fail. The network does not maintain negative peer information for extended periods of time: to bound resources and because of the simplicity of Sybil attacks.

The implementation classifies exceptions that cause connection failures into three classes:

  • internal node exceptions (for example, local disk corruption)
  • network failures (for example, dropped TCP connections)
  • adversarial behavior (for example, a protocol violation detected by the typed-protocols layer or by the consensus layer).

In the case of adversarial behavior, the peer can be immediately demoted from the hot, warm, or cold sets. 

Expanded Features in Prometheus / Grafana

A very common metric which is shown in grafana dashboards is the connected peers int cardano_node_metrics_connectedPeers_int which is limited since it does not show full details of your incoming and outgoing connections. Future releases of cardano with enabled P2P feature will additionally include following metrics and statistics:

  • outbound connections: warm (active connections that don’t participate in the consensus) and hot (active connections that take part in the consensus)
  • inbound connections: warm and hot
  • uni-direction/duplex connections.

Many stake pool operators will smile as they read this! These metrics are a helpful tool in future to investigate connection problems and identify bottlenecks!

What's next?

The assessment of network connections on the semi-public testnet is making great steps towards finalization and it will help to gather valuable feedback and catch unknown issues. Once CF / IOHK are satisfied, they will then be ready to invite all SPOs to test P2P node communications on the public testnet. This will mark the implementation of a smart policy for peer selection. This policy will allow defining final metrics to compare with the previous, non-P2P setting. Most importantly, CF / IOHK will continue testing to verify that all the components work flawlessly in isolation as well as in combination in a wide range of network conditions.


written by: Chris     published at: Dec 10, 2021

Further articles you might be interested in

Cardano Development Update

Cardano Stake Pool P2P Feature Tested Successfully

The Developers of Cardano have announced a new major milestone in the journey to full decentralization: The new P2P feature was tested successfully in a closed testing environment.

May 11, 2021, by Eric Hill

Cardano Development Update

Cardano Africa Agreement

This week's biggest news was the announcement that IOHK has confirmed an agreement with Ethiopia’s Ministry of Education that will bring 5,000,000 secondary school students and 700,000 teachers in 3,500 schools into the Cardano ecosystem.

May 2, 2021, by Eric Hill