Skip to content

Commit

Permalink
Added bootstrap peers docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@bolt12
bolt12 committed Mar 6, 2024
1 parent 0e31e68 commit 4c02a4e
Showing 1 changed file with 91 additions and 15 deletions.
106 changes: 91 additions & 15 deletions docs/getting-started/understanding-config-files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,7 @@ Your __block-producing__ node must __ONLY__ talk to your __relay nodes__, and th

## The P2P topology.json file

The P2P topology file specifies how to obtain the _root peers_ (or _bootstrapping
peers_).
The P2P topology file specifies how to obtain the _root peers_.

* The term _local roots_ refers to a group of peer nodes with which a node will aim to
maintain a specific number of active, or 'hot' connections. These hot connections are
Expand All @@ -34,7 +33,8 @@ peers_).
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_: additional bootstrapping nodes. They are either read from

* _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.
Expand All @@ -53,7 +53,9 @@ A minimal version of this file looks like this:
}
],
"advertise": false,
"valency": 1
"valency": 1,
"warmValency": 2,
"trustable": true
}
],
"publicRoots": [
Expand All @@ -66,20 +68,46 @@ A minimal version of this file looks like this:
"advertise": false
}
],
"useLedgerAfterSlot": 0
"useLedgerAfterSlot": 0,
"bootstrapPeers": [
{
"address": "z.z.z.z",
"port": 3003
}
]
}
```

* The main difference between `LocalRoots` and `PublicRoots` is the ability to specify various groups with varying valencies in the former. This can be valuable for informing your node about different targets within a group to achieve. `LocalRoots` is designed for peers that the node should always keep as hot, such as its own block producer. On the other hand, `PublicRoots` serves as a source of fallback peers, to be used if peers from the ledger (when `useLedgerAfterSlot` is disabled or unavailable) cannot be accessed.

* This means that your node will initiate contact with the node at IP `x.x.x.x` on `port 3001` and resolve the DNS domain `y.y.y.y` (provided it exists). It will then make efforts to establish a connection with at least one of the resolved IPs.

* `valency` (or `hotValency`) tells the node the number of connections it should attempt to select from the specified group. When a DNS address is provided, valency determines the count of resolved IP addresses for which the node should maintain an active (hot) connection.

- `warmValency` is an optional field, similar to `valency` or `hotValency`, that informs the node about the number of peers it should maintain as established (warm). This field is optional and defaults to the value set in the `valency` or `hotValency` field. If a value is specified for `warmValency`, it should be greater than or equal to the one defined in `valency` or `hotValency`; otherwise, `valency` or `hotValency` will be adjusted to match this value. We recommend users set the `warmValency` value to `hotValency` + 1 to ensure at least one backup peer is available to be promoted to a hot connection in case of unexpected events.
* The main difference between `LocalRoots` and `PublicRoots` is the ability to
specify various groups with varying valencies in the former. This can be
valuable for informing your node about different targets within a group to
achieve. `LocalRoots` is designed for peers that the node should always keep
as hot, such as its own block producer. On the other hand, `PublicRoots`
serves as a source of fallback peers, to be used if peers from the ledger
(when `useLedgerAfterSlot` is disabled or unavailable) cannot be accessed.

* This means that your node will initiate contact with the node at IP
`x.x.x.x` on `port 3001` and resolve the DNS domain `y.y.y.y` (provided it
exists). It will then make efforts to establish a connection with at least
one of the resolved IPs.

* `valency` (or `hotValency`) tells the node the number of connections it
should attempt to select from the specified group. When a DNS address is
provided, valency determines the count of resolved IP addresses for which
the node should maintain an active (hot) connection.

- `warmValency` is an optional field, similar to `valency` or `hotValency`,
that informs the node about the number of peers it should maintain as
established (warm). This field is optional and defaults to the value set in
the `valency` or `hotValency` field. If a value is specified for
`warmValency`, it should be greater than or equal to the one defined in
`valency` or `hotValency`; otherwise, `valency` or `hotValency` will be
adjusted to match this value. We recommend users set the `warmValency` value
to `hotValency` + 1 to ensure at least one backup peer is available to be
promoted to a hot connection in case of unexpected events.

Check [this issue](https://github.com/intersectmbo/ouroboros-network/issues/4565) for more
context on this `WarmValency` addition.
context on this `WarmValency` option.

* Local root groups shall be non-overlapping.

Expand All @@ -96,7 +124,10 @@ A minimal version of this file looks like this:
* Local roots should not be greater than the `TargetNumberOfKnownPeers`.
If they are, they will get clamped to the limit.

Your __block-producing__ node must __ONLY__ talk to your __relay nodes__, and the relay node should talk to other relay nodes in the network.
- For `trustablePeers` and `bootstrapPeers` read the next section.

Your __block-producing__ node must __ONLY__ talk to your __relay nodes__, and
the relay node should talk to other relay nodes in the network.

You have the option to notify the node of any changes to the topology configuration file
by sending a SIGHUP signal to the `cardano-node` process. This can be done, for example,
Expand All @@ -112,7 +143,52 @@ forging, ensure that the necessary files are present.
You can disable ledger peers by setting the `useLedgerAfterSlot` to a negative
value.

If you are syncing the network for the first time, please connect to IOG relays at `relays-new.cardano-mainnet.iohkdev.io` by adding them to your local root peers. Additionally, set `useLedgerAfterSlot` to `0` to disable ledger peers. You have the flexibility to use different relays, but it's important to ensure you trust them to provide an honest chain. Once your node is fully synced, feel free to remove these relays from your local root peers. Also, make it a practice to manually verify if other stake pool relays are on the same chain as yours. When you enable ledger peers by setting `useLedgerAfterSlot`, your node will establish connections with relays registered on the chain. It will actively churn through these peers by randomly selecting new ones based on stake distribution while also removing the least performing 20%.
If you are syncing the network for the first time, please connect to IOG
relays at `relays-new.cardano-mainnet.iohkdev.io` by adding them to your local
root peers. Additionally, set `useLedgerAfterSlot` to `-1` to disable ledger
peers. You have the flexibility to use different relays, but it's important to
ensure you trust them to provide an honest chain. Once your node is fully
synced, feel free to remove these relays from your local root peers. Also,
make it a practice to manually verify if other stake pool relays are on the
same chain as yours. When you enable ledger peers by setting
`useLedgerAfterSlot`, your node will establish connections with relays
registered on the chain. It will actively churn through these peers by
randomly selecting new ones based on stake distribution while also removing
the least performing 20%.

### Weak Genesis a.k.a Bootstrap Peers

Bootstrap Peers is a pre-Genesis feature that means to provide a way for a
node to connect to a trustable set of peers when the its chain falls behind.

Bootstrap peers can be disabled by setting `bootstrapPeers: null`, although
they are disabled by default. They are enabled by providing a list of
addresses. By default bootstrap peers are disabled.

Trustable peers are composed by the bootstrap peers (see `bootstrapPeers`
option in the example topology file above) and the trustable local root peers
(see `trustable` option in the example topology file above). By default
peers are not trustable.

In order for the node to be able to start and make progress, the user _must_
provide a trustable source of peers via topology file. This means that the
node will only start if either the bootstrap peers list is non-empty or
there's a local root group that is trustable. Failing to configure the node
with trustable peer sources will make it so that the node crashes with an
exception. *_Please note_* that if the only source of trustable peers is a DNS
name, the node might not be able to make progress once in fallback state, if
DNS is not providing any addresses.

Provided that the node is well configured the node will function as expected.

In the event the node's chain falls too far behind, the node will transition
to a `TooOld` state and will proceed to disconnect from all its connections,
effectively purging itself from any non-trustable peer. After doing so, it
will change to `BootstrapOnly` mode, where it will only learn about trustable
peers (i.e. connect to bootstrap peers and local root trustable peers), thus
connecting only to trusted peers and catching up from them. Once the node
catches up, it will transition to a `YoungEnough` state and proceed to issue
connections to other peer sources.

## The genesis.json file

Expand Down

0 comments on commit 4c02a4e

Please sign in to comment.