more doc updates

storage/blockchain/src/ops/block.rs

@@ -227,6 +227,9 @@ pub fn pop_block(
     Ok((block_height, block_info.block_hash, block))
 }
 //---------------------------------------------------------------------------------------------------- `get_block_blob_with_tx_indexes`
+/// Retrieve a block's raw bytes, the index of the miner transaction and the number of non miner-txs in the block.
+///
+#[doc = doc_error!()]
 pub fn get_block_blob_with_tx_indexes(
     block_height: &BlockHeight,
     tables: &impl Tables,
@@ -249,14 +252,17 @@ pub fn get_block_blob_with_tx_indexes(
     // Add the blocks tx hashes.
     write_varint(&block_txs.len(), &mut block)
         .expect("The number of txs per block will not exceed u64::MAX");
-    for tx in block_txs {
+
-        block.extend_from_slice(&tx);
+    let block_txs_bytes = bytemuck::cast_slice(&block_txs);
-    }
+    block.extend_from_slice(block_txs_bytes);
 
     Ok((block, miner_tx_idx, numb_txs))
 }
 
 //---------------------------------------------------------------------------------------------------- `get_block_extended_header_*`
+/// Retrieve a [`BlockCompleteEntry`] from the database.
+///
+#[doc = doc_error!()]
 pub fn get_block_complete_entry(
     block_hash: &BlockHash,
     tables: &impl TablesIter,

storage/blockchain/src/ops/blockchain.rs

@@ -3,12 +3,10 @@
 //---------------------------------------------------------------------------------------------------- Import
 use cuprate_database::{DatabaseRo, RuntimeError};
 
-use crate::ops::block::block_exists;
-use crate::types::BlockHash;
 use crate::{
-    ops::macros::doc_error,
+    ops::{block::block_exists, macros::doc_error},
     tables::{BlockHeights, BlockInfos},
-    types::BlockHeight,
+    types::{BlockHash, BlockHeight},
 };
 
 //---------------------------------------------------------------------------------------------------- Free Functions
@@ -82,7 +80,7 @@ pub fn cumulative_generated_coins(
 
 /// Find the split point between our chain and a list of [`BlockHash`]s from another chain.
 ///
-/// This function can be used accepts chains in chronological and reverse chronological order, however
+/// This function accepts chains in chronological and reverse chronological order, however
 /// if the wrong order is specified the return value is meaningless.
 ///
 /// For chronologically ordered chains this will return the index of the first unknown, for reverse
@@ -99,7 +97,7 @@ pub fn find_split_point(
 ) -> Result<usize, RuntimeError> {
     let mut err = None;
 
-    // Do a binary search to find the first unknown block in the batch.
+    // Do a binary search to find the first unknown/known block in the batch.
     let idx =
         block_ids.partition_point(
             |block_id| match block_exists(block_id, table_block_heights) {

types/src/blockchain.rs

@@ -29,6 +29,9 @@ use crate::{
 /// See `Response` for the expected responses per `Request`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum BlockchainReadRequest {
+    /// Request [`BlockCompleteEntry`]s.
+    ///
+    /// The input is the block hashes.
     BlockCompleteEntries(Vec<[u8; 32]>),
 
     /// Request a block's extended header.
@@ -124,7 +127,7 @@ pub enum BlockchainReadRequest {
         block_hash: [u8; 32],
         /// The indexes of the transactions from the block.
         /// This is not the global index of the txs, instead it is the local index as they appear in
-        /// the block/
+        /// the block.
         tx_indexes: Vec<u64>,
     },
 
@@ -132,9 +135,7 @@ pub enum BlockchainReadRequest {
     AltBlocksInChain(ChainId),
 
     /// Get a [`Block`] by its height.
-    Block {
+    Block { height: usize },
-        height: usize,
-    },
 
     /// Get a [`Block`] by its hash.
     BlockByHash([u8; 32]),
@@ -154,10 +155,7 @@ pub enum BlockchainReadRequest {
     /// `N` last blocks starting at particular height.
     ///
     /// TODO: document fields after impl.
-    CoinbaseTxSum {
+    CoinbaseTxSum { height: usize, count: u64 },
-        height: usize,
-        count: u64,
-    },
 
     /// Get information on all alternative chains.
     AltChains,
@@ -211,9 +209,13 @@ pub enum BlockchainWriteRequest {
 #[expect(clippy::large_enum_variant)]
 pub enum BlockchainResponse {
     //------------------------------------------------------ Reads
+    /// Response to [`BlockchainReadRequest::BlockCompleteEntries`].
     BlockCompleteEntries {
+        /// The [`BlockCompleteEntry`]s that we had.
         blocks: Vec<BlockCompleteEntry>,
+        /// The hashes of blocks that were requested, but we don't have.
         missing_hashes: Vec<[u8; 32]>,
+        /// Our blockchain height.
         blockchain_height: usize,
     },
 
@@ -287,11 +289,17 @@ pub enum BlockchainResponse {
     ///
     /// If all blocks were unknown `start_height` will be `0`, the other fields will be meaningless.
     NextChainEntry {
+        /// The start height of this entry, `0` if we could not find the split point.
         start_height: usize,
+        /// The current chain height.
         chain_height: usize,
+        /// The next block hashes in the entry.
         block_ids: Vec<[u8; 32]>,
+        /// The block weights of the next blocks.
         block_weights: Vec<usize>,
+        /// The current cumulative difficulty of our chain.
         cumulative_difficulty: u128,
+        /// The block blob of the 2nd block in `block_ids`, if there is one.
         first_block_blob: Option<Vec<u8>>,
     },
 

types/src/types.rs

@@ -259,6 +259,7 @@ pub struct AddAuxPow {
     pub aux_pow: Vec<AuxPow>,
 }
 
+/// The inner response for a request for missing txs.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MissingTxsInBlock {
     pub block: Vec<u8>,