Skip to content

Commit

Permalink
comprehensive spelling review
Browse files Browse the repository at this point in the history
  • Loading branch information
rphair authored Feb 20, 2025
1 parent 2658e0f commit 0b32d29
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions docs/get-started/cardano-node/topology.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ A minimal version of this file looks like this:

### Local Roots

* `LocalRoots` are designed for peers that the node **should always keep as hot or warm**, such as its own block producer or fullfill aranged agreements with other SPOs.
* `LocalRoots` are designed for peers that the node **should always keep as hot or warm**, such as its own block producer or fulfill arranged agreements with other SPOs.

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 try to connect with at least one of the resolved IPs.
Expand Down Expand Up @@ -176,17 +176,17 @@ With bootstrap peers enabled, the node will trace the following:

### [Ouroboros Genesis](https://iohk.io/en/blog/posts/2024/05/08/ouroboros-genesis-design-update/)

Ouroboros Genesis is the upcoming mechanism of trustless syncing in P2P environment which is expected to supercede bootstrap peers described in the previous section. This feature is included starting with `cardano-node 10.2`, and at the time of this writing it is disabled by default - refer to config.json file section below on instructions how to enable this by toggling a feature flag. Once enabled, this mode is incompatibile with bootstrap peers, and will disable the latter by overriding the configuration, and emit a trace of such occurence to inform the operator to update topology file. From the perspective of the topology file a new entry must be added:
Ouroboros Genesis is the upcoming mechanism of trustless syncing in P2P environment which is expected to supersede bootstrap peers described in the previous section. This feature is included starting with `cardano-node 10.2`, and at the time of this writing it is disabled by default - refer to config.json file section below on instructions how to enable this by toggling a feature flag. Once enabled, this mode is incompatible with bootstrap peers, and will disable the latter by overriding the configuration, and emit a trace of such occurrence to inform the operator to update topology file. From the perspective of the topology file a new entry must be added:

`"peerSnapshotFile": "path/to/snapshot.json"`

The file contains a snapshot of so-called big ledger peers which are the largest peers registered on the ledger which cumulatively hold 90% of stake at some arbitrary slot number. By virtue of the size of their stake in the system, they are postulated to be a proxy for honest ledger state. When syncing in this mode, these peers are sampled and connected with to bootstrap the process. Such a snapshot file can be created manually apriori with cardano-cli from a synced node, and may be distributed with a node release in the future. For reference,

### Configuring the node to use P2P

You can enable P2P from the configuration file; the field `EnableP2P` can be set to either `false` or `true`. When setting it to `true`, you will also need to configure the target number of _active_, _established_ and _known_ peers, together with the target number of _root_ peers. These values control the number of outbound connections the node will try to maintain in the appropriate mode to what are collectively named our upstream peers. This is important for the node as blocks are downloadeded strictly from these peers and we want to maintain sufficiently many outbound connections to both:
You can enable P2P from the configuration file; the field `EnableP2P` can be set to either `false` or `true`. When setting it to `true`, you will also need to configure the target number of _active_, _established_ and _known_ peers, together with the target number of _root_ peers. These values control the number of outbound connections the node will try to maintain in the appropriate mode to what are collectively named our upstream peers. This is important for the node as blocks are downloaded strictly from these peers and we want to maintain sufficiently many outbound connections to both:
- ensure we remain on the current network blockchain tip in a timely fashion
- to harden ourselves from potential eclipse attacks in the presence of adverserial actors.
- to harden ourselves from potential eclipse attacks in the presence of adversarial actors.

Importantly, blocks that the node is itself serving on demand or the transactions it is requesting are determined by its downstream clients on which these peer target values have no bearing on. There isn't any fine-grained way to control theses connection modes for our downstream/client peers, ie. the nodes that have our node as its upstream peer. It is these clients that decide for themselves if our node is either in established or active mode from their perspective, but this does impact on our resource usage, such as processor utilization, bandwidth consumption, memory footprint, or file descriptor usage. The last item is subtle and easy to overlook - the cardano-node implementation is carefully designed around minimizing file descriptor usage, but it is a limited global resource which other unrelated processes running on the host consume. Running out of file descriptors may make the node unresponsive and essentially appear stuck, requiring a manual intervention. Regardless, these are general points that apply to all software applications, and in particular to this or other blockchain node implementations.

Expand Down Expand Up @@ -222,9 +222,9 @@ are in effect when the node deems itself caught up to its peers.
* `TargetNumberOfEstablishedBigLedgerPeers` - the target for established connections with big ledger peers (the sum of warm & hot big ledger peers).
* `TargetNumberOfKnownBigLedgerPeers` - the target for known big ledger peers (the sum of cold, warm & hot big ledger peers).

* `TargetNumberOfRootPeers` - a lower limit for known local roots, ledger peers / public root peers. Anything beyoned this target will be filled by peers from peer sharing, ledger / public root peers.
* `TargetNumberOfRootPeers` - a lower limit for known local roots, ledger peers / public root peers. Anything beyond this target will be filled by peers from peer sharing, ledger / public root peers.

Note, when using bootstrap-peers, feature the targets have to be large enough to accomodate all bootstrap peers.
Note, when using bootstrap-peers, feature the targets have to be large enough to accommodate all bootstrap peers.

**Custom targets must satisfy the property that # of known >= # of established >= # of active >= 0 otherwise the node will fail to start as it is a serious misconfiguration.**

Expand Down

0 comments on commit 0b32d29

Please sign in to comment.