Skip to main content

Configuring Topology

Network topology describes the physical and logical structure of a network. In the Cardano Mainnet network, for security reasons each stake pool must operate at least one block-producing node and one relay node. The keys and certificates required to issue blocks are located on the block-producing node. Your block producer must connect only to one or more relay nodes that you—the stake pool operator—control.

For an illustration, see the Cardano Network Topology diagram.

For details on Cardano networking components, visit Peer-to-peer (P2P) Networking.

Before you start the nodes comprising your stake pool, you must:

  • Configure your relay node(s) to connect with your block-producing node
  • Configure your block-producing node to connect only with your relay node(s)

Configuring a Relay Node​

To configure the relay node(s) to connect with the block-producing node in your stake pool configuration:

1. On the computer hosting a relay node, using a terminal window type the following command to navigate to the folder where you downloaded Cardano configuration files:

cd ${NODE_HOME}

2. Using a text editor, open the config.json file, and then edit the following option if needed:

"EnableP2P": true,

3. Save and close the config.json file.

4. To create a backup of the original topology configuration file, type:

cp topology.json topology.json.bak

5. Using a text editor, open the topology.json file, and then add a record for the block-producing node in the localRoots section as follows, where <BlockProducingNodeIPAddress> is the IP address of the block-producing node in your stake pool configuration, and <BlockProducingNodeName> is an optional descriptive label for the block-producing node. Also, set the value true for the trustable key:

{
"bootstrapPeers": [
{
"address": "backbone.cardano.iog.io",
"port": 3001
},
{
"address": "backbone.mainnet.emurgornd.com",
"port": 3001
},
{
"address": "backbone.mainnet.cardanofoundation.org",
"port": 3001
}
],
"localRoots": [
{
"accessPoints": [
{
"address": "<BlockProducingNodeIPAddress>",
"port": 6000,
"name": "<BlockProducingNodeName>"
}
],
"advertise": false,
"comment": "Do NOT advertise the block-producing node",
"trustable": true,
"valency": 1
}
],
"publicRoots": [
{
"accessPoints": [],
"advertise": false
}
],
"useLedgerAfterSlot": 157852837
}
info

To follow best practices, set <BlockProducingNodeIPAddress> to the local area network (LAN) Internet protocol (IP) address of the computer hosting the block-producing node when possible. If necessary—for example, if you set up the block-producing node on a different network than the relay node—then use the wide area network (WAN) IP address.

info

Connecting to backbone.cardano.iog.io, backbone.mainnet.emurgornd.com and backbone.mainnet.cardanofoundation.org in the bootstrapPeers section of the topology.json file allows the relay node to synchronize a local copy of the Cardano blockchain ledger with the network.

Challenge
Challenge

When synchronizing the local copy of the Cardano blockchain ledger with the network, the useLedgerAfterSlot option determines when the Cardano Node instance switches from using fixed peers to discovering peers registered on the blockchain. As the Cardano ledger grows, the recommended value of useLedgerAfterSlot changes. Every few months, update the value of the useLedgerAfterSlot option in the configuration files based on the value recommended in the respective configuration file available on the Environments page.

6. Save and close the topology.json file.

7. To configure additional relay nodes, repeat steps 1 to 6 for each additional relay node in your stake pool configuration.

Configuring the Block-producing Node​

To configure the block-producing node to connect only with the relay node(s) in your stake pool configuration:

1. On the computer hosting the block-producing node in your stake pool configuration, using a terminal window type the following command to navigate to the folder where you downloaded Cardano configuration files:

cd ${NODE_HOME}

2. Using a text editor, open the config-bp.json file, and then edit the following option if needed:

"EnableP2P": true,

3. Save and close the config-bp.json file.

4. To create a backup of the original topology configuration file, type:

cp topology.json topology.json.bak

5. Using a text editor, open the topology.json file, and then replace the contents of the file with one or more records, as needed, to reference only the relay node(s) in your stake pool configuration. For example, the following lines configure a single relay node where <RelayNodeIPAddress> is the IP address of the relay node and <RelayNodeName> is an optional descriptive label for the relay node. Set the value true for the trustable key. Also, set the value of bootstrapPeers to null and the value of useLedgerAfterSlot to -1:

{
"bootstrapPeers": null,
"localRoots": [
{
"accessPoints": [
{
"address": "<RelayNodeIPAddress>",
"port": 6000,
"name": "<RelayNodeName>"
}
],
"advertise": false,
"trustable": true,
"valency": 1
}
],
"publicRoots": [
{
"accessPoints": [],
"advertise": false
}
],
"useLedgerAfterSlot": -1
}
info

To follow best practices, set <RelayNodeIPAddress> to the LAN IP address of the computer hosting the relay node when possible. If necessary—for example, if you set up a relay node on a different network than the block-producing node—then use the WAN IP address. If you configure multiple relay nodes in the localRoots section, then set the valency key to match the number of relay nodes.

Important
Important

Setting useLedgerAfterSlot to the value -1 disables discovering peers registered on the blockchain. Connect the block-producing node in your stake pool configuration only to one or more relay nodes that you as the stake pool operator control.

6. Save and close the topology.json file.

Configuring Port Forwarding​

Port forwarding creates an association between the public WAN IP address of a router and a private LAN IP address dedicated to a computer or device on the private network that the router manages.

So that relay nodes in the Cardano network can connect to a relay node in your stake pool configuration, in your firewall configuration you must open a port and forward traffic received on the port to the computer and port where the relay node listens.

info

In the procedures to configure topology above, all block-producing and relay nodes in the stake pool configuration listen on port 6000 If you followed CoinCashew instructions for Maintaining a Firewall, then also ensure that in ufw you allow incoming traffic on the port where the Cardano Node on the local computer listens, as needed.

To help confirm that your ports are configured as needed, you can use you get signal or CanYouSeeMe.org for example.

Conclusion​

The topology configuration described above allows the nodes in your stake pool configuration to connect securely with each other, as well as with other relay nodes in the Cardano network.

If you configure two or more relays in your stake pool configuration, then consider Enabling Peer Sharing to help improve network security.