Topology Service

Since the test network has to get along without P2P network module for the time being, some static topology files are our way to handle this meanwhile.

This TopologyUpdater service is intended to be a temporary (yes centralistic) solution to allow everyone to activate their relay nodes without having to postpone and wait for manual topology extension requests (message with other pool operators or do pull requests on the IOHK repository).

  • The TopologyUpdater shell script must be executed on the relay node as a cronjob exactly every 60 minutes.
  • After 4 consecutive requests (3 hours) the node is considered a new relay node, and so listed in the topology file.
  • If the node is turned off, it’s automatically delisted after 3 hours.

Read more about at

Based on first participation experiences the topology-Files can be fetched soon from the same relay nodes.


Here’s a basic concept of how topologies without P2P peer discovery will/can look like

First, let’s imagine how a everyone “I wanna peer with IOHK” will look like.

there might be some manual connections between pool operator who know each other.

Now let’s start with an unconnected set of relays and how they will connect if each only connects to a subset of other nodes.

Your node connects to just a couple of other nodes

and there is another node using the same subset (you both act as backup of each other to run this sub-set)

Now if most involved nodes run such a subset of just some few connections it will look like this

This is just to give an idea what a good p2p protocol has to achieve in a decentralised way.

The proposed topology service can generate such sub-sets in a centralized way, by also ensuring removal of orphaned nodes and automated addition of new nodes.

by participating and announcing you node you help to achieve a good interim solution until P2P is in place.


hi @werkof,

thanks for this. I have only one issue: my relays have a load balancer in front and topolgy update script complaints about the domain not matching the IP when I run it. Is there a solution for this?


That’s interesting, because the loadbalancer shouldn’t cause any issue.

Whatever router/firewall/balancer/proxy you have in front: The hostname you announce will DNS-resolve to one (or multiple) IPs. And at each of that IPs one of your relays should answer to requests.

Feel free to DM me the hostname so I can look into.

We have reached a 150 peers who continuously update their tip state, guaranteeing they are actually good and usable peers for your node

Here’s where they are located around the globe (open link to see the map)

1 Like

The topologyUpdater Service also forked into Shelley mainnet.

Here’s how this looked like, while Pool-Operators switched existing MC4 Testnet nodes over to Shelley Mainnet

And this is where the relay nodes are located all over the world



That is really nice @werkof


Only two months ago, in the middle of the testnet preparations we decided to provide our CLIO1 server infrastructure and develop this topologyUpdater service.

Now, two months later, and less than two weeks after Shelley mainnet launch we are a 450 and still growing subscribed peer nodes.

We still have the same peer selection logic in place, looking at the individual requesting node’s geographic distance to all other subscribers. The service always returns a list of very close to as far as possible peers, around the whole globe. This should ensure a global connected network without isolated areas or preferred cluster zones.

If interested you can read more about at


@werkof, @igghibu brings up something we have been facing as well. We run in a cluster environment with a load balancer to handle incoming requests. It is able to handle public connections on port 3001, while our requests/all egress come from each cluster node IP address. Even though those are public-facing IPs, they do not listen on any port.

Is there a way that we could set the client IP in the headers with X-Forwarded-For or something similar?

Technically it wouldn’t be a problem to accept X-Forwarded-For or even simply a &LbRealIp
But both modes debunk the attempt to design and use this service without user-accounts and authentication, just by the real connecting TCP-IP.

I expected the P2P to be ready (enabled) around one month after mainnet-launch (now) but that probably will take some more weeks. One thing I’m working on, is fetching the on-chain registered relays, and “import” it to the topologyUpdater list. Then do only the public reachability test, without knowing if the node is on tip or not.

For me it’s just very important to not introduce something that can easily be used to infiltrate the peer list.

1 Like

Right, I think at this point it wouldn’t be worth it to try and support every use case out there. We’ll just wait for P2P to be implemented.

TopologyUpdater subscriptions first reached 1000 nodes. +100 in one month.

On average one update every 3.6 seconds, from Cardano relay nodes on all 5 continents.