chore(bolt-sidecar): docs again

bolt-sidecar/src/common/backoff.rs

@@ -1,5 +1,3 @@
-//! Utilities for retrying a future with backoff.
-
 use std::{future::Future, time::Duration};
 
 use tokio_retry::{

bolt-sidecar/src/common/mod.rs

@@ -1,6 +1,10 @@
+/// Utilities for retrying a future with backoff.
 pub mod backoff;
+/// A hash map-like bounded data structure with an additional scoring mechanism.
 pub mod score_cache;
+/// Secret key types wrappers for BLS, ECDSA and JWT.
 pub mod secrets;
+/// Utility functions for working with transactions.
 pub mod transactions;
 
 /// The version of the Bolt sidecar binary.

bolt-sidecar/src/common/score_cache.rs

@@ -1,5 +1,3 @@
-//! A hash map-like data structure with an additional scoring mechanism.
-
 use std::{
     borrow::Borrow,
     collections::HashMap,

bolt-sidecar/src/common/secrets.rs

@@ -1,5 +1,3 @@
-//! Secret key types wrappers for BLS, ECDSA and JWT.
-
 use std::{
     fmt::{self, Display},
     fs::read_to_string,

bolt-sidecar/src/common/transactions.rs

@@ -1,5 +1,3 @@
-//! This module contains utility functions for working with transactions.
-
 use alloy::primitives::U256;
 use reth_primitives::PooledTransactionsElement;
 

bolt-sidecar/src/config/limits.rs

@@ -39,9 +39,10 @@ pub struct LimitsOpts {
         default_value_t = LimitsOpts::default().min_priority_fee
     )]
     pub min_priority_fee: u128,
-    /// The maximum size in MiB of the [crate::state::ExecutionState] LRU cache that holds account
-    /// states. Each [crate::primitives::AccountState] is 48 bytes, and its key is 20 bytes, so the
-    /// default value of 1024 KiB = 1 MiB can hold around 15k account states.
+    /// The maximum size in MiB of the [crate::state::ExecutionState] ScoreCache that holds account
+    /// states. Each [crate::primitives::AccountState] is 48 bytes, its score is [usize] bytes, and
+    /// its key is 20 bytes, so the default value of 1024 KiB = 1 MiB can hold around 15k account
+    /// states.
     #[clap(
         long,
         env = "BOLT_SIDECAR_MAX_ACCOUNT_STATES_SIZE",

bolt-sidecar/src/state/account_state.rs

@@ -9,6 +9,14 @@ const INSERT_SCORE: isize = 4;
 const UPDATE_SCORE: isize = -1;
 
 /// A scored cache for account states.
+///
+/// The cache is scored based on the number of times an account state is accessed.
+/// In particular, there is a bonus when an account is read or inserted, because it means we've
+/// received an inclusion preconfirmation requests.
+///
+/// Moreover, updates incur a penalty. That is because after we insert an account, we must keep
+/// track of its updates during new blocks. The goal of this cache is to keep to most active
+/// accounts in it.
 #[derive(Debug, Default)]
 pub struct AccountStateCache(
     pub ScoreCache<GET_SCORE, INSERT_SCORE, UPDATE_SCORE, Address, AccountState>,

bolt-sidecar/src/state/execution.rs

@@ -145,13 +145,6 @@ pub struct ExecutionState<C> {
     /// The cached account states. This should never be read directly.
     /// These only contain the canonical account states at the head block,
     /// not the intermediate states.
-    ///
-    /// The value of the map is a tuple containing the account state and a score.
-    /// The score is needed to determine which accounts to evict when the cache is full with a
-    /// custom logic.
-    /// When a commitment request is made from an account its score is bumped of
-    /// [ACCOUNT_STATE_SCORE_BUMP], and when it updated it is decreased by
-    /// [ACCOUNT_STATE_UPDATE_PENALTY].
     account_states: AccountStateCache,
     /// The block templates by target SLOT NUMBER.
     /// We have multiple block templates because in rare cases we might have multiple