P2P Topology File Explained

Here we try to explain how and why your P2P files should be configured. UPDATED: 4/18/2024

As we move to full P2P we try to explain how and why your P2P files should be configured below.

What we are looking to explain:

❓What is the real difference from Public and Local peers and when and where should you use each?

❓Why use bootstrapping peers? What does it do and why is it need or not needed?

❓When to use advertise flag and why?

❓Can you have multiple Access Points and why?

❓When to use trustable flag and why?

Sample scenarios and example topology files:

If this is the first time you are Enabling P2P on your node, reminder of steps you need to take:

Local vs Public Peers

What are local vs public peers and when should you use each?

As stated at link below:

local roots: should comprise local relays or a local block-producing node, and any other peers that the node needs to maintain a connection with. These connections are typically kept private. public roots: publicly known nodes (e.g. IOG relays, or ledger nodes). They are either read from the configuration file directly or from the chain. The configured ones will be used to pass a recent snapshot of peers needed before the node caches up with the recent enough chain to construct root peers by itself. ⚠️The node does not guarantee a connection with every public root, unlike local ones. However, by being present in the set, it gets an opportunity to establish an outbound connection with that peer.

Local Roots is designed for peers that the node should always keep as hot or warm, such as its own block producer. On the other hand, Public Roots serves as a source of fallback peers.

Source:

https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/understanding-config-files.md#the-p2p-topologyjson-file

Bootstrapping Peers

Bootstrapping peers are good for when your node has had an extended outage, you'll sync from those and trusted peers and then ledger once on tip.

Advertise Flag

Advertise will tell your peers "hey I have this really good peer, you should try to connect to them" which can give that relay more inbound connections. Could be used for situations like unregistered relays.

If you set advertise to true in topology file you must also add the following to your mainnet-config.json file: 

"PeerSharing": true

Node Versions BEFORE 8.9.1 also require:

"ExperimentalProtocolsEnabled": true,

Access Points

You can have multiple access points within Local Roots. Why would you want to use this? This way you can keep advertise as false for your BP while True for your relay. For example, below is a sample topology file for P2P where we have two access points

Trustable Flag

Trustable peers are composed by the bootstrap peers and the trustable local root peers. By default local root peers are not trustable.

Your own Relays and BP should be set to "trustable": true

Source: https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/understanding-config-files.md#the-p2p-topologyjson-file

P2P Topology for BP with 2 Relays Sample

✅Here we set "useLedgerAfterSlot": -1 so the BP doesn't try to connect to other nodes using ledger peer data.

✅We set "advertise": false, since these are local root on BP and we want to keep private.

✅Since we have 2 Relays we set "valency": 2, if we had 3 Relays it would be set to 3.

✅We need to set "bootstrapPeers": null on BP and set our Relays to "trustable": true,

✅Last of all we leave Public Roots blank by using "publicRoots": []

In the sample below you need to change "relay1.Address" and "relay2.Address" to your relay address and change "port": 3001 to the port you use.

{
  "bootstrapPeers": null,
  "localRoots": [
    {
      "accessPoints": [
        {
          "address": "relay1.Address",
          "port": 3001
        },
        {
          "address": "relay2.Address",
          "port": 3001
        }
      ],
      "advertise": false,
      "trustable": true,
      "valency": 2
    }
  ],
  "publicRoots": [],
  "useLedgerAfterSlot": -1
}

P2P Topology for Relay using 2 Access Points, one for relays and one for BP

✅Here we use 2 Access Points under local roots so we can advertise our relays while hiding our BP

✅We set "advertise": false, on BP Access Point since we want to keep private.

✅Since we have 2 Relays we set "valency": 2, if we had 3 Relays it would be set to 3, if 1 Relay it would be set to 1 and so on.

✅We need to set "bootstrapPeers" to the address below and set our Relays to "trustable": true, so we can sync if we get too far off the tip.

✅Last of all we leave Public Roots blank by using "publicRoots": []

In the sample below you need to change "relay1.Address", "relay2.Address" and "blockProducerAddress" to your relay and BP address and change "port": 3001 to the port you use.

