more doc updates

storage/blockchain/src/ops/alt_block/block.rs

@@ -24,12 +24,9 @@ use crate::{
 ///
 /// # Panics
 /// This function will panic if:
-/// - `block.height` is == `0`
+/// - `alt_block.height` is == `0`
+/// - `alt_block.txs.len()` != `alt_block.block.transactions.len()`
 ///
-/// # Already exists
-/// This function will operate normally even if `block` already
-/// exists, i.e., this function will not return `Err` even if you
-/// call this function infinitely with the same block.
 pub fn add_alt_block(
     alt_block: &AltBlockInformation,
     tables: &mut impl TablesMut,

storage/blockchain/src/ops/alt_block/mod.rs

@@ -18,8 +18,8 @@
 //! ```
 //!
 //! In that example if we were to receive an alt-block which immediately follows the top block of `ChainID(X)`
-//! then that block will also be stored under `ChainID(X)`. However if it follows from another block from `ChainID(X)`
+//! then that block will also be stored under `ChainID(X)`. However, if it follows from another block from `ChainID(X)`
-//! we will split into a chain with a different ID.
+//! we will split into a chain with a different ID:
 //!
 //! ```text
 //!      |
@@ -39,7 +39,7 @@
 //! [`get_alt_chain_history_ranges`] covers this and is the method to get the ranges of heights needed from each [`ChainID`](cuprate_types::ChainId)
 //! to get all the alt-blocks in a given [`ChainID`](cuprate_types::ChainId).
 //!
-//! Although this should be kept in mind as a possibility because Cuprate's block downloader will only track a single chain it is
+//! Although this should be kept in mind as a possibility, because Cuprate's block downloader will only track a single chain it is
 //! unlikely that we will be tracking [`ChainID`](cuprate_types::ChainId) that don't immediately connect to the main-chain.
 //!
 //! ## Why not use block's previous field?

storage/blockchain/src/ops/alt_block/tx.rs

@@ -4,9 +4,11 @@ use monero_serai::transaction::Transaction;
 use cuprate_database::{DatabaseRo, DatabaseRw, RuntimeError, StorableVec};
 use cuprate_types::VerifiedTransactionInformation;
 
-use crate::ops::macros::{doc_add_alt_block_inner_invariant, doc_error};
+use crate::{
-use crate::tables::{Tables, TablesMut};
+    ops::macros::{doc_add_alt_block_inner_invariant, doc_error},
-use crate::types::{AltTransactionInfo, TxHash};
+    tables::{Tables, TablesMut},
+    types::{AltTransactionInfo, TxHash},
+};
 
 /// Adds a [`VerifiedTransactionInformation`] form an alt-block to the DB, if
 /// that transaction is not already in the DB.

storage/blockchain/src/service/free.rs

@@ -3,13 +3,14 @@
 //---------------------------------------------------------------------------------------------------- Import
 use std::sync::Arc;
 
-use crate::service::{init_read_service, init_write_service};
+use cuprate_database::{ConcreteEnv, InitError};
+use cuprate_types::{AltBlockInformation, VerifiedBlockInformation};
+
 use crate::{
     config::Config,
     service::types::{BlockchainReadHandle, BlockchainWriteHandle},
 };
-use cuprate_database::{ConcreteEnv, InitError};
+use crate::service::{init_read_service, init_write_service};
-use cuprate_types::{AltBlockInformation, VerifiedBlockInformation};
 
 //---------------------------------------------------------------------------------------------------- Init
 #[cold]
@@ -81,7 +82,12 @@ pub(super) const fn compact_history_genesis_not_included<const INITIAL_BLOCKS: u
     top_block_height > INITIAL_BLOCKS && !(top_block_height - INITIAL_BLOCKS + 2).is_power_of_two()
 }
 
-//---------------------------------------------------------------------------------------------------- Compact history
+//---------------------------------------------------------------------------------------------------- Map Block
+/// Maps [`AltBlockInformation`] to [`VerifiedBlockInformation`]
+///
+/// # Panics
+/// This will panic if the block is invalid, so should only be used on blocks that have been popped from
+/// the main-chain.
 pub(super) fn map_valid_alt_block_to_verified_block(
     alt_block: AltBlockInformation,
 ) -> VerifiedBlockInformation {

storage/blockchain/src/service/read.rs

@@ -1,11 +1,11 @@
 //! Database reader thread-pool definitions and logic.
 
+//---------------------------------------------------------------------------------------------------- Import
 use std::{
     collections::{HashMap, HashSet},
     sync::Arc,
 };
 
-//---------------------------------------------------------------------------------------------------- Import
 use rayon::{
     iter::{IntoParallelIterator, ParallelIterator},
     prelude::*,
@@ -14,18 +14,17 @@ use rayon::{
 use thread_local::ThreadLocal;
 
 use cuprate_database::{ConcreteEnv, DatabaseRo, Env, EnvInner, RuntimeError};
-use cuprate_database_service::{init_thread_pool, DatabaseReadService, ReaderThreads};
+use cuprate_database_service::{DatabaseReadService, init_thread_pool, ReaderThreads};
 use cuprate_helper::map::combine_low_high_bits_to_u128;
 use cuprate_types::{
     blockchain::{BlockchainReadRequest, BlockchainResponse},
     Chain, ChainId, ExtendedBlockHeader, OutputOnChain,
 };
 
-use crate::ops::alt_block::get_alt_block;
 use crate::{
     ops::{
         alt_block::{
-            get_alt_block_extended_header_from_height, get_alt_block_hash,
+            get_alt_block, get_alt_block_extended_header_from_height, get_alt_block_hash,
             get_alt_chain_history_ranges,
         },
         block::{

storage/blockchain/src/service/write.rs

@@ -5,8 +5,8 @@ use std::sync::Arc;
 use cuprate_database::{ConcreteEnv, DatabaseRo, DatabaseRw, Env, EnvInner, RuntimeError, TxRw};
 use cuprate_database_service::DatabaseWriteHandle;
 use cuprate_types::{
-    blockchain::{BlockchainResponse, BlockchainWriteRequest},
+    AltBlockInformation,
-    AltBlockInformation, Chain, ChainId, VerifiedBlockInformation,
+    blockchain::{BlockchainResponse, BlockchainWriteRequest}, Chain, ChainId, VerifiedBlockInformation,
 };
 
 use crate::{
@@ -107,8 +107,8 @@ fn pop_blocks(env: &ConcreteEnv, numb_blocks: usize) -> ResponseResult {
     let env_inner = env.env_inner();
     let mut tx_rw = env_inner.tx_rw()?;
 
-    // TODO: try blocks
+    // TODO: turn this function into a try block once stable.
-    let result = {
+    let mut result = || {
         // flush all the current alt blocks as they may reference blocks to be popped.
         crate::ops::alt_block::flush_alt_blocks(&env_inner, &mut tx_rw)?;
 
@@ -136,7 +136,7 @@ fn pop_blocks(env: &ConcreteEnv, numb_blocks: usize) -> ResponseResult {
         Ok(old_main_chain_id)
     };
 
-    match result {
+    match result() {
         Ok(old_main_chain_id) => {
             TxRw::commit(tx_rw)?;
             Ok(BlockchainResponse::PopBlocks(old_main_chain_id))
@@ -156,7 +156,8 @@ fn reverse_reorg(env: &ConcreteEnv, chain_id: ChainId) -> ResponseResult {
     let env_inner = env.env_inner();
     let tx_rw = env_inner.tx_rw()?;
 
-    let result = {
+    // TODO: turn this function into a try block once stable.
+    let result = || {
         let mut tables_mut = env_inner.open_tables_mut(&tx_rw)?;
 
         let chain_info = tables_mut.alt_chain_infos().get(&chain_id.into())?;
@@ -197,7 +198,7 @@ fn reverse_reorg(env: &ConcreteEnv, chain_id: ChainId) -> ResponseResult {
         Ok(())
     };
 
-    match result {
+    match result() {
         Ok(()) => {
             TxRw::commit(tx_rw)?;
             Ok(BlockchainResponse::Ok)
@@ -218,7 +219,7 @@ fn flush_alt_blocks(env: &ConcreteEnv) -> ResponseResult {
     let env_inner = env.env_inner();
     let mut tx_rw = env_inner.tx_rw()?;
 
-    let result = { crate::ops::alt_block::flush_alt_blocks(&env_inner, &mut tx_rw) };
+    let result = crate::ops::alt_block::flush_alt_blocks(&env_inner, &mut tx_rw);
 
     match result {
         Ok(()) => {

storage/blockchain/src/tables.rs

@@ -131,21 +131,37 @@ cuprate_database::define_tables! {
     14 => TxUnlockTime,
     TxId => UnlockTime,
 
+    /// Information on alt-chains.
     15 => AltChainInfos,
     RawChainId => AltChainInfo,
 
+    /// Alt-block heights.
+    ///
+    /// Contains the height of all alt-blocks.
     16 => AltBlockHeights,
     BlockHash => AltBlockHeight,
 
+    /// Alt-block information.
+    ///
+    /// Contains information on all alt-blocks.
     17 => AltBlocksInfo,
     AltBlockHeight => CompactAltBlockInfo,
 
+    /// Alt-block blobs.
+    ///
+    /// Contains the raw bytes of all alt-blocks.
     18 => AltBlockBlobs,
     AltBlockHeight => BlockBlob,
 
+    /// Alt-Block transactions blobs.
+    ///
+    /// Contains the raw bytes of alt transactions, if those transactions are not in the main-chain.
     19 => AltTransactionBlobs,
     TxHash => TxBlob,
 
+    /// Alt-Block transactions information.
+    ///
+    /// Contains information on all alt transactions, even if they are in the main-chain.
     20 => AltTransactionInfos,
     TxHash => AltTransactionInfo,
 }

test-utils/src/data/mod.rs

@@ -25,13 +25,11 @@
 //! let tx: VerifiedTransactionInformation = TX_V1_SIG0.clone();
 //! ```
 
-mod constants;
 pub use constants::{
     BLOCK_43BD1F, BLOCK_5ECB7E, BLOCK_BBD604, BLOCK_F91043, TX_2180A8, TX_3BC7FF, TX_84D48D,
     TX_9E3F73, TX_B6B439, TX_D7FEBD, TX_E2D393, TX_E57440,
 };
+pub use statics::{BLOCK_V16_TX0, BLOCK_V1_TX2, BLOCK_V9_TX3, TX_V1_SIG0, TX_V1_SIG2, TX_V2_RCT3};
 
+mod constants;
 mod statics;
-pub use statics::{
-    tx_fee, BLOCK_V16_TX0, BLOCK_V1_TX2, BLOCK_V9_TX3, TX_V1_SIG0, TX_V1_SIG2, TX_V2_RCT3,
-};

test-utils/src/rpc/client.rs

@@ -1,18 +1,16 @@
 //! HTTP RPC client.
 
 //---------------------------------------------------------------------------------------------------- Use
+use monero_rpc::Rpc;
+use monero_serai::block::Block;
+use monero_simple_request_rpc::SimpleRequestRpc;
 use serde::Deserialize;
 use serde_json::json;
 use tokio::task::spawn_blocking;
 
-use monero_rpc::Rpc;
+use cuprate_helper::tx_utils::tx_fee;
-use monero_serai::block::Block;
-use monero_simple_request_rpc::SimpleRequestRpc;
-
 use cuprate_types::{VerifiedBlockInformation, VerifiedTransactionInformation};
 
-use crate::data::tx_fee;
-
 //---------------------------------------------------------------------------------------------------- Constants
 /// The default URL used for Monero RPC connections.
 pub const LOCALHOST_RPC_URL: &str = "http://127.0.0.1:18081";
@@ -184,9 +182,10 @@ impl HttpRpcClient {
 //---------------------------------------------------------------------------------------------------- TESTS
 #[cfg(test)]
 mod tests {
-    use super::*;
     use hex_literal::hex;
 
+    use super::*;
+
     /// Assert the default address is localhost.
     #[tokio::test]
     async fn localhost() {