streamline docs

Tofel · Tofel · commit e05e656ef467 · 2024-12-17T12:11:37.000+01:00
diff --git a/book/src/docker/blockchain_nodes.md b/book/src/docker/blockchain_nodes.md
@@ -1,36 +1,40 @@
-# Blockchain nodes
+# Blockchain Nodes
 
-It is highly advised that if you did decide to play around with these Docker containers that you use an existing Ethereum enviroment builder
-instead of trying to put all the pieces together. That's especially important for Proof-Of-Stake networks, where the setup is a multi-stage
-operation that needs to be executed in specific order and where multiple containers need access to the same (or shared) state.
+If you plan to experiment with these Docker containers, **use an existing Ethereum environment builder** rather than assembling components manually. This is particularly important for Proof-of-Stake (PoS) networks, where the setup involves multi-stage operations and shared state across multiple containers.
 
-By default, each of supported clients has a default image version that's defined [here](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/lib/docker/ethereum/images.go).
-All of them apart from Reth, come in two flavours: one that is a Proof-Of-Stake (Ethereum 2.0) network and another that's a Proof-Of-Work/Authority (Ethereum 1.0). Reth has only the former
-since the latter was never implemented by its creators.
+Each supported client has a default image version defined [here](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/lib/docker/ethereum/images.go). Clients (except Reth) are available in two flavors:
+- **Proof-of-Stake (PoS)**: Ethereum 2.0.
+- **Proof-of-Work/Authority (PoW/PoA)**: Ethereum 1.0.
 
-All of these epehemeral networks are using a grossly simplified configuration that is composed of a single blockchain node. Technically that's also true, in case of PoS networks,
-even though they are running three containers:
-* execution layer container
-* consensus layer container
-* validator
+Reth supports only PoS networks.
+
+These ephemeral networks use a simplified configuration with a single blockchain node. For PoS, three containers simulate this:
+- Execution layer
+- Consensus layer
+- Validator
 
 > [!NOTE]