Leave "bootstrapPeers" addresses and ports as is

{
  "localRoots": [
    {
      "accessPoints": [
        {
          "address": "relay1.Address",
          "port": 3001
        },
        {
          "address": "relay2.Address",
          "port": 3001
        }
      ],
      "advertise": true,
      "valency": 2,
      "trustable": true
    },
    {
      "accessPoints": [
        {
          "address": "blockProducerAddress",
          "port": 3001
        }
      ],
      "advertise": false,
      "valency": 1,
      "trustable": true
    }
  ],
  "bootstrapPeers": [
        {
          "address": "backbone.cardano.iog.io",
          "port": 3001
        },
        {
          "address": "backbone.mainnet.emurgornd.com",
          "port": 3001
        }
  ],
  "publicRoots": [
    {
      "accessPoints": [],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 116812831
}

P2P Topology for Relay using 3 Access Points, one for relays, one for BP, and one for SPO friends

✅See notes from example above and don't forget to change SPO.relay.Addresses and port below to match your SPO friends address and ports

{
  "localRoots": [
    {
      "accessPoints": [
        {
          "address": "relay1.Address",
          "port": 3001
        },
        {
          "address": "relay2.Address",
          "port": 3001
        }
      ],
      "advertise": true,
      "valency": 2,
      "trustable": true
    },
    {
      "accessPoints": [
        {
          "address": "blockProducerAddress",
          "port": 3001
        }
      ],
      "advertise": false,
      "valency": 1,
      "trustable": true
    },
    {
      "accessPoints": [
        {
          "address": "SPO.relay2.Address",
          "port": 3001
        },
        {
          "address": "SPO.relay2.Address",
          "port": 3001
        }
      ],
      "advertise": false,
      "valency": 2,
      "trustable": false
    }
  ],
  "bootstrapPeers": [
        {
          "address": "backbone.cardano.iog.io",
          "port": 3001
        },
        {
          "address": "backbone.mainnet.emurgornd.com",
          "port": 3001
        }
  ],
  "publicRoots": [
    {
      "accessPoints": [],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 116812831
}

Using these 3 samples you can modify to fit your situation.

You can add access points, turnoff or on advertise flag and trustable flag where necessary.

⚠️REMINDER:

If this is the first time you are Enabling P2P on your node you need to make sure you took these 2 steps:

1) Update mainnet-conf json

cd $NODE_HOME
sudo nano mainnet-config.json

add: 

"EnableP2P": true,
"PeerSharing": true,
"TargetNumberOfRootPeers": 100,
"TargetNumberOfKnownPeers": 100,
"TargetNumberOfEstablishedPeers": 50,
"TargetNumberOfActivePeers": 20,
"TargetNumberOfKnownBigLedgerPeers": 15,
"TargetNumberOfEstablishedBigLedgerPeers": 10,
"TargetNumberOfActiveBigLedgerPeers": 5,

On BP just add "EnableP2P": true, line

and "PeerSharing": false, line.

If you set advertise to true in topology file you must also add the following to your mainnet-config.json file: 

"PeerSharing": true

Node Versions BEFORE 8.9.1 also require:

"ExperimentalProtocolsEnabled": true,

2) Remove relay-topology_pull.sh or remove cronjob for it

List crontabs by running:

crontab -l

Edit Crontab and remove relay-topology_pull.sh if you have one by running:

crontab -e

Take opportunity to update server and reboot

sudo systemctl stop cardano-node
sudo apt-get update && sudo apt-get upgrade -y && sudo reboot

Congratulations you did it!

Additional Resources:

Additional Resources:

https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/understanding-config-files.md#the-p2p-topologyjson-file

https://book.play.dev.cardano.org/env-mainnet.html

https://updates.cardano.intersectmbo.org/2024-04-15-network/

Contributors

Thanks to the following pools for helping to put together these guides. Please consider delegating to their pools to support them. Are you a pool? Consider buying them a coffee

PreviousAnswering SPO On-Chain Polls

Last updated