ETH2 Block Proposal Monitor

ETH2 Block Proposal Monitor is a tool for Ethereum validators to monitor block proposals and rewards of their validators. Through Prometheus metrics, it provides the tools required to monitor and alert whenever a validator proposes an empty block, or misses the proposal. It also contains functionality to monitor MEV rewards, as well as regular rewards, generated by the validators monitored.

Installation Guide

Requirements:

• A beacon chain RPC node, such as Prysm. This is required to monitor blocks that were not relayed by a relayer.
• List of validators' public keys to monitor.
• Optional: An ETH1 RPC node for manual reward calculation.

Setup (Docker)

1. Make sure you have Docker installed on your system
2. Pull the docker image from the repository: docker pull simplystaking/eth-block-proposal-monitor
3. Run the image. The database is stored in /usr/src/eth-block-monitor/data in the container, thus we always suggest creating a corresponding volume on the host machine to this directory, to ensure no data loss on the deletion of the container, or when updating.

# example 1: the database will be stored in /root/data on the host machine, and the pubkeys.txt file is in the same directory
docker run -d --name eth-block-monitor --log-driver=journald --restart always -v /root/data:/usr/src/eth-block-monitor/data -p 0.0.0.0:7999:7999 eth-block-monitor --port 7999 --pubkeys_file "/usr/src/eth-block-monitor/data/pubkeys.txt" --eth1_rpc "<EL-RPC-URL>" --eth2_rpc "<CL-RPC-URL>" --eth1_parallel --eth2_parallel --rewards --sync_committee

# example 2: instead of passing command-line options, the options are in config.json. place config.json and pubkeys.txt in /root/data
docker run -d --name eth-block-monitor --log-driver=journald --restart always -v /root/data:/usr/src/eth-block-monitor/data -p 0.0.0.0:7999:7999 eth-block-monitor -c "/usr/src/eth-block-monitor/data/config.json" --pubkeys_file "/usr/src/eth-block-monitor/data/pubkeys.txt"

# example 3: options are in config.json, but you will be passing the public keys as a command-line option. place config.json /root/data
docker run -d --name eth-block-monitor --log-driver=journald --restart always -v /root/data:/usr/src/eth-block-monitor/data -p 0.0.0.0:7999:7999 eth-block-monitor -c "/usr/src/eth-block-monitor/data/config.json" --pubkeys "0x001,0x002,0x003,0x004"

Setup (Manual)

1. Install Python 3.8+ (we are using v3.8.10).
2. Install the required packages by running: pip3 install -r requirements.txt or pip install -r requirements.txt.
3. In config.json, or through command-line options:
   1. Edit the value of "eth2_rpc" to the endpoint of your beacon chain RPC node.
   2. Optional: Edit the value of "reward_metrics" to true or false. If set to true, ensure to also populate the value of "eth1_rpc" to the endpoint of your ETH1 RPC node. Additionally, the value of "parallel_requests_eth1" may be changed, which significantly reduces the number of requests done to the ETH1 RPC node per second.
   3. Optional: In config.json, edit the value of "sync_committee_participation" to true or false. If set to true, you can additionally edit the value of "parallel_requests_eth2", which significantly reduces the number of requests done to the Beacon Chain node when first getting the Validator indexes.
   4. Optional: In config.json, edit the value of "port" to your preferred value. This value determines on which port the Prometheus metrics will be outputted on.
   5. Optional: In config.json, the value of "continue_from_last_slot" can be edited to start from a later/earlier slot. By default, the first time the script is ran, it will only gather the last 100 slots. After enabling "continue_from_last_slot", also edit the value of "last_slot" to the slot value to start gathering data from.
   6. Optional: In config.json, you can enable "pruning" to delete old slot data. You can choose the number of last slots to keep by editing the "keep_last_slots" value.
