Skip to content

Topology Guide Overview

Dingo works with the embedded default topology file, but as an SPO you should use your own topology.json. This guide will use the preview network topology file as a sample. All network topology files can be found here: https://book.play.dev.cardano.org/environments.html

Please modify for your network and node layout. This guide uses the common layout of one block producer behind two relays.

This guide will cover:


Default Preview Topology JSON File

The default Preview topology JSON file looks like this:

{
"bootstrapPeers": [
{
"address": "preview-node.play.dev.cardano.org",
"port": 3001
}
],
"localRoots": [
{
"accessPoints": [],
"advertise": false,
"trustable": false,
"valency": 1
}
],
"peerSnapshotFile": "peer-snapshot.json",
"publicRoots": [
{
"accessPoints": [],
"advertise": false
}
],
"useLedgerAfterSlot": 119231973
}

Copy useLedgerAfterSlot and bootstrapPeers from the official topology for your network. The Preview slot above will go stale and is wrong for preprod/mainnet.


Understanding Topology Flags

To understand how to modify and use the topology JSON file it’s important to understand:

Local vs Public Peers

Local roots are 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 serve as a source of fallback peers.

Bootstrapping Peers

Bootstrapping peers are good for when your node has had an extended outage: the node syncs from those peers, then uses ledger peers once it is on tip.
When `advertise` is true, the node may share that peer’s address through peer sharing. That can increase inbound connections to the advertised peer. This is useful for unregistered relays. Never advertise the block producer.

Access Points

Access points sit inside a `localRoots` group. Why would you want to use this? This way you can keep advertise as false for your BP while true for your relay.

Trustable Flag

Dingo accepts `trustable` so that cardano-node topology files load unchanged, but it does not use the flag. A trustable local root does not help a node that is behind the tip leave Genesis chain selection.

On mainnet, preprod and preview, Genesis chain selection uses genesisBootstrap.corroborationPeers: 0 by default, so a node can advance Genesis selection with a single upstream peer. Set genesisBootstrap.corroborationPeers to a positive value to enable the corroboration gate and require independent corroborating peers before the node follows a chain. Dingo does not inject network-specific control groups when configuration omits genesisBootstrap.controlGroups. To require a fixed control-group set, configure genesisBootstrap.controlGroups explicitly in dingo.yaml; Dingo counts only the listed endpoints and groups them by the identity each endpoint specifies.


Relay Sample Topology File

For a typical 2 relay and BP setup, for the topology on your relay use:
  • Use two localRoots groups so you can advertise your other relays while hiding your BP.
  • Set "advertise": false, on the group that contains the BP, to keep the BP private.
  • Because there is one additional relay, (2 relays in total) set “valency”: 1, if you had two additional relays (3 relays in total), you would set “valency”: 2, and so on.
  • Dingo accepts hotValency as an alias for valency; when both keys are present, valency takes precedence. For non-empty topology groups, Dingo validates warmValency against the number of access points.
  • Keep useLedgerAfterSlot at your network’s value, so the relay can catch up after falling behind the tip.
  • Genesis/snapshot mode uses peerSnapshotFile instead of (or in addition to) bootstrap peers.
  • Leave Public roots blank by using "publicRoots": [{ "accessPoints": [], "advertise": false }].

In the sample below change “relay2.Address” and “blockProducerAddress” to your relay and BP address and change “port”: 3001 to the port you use.

{
"bootstrapPeers": [
{
"address": "preview-node.play.dev.cardano.org",
"port": 3001
}
],
"localRoots": [
{
"accessPoints": [
{
"address": "relay2.Address",
"port": 3001
}
],
"advertise": true,
"valency": 1,
"trustable": true
},
{
"accessPoints": [
{
"address": "blockProducerAddress",
"port": 3001
}
],
"advertise": false,
"valency": 1,
"trustable": true
}
],
"peerSnapshotFile": "peer-snapshot.json",
"publicRoots": [
{
"accessPoints": [],
"advertise": false
}
],
"useLedgerAfterSlot": 119231973
}

BP Sample Topology File

A block producer keeps your own relays as its only local roots. Use the following configuration:
  • Set "bootstrapPeers": null.
  • Set "advertise": false, since these are the BP’s local roots and should stay private.
  • This example uses 2 relays, so it sets "valency": 2. With three relays, set it to 3.
  • Leave Public roots blank by using "publicRoots": [{ "accessPoints": [], "advertise": false }].
  • Set useLedgerAfterSlot to your network’s value, as on the relays. With -1, a BP with one relay, or with relays that share one IPv4 /24 or IPv6 /64, may need ledger peers to catch up after a restart if it falls behind the tip (dingo#5831). The default genesisBootstrap.corroborationPeers: 0 does not prevent Genesis chain selection in this topology. When genesisBootstrap.corroborationPeers has a positive value, ensure the BP can reach the required peers. The BP then also connects to ledger peers.
  • The BP does not need peerSnapshotFile or bootstrapPeers.

Sample BP Topology JSON FILE:

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

After you save each topology file, point Dingo at it, restart the node, and confirm the block producer has hot connections to your relays.

Add this to the existing /etc/dingo/dingo.yaml (do not overwrite the file):

sudo bash -c "cat <<EOF >> /etc/dingo/dingo.yaml
# Path to the topology configuration file
topology: \"$DINGO_HOME/config/topology.json\"
EOF"

Paths follow the Dingo SPO guides; adjust them if necessary.

$DINGO_HOME expands when you run that command, the same way it does in the Dingo Node Setup guide. Use a different topology.json on the block producer and on each relay.


You can check the file with:

sudo nano /etc/dingo/dingo.yaml

Then restart:

sudo systemctl restart dingo

Congratulations! You now have custom topology files for your relays and block producer.

Section titled “Congratulations! You now have custom topology files for your relays and block producer.”

Doc Holiday logo

Docs authored by Doc Holiday