-> We use our own fork of [Ethereum Genesis Generator](https://github.com/ethpandaops/ethereum-genesis-generator) to
-> create genesis files both for PoW/PoA and PoS Ethereum networks.
-
-## Execution Layer
-Following execution layers are available
-* Besu
-* Erigon
-* Geth
-* Nethermind
-* Reth
-
-## Consensus Layer
-Only one consensus client is available: Prysm.
-
-# Quick start
-The simplest of starting a new Ethereum network is by specifying only the execution layer:
+> We use a fork of [Ethereum Genesis Generator](https://github.com/ethpandaops/ethereum-genesis-generator) to create genesis files for PoS networks.
+
+---
+
+## Execution Layer Clients
+The following execution layer clients are available:
+- Besu
+- Erigon
+- Geth
+- Nethermind
+- Reth
+
+## Consensus Layer Client
+- **Prysm** (the only available consensus client).
+
+---
+
+# Quick Start
+
+The simplest way to start an Ethereum network is by specifying the execution layer only:
+
 ```go
 builder := NewEthereumNetworkBuilder()
 cfg, err := builder.
@@ -45,15 +49,14 @@ if err != nil {
     panic(err)
 }
 ```
+If no version is specified, **Ethereum 1.0 (pre-Merge)** will be used.
 
-If no Ethereum version is specified, Ethereum 1.0 (pre-Merge) will be used.
+### Starting Ethereum 2.0 Networks
+To start an Ethereum 2.0 network, add the Ethereum version parameter:
 
-# Ethereum 2 network
-To start Ethereum 2.0 network you need to pass one more parameter to the builder:
 ```go
 builder := NewEthereumNetworkBuilder()
 cfg, err := builder.
-    // notice the new parameter
     WithEthereumVersion(config_types.EthereumVersion_Eth2).
     WithExecutionLayer(config_types.ExecutionLayer_Geth).
     Build()
@@ -66,14 +69,14 @@ if err != nil {
     panic(err)
 }
 ```
-
 > [!NOTE]
-> It takes significantly longer to boot up an Ethereum 2.0 network due to number of
-> containers involved. 1 minute long wait times are not unheard of, so if startup
-> speed is crucial think if Ethereum 1.0 is good enough for your use case.
+> Booting Ethereum 2.0 networks takes longer due to the additional containers. Wait times of up to 1 minute are common.
+
+---
+
+## Custom Docker Images
+To use custom Docker images instead of the defaults:
 
-# Custom docker images
-If you don't want to use default image versions you can pass custom ones in the following manner:
 ```go
 builder := NewEthereumNetworkBuilder()
 cfg, err := builder.
@@ -90,73 +93,47 @@ if err != nil {
     panic(err)
 }
 ```
-Where available container types are:
+### Available Container Types
 ```go
 const (
-	ContainerType_ExecutionLayer     ContainerType = "execution_layer"
-	ContainerType_ConsensusLayer     ContainerType = "consensus_layer"
-	ContainerType_ConsensusValidator ContainerType = "consensus_validator"
-	ContainerType_GenesisGenerator   ContainerType = "genesis_generator"
-	ContainerType_ValKeysGenerator   ContainerType = "val_keys_generator"
+    ContainerType_ExecutionLayer     ContainerType = "execution_layer"
+    ContainerType_ConsensusLayer     ContainerType = "consensus_layer"
+    ContainerType_ConsensusValidator ContainerType = "consensus_validator"
+    ContainerType_GenesisGenerator   ContainerType = "genesis_generator"
+    ContainerType_ValKeysGenerator   ContainerType = "val_keys_generator"
 )
 ```
-When passing custom docker image for execution layer you don't need to use neither `WithEthereumVersion()` nor `WithExecutionLayer()` functions
-as we will get these from the Docker image.
-
 > [!NOTE]
-> There are two useful "synthetic" Docker tags you can use with custom images:
-> - `latest_available` - which represents the latest release (including pre-releases)
-> - `latest_stable` - which represents latest **stable** release
+> Use the `latest_available` tag for the most recent release, including pre-releases, or the `latest_stable` tag for the latest officially stable release. The `latest_available` may include beta or development versions, whereas `latest_stable` ensures compatibility with production environments.
+
+---
+
+# Advanced Options
+
+## Connect to Existing Docker Networks
+By default, a new random Docker network is created. To use an existing one:
 
-# Existing Docker network(s)
-By default, the chain will be started on a new Docker network with random name. If you want it to connect to existing one instead, use the following option:
 ```go
 builder := NewEthereumNetworkBuilder()
 cfg, err := builder.
     WithExecutionLayer(types.ExecutionLayer_Nethermind).
     WithDockerNetworks([]string{"my-existing-network"}).
     Build()
-if err != nil {
-    panic(err)
-}
 ```
 
-# Chain customisation
-Below you will find a description of easily customisable parameters of the chain or its startup.
-
-## Slots per epoch and seconds per slot (Ethereum 2.0 only)
-These parameters control how fast epochs progress.
-
-`Seconds per slot` represents the number of seconds that validator have to vote on blocks.
-The lower the value the faster the epoch finalisation. If it's too low, validators will not be
-able to vote and no new blocks will be produced. Minimum allowed value is `3`.
-
-`Slots per epoch` represent the number of voting runds per epoch. The lower the number, the faster
-the finalization. Minimum allowed value is `2.`
-
-## ChainID
-Can be anything as long as it's an integer.
-
-## Addresses to fund
-Addresses that will be funded with `9000000000000000000000000000 wei` in the genesis.
+## Chain Customization
 
-## Hard Forks (Ethereum 2.0 only)
-Map of hard fork name to epoch, in which the fork should happen. Has to be `> 0`. It's useful for testing
-how software will behave during the fork. Currently, the only fork that's supported is `Deneb`, but it can
-only be used with Docker images that belong to "pre-Deneb times" and running on `Shanghai` version of Ethereum 2.0
-(so pretty old versions). For the latest images there are no supported future forks as of time of this documentation
-creation there were no dates set for any of the incoming forks (which means none of them is supported by neither
-execution nor consensus layer clients).
+### Ethereum 2.0 Parameters
+- **Seconds per slot**: This defines how many seconds validators have to propose and vote on blocks. Lower values accelerate block production and epoch finalization but can cause issues if validators fail to keep up. The minimum allowed value is `3`.
+- **Slots per epoch**: Determines the number of slots (voting rounds) per epoch. Lower values mean epochs finalize faster, but fewer voting rounds can impact network stability. The minimum value is `2`.
+- **Genesis delay**: The extra delay (in seconds) before the genesis block starts. This ensures all containers (execution, consensus, and validator) are up and running before block production begins.
+- **Validator count**: Specifies the number of validators in the network. A higher count increases the robustness of block validation but requires more resources. The minimum allowed value is `4`.
 
-## Validator count (Ethereum 2.0 only)
-Number of validators to run. `4` is a minimum allowed.
+### General Parameters
+- **ChainID**: Integer value for the chain.
+- **Addresses to fund**: Pre-fund accounts in the genesis block.
 
-## Genesis Delay (Ethereum 2.0 only)
-Extra delay added to genesis block timestamp to be sure that both layers are up and running before it happens. Increasing it could be
-useful in case of running on very slow system.
-
-## Default values
-Default chain config comes with the following values:
+### Default Configuration
 ```toml
 seconds_per_slot=12
 slots_per_epoch=6
@@ -166,86 +143,60 @@ chain_id=1337
 addresses_to_fund=["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"]
 ```
 
-# Other useful options
-## Blockchain node log level
-By default, all blockchain nodes use `info` log level, but you can change that with the following option:
+---
+
+## Log Level
+Customize node log levels (default: `info`):
 ```go
-builder := NewEthereumNetworkBuilder()
-cfg, err := builder.
-    WithCustomDockerImages(map[config.ContainerType]string{
-        config.ContainerType_ExecutionLayer: "ethereum/client-go:v1.15.0",
-    }).
-    WithNodeLogLevel("debug").
-    Build()
-if err != nil {
-    panic(err)
-}
+WithNodeLogLevel("debug")
 ```
-This configuration is applied only to execution layer nodes. Following values are supported:
-* `trace`
-* `debug`
-* `info`
-* `warn`
-* `error`
-
-## Waiting for first epoch finalization (Ethereum 2.0 only)
-In case you want the network to wait until first epoch has been finalised you can use the following option:
+Supported values:
+- `trace`, `debug`, `info`, `warn`, `error`
+
+## Wait for Finalization (Ethereum 2.0)
+Wait until the first epoch finalizes:
 ```go
-builder := NewEthereumNetworkBuilder()
-cfg, err := builder.
-    WithCustomDockerImages(map[config.ContainerType]string{
-        config.ContainerType_ExecutionLayer: "ethereum/client-go:v1.15.0",
-    }).
-    WithWaitingForFinalization().
-    Build()
-if err != nil {
-    panic(err)
-}
+WithWaitingForFinalization()
 ```
 
-# Accessing containers from inside and outside of the Docker network
-Function that starts the environment returns an error or two values:
-* instance of `blockchain.Network` that can be used to start our test clients
-* instance of `test_env.RpcProvider` that has a list of useful endpoints
+---
 
-These endpoints come in two flavours:
-* public (accessible from other Docker networks and the host machine)
-* private (accessible only from inside the same Docker network)
+# Accessing Containers
+The `builder.Start()` function returns:
+1. **Network configuration**: Input to test clients.
+2. **RPC endpoints**:
+   - **Public**: Accessible externally.
+   - **Private**: Internal to the Docker network.
 
-And are the HTTP and WS endpoints of the execution layer clients, ones which the Chainlink Node
-needs to communicate with. Beacon Chain (consensus layer) endpoints are not exposed.
+### Endpoint Usage
+- Use **public endpoints** for Ethereum clients deploying contracts, interacting with the chain, etc.
+- Use **private endpoints** for Chainlink nodes within the same Docker network.
 
-If you're wondering which one to use, the usual case would be:
-* public for the Ethereum Client that will interact with the chain, deploy contracts, etc.
-* private for the Chainlink Node if it uses the same Docker network as the chain, public otherwise
+---
 
-# Ethereum 2.0 container creation sequence
-Since the sequence of container creation and interaction for Ethereum 2.0 is much more complicated
-than for Ethereum 1.0 (where we only need to start a single container) below you will find a sequence
-diagram that explains it in more detail:
+# Ethereum 2.0 Container Creation Sequence
+The following sequence explains Ethereum 2.0 container startup:
 
 ```mermaid
----
-title: Ethereum 2.0 container creation sequence
----
 sequenceDiagram
-    participant Host Machine
-    participant Validators Keys Generator
+    participant Host
+    participant Validator Keys Generator
     participant Genesis Generator
-    participant Execution Layer (e.g. Besu or Geth)
-    participant Consensus Layer (Prysm Beacon Chain)
-    participant Consensus Layer (Prysm Validator)
+    participant Execution Layer
+    participant Beacon Chain (Consensus Layer)
+    participant Validator
     participant After Genesis Helper
     participant User
-    Validators Keys Generator->>Host Machine: Generate new validators keys<br/> and save them to on the host
-    Genesis Generator->>Host Machine: Generate Ethereum 1.0 and Ethereum 2.0 genesis files<br/> and save them on the host
-    Host Machine->>Execution Layer (e.g. Besu or Geth): Read Ehtereum 1.0 genesis and start
-    Host Machine->>Consensus Layer (Prysm Beacon Chain): Read Ehtereum 2.0 genesis and start
-    Consensus Layer (Prysm Beacon Chain)->>Execution Layer (e.g. Besu or Geth): Conntect and start<br/> following the chain
-    Host Machine->>Consensus Layer (Prysm Validator): Read validator keys and start
-    Consensus Layer (Prysm Validator)->>Consensus Layer (Prysm Beacon Chain): Connect and start voting on blocks
-    loop observe chain
-    After Genesis Helper->>Execution Layer (e.g. Besu or Geth): Wait until new blocks are produced
+
+    Validator Keys Generator->>Host: Generate validator keys
+    Genesis Generator->>Host: Create genesis files
+    Host->>Execution Layer: Start with genesis
+    Host->>Beacon Chain (Consensus Layer): Start with genesis
+    Beacon Chain (Consensus Layer)->>Execution Layer: Connect and sync
+    Host->>Validator: Start with validator keys
+    Validator->>Beacon Chain (Consensus Layer): Begin block voting
+    loop new blocks
+    After Genesis Helper->>Execution Layer: Monitor new blocks
     end
-    After Genesis Helper->>User: Allow to proceed<br/> and interact with the chain
+    After Genesis Helper->>User: Ready to interact
 ```
