document types

storage/blockchain/src/types.rs

@@ -327,6 +327,29 @@ pub struct RctOutput {
 // TODO: local_index?
 
 //---------------------------------------------------------------------------------------------------- RawChain
+/// [`Chain`] in a format which can be stored in the DB.
+///
+/// Implements [`Into`] and [`From`] for [`Chain`].
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+/// use cuprate_types::Chain;
+///
+/// // Assert Storable is correct.
+/// let a: RawChain = Chain::Main.into();
+/// let b = Storable::as_bytes(&a);
+/// let c: RawChain = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<RawChain>(), 8);
+/// assert_eq!(align_of::<RawChain>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(transparent)]
 pub struct RawChain(u64);
@@ -348,6 +371,7 @@ impl From<RawChain> for Chain {
 
 impl From<RawChainId> for RawChain {
     fn from(value: RawChainId) -> Self {
+        // A [`ChainID`] with an inner value of `0` is invalid.
         assert_ne!(value.0, 0);
 
         Self(value.0)
@@ -355,6 +379,29 @@ impl From<RawChainId> for RawChain {
 }
 
 //---------------------------------------------------------------------------------------------------- RawChainId
+/// [`ChainId`] in a format which can be stored in the DB.
+///
+/// Implements [`Into`] and [`From`] for [`ChainId`].
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+/// use cuprate_types::ChainId;
+///
+/// // Assert Storable is correct.
+/// let a: RawChainId = ChainId(10.try_into().unwrap()).into();
+/// let b = Storable::as_bytes(&a);
+/// let c: RawChainId = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<RawChainId>(), 8);
+/// assert_eq!(align_of::<RawChainId>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(transparent)]
 pub struct RawChainId(u64);
@@ -374,31 +421,112 @@ impl From<RawChainId> for ChainId {
 impl Key for RawChainId {}
 
 //---------------------------------------------------------------------------------------------------- AltChainInfo
+/// Information on an alternative chain.
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+/// use cuprate_types::Chain;
+///
+/// // Assert Storable is correct.
+/// let a: AltChainInfo = AltChainInfo {
+///     parent_chain: Chain::Main.into(),
+///     common_ancestor_height: 0,
+///     chain_height: 1,
+/// };
+/// let b = Storable::as_bytes(&a);
+/// let c: AltChainInfo = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<AltChainInfo>(), 24);
+/// assert_eq!(align_of::<AltChainInfo>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(C)]
 pub struct AltChainInfo {
+    /// The chain this alt chain forks from.
     pub parent_chain: RawChain,
+    /// The height of the first block we share with the parent chain.
     pub common_ancestor_height: usize,
+    /// The chain height of the blocks in this alt chain.
     pub chain_height: usize,
 }
 
 //---------------------------------------------------------------------------------------------------- AltBlockHeight
+/// Represents the height of a block on an alt-chain.
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+/// use cuprate_types::ChainId;
+///
+/// // Assert Storable is correct.
+/// let a: AltBlockHeight = AltBlockHeight {
+///     chain_id: ChainId(1.try_into().unwrap()).into(),
+///     height: 1,
+/// };
+/// let b = Storable::as_bytes(&a);
+/// let c: AltBlockHeight = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<AltBlockHeight>(), 16);
+/// assert_eq!(align_of::<AltBlockHeight>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(C)]
 pub struct AltBlockHeight {
+    /// The [`ChainId`] of the chain this alt block is on, in raw form.
     pub chain_id: RawChainId,
+    /// The height of this alt-block.
     pub height: usize,
 }
 
 impl Key for AltBlockHeight {}
 
 //---------------------------------------------------------------------------------------------------- CompactAltBlockInfo
+/// Represents information on an alt-chain.
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+///
+/// // Assert Storable is correct.
+/// let a: CompactAltBlockInfo = CompactAltBlockInfo {
+///     block_hash: [1; 32],
+///     pow_hash: [2; 32],
+///     height: 10,
+///     weight: 20,
+///     long_term_weight: 30,
+///     cumulative_difficulty_low: 40,
+///     cumulative_difficulty_high: 50,
+/// };
+///     
+/// let b = Storable::as_bytes(&a);
+/// let c: CompactAltBlockInfo = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<CompactAltBlockInfo>(), 104);
+/// assert_eq!(align_of::<CompactAltBlockInfo>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(C)]
 pub struct CompactAltBlockInfo {
     /// The block's hash.
-    ///
-    /// [`Block::hash`].
     pub block_hash: [u8; 32],
     /// The block's proof-of-work hash.
     pub pow_hash: [u8; 32],
@@ -408,24 +536,46 @@ pub struct CompactAltBlockInfo {
     pub weight: usize,
     /// The long term block weight, which is the weight factored in with previous block weights.
     pub long_term_weight: usize,
-    /// The cumulative difficulty of all blocks up until and including this block.
+    /// The low 64 bits of the cumulative difficulty.
     pub cumulative_difficulty_low: u64,
+    /// The high 64 bits of the cumulative difficulty.
     pub cumulative_difficulty_high: u64,
 }
 
 //---------------------------------------------------------------------------------------------------- AltTransactionInfo
+/// Represents information on an alt transaction.
+///
+/// ```rust
+/// # use std::borrow::*;
+/// # use cuprate_blockchain::{*, types::*};
+/// use cuprate_database::Storable;
+///
+/// // Assert Storable is correct.
+/// let a: AltTransactionInfo = AltTransactionInfo {
+///     tx_weight: 1,
+///     fee: 6,
+///     tx_hash: [6; 32],
+/// };
+///     
+/// let b = Storable::as_bytes(&a);
+/// let c: AltTransactionInfo = Storable::from_bytes(b);
+/// assert_eq!(a, c);
+/// ```
+///
+/// # Size & Alignment
+/// ```rust
+/// # use cuprate_blockchain::types::*;
+/// assert_eq!(size_of::<AltTransactionInfo>(), 48);
+/// assert_eq!(align_of::<AltTransactionInfo>(), 8);
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash, Pod, Zeroable)]
 #[repr(C)]
 pub struct AltTransactionInfo {
     /// The transaction's weight.
-    ///
-    /// [`Transaction::weight`].
     pub tx_weight: usize,
     /// The transaction's total fees.
     pub fee: u64,
     /// The transaction's hash.
-    ///
-    /// [`Transaction::hash`].
     pub tx_hash: [u8; 32],
 }
 

types/src/blockchain.rs

@@ -105,10 +105,6 @@ pub enum BlockchainReadRequest {
 
 //---------------------------------------------------------------------------------------------------- WriteRequest
 /// A write request to the blockchain database.
-///
-/// There is currently only 1 write request to the database,
-/// as such, the only valid [`BlockchainResponse`] to this request is
-/// the proper response for a [`BlockchainResponse::WriteBlockOk`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum BlockchainWriteRequest {
     /// Request that a block be written to the database.