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 7, 2024
1 parent 0e31e68 commit 0a717b0
Showing 1 changed file with 87 additions and 15 deletions.
102 changes: 87 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,47 @@ 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 or warm, such as its own block producer. On the other hand,
`PublicRoots` serves as a source of fallback peers, to be used if we are
before the configured `useLedgerAfterSlot` slot.

* 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.

* `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.
Note: one can also use the deprecated now `valency` field for `hotValency`.

- `warmValency` is an optional field, similar to `hotValency`,
that informs the node about the number of peers it should maintain as
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 `hotValency`; otherwise,
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 +125,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 +144,47 @@ 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%.
### Light 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`. 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
local root peers are not trustable.

In order for the node to be able to start and make progress, when bootstrap
peers are enabled, 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.

With bootstrap peers enabled the node will trace:

- `TraceLedgerStateJudgmentChanged {TooOld,YoungEnoug}`: If it has changed to
any of these states.

- `TooOld` state means that the information the node is getting from its peers
is outdated and behind at least 20 min. This means there's something wrong
and that the node should only connect to trusted peers (trusted peers are
bootstrap peers and trustable local root peers) in order to sync.

- `YoungEnough` state means that the node is caught up and that it can now
connect to non-trusted peers.

- `TraceOnlyBootstrap`: Once the node transitions to `TooOld` the node will
disconnect from all non-trusted peers and reconnect to only trusted ones in
order to sync from trusted sources only. This tracing message means that the
node has successfully purged all non-trusted connections and is only going
to connect to trusted peers.

## The genesis.json file

Expand Down

0 comments on commit 0a717b0

Please sign in to comment.