diff --git a/docs/getting-started/understanding-config-files.md b/docs/getting-started/understanding-config-files.md index de31a27..de794dc 100644 --- a/docs/getting-started/understanding-config-files.md +++ b/docs/getting-started/understanding-config-files.md @@ -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 @@ -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. @@ -53,7 +53,9 @@ A minimal version of this file looks like this: } ], "advertise": false, - "valency": 1 + "valency": 1, + "warmValency": 2, + "peerTrustable": true } ], "publicRoots": [ @@ -66,20 +68,46 @@ A minimal version of this file looks like this: "advertise": false } ], - "useLedgerAfterSlot": 0 + "useLedgerAfterSlot": 0, + "useBootstrapPeers": [ + { + "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. @@ -107,12 +135,58 @@ Please be aware that this procedure is specific to the topology configuration fi the node configuration file. Additionally, the SIGHUP signal will prompt the system to re-read the block forging credentials file paths and attempt to fetch them to initiate block forging. If this process fails, block forging will be disabled. To re-enable block -forging, ensure that the necessary files are present. +forging, ensure that the necessary files are present (check [here](../../reference/dynamic-block-forging) +for more details about dynamically enabling/disabling block forging). 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%. + +### 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 `useBootstrapPeers: false`. They +are enabled by providing a list of addresses. By default bootstrap peers are +disabled. + +Trustable peers are composed by the bootstrap peers (see `useBootstrapPeers` +option in the example topology file above) and the trustable local root peers +(see `peerTrustable` 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