Add beacon.watch (#3362)

> This is currently a WIP and all features are subject to alteration or removal at any time.

## Overview

The successor to #2873.

Contains the backbone of `beacon.watch` including syncing code, the initial API, and several core database tables.

See `watch/README.md` for more information, requirements and usage.

watch/src/block_rewards/database.rs

@@ -0,0 +1,137 @@
+use crate::database::{
+    schema::{beacon_blocks, block_rewards},
+    watch_types::{WatchHash, WatchSlot},
+    Error, PgConn, MAX_SIZE_BATCH_INSERT,
+};
+
+use diesel::prelude::*;
+use diesel::{Insertable, Queryable};
+use log::debug;
+use serde::{Deserialize, Serialize};
+use std::time::Instant;
+
+#[derive(Debug, Queryable, Insertable, Serialize, Deserialize)]
+#[diesel(table_name = block_rewards)]
+pub struct WatchBlockRewards {
+    pub slot: WatchSlot,
+    pub total: i32,
+    pub attestation_reward: i32,
+    pub sync_committee_reward: i32,
+}
+
+/// Insert a batch of values into the `block_rewards` table.
+///
+/// On a conflict, it will do nothing, leaving the old value.
+pub fn insert_batch_block_rewards(
+    conn: &mut PgConn,
+    rewards: Vec<WatchBlockRewards>,
+) -> Result<(), Error> {
+    use self::block_rewards::dsl::*;
+
+    let mut count = 0;
+    let timer = Instant::now();
+
+    for chunk in rewards.chunks(MAX_SIZE_BATCH_INSERT) {
+        count += diesel::insert_into(block_rewards)
+            .values(chunk)
+            .on_conflict_do_nothing()
+            .execute(conn)?;
+    }
+
+    let time_taken = timer.elapsed();
+    debug!("Block rewards inserted, count: {count}, time_taken: {time_taken:?}");
+    Ok(())
+}
+
+/// Selects the row from the `block_rewards` table where `slot` is minimum.
+pub fn get_lowest_block_rewards(conn: &mut PgConn) -> Result<Option<WatchBlockRewards>, Error> {
+    use self::block_rewards::dsl::*;
+    let timer = Instant::now();
+
+    let result = block_rewards
+        .order_by(slot.asc())
+        .limit(1)
+        .first::<WatchBlockRewards>(conn)
+        .optional()?;
+
+    let time_taken = timer.elapsed();
+    debug!("Block rewards requested: lowest, time_taken: {time_taken:?}");
+    Ok(result)
+}
+
+/// Selects the row from the `block_rewards` table where `slot` is maximum.
+pub fn get_highest_block_rewards(conn: &mut PgConn) -> Result<Option<WatchBlockRewards>, Error> {
+    use self::block_rewards::dsl::*;
+    let timer = Instant::now();
+
+    let result = block_rewards
+        .order_by(slot.desc())
+        .limit(1)
+        .first::<WatchBlockRewards>(conn)
+        .optional()?;
+
+    let time_taken = timer.elapsed();
+    debug!("Block rewards requested: highest, time_taken: {time_taken:?}");
+    Ok(result)
+}
+
+/// Selects a single row of the `block_rewards` table corresponding to a given `root_query`.
+pub fn get_block_rewards_by_root(
+    conn: &mut PgConn,
+    root_query: WatchHash,
+) -> Result<Option<WatchBlockRewards>, Error> {
+    use self::beacon_blocks::dsl::{beacon_blocks, root};
+    use self::block_rewards::dsl::*;
+    let timer = Instant::now();
+
+    let join = beacon_blocks.inner_join(block_rewards);
+
+    let result = join
+        .select((slot, total, attestation_reward, sync_committee_reward))
+        .filter(root.eq(root_query))
+        .first::<WatchBlockRewards>(conn)
+        .optional()?;
+
+    let time_taken = timer.elapsed();
+    debug!("Block rewards requested: {root_query}, time_taken: {time_taken:?}");
+    Ok(result)
+}
+
+/// Selects a single row of the `block_rewards` table corresponding to a given `slot_query`.
+pub fn get_block_rewards_by_slot(
+    conn: &mut PgConn,
+    slot_query: WatchSlot,
+) -> Result<Option<WatchBlockRewards>, Error> {
+    use self::block_rewards::dsl::*;
+    let timer = Instant::now();
+
+    let result = block_rewards
+        .filter(slot.eq(slot_query))
+        .first::<WatchBlockRewards>(conn)
+        .optional()?;
+
+    let time_taken = timer.elapsed();
+    debug!("Block rewards requested: {slot_query}, time_taken: {time_taken:?}");
+    Ok(result)
+}
+
+/// Selects `slot` from all rows of the `beacon_blocks` table which do not have a corresponding
+/// row in `block_rewards`.
+#[allow(dead_code)]
+pub fn get_unknown_block_rewards(conn: &mut PgConn) -> Result<Vec<Option<WatchSlot>>, Error> {
+    use self::beacon_blocks::dsl::{beacon_blocks, root, slot};
+    use self::block_rewards::dsl::block_rewards;
+
+    let join = beacon_blocks.left_join(block_rewards);
+
+    let result = join
+        .select(slot)
+        .filter(root.is_null())
+        // Block rewards cannot be retrieved for `slot == 0` so we need to exclude it.
+        .filter(slot.ne(0))
+        .order_by(slot.desc())
+        .nullable()
+        .load::<Option<WatchSlot>>(conn)?;
+
+    Ok(result)
+}

watch/src/block_rewards/mod.rs

@@ -0,0 +1,38 @@
+pub mod database;
+mod server;
+mod updater;
+
+use crate::database::watch_types::WatchSlot;
+use crate::updater::error::Error;
+
+pub use database::{
+    get_block_rewards_by_root, get_block_rewards_by_slot, get_highest_block_rewards,
+    get_lowest_block_rewards, get_unknown_block_rewards, insert_batch_block_rewards,
+    WatchBlockRewards,
+};
+pub use server::block_rewards_routes;
+
+use eth2::BeaconNodeHttpClient;
+use types::Slot;
+
+/// Sends a request to `lighthouse/analysis/block_rewards`.
+/// Formats the response into a vector of `WatchBlockRewards`.
+///
+/// Will fail if `start_slot == 0`.
+pub async fn get_block_rewards(
+    bn: &BeaconNodeHttpClient,
+    start_slot: Slot,
+    end_slot: Slot,
+) -> Result<Vec<WatchBlockRewards>, Error> {
+    Ok(bn
+        .get_lighthouse_analysis_block_rewards(start_slot, end_slot)
+        .await?
+        .into_iter()
+        .map(|data| WatchBlockRewards {
+            slot: WatchSlot::from_slot(data.meta.slot),
+            total: data.total as i32,
+            attestation_reward: data.attestation_rewards.total as i32,
+            sync_committee_reward: data.sync_committee_rewards as i32,
+        })
+        .collect())
+}

watch/src/block_rewards/server.rs

@@ -0,0 +1,31 @@
+use crate::block_rewards::database::{
+    get_block_rewards_by_root, get_block_rewards_by_slot, WatchBlockRewards,
+};
+use crate::database::{get_connection, PgPool, WatchHash, WatchSlot};
+use crate::server::Error;
+
+use axum::{extract::Path, routing::get, Extension, Json, Router};
+use eth2::types::BlockId;
+use std::str::FromStr;
+
+pub async fn get_block_rewards(
+    Path(block_query): Path<String>,
+    Extension(pool): Extension<PgPool>,
+) -> Result<Json<Option<WatchBlockRewards>>, Error> {
+    let mut conn = get_connection(&pool).map_err(Error::Database)?;
+    match BlockId::from_str(&block_query).map_err(|_| Error::BadRequest)? {
+        BlockId::Root(root) => Ok(Json(get_block_rewards_by_root(
+            &mut conn,
+            WatchHash::from_hash(root),
+        )?)),
+        BlockId::Slot(slot) => Ok(Json(get_block_rewards_by_slot(
+            &mut conn,
+            WatchSlot::from_slot(slot),
+        )?)),
+        _ => Err(Error::BadRequest),
+    }
+}
+
+pub fn block_rewards_routes() -> Router {
+    Router::new().route("/v1/blocks/:block/rewards", get(get_block_rewards))
+}

watch/src/block_rewards/updater.rs

@@ -0,0 +1,157 @@
+use crate::database::{self, Error as DbError};
+use crate::updater::{Error, UpdateHandler};
+
+use crate::block_rewards::get_block_rewards;
+
+use eth2::types::EthSpec;
+use log::{debug, error, warn};
+
+const MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS: u64 = 1600;
+
+impl<T: EthSpec> UpdateHandler<T> {
+    /// Forward fills the `block_rewards` table starting from the entry with the
+    /// highest slot.
+    ///
+    /// It constructs a request to the `get_block_rewards` API with:
+    /// `start_slot` -> highest filled `block_rewards` + 1 (or lowest beacon block)
+    /// `end_slot` -> highest beacon block
+    ///
+    /// Request range will not exceed `MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS`.
+    pub async fn fill_block_rewards(&mut self) -> Result<(), Error> {
+        let mut conn = database::get_connection(&self.pool)?;
+
+        //  Get the slot of the highest entry in the `block_rewards` table.
+        let highest_filled_slot_opt = if self.config.block_rewards {
+            database::get_highest_block_rewards(&mut conn)?.map(|reward| reward.slot)
+        } else {
+            return Err(Error::NotEnabled("block_rewards".to_string()));
+        };
+
+        let mut start_slot = if let Some(highest_filled_slot) = highest_filled_slot_opt {
+            highest_filled_slot.as_slot() + 1
+        } else {
+            // No entries in the `block_rewards` table. Use `beacon_blocks` instead.
+            if let Some(lowest_beacon_block) =
+                database::get_lowest_beacon_block(&mut conn)?.map(|block| block.slot)
+            {
+                lowest_beacon_block.as_slot()
+            } else {
+                // There are no blocks in the database, do not fill the `block_rewards` table.
+                warn!("Refusing to fill block rewards as there are no blocks in the database");
+                return Ok(());
+            }
+        };
+
+        // The `block_rewards` API cannot accept `start_slot == 0`.
+        if start_slot == 0 {
+            start_slot += 1;
+        }
+
+        if let Some(highest_beacon_block) =
+            database::get_highest_beacon_block(&mut conn)?.map(|block| block.slot)
+        {
+            let mut end_slot = highest_beacon_block.as_slot();
+
+            if start_slot > end_slot {
+                debug!("Block rewards are up to date with the head of the database");
+                return Ok(());
+            }
+
+            // Ensure the size of the request does not exceed the maximum allowed value.
+            if start_slot < end_slot.saturating_sub(MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS) {
+                end_slot = start_slot + MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS
+            }
+
+            let rewards = get_block_rewards(&self.bn, start_slot, end_slot).await?;
+            database::insert_batch_block_rewards(&mut conn, rewards)?;
+        } else {
+            // There are no blocks in the `beacon_blocks` database, but there are entries in the
+            // `block_rewards` table. This is a critical failure. It usually means someone has
+            // manually tampered with the database tables and should not occur during normal
+            // operation.
+            error!("Database is corrupted. Please re-sync the database");
+            return Err(Error::Database(DbError::DatabaseCorrupted));
+        }
+
+        Ok(())
+    }
+
+    /// Backfill the `block_rewards` tables starting from the entry with the
+    /// lowest slot.
+    ///
+    /// It constructs a request to the `get_block_rewards` API with:
+    /// `start_slot` -> lowest_beacon_block
+    /// `end_slot` -> lowest filled `block_rewards` - 1 (or highest beacon block)
+    ///
+    /// Request range will not exceed `MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS`.
+    pub async fn backfill_block_rewards(&mut self) -> Result<(), Error> {
+        let mut conn = database::get_connection(&self.pool)?;
+        let max_block_reward_backfill = self.config.max_backfill_size_epochs * self.slots_per_epoch;
+
+        // Get the slot of the lowest entry in the `block_rewards` table.
+        let lowest_filled_slot_opt = if self.config.block_rewards {
+            database::get_lowest_block_rewards(&mut conn)?.map(|reward| reward.slot)
+        } else {
+            return Err(Error::NotEnabled("block_rewards".to_string()));
+        };
+
+        let end_slot = if let Some(lowest_filled_slot) = lowest_filled_slot_opt {
+            lowest_filled_slot.as_slot().saturating_sub(1_u64)
+        } else {
+            // No entries in the `block_rewards` table. Use `beacon_blocks` instead.
+            if let Some(highest_beacon_block) =
+                database::get_highest_beacon_block(&mut conn)?.map(|block| block.slot)
+            {
+                highest_beacon_block.as_slot()
+            } else {
+                // There are no blocks in the database, do not backfill the `block_rewards` table.
+                warn!("Refusing to backfill block rewards as there are no blocks in the database");
+                return Ok(());
+            }
+        };
+
+        if end_slot <= 1 {
+            debug!("Block rewards backfill is complete");
+            return Ok(());
+        }
+
+        if let Some(lowest_block_slot) = database::get_lowest_beacon_block(&mut conn)? {
+            let mut start_slot = lowest_block_slot.slot.as_slot();
+
+            if start_slot >= end_slot {
+                debug!("Block rewards are up to date with the base of the database");
+                return Ok(());
+            }
+
+            // Ensure that the request range does not exceed `max_block_reward_backfill` or
+            // `MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS`.
+            if start_slot < end_slot.saturating_sub(max_block_reward_backfill) {
+                start_slot = end_slot.saturating_sub(max_block_reward_backfill)
+            }
+
+            if start_slot < end_slot.saturating_sub(MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS) {
+                start_slot = end_slot.saturating_sub(MAX_SIZE_SINGLE_REQUEST_BLOCK_REWARDS)
+            }
+
+            // The `block_rewards` API cannot accept `start_slot == 0`.
+            if start_slot == 0 {
+                start_slot += 1
+            }
+
+            let rewards = get_block_rewards(&self.bn, start_slot, end_slot).await?;
+
+            if self.config.block_rewards {
+                database::insert_batch_block_rewards(&mut conn, rewards)?;
+            }
+        } else {
+            // There are no blocks in the `beacon_blocks` database, but there are entries in the
+            // `block_rewards` table. This is a critical failure. It usually means someone has
+            // manually tampered with the database tables and should not occur during normal
+            // operation.
+            error!("Database is corrupted. Please re-sync the database");
+            return Err(Error::Database(DbError::DatabaseCorrupted));
+        }
+
+        Ok(())
+    }
+}