4. Populate pubkeys.txt with the public keys of the validators you'd like to monitor. This is a comma-separated list. You can also provide the public keys through the command-line option --pubkeys. If using a file, unless a different path is provided with the --pubkeys_file option, the script will look for the file in /data/.

Setup (Linux)

If you're on Linux, you can follow these commands to create a user and run the script as that user:

# create the non-root user
adduser monitoring --disabled-login
# install python3 with pip
sudo apt-get update -y && sudo apt-get install python3-pip -y

# as the user, clone the repository
su monitoring
cd
git clone https://github.com/SimplyVC/eth-block-proposal-monitor
cd eth-block-proposal-monitor

# install the requirements using pip
pip3 install -r requirements.txt

# at this point you can edit the config.json file to provide an RPC endpoint etc (see Setup above)

exit

# as root, make the setup script executable
chmod +x /home/monitoring/eth-block-proposal-monitor/setup.sh
# run the script and check the logs of the service file to ensure it is working fine
/home/monitoring/eth-block-proposal-monitor/setup.sh && journalctl -f -u eth2_block_monitoring

Config File

For a complete and up-to-date list of the options that can be provided through command-line or using the config file, run the script with -h or --help.

Usage

After running the main.py script, Prometheus metrics are outputted on localhost on your chosen port. The script queries relays that are included in relay_config.json every 20 seconds, and stores information about each slot. After each iteration, the data is saved (to slot_data.db - this is an sqlite3 database) and the metrics are published.

Updating

Before updating to a newer version or commit, we always recommend saving a copy of your database (i.e. /data/slot_data.db), so that you can rollback.

Metrics

The tool contains the following list of Prometheus metrics:

1. RelayBlocksProposed{relay} -> int: The number of blocks proposed per relay by the validators we are monitoring.
2. ValidatorBlocksProposed{public_key} -> int: The number of blocks proposed by each validator that we are monitoring.
3. MissedBlockProposals{public_key} -> int: The number of missed block proposals by each validator that we are monitoring.
4. EmptyBlockProposals{public_key} -> int: The number of empty blocks proposed by each validator that we are monitoring.
5. TotalRelayBlocksProposed{relay} -> int: The total number of blocks proposed through each relay (since the first slot monitored by the script). This includes blocks proposed by validators that are not being monitored.
6. RelayTotalRewards{relay} -> float: The total reward (in ETH) generated by each relay. This metric is global, i.e. it includes rewards generated by validators that are not being monitored.
7. AvgRelayerRewards{relay} -> float: The average reward (in ETH) generated by each relay. This metric is global.
8. UnknownRewardBlocks{relay} -> int: The number of blocks with an unknown reward per each relay. Blocks will have an unknown reward when there is a missed proposal or when the block is empty. This metric is global.
9. TotalValidatorRewards{relay} -> float: The total reward (in ETH) generated through each relay by the validators we are monitoring.
10. AvgValidatorRewards{relay} -> float: The average reward (in ETH) generated through each relay by the validators we are monitoring.
11. ValUnknownRewardBlocks{relay} -> int: The number of blocks with an unknown reward proposed by the validators we are monitoring through each relay.
12. ValidatorSyncParticipated{public_key, epoch} -> int: The number of slots the validator participated in, in the sync committee starting at the epoch indicated.
13. ValidatorSyncMissed{public_key, epoch} -> int: The number of slots the validator did not participate in, in the sync committee starting at the epoch indicated.
14. CurrentSyncCommitteeEpoch{epoch} -> int: If metric value is 1, it is the starting epoch of the current sync committee, if it is 0, then it is the starting epoch of the previous sync committee. This metric is mostly used for the Grafana dashboard.
15. UpcomingBlockProposal{public_key} -> int: The slot number at which the validator will propose a block.
16. UpcomingSyncCommitteeParticipations{public_key} -> int: The epoch at which the validator will start participating in the sync committee.
17. CurrentSlotNumber -> int: The latest slot number that the tool processed.