diff --git a/docs/img/solo-staking/advisories.png b/docs/img/solo-staking/advisories.png new file mode 100644 index 0000000..8458b97 Binary files /dev/null and b/docs/img/solo-staking/advisories.png differ diff --git a/docs/img/solo-staking/confirm_deposit.png b/docs/img/solo-staking/confirm_deposit.png new file mode 100644 index 0000000..8103e8e Binary files /dev/null and b/docs/img/solo-staking/confirm_deposit.png differ diff --git a/docs/img/solo-staking/confirm_deposit_success.png b/docs/img/solo-staking/confirm_deposit_success.png new file mode 100644 index 0000000..272635c Binary files /dev/null and b/docs/img/solo-staking/confirm_deposit_success.png differ diff --git a/docs/img/solo-staking/connect_wallet.png b/docs/img/solo-staking/connect_wallet.png new file mode 100644 index 0000000..ebc222f Binary files /dev/null and b/docs/img/solo-staking/connect_wallet.png differ diff --git a/docs/img/solo-staking/consensus_choice_holesky.png b/docs/img/solo-staking/consensus_choice_holesky.png new file mode 100644 index 0000000..e28a816 Binary files /dev/null and b/docs/img/solo-staking/consensus_choice_holesky.png differ diff --git a/docs/img/solo-staking/consensus_choice_mainnet.png b/docs/img/solo-staking/consensus_choice_mainnet.png new file mode 100644 index 0000000..39d27ad Binary files /dev/null and b/docs/img/solo-staking/consensus_choice_mainnet.png differ diff --git a/docs/img/solo-staking/execution_choice_holesky.png b/docs/img/solo-staking/execution_choice_holesky.png new file mode 100644 index 0000000..91e7aa5 Binary files /dev/null and b/docs/img/solo-staking/execution_choice_holesky.png differ diff --git a/docs/img/solo-staking/execution_choice_mainnet.png b/docs/img/solo-staking/execution_choice_mainnet.png new file mode 100644 index 0000000..c3b3599 Binary files /dev/null and b/docs/img/solo-staking/execution_choice_mainnet.png differ diff --git a/docs/img/solo-staking/generate_deposit_keys_cli_success.png b/docs/img/solo-staking/generate_deposit_keys_cli_success.png new file mode 100644 index 0000000..dccbce7 Binary files /dev/null and b/docs/img/solo-staking/generate_deposit_keys_cli_success.png differ diff --git a/docs/img/solo-staking/generate_key_pairs_address_holesky.png b/docs/img/solo-staking/generate_key_pairs_address_holesky.png new file mode 100644 index 0000000..adfb1eb Binary files /dev/null and b/docs/img/solo-staking/generate_key_pairs_address_holesky.png differ diff --git a/docs/img/solo-staking/generate_key_pairs_address_mainnet.png b/docs/img/solo-staking/generate_key_pairs_address_mainnet.png new file mode 100644 index 0000000..5e1560d Binary files /dev/null and b/docs/img/solo-staking/generate_key_pairs_address_mainnet.png differ diff --git a/docs/img/solo-staking/generate_key_pairs_cli_mainnet.png b/docs/img/solo-staking/generate_key_pairs_cli_mainnet.png new file mode 100644 index 0000000..63c7beb Binary files /dev/null and b/docs/img/solo-staking/generate_key_pairs_cli_mainnet.png differ diff --git a/docs/img/solo-staking/launchpad_holesky.png b/docs/img/solo-staking/launchpad_holesky.png new file mode 100644 index 0000000..e7b8407 Binary files /dev/null and b/docs/img/solo-staking/launchpad_holesky.png differ diff --git a/docs/img/solo-staking/launchpad_hoodi.png b/docs/img/solo-staking/launchpad_hoodi.png new file mode 100644 index 0000000..88aacfa Binary files /dev/null and b/docs/img/solo-staking/launchpad_hoodi.png differ diff --git a/docs/img/solo-staking/launchpad_mainnet.png b/docs/img/solo-staking/launchpad_mainnet.png new file mode 100644 index 0000000..5efc448 Binary files /dev/null and b/docs/img/solo-staking/launchpad_mainnet.png differ diff --git a/docs/img/solo-staking/typeOfStakingAccount.png b/docs/img/solo-staking/typeOfStakingAccount.png new file mode 100644 index 0000000..22e8d13 Binary files /dev/null and b/docs/img/solo-staking/typeOfStakingAccount.png differ diff --git a/docs/img/solo-staking/typeOfStakingAccount2.png b/docs/img/solo-staking/typeOfStakingAccount2.png new file mode 100644 index 0000000..fa57f42 Binary files /dev/null and b/docs/img/solo-staking/typeOfStakingAccount2.png differ diff --git a/docs/img/solo-staking/upload_deposit_data.png b/docs/img/solo-staking/upload_deposit_data.png new file mode 100644 index 0000000..a69d341 Binary files /dev/null and b/docs/img/solo-staking/upload_deposit_data.png differ diff --git a/docs/img/solo-staking/validator-exit.png b/docs/img/solo-staking/validator-exit.png new file mode 100644 index 0000000..beca30e Binary files /dev/null and b/docs/img/solo-staking/validator-exit.png differ diff --git a/docs/img/solo-staking/validator_status.png b/docs/img/solo-staking/validator_status.png new file mode 100644 index 0000000..5cad636 Binary files /dev/null and b/docs/img/solo-staking/validator_status.png differ diff --git a/docs/use-cases/solo-staking.md b/docs/use-cases/solo-staking.md deleted file mode 100644 index 0bd7b8c..0000000 --- a/docs/use-cases/solo-staking.md +++ /dev/null @@ -1,17 +0,0 @@ -# Solo Staking with Web3 Pi - -!!! warning "Under Development & High Risk" - - Web3 Pi does not currently offer official support for staking configurations. Proceed at your own risk. - -While Web3 Pi provides the necessary Execution and Consensus client foundation, configuring it securely and reliably for staking requires significant technical expertise beyond the standard setup. - -You are welcome to explore configuring your node for staking independently, but please be aware: - -- **This is an advanced procedure.** -- Web3 Pi **does not currently offer official support** for staking configurations. -- You proceed **entirely at your own risk.** Mistakes can lead to financial penalties (slashing). - -We strongly recommend thoroughly understanding the responsibilities and substantial risks involved before attempting solo staking. - -➡️ **[Review Staking Risks and Considerations](../introduction/staking.md)** diff --git a/docs/use-cases/solo-staking/index.md b/docs/use-cases/solo-staking/index.md new file mode 100644 index 0000000..ce95974 --- /dev/null +++ b/docs/use-cases/solo-staking/index.md @@ -0,0 +1,474 @@ +# Solo Staking on Web3 Pi + +## 1. Introduction + +### Overview + +Solo staking on the Ethereum network involves active participation in the Proof-of-Stake consensus mechanism. By running your own validator node, you help secure the network by proposing and attesting to new blocks. In return for this service, you receive rewards in ETH. Choosing a dedicated, energy-efficient device like the Web3 Pi for solo staking supports network decentralization, provides full control over your keys and operations, and minimizes energy consumption compared to traditional computers. + +### Purpose of this Guide + +This guide provides detailed, manual, step-by-step instructions on how to configure solo staking on the Web3 Pi device. It assumes that the basic setup of the Web3 Pi has already been completed and the device is accessible on your local network. We will focus on configuration via an SSH connection, using the pre-installed clients: Geth as the Execution Layer (EL) client and Nimbus as the Consensus Layer (CL) client. + +### Client Selection + +The Web3 Pi comes with pre-installed Ethereum clients: Geth, Nimbus, and Lighthouse. This guide focuses on the preferred combination of Geth + Nimbus. + +## 2. Important: Warnings, Recommendations, and Prerequisites + +### Warning (Disclaimer) + +**Running an Ethereum validator involves significant financial risk and technical responsibility. By following this guide, you acknowledge that you are doing so entirely at your own risk.** + +Potential risks include, but are not limited to: + +- **Slashing:** Loss of part or all of your deposited ETH due to incorrect validator configuration or actions contrary to the network protocol (e.g., double signing blocks/attestations). +- **Inactivity Penalties:** Gradual loss of deposited ETH if your validator is offline or fails to perform its duties (e.g., attestations) on time. +- **Hardware Failure:** Potential downtime or data loss in case of Raspberry Pi, hard drive/SSD, or SD card failure. +- **Connectivity Issues:** Interruptions in Internet access can lead to inactivity penalties. +- **Software Bugs:** Issues in EL or CL clients can cause unexpected behavior, downtime, or penalties. +- **Security Breaches:** Compromise of the validator machine could lead to loss of funds (if withdrawal keys are compromised in the future) or slashing (if an attacker gains control of the validation process). + +The Web3 Pi project nor the authors of this guide bear any responsibility for any losses incurred as a result of using these instructions or running a validator. + +### Recommendation: Uninterruptible Power Supply (UPS) + +**We strongly recommend connecting your Web3 Pi device and essential network equipment (such as your router/modem) to an uninterruptible power supply (UPS).** + +A UPS protects against voltage fluctuations and short power outages, which are common causes of node downtime, potential data corruption on the disk, and can lead to inactivity penalties for your validator (in Solo Staking). + +### Prerequisites + +Before starting the configuration, ensure you meet the following requirements: + +- **32 ETH:** You must have access to exactly 32 ETH for each validator you intend to run. These funds will be locked as your deposit (stake). This is a requirement of the Ethereum protocol. +- **Configured Web3 Pi:** A fully assembled and operational Web3 Pi device, connected to your local network, with the Web3 Pi operating system and Ethereum clients installed. We assume the basic device configuration has already been completed according to the main Web3 Pi documentation. +- **SSH Access:** You need an SSH client installed on your computer (e.g., Terminal on macOS/Linux, PuTTY or Windows Terminal on Windows) and the ability to connect to your Web3 Pi via SSH using its IP address and the `ethereum` user credentials. + +## 3. Network Selection + +Before you begin synchronization, choose which network you want to sync with (`mainnet` for real staking, `holesky` or `hoodi` for testnets). Edit the `config.txt` file: + +```bash +sudo nano /boot/firmware/config.txt +``` + +Find the `eth_network` key and set it to your preferred network (`mainnet`, `holesky`, or `hoodi`). Save the changes (Ctrl+X, then Y, then Enter). Restart the Pi to load the new configuration: + +```bash +sudo reboot +``` + +!!! warning + + If you previously started synchronization with a different network, remove the old downloaded data with the command: `sudo rm -r /mnt/storage/.ethereum` + +## 4. Configure the Execution Layer Client (Geth) + +The script to run the Geth client is located in the directory: +`/home/ethereum/clients/geth/geth.sh`. Staking does not require any changes to the Geth configuration. + +A full list and description of all available Geth command-line options can be found in the official Geth documentation: + +## 5. Configure the Consensus Layer Client (Nimbus) + +The script to run the Nimbus client is located in the directory: +`/home/ethereum/clients/nimbus/nimbus.sh`. Properly configured staking requires setting the address where rewards for newly proposed blocks will be sent. + +Open the script in a text editor: + +```bash +nano /home/ethereum/clients/nimbus/nimbus.sh +``` + +Find the place where the `nimbus_beacon_node` command is executed (towards the end of the file). Look for the line that starts with `nimbus_beacon_node --non-interactive --tcp-port...` + +Add your fee recipient address as a new argument at the end of that line: +` --suggested-fee-recipient='0xYOUR_ETHEREUM_ADDRESS'` + +Replace `0xYOUR_ETHEREUM_ADDRESS` with your actual Ethereum address. + +### Saving and Closing the Editor + +Save the changes and close the editor (Ctrl+X, then Y, then Enter). + +### Fee Recipient Address + +Ensure the address provided in `--suggested-fee-recipient` is secure and you have access to it. + +More details about Nimbus configuration options can be found in the official Nimbus documentation (Nimbus Book): + +## 6. Generate Validator Keys using Ethereum Launchpad + +### Official Tool + +Validator keys **must** be generated using the official Staking Launchpad website. + +=== "Mainnet" + + Go to the official Staking Launchpad site for Mainnet:
+ + + ![](../../img/solo-staking/launchpad_mainnet.png "The Ethereum Staking Launchpad website") + +=== "Holesky" + + Go to the official Staking Launchpad site for the Holesky testnet: + + + ![](../../img/solo-staking/launchpad_holesky.png "The Ethereum Staking Launchpad website") + +=== "Hoodi" + + Go to the official Staking Launchpad site for the Hoodi testnet: + + + ![](../../img/solo-staking/launchpad_hoodi.png "The Ethereum Staking Launchpad website") + +### Proceed through the advisories checklist + +Make sure to read all the contents carefully before proceeding through each step. +Don't skip anything unless you're absolutely sure what each step entails. + +![](../../img/solo-staking/advisories.png "Checklist of advisories screen") + +### Choose your clients + +The launchpad is aimed at a general user and there are various considerations for choosing +specific execution and consensus layer clients. Due to mechanics of the global staking ecosystem, +to strengthen the network and limit the impact of potential attacks, it's generally recommended +to choose a minority client. + +However, while the above is true, and while the launchpad enables you to choose any +of the available clients, the default, battle-tested configuration for the Web3 Pi +includes `geth` and `nimbus` specifically. + +We have devoted a considerable effort to finding the setup that's optimally suited to +the characteristics of a such a small-footprint device as Raspberry Pi 5 and +this is the pair of clients which we both recommend and, by extension, include +in our default Web3 Pi image. + +So, unless you're sure you wish to choose differently, and are willing to reconfigure +the device, this is the pair that you should also choose. + +![](../../img/solo-staking/execution_choice_mainnet.png "Choice of the execution client screen") + +![](../../img/solo-staking/consensus_choice_mainnet.png "Choice of the consensus client screen") + +### Generate key pairs + +Now you're ready to generate the key pairs, which control your Ether stake and which +bind the stake to a given validator. + +#### Security considerations + +We cannot stress enough how important it is to execute this step in a secure manner. +Given that once you submit your deposit, your validator keys are directly bound to +your stake, an attacker with malicious intent and in possession of these keys, can, +in the least cause you to lose your staking rewards, and at most, even trigger +a complete loss of your stake through slashing. + +That's why, once you download and install the chosen key generator tool, +it is recommended to run it on a machine that's disconnected from the network. + +Please also ensure you keep your mnemonic phrase safe and out of reach of anybody but you. +This is the only way to regenerate your validator key if it gets lost. + +#### Provide the withdrawal address + +We strongly recommend setting the withdrawal key right away when generating the validator keys. +Although it is optional and can be performed later on, it can also be performed only once. +Setting it at this stage ensures that even if an attacker were to take control of your validator +keys, they will never be able to override the address to which your stake and the rewards are withdrawn. + +![](../../img/solo-staking/generate_key_pairs_address_mainnet.png "Provide your withdrawal address") + +#### Type of staking account + +You need to choose between two account types: *Compounding* or *Regular withdrawals*. + +* A *Compounding* account (recommended for most users) allows your rewards to automatically compound, supports balances up to 2048 ETH, and offers partial withdrawals through a smart contract request. +* A *Regular withdrawals* account has a maximum effective balance of 32 ETH, allows regular gasless withdrawals of any balance above 32 ETH, and can later be migrated to a compounding account." + +![](../../img/solo-staking/typeOfStakingAccount2.png "What type of staking account?") + + +#### Generate the keys + +Once you fill in the number of validators and the withdrawal address, you proceed with the key +generation itself. You're free to choose whichever tool suits you best, +depending on your platform and preferences. +For the sake of this guide, we'll use the CLI app as the example. + +![](../../img/solo-staking/generate_key_pairs_cli_mainnet.png "Run the key generator") + +=== "Mainnet" + ```bash + ./deposit new-mnemonic --chain mainnet + ``` + +=== "Holesky" + ```bash + ./deposit new-mnemonic --chain holesky + ``` +=== "Hoodi" + ```bash + ./deposit new-mnemonic --chain hoodi + ``` + + +In case of the CLI app, the Launchpad gives you the exact command that you should run in your +terminal. While you proceed, you'll be asked to provide the password to encrypt the keystore file +and will receive the mnemonic phrase which can be used to recover the key. + +As mentioned previously, it is critical that you keep these mnemonics safe and private. + +!!! danger "Critical Security Steps" + + During key generation, the following will be created: + + - **Mnemonic Phrase (Seed Phrase):** This is the master key to your ETH. + - Write it down VERY carefully on paper or metal. + - Verify the backup. + - Store it in multiple, extremely secure, offline locations. + - **Never store it digitally or on an online device.** + - **Losing the phrase = permanent loss of funds.** + + - **Keystore Password:** Set a very strong, unique password to encrypt the `keystore-*.json` file(s). Store this password securely (e.g., in a password manager). + +![](../../img/solo-staking/generate_deposit_keys_cli_success.png "CLI key generator success.") + +### Upload your deposit data + +After the key generator succeeds, you need to upload the just-generated `deposit_data-xxxxxx.json` +file to the Launchpad, so that it can prepare the deposit transaction for you. + +![](../../img/solo-staking/upload_deposit_data.png "CLI key generator success.") + +Once you upload that file and click continue, the last remaining step is to submit your ETH stake to +the deposit contract. + +### Confirm the deposit + +In order to do that, the Launchpad will use your MetaMask wallet to generate and send the +deposit transaction. + +![](../../img/solo-staking/connect_wallet.png "Connect your MetaMask wallet.") + +Please double-check the withdrawal address and then proceed with the checklist and afterwards, with the +confirmation of the deposit transaction. + +!!! warning + + Please ensure that the address is correct, you have proper access rights to it, and that you are connected to the correct network (mainnet/holesky/hoodi). + +!!! danger "CRITICAL DEPOSIT TIMING" + + **DO NOT MAKE THE 32 ETH DEPOSIT UNTIL ALL OF THE FOLLOWING CONDITIONS ARE MET:** + + 1. Geth is fully synchronized. + 2. Nimbus is fully synchronized. + 3. Both services (`w3p_geth`, `w3p_nimbus-beacon`) have been running stably for several hours. + 4. Nimbus logs show that your validator keys are recognized (e.g., `Local validator attached`). + + **Making the deposit before the node is fully synced and ready will result in inactivity penalties.** + + However, you will still need to wait in the activation queue after making the deposit. The length of this queue depends on the number of new validators joining - sometimes it takes days, giving enough time to finish syncing the node, but other times it may be only hours, leaving little room for synchronization. + +![](../../img/solo-staking/confirm_deposit.png "Confirm the deposit transaction.") + +After the transaction is sent and processed by the blockchain, you'll get the final confirmation +that the deposit has been made. + +![](../../img/solo-staking/confirm_deposit_success.png "Deposit success.") + +You also get the link to the status website which lists all the active validators, and which +allows you to get the status of your validator. Please note though, that the status for your validator +may not be immediately visible, and you may need to wait a few minutes until your stake is detected +by the website. + +On successful submission and detection of the deposit, your validator status will appear as "Deposited". + +![](../../img/solo-staking/validator_status.png "Deposit success.") + +You can find your validator public key in the file `~/validator_keys/deposit_data...`. Inside, locate the `pubkey` field, copy its value, and paste it into the search field on the page below: + +=== "Mainnet" + + + +=== "Holesky" + + + +=== "Hoodi" + + + +## 7. Import Validator Keys into Nimbus + +### Secure Transfer of Keystore Files + +Create a new directory `validator_keys` on your Pi and transfer the keystore files from the machine where they were generated to your Pi: + +```bash +# On your local machine (where keys were generated): +# Create the directory on the Pi via SSH +ssh ethereum@ mkdir -p ~/validator_keys + +# Securely copy the keystore files to the Pi +scp path/to/keystore*.json ethereum@:~/validator_keys/ +``` + +Replace `` with your Web3 Pi's IP address and `path/to/keystore*.json` with the actual path to your generated keystore file(s). You will be prompted for the `ethereum` user's password. + +### Key Import Command + +Connect to your Web3 Pi via SSH again. + +Import the uploaded keys using the `nimbus_beacon_node deposits import` command. The `--data-dir` path depends on your chosen network: + +=== "Mainnet" + + ```bash + sudo nimbus_beacon_node deposits import \ + --data-dir=/mnt/storage/.nimbus/data/shared_mainnet_0/ \ + ~/validator_keys + ``` + +=== "Holesky" + + ```bash + sudo nimbus_beacon_node deposits import \ + --data-dir=/mnt/storage/.nimbus/data/shared_holesky_0/ \ + ~/validator_keys + ``` + +=== "Hoodi" + + ```bash + sudo nimbus_beacon_node deposits import \ + --data-dir=/mnt/storage/.nimbus/data/shared_hoodi_0/ \ + ~/validator_keys + ``` + +You will be prompted to enter the **keystore password** you created during key generation for each key being imported. + +### Verification + +After a successful import, the encrypted keys will be stored within the Nimbus data directory. You can verify that the validator directories were created: + +=== "Mainnet" + + ```bash + sudo ls /mnt/storage/.nimbus/data/shared_mainnet_0/validators + ``` + +=== "Holesky" + + ```bash + sudo ls /mnt/storage/.nimbus/data/shared_holesky_0/validators + ``` + +=== "Hoodi" + + ```bash + sudo ls /mnt/storage/.nimbus/data/shared_hoodi_0/validators + ``` + +You should see a new directory (or directories) within the `validators` folder named after the public key(s) of your validator(s). + +### Remove Keystore Files from Home Directory + +After confirming a successful import and ensuring you have secure **offline** backups, remove the keystore files from the `ethereum` user's home directory on the Pi: + +```bash +rm -rf ~/validator_keys +``` + +!!! warning + + This step permanently deletes the copied keystore files from the Pi's home directory. **Only do this after confirming successful import AND verifying your offline backups.** Your offline backup is crucial for recovery. + +## 8. Start Services and Verify Operation + +### Restart Services + +Restart Nimbus to load the new configuration and recognize the imported keys: + +```bash +sudo systemctl restart w3p_nimbus-beacon +``` + +### Check Service Status + +Check the status of the Nimbus service: + +```bash +sudo systemctl status w3p_nimbus-beacon +``` + +Look for `Active: active (running)` and check the latest log entries for any errors. Press `q` to exit the status view. + +### Monitor Logs + +Tail the logs live using `journalctl`: + +```bash +sudo journalctl -fu w3p_nimbus-beacon +``` + +Press `Ctrl+C` to stop monitoring. + +### What to Look For: + +Look for log lines containing `Loading validators` and `Local validator attached`. This indicates that the validator key(s) have been loaded correctly and Nimbus is ready to perform validation duties once synced and activated. + +## 9. Monitor Synchronization + +### Client Synchronization + +Geth and Nimbus must be fully synchronized with the network. This process usually takes less than **24 hours on Ethereum Mainnet**, though in some cases it may take longer." + +Use the Grafana dashboard available at `http://:3000` to monitor the synchronization progress. + +### Validator Activation + +After your deposit transaction is confirmed on the Ethereum network, your validator enters an activation queue. The waiting time varies depending on network congestion and the number of validators waiting. Monitor your validator's status on a Beacon Chain explorer for your network: + +=== "Mainnet" + + + +=== "Holesky" + + + +=== "Hoodi" + + + +Once activated, your validator will begin performing duties (attesting, proposing blocks) and earning rewards. + +## 10. Ongoing Operational Best Practices + +Maintaining a validator requires ongoing attention. + +### Monitoring + +- **Validator Status:** Regularly check your validator's performance (effectiveness score, attestations, block proposals) on the appropriate Beacon Chain explorer. Consider setting up monitoring alerts. +- **Node Status:** Periodically check the status of the services (`sudo systemctl status w3p_geth w3p_nimbus-beacon`) and monitor logs (`sudo journalctl -fu w3p_geth`, `sudo journalctl -fu w3p_nimbus-beacon`) on the Web3 Pi for errors or warnings. +- **System Resources:** Monitor CPU usage, RAM usage, disk space (`df -h /mnt/storage`), disk I/O, and network traffic. Tools like `htop`, `df`, `iostat`, and the built-in `armbianmonitor -m` or Grafana dashboards are useful. Ensure the SSD has sufficient free space as the blockchain data grows. + +### Updates + +- **Client Software (Geth/Nimbus):** Keep your clients up to date. Follow official announcements for new releases. Update using standard system commands: `sudo apt update && sudo apt upgrade`. +- **Operating System:** Regularly update the underlying system: `sudo apt update && sudo apt upgrade`. + +### Backups + +- **Mnemonic Phrase:** **MOST IMPORTANT.** Keep it securely stored offline. +- **Keystore Files and Password:** A secure offline backup will speed up recovery if needed. +- **(Optional):** Backup configuration files (e.g., `/etc/systemd/system/w3p_*.service.d/override.conf`, UFW firewall configuration if customized). + +Adhering to these practices will help ensure the stable and secure operation of your validator. diff --git a/docs/use-cases/solo-staking/mev-boost.md b/docs/use-cases/solo-staking/mev-boost.md new file mode 100644 index 0000000..888436e --- /dev/null +++ b/docs/use-cases/solo-staking/mev-boost.md @@ -0,0 +1,149 @@ +# MEV-Boost on Web3 Pi + +## What is MEV-Boost? + +**MEV-Boost** is an open-source middleware that allows Ethereum validators to receive blocks from a network of third-party block builders, rather than building blocks themselves. This enables validators to participate in **Proposer-Builder Separation (PBS)**, maximizing potential rewards by capturing **Maximal Extractable Value (MEV)** from block builders in a decentralized and permissionless way. + +MEV-Boost is optional, but using it can increase your validator rewards by allowing you to select blocks that contain the most profitable transactions. Read more about the benefits of using MEV-Boost in the article [Why Run MEV-Boost?](https://writings.flashbots.net/why-run-mevboost). + +## How MEV-Boost Works + +- **Block builders** construct blocks containing transactions and MEV opportunities. +- **Relays** act as trusted intermediaries, forwarding blocks from builders to validators. +- **MEV-Boost** runs alongside your consensus client (Nimbus) and requests blocks from relays. +- Your validator proposes the most profitable block received via MEV-Boost. + +## Prerequisites + +- A fully synchronized Web3 Pi running **Geth** (Execution Layer) and **Nimbus** (Consensus Layer). +- Your validator is already set up and operational. + +## Installing and Configuring MEV-Boost + +This guide will walk you through the steps to install and configure MEV-Boost on your Web3 Pi device, allowing your Nimbus validator to utilize MEV-Boost for enhanced block rewards. Make sure to familiarize yourself with the [official MEV-Boost documentation](https://github.com/flashbots/mev-boost). It is also highly recommended to read the [official MEV-Boost installation guide](https://github.com/eth-educators/ethstaker-guides/blob/main/docs/prepare-for-the-merge.md#installing-mev-boost) before proceeding, as it provides additional context and troubleshooting tips. + +### 1. Setup permissions + +It is recommended to run MEV-Boost with a dedicated user for security reasons. Create a user named `mevboost`: + +```bash +sudo useradd --no-create-home --shell /bin/false mevboost +``` + +### 2. Install MEV-Boost + +MEV-Boost can be downloaded from the [official GitHub repository](https://github.com/flashbots/mev-boost/releases). As of May 2025, the latest version is `1.9`. Adjust the command below if a newer version is available. Remember to pick the `arm64` architecture. + +```bash +cd ~ +wget https://github.com/flashbots/mev-boost/releases/download/v1.9/mev-boost_1.9_linux_arm64.tar.gz +tar -xvf mev-boost_1.9_linux_arm64.tar.gz +sudo cp mev-boost /usr/local/bin/ +rm mev-boost LICENSE README.md mev-boost_1.9_linux_arm64.tar.gz +sudo chown mevboost:mevboost /usr/local/bin/mev-boost +``` + +### 3. Choose Relays + +MEV-Boost relies on trusted relays that act as intermediaries between block builders and validators. You can connect to multiple relays to ensure redundancy and maximize your chances of receiving profitable blocks. You should do your own research to choose the relays that you trust. As a starting point, you can use the [list of public relays provided by EthStaker](https://ethstaker.org/mev-relay-list). + +### 4. Create a Systemd Service + +Create a systemd service file to launch MEV-Boost automatically on boot: + +```bash +sudo nano /etc/systemd/system/mev-boost.service +``` + +Add the following content to the file: + +```ini +[Unit] +Description=mev-boost +Wants=network-online.target +After=network-online.target + +[Service] +Type=simple +User=mevboost +Group=mevboost +Restart=always +RestartSec=5 +ExecStart=mev-boost \ + -mainnet \ + -min-bid 0.05 \ + -relay-check \ + -relays https://relay1,https://relay2 + +[Install] +WantedBy=multi-user.target +``` + +Replace `https://relay1,https://relay2` with the actual relay URLs you want to connect to. You can specify multiple relays separated by commas. + +Replace the `-mainnet` flag with `-holesky` or `-hoodi` if you are using a testnet. + +The `-min-bid` option sets the minimum reward amount that your validator will accept from the relays. Outsourcing **all** block building to MEV-Boost provides very little benefit, but it can lead to decreased censorship resilience of the Ethereum network. It is recommended to build low-MEV blocks locally and use MEV-Boost for high-MEV blocks. You can read more about the tradeoff between opportunity-cost and network resilience in the article [The Cost of Resilience](https://writings.flashbots.net/the-cost-of-resilience). `0.05` ETH is a reasonable default value, but you can adjust it based on your preferences. + +### 5. Run the MEV-Boost Service + +Reload the systemd configuration and start the MEV-Boost service: + +```bash +sudo systemctl daemon-reload +sudo systemctl start mev-boost +``` + +Check the status of the service to ensure it is running correctly: + +```bash +sudo systemctl status mev-boost +``` + +If everything is set up correctly, you should see the service running without errors. Enable the service to start on boot: + +```bash +sudo systemctl enable mev-boost +``` + +### 6. Configure Nimbus to Use MEV-Boost + +Edit your Nimbus service configuration to add the MEV-Boost endpoint: + +1. Open your Nimbus launch script (e.g., `/home/ethereum/clients/nimbus/nimbus.sh`). +2. Add the following argument to the `nimbus_beacon_node` command: + ``` + --payload-builder=true --payload-builder-url=http://127.0.0.1:18550 + ``` + Example: + ```bash + nimbus_beacon_node ...existing options... --payload-builder=true --payload-builder-url=http://127.0.0.1:18550 + ``` +3. Save and exit the editor. +4. Restart the Nimbus service: + ```bash + sudo systemctl restart w3p_nimbus-beacon + ``` + +You can learn more about configuring Nimbus to use MEV-Boost in the [official Nimbus documentation](https://nimbus.guide/external-block-builder.html). + +### 7. Verify Nimbus is Using MEV-Boost + +To verify that Nimbus is successfully using MEV-Boost, check the logs for messages indicating that it is receiving blocks from MEV-Boost: + +```bash +sudo journalctl -u w3p_nimbus-beacon -f +``` + +You should see log entries indicating that Nimbus is using an external payload builder: + +``` +Using external payload builder payloadBuilderUrl=http://127.0.0.1:18550 +``` + +## Security and Privacy Considerations + +- Only use reputable relays to avoid censorship or malicious blocks. +- MEV-Boost does not require your validator keys; it only facilitates block selection. +- Keep MEV-Boost and your clients updated for security and compatibility. +- Keep in mind that MEV-Boost requires you to trust the relays and their participants. If your validator signs a faulty block, it may be penalized by the network. This could result in slashing, where a portion of your staked ETH is forfeited. diff --git a/docs/use-cases/solo-staking/voluntary-exit.md b/docs/use-cases/solo-staking/voluntary-exit.md new file mode 100644 index 0000000..0c6c62d --- /dev/null +++ b/docs/use-cases/solo-staking/voluntary-exit.md @@ -0,0 +1,29 @@ +# Exiting the Validator (Voluntary Exit) + +If you decide to stop validating, you can initiate a voluntary exit. This process will remove your validator from the active set and stop it from earning rewards. +You can read more about the process in the official nimbus documentation: + +## Initiate Voluntary Exit + +To initiate a voluntary exit, use the following command: + +```bash +nimbus_beacon_node deposits exit --validator=/path/to/keystore.json +``` + +Replace `/path/to/keystore.json` with the path to your validator keystore file. +You will be asked to enter the password for the keystore file. + +## Confirm Exit + +Nimbus will ask you to confirm the exit. Make sure you understand the implications of what you're doing before proceeding. + +![confirmation screen](../../img/solo-staking/validator-exit.png) + +## Monitor Exit Status + +After initiating the exit, you can monitor the status of your validator using a Beacon Chain explorer. The exit process may take some time, depending on network conditions and the number of validators exiting. + +## Withdrawal of Funds + +Once your validator has exited, you will be able to withdraw your staked ETH and any earned rewards. The withdrawal process is not instantaneous and may take a few days to complete, depending on network conditions and the number of validators exiting. You can monitor the status of your withdrawal using a Beacon Chain explorer. diff --git a/mkdocs.yml b/mkdocs.yml index debf13a..649c2fb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,7 +126,10 @@ nav: - Use Cases: - Install in your wallet: 'use-cases/wallet.md' - Transaction Firewall: 'use-cases/transaction-firewall.md' - - Solo Staking (coming soon): 'use-cases/solo-staking.md' + - Solo Staking: + - 'use-cases/solo-staking/index.md' + - Voluntary Exit: 'use-cases/solo-staking/voluntary-exit.md' + - MEV-Boost: 'use-cases/solo-staking/mev-boost.md' - Support: - Troubleshooting: 'support/troubleshooting.md' - Cheatsheet: 'support/cheatsheet.md'