diff --git a/docs/private-networks/how-to/configure/consensus/index.md b/docs/private-networks/how-to/configure/consensus/index.md index b3903983..43c5c35e 100644 --- a/docs/private-networks/how-to/configure/consensus/index.md +++ b/docs/private-networks/how-to/configure/consensus/index.md @@ -11,11 +11,10 @@ Besu supports the following consensus protocols: * [IBFT 2.0](ibft.md) (proof of authority) - Supported for existing private networks. * [Clique](clique.md) (proof of authority) - Not recommended for production use. -* [Proof of stake](https://docs.teku.consensys.net/en/latest/Concepts/Proof-of-Stake/) - Used on Ethereum Mainnet - post-[Merge](../../../../public-networks/concepts/the-merge.md) and can also be used on the [Merge testnet](../../../../public-networks/tutorials/merge-testnet.md). -* [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) (proof of work) - Used on Ethereum Mainnet - pre-[Merge](../../../../public-networks/concepts/the-merge.md) and can also be used in - [small development networks](../../../tutorials/ethash.md). +* [Proof of stake](../../../../public-networks/concepts/proof-of-stake.md) - Used on Ethereum + Mainnet and public testnets. +* [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) (proof of work) - Can + be used in [small development networks](../../../tutorials/ethash.md). See a [comparison of the proof of authority consensus protocols](../../../concepts/poa.md). diff --git a/docs/private-networks/reference/api/index.md b/docs/private-networks/reference/api/index.md index 1dd6504d..2270a49d 100644 --- a/docs/private-networks/reference/api/index.md +++ b/docs/private-networks/reference/api/index.md @@ -325,8 +325,8 @@ transaction data using `eea_sendRawTransaction`. with the chain. For example, [IBFT 2.0](../../how-to/configure/consensus/ibft.md) and [QBFT](../../how-to/configure/consensus/qbft.md) provide the required finality. - Using private transactions with [pruning](../../../public-networks/how-to/connect/sync-node.md) or - [fast sync](../../../public-networks/reference/cli/options.md#sync-mode) is not supported. + Using private transactions with [pruning](../../../public-networks/concepts/data-storage-formats.md#pruning) + or [fast sync](../../../public-networks/reference/cli/options.md#sync-mode) isn't supported. Besu doesn't implement [`eea_sendTransaction`](../../how-to/send-transactions/private-transactions.md). diff --git a/docs/public-networks/concepts/data-storage-formats.md b/docs/public-networks/concepts/data-storage-formats.md index 07752c42..7308adb5 100644 --- a/docs/public-networks/concepts/data-storage-formats.md +++ b/docs/public-networks/concepts/data-storage-formats.md @@ -55,9 +55,9 @@ To run a node with Bonsai Tries data storage format, use the command line option ### Storage requirements Forest mode uses significantly more memory than Bonsai. -With an [archive node](../how-to/connect/sync-node.md#run-an-archive-node), forest mode uses an estimated 12 TB of +With an [archive node](../get-started/connect/sync-node.md#run-an-archive-node), forest mode uses an estimated 12 TB of storage, while Bonsai uses an estimated 1100 GB of storage. -With a [full node](../how-to/connect/sync-node.md#run-a-full-node), forest mode uses an estimated 750 GB of storage, +With a [full node](../get-started/connect/sync-node.md#run-a-full-node), forest mode uses an estimated 750 GB of storage, while Bonsai uses an estimated 650 GB of storage. ### Accessing data @@ -78,8 +78,8 @@ The default limit Bonsai looks back is 512. To change the parameter, use the ### Syncing nodes -The following table shows the ways you can [sync a full node](../how-to/connect/sync-node.md#run-a-full-node) with the different data -storage formats using [fast](../how-to/connect/sync-node.md#fast-synchronization) and [snap](../how-to/connect/sync-node.md#snap-synchronization) sync. +The following table shows the ways you can [sync a full node](../get-started/connect/sync-node.md#run-a-full-node) with the different data +storage formats using [fast](../get-started/connect/sync-node.md#fast-synchronization) and [snap](../get-started/connect/sync-node.md#snap-synchronization) sync. | Data storage format | Sync mode | Storage estimate | Can other nodes sync to your node? | |---------------------|-----------|------------------|------------------------------------| diff --git a/docs/public-networks/concepts/proof-of-stake.md b/docs/public-networks/concepts/proof-of-stake.md index 263737c2..f122c79e 100644 --- a/docs/public-networks/concepts/proof-of-stake.md +++ b/docs/public-networks/concepts/proof-of-stake.md @@ -4,7 +4,7 @@ description: Ethereum proof of stake # Proof of stake -[The Merge](the-merge.md) transitions Ethereum Mainnet to +[The Merge](the-merge.md) transitioned Ethereum Mainnet to [proof of stake (PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) consensus. PoS is preferred over proof of work and proof of authority as a consensus mechanism @@ -46,7 +46,7 @@ In Ethereum's PoS, you must run a [full node](the-merge.md#execution-and-consens !!! note - You must run a beacon node and an execution client to operate a full node on Mainnet post-Merge. + You must run a beacon node and an execution client to operate a full node on Mainnet. To become a validator, you must also run a validator client (either [in the same process as the beacon node](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#start-the-clients-in-a-single-process) or [separately](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#run-the-clients-separately)). diff --git a/docs/public-networks/concepts/the-merge.md b/docs/public-networks/concepts/the-merge.md index 90235e31..5f52fd54 100644 --- a/docs/public-networks/concepts/the-merge.md +++ b/docs/public-networks/concepts/the-merge.md @@ -4,20 +4,28 @@ description: What is the Merge? # The Merge -[The Merge](https://ethereum.org/en/upgrades/merge/) is an Ethereum upgrade that merges the [Beacon Chain] into -Ethereum Mainnet, turning Mainnet into a combination of an +!!! important + + The Merge was executed on **September 15, 2022**. + +[The Merge](https://ethereum.org/en/upgrades/merge/) was an Ethereum upgrade that merged the +[Beacon Chain] into Ethereum Mainnet, turning Mainnet into a combination of an [execution layer and consensus layer](#execution-and-consensus-clients). -The Merge transitions Mainnet from proof of work to -[proof of stake consensus](proof-of-stake.md). +The Merge transitioned Mainnet from proof of work to [proof of stake consensus](proof-of-stake.md). + +You can run Besu as an execution client with: -Update and configure Besu to be [ready for The Merge](../how-to/prepare-for-the-merge.md). -You can also run Besu with a consensus client such as [Teku] on the [Merge testnet](../tutorials/merge-testnet.md). +- [Any consensus client on Mainnet](../get-started/connect/mainnet.md). +- [Any consensus client on a testnet](../get-started/connect/testnet.md). +- [Teku on Mainnet](../tutorials/besu-teku-mainnet.md). +- [Teku on a testnet](../tutorials/besu-teku-testnet.md). ## Execution and consensus clients -After The Merge, a full Ethereum Mainnet node will be a combination of an execution client (previously called an -[Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and a consensus client (previously -called an [Ethereum 2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client). +After The Merge, a full Ethereum Mainnet node is a combination of an execution client (previously +called an [Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and +a consensus client (previously called an +[Ethereum 2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client). Execution and consensus clients communicate with each other using the [Engine API](../how-to/use-engine-api.md). @@ -26,45 +34,45 @@ Execution and consensus clients communicate with each other using the ### Execution clients -Execution clients, such as Besu, manage the execution layer, including executing transactions and updating the world state. -Execution clients serve [JSON-RPC API](../reference/engine-api/index.md) requests and communicate with each other in a -peer-to-peer network. +Execution clients, such as Besu, manage the execution layer, including executing transactions and +updating the world state. +Execution clients serve [JSON-RPC API](../reference/engine-api/index.md) requests and communicate +with each other in a peer-to-peer network. ### Consensus clients Consensus clients, such as [Teku], contain beacon node and validator client implementations. The beacon node is the primary link to the [Beacon Chain] (consensus layer). -The validator client performs [validator duties](proof-of-stake.md) on -the consensus layer. -Consensus clients serve [REST API](https://docs.teku.consensys.net/en/stable/Reference/Rest_API/Rest/) requests and -communicate with each other in a peer-to-peer network. +The validator client performs [validator duties](proof-of-stake.md) on the consensus layer. +Consensus clients serve [REST API](https://docs.teku.consensys.net/en/stable/Reference/Rest_API/Rest/) +requests and communicate with each other in a peer-to-peer network. -## What happens during The Merge +## What happened during The Merge -Before The Merge, the execution and consensus clients' configurations will be -[updated](../how-to/prepare-for-the-merge.md#update-besu) to listen for a certain total terminal difficulty (TTD) -to be reached. +Before The Merge, the execution and consensus clients' configurations were updated to listen for a +certain total terminal difficulty (TTD) to be reached. !!! info - The TTD is a specific value for the total difficulty, which is the sum of the proof-of-work mining difficulty for - all blocks up to some point in the blockchain. + The TTD is a specific value for the total difficulty, which is the sum of the proof-of-work + mining difficulty for all blocks up to some point in the blockchain. -The consensus layer will enable the Merge configuration (Bellatrix) before reaching the TTD. -Once the execution layer blocks reach the TTD, the Beacon Chain will merge into Ethereum Mainnet, and Ethereum will move -to a proof of stake network. +The consensus layer enabled the Merge configuration (Bellatrix) before reaching the TTD. +Once the execution layer blocks reached the TTD, the Beacon Chain merged into Ethereum Mainnet, and +Ethereum transitioned to a proof of stake network. -After The Merge, a Mainnet node operator must run both an execution client and a beacon node at the same time. -To become a validator, you must also run a validator client (either -[in the same process as the beacon node](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#start-the-clients-in-a-single-process) -or [separately](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#run-the-clients-separately). +!!! important + + After The Merge, a Mainnet node operator must run both an execution client and a beacon node at + the same time. + To become a validator, you must also run a validator client (either + [in the same process as the beacon node](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#start-the-clients-in-a-single-process) + or [separately](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Run-Teku/#run-the-clients-separately). After The Merge, validators earn rewards for performing [validator duties](proof-of-stake.md), and [fee recipients](https://docs.teku.consensys.net/en/latest/HowTo/Prepare-for-The-Merge/#configure-the-fee-recipient) -will also earn rewards for the inclusion of execution layer transactions. - -Update and configure Besu to be [ready for The Merge](../how-to/prepare-for-the-merge.md). +also earn rewards for the inclusion of execution layer transactions. [Beacon Chain]: https://ethereum.org/en/upgrades/beacon-chain/ diff --git a/docs/public-networks/get-started/connect/index.md b/docs/public-networks/get-started/connect/index.md new file mode 100644 index 00000000..abf91482 --- /dev/null +++ b/docs/public-networks/get-started/connect/index.md @@ -0,0 +1,9 @@ +--- +title: Connect to a network overview +hide: + - feedback +--- + +# Connect to a network + +This section provides information on connecting Besu to a public Ethereum network. diff --git a/docs/public-networks/get-started/connect/mainnet.md b/docs/public-networks/get-started/connect/mainnet.md new file mode 100644 index 00000000..0fea9b99 --- /dev/null +++ b/docs/public-networks/get-started/connect/mainnet.md @@ -0,0 +1,145 @@ +--- +description: How to connect to Mainnet +--- + +# Connect to Mainnet + +!!! important + + [The Merge](../../concepts/the-merge.md) was executed on **September 15, 2022**. + Ethereum is now a [proof of stake](../../concepts/proof-of-stake.md) network, and a full Ethereum + node requires both [an execution client and a consensus client](../../concepts/the-merge.md#execution-and-consensus-clients). + +Run Besu as an [execution client](../../concepts/the-merge.md#execution-clients) with any consensus +client on Ethereum Mainnet. + +If you're using [Teku] as a consensus client, you can follow the +[Besu and Teku Mainnet tutorial](../../tutorials/besu-teku-mainnet.md). + +## Prerequisites + +- [Besu installed](../install/binary-distribution.md). +- A consensus client installed. + For example, [Teku](https://docs.teku.consensys.net/en/latest/). + +## Steps + +### 1. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and the consensus client. +This is a shared JWT secret the clients use to authenticate each other when using the +[Engine API](../../how-to/use-engine-api.md). + +### 2. Start Besu + +Run the following command or specify the options in a +[configuration file](../../how-to/configuration-file.md): + +```bash +besu \ + --sync-mode=X_SNAP \ + --data-storage-format=BONSAI \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ + --Xmerge-support=true \ + --engine-jwt-secret= +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 1](#1-generate-the-shared-secret) + using the [`--engine-jwt-secret`](../../reference/cli/options.md#engine-jwt-secret) option. +- The IP address of your Besu node using the [`--host-allowlist`](../../reference/cli/options.md#host-allowlist) + and [`--engine-host-allowlist`](../../reference/cli/options.md#engine-host-allowlist) options. + +Also, in the command: + +- [`--sync-mode`](../../reference/cli/options.md#sync-mode) specifies using [snap sync](sync-node.md#snap-synchronization). +- [`--data-storage-format`](../../reference/cli/options.md#data-storage-format) specifies using + [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries). +- [`--rpc-http-enabled`](../../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC + service. +- [`--rpc-http-host`](../../reference/cli/options.md#rpc-http-host) is set to `0.0.0.0` to allow + remote RPC connections. +- [`--rpc-ws-enabled`](../../reference/cli/options.md#rpc-ws-enabled) enables the WebSocket JSON-RPC + service. +- [`--rpc-ws-host`](../../reference/cli/options.md#rpc-ws-host) is set to `0.0.0.0` to allow remote + RPC connections. +- `--Xmerge-support` enables Merge support. + +You can modify the option values and add other [command line options](../../reference/cli/options.md) +as needed. + +### 3. Generate validator keys and stake ETH + +If you're running a beacon node only, skip to the next step. + +If you're also running a validator client, have a funded Ethereum address ready (32 ETH and gas fees +for each validator). + +Generate validator keys and stake your ETH for one or more validators using the +[Staking Launchpad](https://launchpad.ethereum.org/en/). + +!!! important + + Save the password you use to generate each key pair in a `.txt` file. + You should also have a `.json` file for each validator key pair. + + Ensure your Besu node is fully synced before submitting your staking deposit. + This can take several days. + +### 4. Start the consensus client + +Refer to your consensus client documentation to configure and start the consensus client. + +!!! important + + If you're running a validator client, make sure you set a fee recipient address. + +If you're using Teku, follow the [Besu and Teku Mainnet tutorial](../../tutorials/besu-teku-mainnet.md#5-start-teku). + +### 5. After starting the clients + +After starting Besu and the consensus client, your node starts syncing and connecting to peers. + +!!! example + + === "Besu logs" + + ```bash + 2022-03-21 20:42:09.295-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.298-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.848-07:00 | nioEventLoopGroup-3-8 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 4 + 2022-03-21 20:42:18.452-07:00 | nioEventLoopGroup-3-8 | INFO | SyncTargetManager | Found common ancestor with peer Peer 0xab3a286b181721c794... at block 55127 + 2022-03-21 20:42:18.454-07:00 | nioEventLoopGroup-3-8 | INFO | PipelineChainDownloader | PipelineChain download complete + ``` + + === "Teku logs" + + ```bash + 2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 + 2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 + 2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 + 2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 + 2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 + ``` + +You can check your validator status by searching your Ethereum address on the [Beacon Chain explorer](https://beaconcha.in/). +It may take up to multiple days for your validator to be activated and start proposing blocks. + +!!! caution + + If you restart your node before snap or checkpoint sync completes, syncing restarts from scratch. + + +[Teku]: https://docs.teku.consensys.net/en/stable/ diff --git a/docs/public-networks/how-to/connect/sync-node.md b/docs/public-networks/get-started/connect/sync-node.md similarity index 94% rename from docs/public-networks/how-to/connect/sync-node.md rename to docs/public-networks/get-started/connect/sync-node.md index fc060359..09708d7a 100644 --- a/docs/public-networks/how-to/connect/sync-node.md +++ b/docs/public-networks/get-started/connect/sync-node.md @@ -54,7 +54,7 @@ options. Using fast sync with [private transactions](../../../private-networks/concepts/privacy/index.md) isn't supported. You can observe the `besu_synchronizer_fast_sync_*` and `besu_synchronizer_world_state_*` -[metrics](../monitor/metrics.md#metrics-list) to monitor fast sync. +[metrics](../../how-to/monitor/metrics.md#metrics-list) to monitor fast sync. !!! note @@ -119,7 +119,11 @@ You can't switch from fast sync to snap sync. If your node is blocked in the middle of a fast sync, you can start over using snap sync instead by stopping the node, deleting the data directory, and starting over using `--sync-mode=X_SNAP`. -See [how to read the Besu metrics charts](../monitor/understand-metrics.md) when using snap sync. +See [how to read the Besu metrics charts](../../how-to/monitor/understand-metrics.md) when using snap sync. + +!!! caution + + If you restart your node before snap sync completes, syncing restarts from scratch. ### Checkpoint synchronization @@ -150,6 +154,10 @@ number, and total difficulty as in the following example. } ``` +!!! caution + + If you restart your node before checkpoint sync completes, syncing restarts from scratch. + !!! note If using [Clique](../../../private-networks/how-to/configure/consensus/clique.md) consensus, the diff --git a/docs/public-networks/get-started/connect/testnet.md b/docs/public-networks/get-started/connect/testnet.md new file mode 100644 index 00000000..b6637267 --- /dev/null +++ b/docs/public-networks/get-started/connect/testnet.md @@ -0,0 +1,151 @@ +--- +Description: How to connect to a testnet +--- + +# Connect to a testnet + +Run Besu as an [execution client](../../concepts/the-merge.md#execution-clients) with any consensus +client on the [Goerli](https://github.com/eth-clients/goerli) and +[Sepolia](https://github.com/eth-clients/sepolia) testnets. + +If you're using [Teku](https://docs.teku.consensys.net/en/latest/) as a consensus client, you can +follow the [Besu and Teku testnet tutorial](../../tutorials/besu-teku-testnet.md). + +!!! note + + Sepolia is a permissioned network and you can't run a validator client on it without + [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. + You can connect your consensus client using the beacon node only, without any validator duties. + +## Prerequisites + +- [Besu installed](../install/binary-distribution.md). +- A consensus client installed. + For example, [Teku](https://docs.teku.consensys.net/en/latest/). + +## Steps + +### 1. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and the consensus client. +This is a shared JWT secret the clients use to authenticate each other when using the +[Engine API](../../how-to/use-engine-api.md). + +### 2. Start Besu + +Run the following command or specify the options in a +[configuration file](../../how-to/configuration-file.md): + +=== "Goerli" + + ```bash + besu \ + --network=goerli \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --Xmerge-support=true \ + --engine-jwt-secret= + ``` + +=== "Sepolia" + + ```bash + besu \ + --network=sepolia \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --Xmerge-support=true \ + --engine-jwt-secret= + ``` + +Specify the path to the `jwtsecret.hex` file generated in [step 1](#1-generate-the-shared-secret) +using the [`--engine-jwt-secret`](../../reference/cli/options.md#engine-jwt-secret) option. + +You can modify the option values and add other [command line options](../../reference/cli/options.md) +as needed. + +### 3. Generate validator keys and stake ETH + +If you're running a beacon node only, skip to the next step. + +If you're running a validator client, create a test Ethereum address (you can do this in +[MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015289452-How-to-create-an-additional-account-in-your-wallet)). +Fund this address with testnet ETH (32 ETH and gas fees for each validator) using a faucet. +See the list of [Goerli faucets](https://github.com/eth-clients/goerli#meta-data-g%C3%B6rli) and +[Sepolia faucets](https://github.com/eth-clients/sepolia#meta-data-sepolia). + +!!! note + + If you're unable to get ETH using the faucet, you can ask for help on the + [EthStaker Discord](https://discord.io/ethstaker). + +Generate validator keys and stake your testnet ETH for one or more validators using the +[Goerli Staking Launchpad](https://goerli.launchpad.ethereum.org/). + +!!! important + + Save the password you use to generate each key pair in a `.txt` file. + You should also have a `.json` file for each validator key pair. + + Ensure your Besu node is fully synced before submitting your staking deposit. + This can take several days. + +### 4. Start the consensus client + +Refer to your consensus client documentation to configure and start the consensus client. + +!!! important + + If you're running a validator client, make sure you set a fee recipient address. + +If you're using Teku, follow the [Besu and Teku testnet tutorial](../../tutorials/besu-teku-testnet.md#5-start-teku). + +### 5. After starting the clients + +After starting Besu and the consensus client, your node starts syncing and connecting to peers. + +!!! example + + === "Besu logs" + + ```bash + 2022-03-21 20:42:09.295-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.298-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.848-07:00 | nioEventLoopGroup-3-8 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 4 + 2022-03-21 20:42:18.452-07:00 | nioEventLoopGroup-3-8 | INFO | SyncTargetManager | Found common ancestor with peer Peer 0xab3a286b181721c794... at block 55127 + 2022-03-21 20:42:18.454-07:00 | nioEventLoopGroup-3-8 | INFO | PipelineChainDownloader | PipelineChain download complete + ``` + + === "Teku logs" + + ```bash + 2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 + 2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 + 2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 + 2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 + 2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 + ``` + +!!! caution + + If you restart your node before snap or checkpoint sync completes, syncing restarts from scratch. + +You can check your validator status by searching your Ethereum address on the +[Goerli Beacon Chain explorer](https://goerli.beaconcha.in/). +It may take up to multiple days for your validator to be activated and start proposing blocks. diff --git a/docs/public-networks/get-started/migrate-to-besu.md b/docs/public-networks/get-started/migrate-to-besu.md index 227b7af7..13d39ccd 100644 --- a/docs/public-networks/get-started/migrate-to-besu.md +++ b/docs/public-networks/get-started/migrate-to-besu.md @@ -12,7 +12,7 @@ To migrate from a different client, and connect your [consensus client](../concepts/the-merge.md#consensus-clients) to Besu instead of your original execution client. -To minimize downtime while [Besu syncs](../how-to/connect/sync-node.md) and avoid downtime penalties, +To minimize downtime while [Besu syncs](connect/sync-node.md) and avoid downtime penalties, you can sync Besu with a new consensus layer instance. Once Besu has fully synced you can connect it to your existing consensus client. diff --git a/docs/public-networks/get-started/start-node.md b/docs/public-networks/get-started/start-node.md index fc6b71d5..1ea414a6 100644 --- a/docs/public-networks/get-started/start-node.md +++ b/docs/public-networks/get-started/start-node.md @@ -47,54 +47,19 @@ the file using the [`--genesis-file`](../reference/cli/options.md#genesis-file) ## Syncing and storage By default, Besu syncs to the current state of the blockchain using -[fast sync](../how-to/connect/sync-node.md#fast-synchronization) in: +[fast sync](connect/sync-node.md#fast-synchronization) in: - Networks specified using [`--network`](../reference/cli/options.md#network) except for the `dev` development network. - Ethereum Mainnet. -We recommend using [snap sync](../how-to/connect/sync-node.md#snap-synchronization) for a faster sync, by starting Besu +We recommend using [snap sync](connect/sync-node.md#snap-synchronization) for a faster sync, by starting Besu with [`--sync-mode=X_SNAP`](../reference/cli/options.md#sync-mode). By default, Besu stores data in the [Forest of Tries](../concepts/data-storage-formats.md#forest-of-tries) format. We recommend using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries) for lower storage requirements, by starting Besu with [`--data-storage-format=BONSAI`](../reference/cli/options.md#data-storage-format). -## Confirm node is running - -If you started Besu with the -[`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) option, use -[cURL](https://curl.haxx.se/) to call [JSON-RPC API methods](../reference/api/index.md) to -confirm the node is running. - -!!!example - - * `eth_chainId` returns the chain ID of the network. - - ```bash - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' localhost:8545 - ``` - - * `eth_syncing` returns the starting, current, and highest block. - - ```bash - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 - ``` - - For example, after connecting to Mainnet, `eth_syncing` will return something similar to: - - ```json - { - "jsonrpc" : "2.0", - "id" : 1, - "result" : { - "startingBlock" : "0x0", - "currentBlock" : "0x2d0", - "highestBlock" : "0x66c0" - } - } - ``` - ## Run a node for testing To run a node that mines blocks at a rate suitable for testing purposes: @@ -141,6 +106,8 @@ besu --network=goerli --data-path=/ Where `` and `` are the path and directory to save the Goerli chain data to. +See the [guide on connecting to a testnet](connect/testnet.md) for more information. + ## Run a node on Sepolia testnet To run a node on [Sepolia](https://github.com/goerli/sepolia) specifying a data directory: @@ -152,6 +119,8 @@ besu --network=sepolia --data-path=/ Where `` and `` are the path and directory to save the Sepolia chain data to. +See the [guide on connecting to a testnet](connect/testnet.md) for more information. + ## Run a node on Ethereum Mainnet To run a node on the Ethereum Mainnet: @@ -166,6 +135,8 @@ To run a node on Mainnet with the HTTP JSON-RPC service enabled and available fo besu --rpc-http-enabled ``` +See the [guide on connecting to Mainnet](connect/mainnet.md) for more information. + ## Besu launcher Use the Besu launcher to interactively configure and start a node with the most common options. The @@ -200,3 +171,38 @@ If a configuration file is already present in the directory where the command is Besu will start and use the values in the configuration file. To force the launcher to interact during a restart, use the `--Xlauncher-force` option, or delete the configuration file. + +## Confirm node is running + +If you started Besu with the +[`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) option, use +[cURL](https://curl.haxx.se/) to call [JSON-RPC API methods](../reference/api/index.md) to +confirm the node is running. + +!!! example + + * `eth_chainId` returns the chain ID of the network. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' localhost:8545 + ``` + + * `eth_syncing` returns the starting, current, and highest block. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 + ``` + + For example, after connecting to Mainnet, `eth_syncing` will return something similar to: + + ```json + { + "jsonrpc" : "2.0", + "id" : 1, + "result" : { + "startingBlock" : "0x0", + "currentBlock" : "0x2d0", + "highestBlock" : "0x66c0" + } + } + ``` diff --git a/docs/public-networks/how-to/monitor/understand-metrics.md b/docs/public-networks/how-to/monitor/understand-metrics.md index 888b3598..c75b16eb 100644 --- a/docs/public-networks/how-to/monitor/understand-metrics.md +++ b/docs/public-networks/how-to/monitor/understand-metrics.md @@ -6,7 +6,7 @@ tags: # Understand metrics -When running Besu on Ethereum Mainnet using [snap sync](../connect/sync-node.md#snap-synchronization), +When running Besu on Ethereum Mainnet using [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), you might notice graphical patterns that stand out in different metrics charts. These patterns are related to the [CPU usage](#cpu-usage) and [block time](#block-time) of the Besu sync process. diff --git a/docs/public-networks/how-to/prepare-for-the-merge.md b/docs/public-networks/how-to/prepare-for-the-merge.md index 01b65910..0d6f7008 100644 --- a/docs/public-networks/how-to/prepare-for-the-merge.md +++ b/docs/public-networks/how-to/prepare-for-the-merge.md @@ -4,6 +4,12 @@ description: How to prepare for The Merge # Prepare for The Merge +!!! warning "Important" + + [The Merge](../concepts/the-merge.md) was executed on **September 15, 2022**. + This page will remain up for a short period of time for your reference. + Please see the [guide on connecting Besu to Mainnet](../get-started/connect/mainnet.md). + If you're running one or more [beacon nodes](../concepts/the-merge.md#consensus-clients) with Besu on Ethereum Mainnet, prepare for [The Merge](../concepts/the-merge.md) by [configuring Besu as an execution client](#configure-besu-as-an-execution-client) and @@ -13,7 +19,7 @@ If you're using Besu with [Teku] as the consensus client, [prepare Teku for the Merge](https://docs.teku.consensys.net/en/latest/HowTo/Prepare-for-The-Merge/). You can also -[run Besu with Teku on the Merge testnet](../tutorials/merge-testnet.md). +[run Besu with Teku on the Merge testnet](../tutorials/besu-teku-testnet.md). ## Configure Besu as an execution client @@ -63,7 +69,7 @@ Engine API. Besu uses the same key to validate the token presented. ### 3. Sync Besu Validators can't produce attestations or blocks without a fully synced execution endpoint. -To expedite network participation, [sync Besu](connect/sync-node.md) on Ethereum Mainnet before the Merge +To expedite network participation, [sync Besu](../get-started/connect/sync-node.md) on Ethereum Mainnet before the Merge configuration (Bellatrix) comes online. !!! caution diff --git a/docs/public-networks/how-to/use-engine-api.md b/docs/public-networks/how-to/use-engine-api.md index 754769c5..6f81039f 100644 --- a/docs/public-networks/how-to/use-engine-api.md +++ b/docs/public-networks/how-to/use-engine-api.md @@ -4,8 +4,9 @@ description: How to enable and use the Engine API # Use the Engine API -After [The Merge](../concepts/the-merge.md), consensus and execution clients communicate with each other using the Engine API. -These [API methods](../reference/engine-api/index.md) are a separate subsection of the [JSON-RPC API](../how-to/use-besu-api/index.md). +[Consensus and execution clients](../concepts/the-merge.md#execution-and-consensus-clients) +communicate with each other using the [Engine API](../reference/engine-api/index.md). +These API methods are a separate subsection of the [JSON-RPC API](../how-to/use-besu-api/index.md). ## Configure the Engine API @@ -43,11 +44,11 @@ By default, Besu accepts requests and connections from `localhost` and `127.0.0. If your application publishes RPC ports, specify the hostnames when starting Besu. -Specify "*" for `--engine-host-allowlist` to effectively disable host protection. +Specify `*` for `--engine-host-allowlist` to effectively disable host protection. !!! caution - Specifying "*" for `--engine-host-allowlist` is not recommended for production code. + We don't recommend specifying `*` for `--engine-host-allowlist` in production. ## Authentication diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 143473ce..7f46a799 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -578,7 +578,7 @@ Shared secret used to authenticate [consensus clients](../../concepts/the-merge. HTTP and WebSocket). Contents of file must be at least 32 hex-encoded bytes and not begin with `0x`. May be a relative or absolute path. -See an [example of how to generate this](../../tutorials/merge-testnet.md#prerequisites). +See an [example of how to generate this](../../get-started/connect/mainnet.md#1-generate-the-shared-secret). ### `engine-rpc-port` @@ -695,7 +695,7 @@ Contact email address to send to the Ethstats server specified by [`--ethstats`] fast-sync-min-peers=8 ``` -The minimum number of peers required before starting [fast synchronization](../../how-to/connect/sync-node.md#run-a-full-node). +The minimum number of peers required before starting [fast synchronization](../../get-started/connect/sync-node.md#run-a-full-node). The default is 5. !!! note @@ -3181,10 +3181,10 @@ The default is `false`. ``` The synchronization mode. -Use `FAST` for [fast sync](../../how-to/connect/sync-node.md#fast-synchronization), `FULL` for -[full sync](../../how-to/connect/sync-node.md#run-an-archive-node), `X_SNAP` for -[snap sync](../../how-to/connect/sync-node.md#snap-synchronization), and `X_CHECKPOINT` for -[checkpoint sync](../../how-to/connect/sync-node.md#checkpoint-synchronization). +Use `FAST` for [fast sync](../../get-started/connect/sync-node.md#fast-synchronization), `FULL` for +[full sync](../../get-started/connect/sync-node.md#run-an-archive-node), `X_SNAP` for +[snap sync](../../get-started/connect/sync-node.md#snap-synchronization), and `X_CHECKPOINT` for +[checkpoint sync](../../get-started/connect/sync-node.md#checkpoint-synchronization). * The default is `FULL` when connecting to a private network by not using the [`--network`](#network) option and specifying the [`--genesis-file`](#genesis-file) option. diff --git a/docs/public-networks/reference/engine-api/index.md b/docs/public-networks/reference/engine-api/index.md index 2abc35f4..43c9afc1 100644 --- a/docs/public-networks/reference/engine-api/index.md +++ b/docs/public-networks/reference/engine-api/index.md @@ -4,8 +4,10 @@ description: Engine API methods reference # Engine API methods -After [The Merge](../../concepts/the-merge.md), consensus and execution clients communicate with each other using the Engine API. -When running Besu as an execution client, [use these API calls](../../how-to/use-engine-api.md) to communicate with a consensus client. +[Consensus and execution clients](../../concepts/the-merge.md#execution-and-consensus-clients) +communicate with each other using the Engine API. +When running Besu as an execution client, [use these API calls](../../how-to/use-engine-api.md) to +communicate with a consensus client. See the [Ethereum Engine API specification](https://github.com/ethereum/execution-apis/blob/0b965fb714ccd3faa3c939fdce1726e56679cdec/src/engine/specification.md) for more information. diff --git a/docs/public-networks/tutorials/besu-teku-mainnet.md b/docs/public-networks/tutorials/besu-teku-mainnet.md new file mode 100644 index 00000000..a9971a3f --- /dev/null +++ b/docs/public-networks/tutorials/besu-teku-mainnet.md @@ -0,0 +1,205 @@ +--- +Description: How to run Besu and Teku on Mainnet +--- + +# Run Besu and Teku on Mainnet + +Run Besu as an [execution client](../concepts/the-merge.md#execution-clients) and +[Teku](https://docs.teku.consensys.net/en/stable/) +as a [consensus client](../concepts/the-merge.md#consensus-clients) on Ethereum Mainnet. + +## 1. Install Besu and Teku + +Install [Besu](../get-started/install/binary-distribution.md) and +[Teku](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Installation-Options/Install-Binaries/). + +Ensure you meet the prerequisites for the installation option you use. +For example, you must have Java 11+ if using the Besu and Teku binary distributions. + +Ensure you meet the [system requirements for Besu on public networks](../get-started/system-requirements.md). + +## 2. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting both Besu and Teku. +This is a shared JWT secret the clients use to authenticate each other when using the +[Engine API](../how-to/use-engine-api.md). + +## 3. Start Besu + +Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md): + +```bash +besu \ + --sync-mode=X_SNAP \ + --data-storage-format=BONSAI \ + --rpc-http-enabled=true \ + --rpc-http-host="0.0.0.0" \ + --rpc-ws-enabled=true \ + --rpc-ws-host="0.0.0.0" \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ + --Xmerge-support=true \ + --engine-jwt-secret= +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using + the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. +- The IP address of your Besu node using the [`--host-allowlist`](../reference/cli/options.md#host-allowlist) + and [`--engine-host-allowlist`](../reference/cli/options.md#engine-host-allowlist) options. + +Also, in the command: + +- [`--sync-mode`](../reference/cli/options.md#sync-mode) specifies using [snap sync](../get-started/connect/sync-node.md#snap-synchronization). +- [`--data-storage-format`](../reference/cli/options.md#data-storage-format) specifies using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries). +- [`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC + service. +- [`--rpc-http-host`](../reference/cli/options.md#rpc-http-host) is set to `0.0.0.0` to allow remote + RPC connections. +- [`--rpc-ws-enabled`](../reference/cli/options.md#rpc-ws-enabled) enables the WebSocket JSON-RPC + service. +- [`--rpc-ws-host`](../reference/cli/options.md#rpc-ws-host) is set to `0.0.0.0` to allow remote RPC + connections. +- `--Xmerge-support` enables Merge support. + +You can modify the option values and add other [command line options](../reference/cli/options.md) +as needed. + +## 4. Generate validator keys and stake ETH + +If you're running a [beacon node only](#beacon-node-only), skip to the next step. + +If you're also running a [validator client](#beacon-node-and-validator-client), have a funded +Ethereum address ready (32 ETH and gas fees for each validator). + +Generate validator keys and stake your ETH for one or more validators using the +[Staking Launchpad](https://launchpad.ethereum.org/en/). + +!!! important + + Save the password you use to generate each key pair in a `.txt` file. + You should also have a `.json` file for each validator key pair. + + Ensure your Besu node is fully synced before submitting your staking deposit. + This can take several days. + +## 5. Start Teku + +Open a new terminal window. + +### Beacon node only + +To run Teku as a beacon node only (without validator duties), run the following command or specify the +options in the [Teku configuration file]: + +```bash +teku \ + --data-path "datadir-teku" \ + --ee-endpoint http://localhost:8551 \ + --ee-jwt-secret-file \ + --log-destination console \ + --rest-api-enabled=true \ +``` + +Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using +the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) +option. + +Also, in the command: + +- [`--data-path`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#data-base-path-data-path) + is set to the path to the Teku data directory. +- [`ee-endpoint`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#ee-endpoint) + is set to the default URL of Besu's Engine API. +- [`log-destination`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#log-destination) + specifies outputting log information to the console. +- [`rest-api-enabled`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#rest-api-enabled) + enables Teku's REST API service. + +You can modify the option values and add other [Teku command line options] as needed. + +### Beacon node and validator client + +To run Teku as a beacon node and validator in a single process, run the following command or specify +the options in the [Teku configuration file]: + +```bash +teku \ + --data-path "datadir-teku" \ + --ee-endpoint http://localhost:8551 \ + --ee-jwt-secret-file \ + --log-destination console \ + --rest-api-enabled=true \ + --validators-proposer-default-fee-recipient= \ + --validator-keys=:[,:,...] \ +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the + [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. +- An Ethereum address you own as the default fee recipient using the + [`--validators-proposer-default-fee-recipient`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient) + option. +- The paths to the keystore `.json` file and password `.txt` file created in + [step 4](#4-generate-validator-keys-and-stake-eth) for each validator using the + [`--validator-keys`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#validator-keys) option. + Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. + +Also, in the command: + +- [`--data-path`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#data-base-path-data-path) + is set to the path to the Teku data directory. +- [`ee-endpoint`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#ee-endpoint) + is set to the default URL of Besu's Engine API. +- [`log-destination`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#log-destination) + specifies outputting log information to the console. +- [`rest-api-enabled`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#rest-api-enabled) + enables Teku's REST API service. + +You can modify the option values and add other [Teku command line options] as needed. + +## After starting Besu and Teku + +After starting Besu and Teku, your node starts syncing and connecting to peers. + +!!! example + + === "Besu logs" + + ```bash + 2022-03-21 20:42:09.295-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.298-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 + 2022-03-21 20:42:14.848-07:00 | nioEventLoopGroup-3-8 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 4 + 2022-03-21 20:42:18.452-07:00 | nioEventLoopGroup-3-8 | INFO | SyncTargetManager | Found common ancestor with peer Peer 0xab3a286b181721c794... at block 55127 + 2022-03-21 20:42:18.454-07:00 | nioEventLoopGroup-3-8 | INFO | PipelineChainDownloader | PipelineChain download complete + ``` + + === "Teku logs" + + ```bash + 2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 + 2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 + 2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 + 2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 + 2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 + ``` + +You can check your validator status by searching your Ethereum address on the [Beacon Chain explorer](https://beaconcha.in/). +It may take up to multiple days for your validator to be activated and start proposing blocks. + +!!! caution + + If you restart your node before snap or checkpoint sync completes, syncing restarts from scratch. + + + +[Teku configuration file]: https://docs.teku.consensys.net/en/latest/HowTo/Configure/Use-Configuration-File/ +[Teku command line options]: https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/ diff --git a/docs/public-networks/tutorials/merge-testnet.md b/docs/public-networks/tutorials/besu-teku-testnet.md similarity index 75% rename from docs/public-networks/tutorials/merge-testnet.md rename to docs/public-networks/tutorials/besu-teku-testnet.md index 884a23fb..63ad9efe 100644 --- a/docs/public-networks/tutorials/merge-testnet.md +++ b/docs/public-networks/tutorials/besu-teku-testnet.md @@ -1,18 +1,19 @@ --- -Description: How to run Besu and Teku on the Merge testnet +Description: How to run Besu and Teku on a testnet --- -# Run Besu and Teku on a post-Merge testnet +# Run Besu and Teku on a testnet -You can test Besu as an [execution client](../concepts/the-merge.md#execution-clients) and +Run Besu as an [execution client](../concepts/the-merge.md#execution-clients) and [Teku](https://docs.teku.consensys.net/en/stable/) -as a [consensus client](../concepts/the-merge.md#consensus-clients) on a post-Merge testnet. -This tutorial uses the [Goerli testnet](https://github.com/eth-clients/goerli) and -[Sepolia testnet](https://github.com/eth-clients/sepolia) as examples. +as a [consensus client](../concepts/the-merge.md#consensus-clients) on the +[Goerli](https://github.com/eth-clients/goerli) and [Sepolia](https://github.com/eth-clients/sepolia) +Ethereum testnets. !!! note - Sepolia is a permissioned network and can't be run using a validator client without [requesting to become a validator first](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg). + Sepolia is a permissioned network and you can't run a validator client on it without + [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. You can connect your consensus client using the beacon node only, without any validator duties. ## 1. Install Besu and Teku @@ -23,7 +24,7 @@ Install [Besu](../get-started/install/binary-distribution.md) and Ensure you meet the prerequisites for the installation option you use. For example, you must have Java 11+ if using the Besu and Teku binary distributions. -Ensure you meet the [system requirements for Besu on Mainnet](../get-started/system-requirements.md). +Ensure you meet the [system requirements for Besu on public networks](../get-started/system-requirements.md). ## 2. Generate the shared secret @@ -39,7 +40,7 @@ This is a shared JWT secret the clients use to authenticate each other when usin ## 3. Start Besu -Run the following command: +Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md): === "Goerli" @@ -47,13 +48,12 @@ Run the following command: besu \ --network=goerli \ --rpc-http-enabled=true \ - --rpc-http-host="0.0.0.0" \ + --rpc-http-host=0.0.0.0 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --rpc-ws-host="0.0.0.0" \ + --rpc-ws-host=0.0.0.0 \ --host-allowlist="*" \ --engine-host-allowlist="*" \ - --engine-rpc-port=8551 \ --Xmerge-support=true \ --engine-jwt-secret= ``` @@ -64,13 +64,12 @@ Run the following command: besu \ --network=sepolia \ --rpc-http-enabled=true \ - --rpc-http-host="0.0.0.0" \ + --rpc-http-host=0.0.0.0 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --rpc-ws-host="0.0.0.0" \ + --rpc-ws-host=0.0.0.0 \ --host-allowlist="*" \ --engine-host-allowlist="*" \ - --engine-rpc-port=8551 \ --Xmerge-support=true \ --engine-jwt-secret= ``` @@ -78,15 +77,17 @@ Run the following command: Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. -See the [`--engine-*`](../reference/cli/options.md#engine-host-allowlist) options for more information on running -Besu as an execution client. +You can modify the option values and add other [command line options](../reference/cli/options.md) +as needed. ## 4. Generate validator keys and stake ETH -If you're running a [validator client](#beacon-node-and-validator-client), create a test Ethereum address (you can do -this in +If you're running a [beacon node only](#beacon-node-only), skip to the next step. + +If you're also running a [validator client](#beacon-node-and-validator-client), create a test +Ethereum address (you can do this in [MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015289452-How-to-create-an-additional-account-in-your-wallet)). -Fund this address with testnet ETH using a faucet. +Fund this address with testnet ETH (32 ETH and gas fees for each validator) using a faucet. See the list of [Goerli faucets](https://github.com/eth-clients/goerli#meta-data-g%C3%B6rli) and [Sepolia faucets](https://github.com/eth-clients/sepolia#meta-data-sepolia). !!! note @@ -110,7 +111,8 @@ Open a new terminal window. ### Beacon node only -To run Teku as a beacon node (without validator duties), run the following command: +To run Teku as a beacon node only (without validator duties), run the following command or specify the +options in the [Teku configuration file]: === "Goerli" @@ -122,7 +124,6 @@ To run Teku as a beacon node (without validator duties), run the following comma --ee-jwt-secret-file \ --log-destination console \ --rest-api-enabled=true \ - --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" ``` === "Sepolia" @@ -135,16 +136,18 @@ To run Teku as a beacon node (without validator duties), run the following comma --ee-jwt-secret-file \ --log-destination console \ --rest-api-enabled=true \ - --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" ``` Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. +You can modify the option values and add other [Teku command line options] as needed. + ### Beacon node and validator client -To run Teku as a beacon node and validator in a single process, run the following command: +To run Teku as a beacon node and validator in a single process, run the following command or specify +the options in the [Teku configuration file]: === "Goerli" @@ -158,12 +161,12 @@ To run Teku as a beacon node and validator in a single process, run the followin --rest-api-enabled=true \ --validators-proposer-default-fee-recipient= \ --validator-keys=:[,:,...] \ - --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" ``` === "Sepolia" - Sepolia is a permissioned network and can't be run using a validator client without [requesting to become a validator first](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg). + Sepolia is a permissioned network and you can't run a validator client on it without + [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. Specify: @@ -178,8 +181,7 @@ Specify: [`--validator-keys`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#validator-keys) option. Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. -See the Teku [`--validators-*`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validator-keys) -options for more information on running Teku as a validator. +You can modify the option values and add other [Teku command line options] as needed. ## After starting Besu and Teku @@ -213,3 +215,8 @@ It may take up to multiple days for your validator to be activated and start pro !!! caution If you restart your node before snap or checkpoint sync completes, syncing restarts from scratch. + + + +[Teku configuration file]: https://docs.teku.consensys.net/en/latest/HowTo/Configure/Use-Configuration-File/ +[Teku command line options]: https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/ diff --git a/mkdocs.navigation.yml b/mkdocs.navigation.yml index 1a6bcc5d..0c4cbf2a 100644 --- a/mkdocs.navigation.yml +++ b/mkdocs.navigation.yml @@ -19,6 +19,11 @@ nav: - Run Besu from Docker image: public-networks/get-started/install/run-docker-image.md - Install binary distribution: public-networks/get-started/install/binary-distribution.md - Start Besu: public-networks/get-started/start-node.md + - Connect to a network: + - public-networks/get-started/connect/index.md + - Sync Besu: public-networks/get-started/connect/sync-node.md + - Connect to Mainnet: public-networks/get-started/connect/mainnet.md + - Connect to a testnet: public-networks/get-started/connect/testnet.md - Migrate to Besu: public-networks/get-started/migrate-to-besu.md - How to: - Prepare for The Merge: public-networks/how-to/prepare-for-the-merge.md @@ -32,8 +37,7 @@ nav: - Use the Engine API: public-networks/how-to/use-engine-api.md - Use a configuration file: public-networks/how-to/configuration-file.md - Create and send transactions: public-networks/how-to/send-transactions.md - - Connect to a network: - - Sync Besu: public-networks/how-to/connect/sync-node.md + - Find and connect to peers: - Configure static nodes: public-networks/how-to/connect/static-nodes.md - Configure ports: public-networks/how-to/connect/configure-ports.md - Manage peers: public-networks/how-to/connect/manage-peers.md @@ -73,7 +77,8 @@ nav: - Genesis file: public-networks/concepts/genesis-file.md - Node keys: public-networks/concepts/node-keys.md - Tutorials: - - Run Besu and Teku on the Merge testnet: public-networks/tutorials/merge-testnet.md + - Run Besu and Teku on Mainnet: public-networks/tutorials/besu-teku-mainnet.md + - Run Besu and Teku on a testnet: public-networks/tutorials/besu-teku-testnet.md - Reference: - Besu command line: - Options: public-networks/reference/cli/options.md diff --git a/mkdocs.redirects.yml b/mkdocs.redirects.yml index 76b69528..2af20e9a 100644 --- a/mkdocs.redirects.yml +++ b/mkdocs.redirects.yml @@ -76,7 +76,7 @@ plugins: HowTo/Find-and-Connect/Configuring-Ports.md: public-networks/how-to/connect/configure-ports.md HowTo/Find-and-Connect/Managing-Peers.md: public-networks/how-to/connect/manage-peers.md HowTo/Find-and-Connect/Specifying-NAT.md: public-networks/how-to/connect/specify-nat.md - Concepts/Node-Types.md: public-networks/how-to/connect/sync-node.md + Concepts/Node-Types.md: public-networks/get-started/connect/sync-node.md HowTo/Monitor/Metrics.md: public-networks/how-to/monitor/metrics.md HowTo/Monitor/Logging.md: public-networks/how-to/monitor/logging.md HowTo/Monitor/Elastic-Stack.md: private-networks/how-to/monitor/elastic-stack.md @@ -97,7 +97,7 @@ plugins: HowTo/Troubleshoot/Trace-Transactions.md: public-networks/how-to/troubleshoot/trace-transactions.md Concepts/Node-Keys.md: public-networks/concepts/node-keys.md Concepts/Data-Storage-Formats.md: public-networks/concepts/data-storage-formats.md - Tutorials/Merge-Testnet.md: public-networks/tutorials/merge-testnet.md + Tutorials/Merge-Testnet.md: public-networks/tutorials/besu-teku-testnet.md Reference/CLI/CLI-Syntax.md: public-networks/reference/cli/options.md Reference/CLI/CLI-Subcommands.md: public-networks/reference/cli/subcommands.md Reference/API-Methods.md: public-networks/reference/api/index.md @@ -200,3 +200,5 @@ plugins: Concepts/Pruning.md: public-networks/concepts/data-storage-formats.md Concepts/TLS.md: private-networks/how-to/configure/tls/client-and-server.md public-networks/how-to/troubleshoot/java-flight-recorder.md: public-networks/how-to/configure-jvm/java-flight-recorder.md + public-networks/how-to/connect/sync-node.md: public-networks/get-started/connect/sync-node.md + public-networks/tutorials/merge-testnet.md: public-networks/tutorials/besu-teku-testnet.md