diff --git a/util/gen-types/Cargo.toml b/util/gen-types/Cargo.toml index 2104ffe8f7d..5bc2e8815db 100644 --- a/util/gen-types/Cargo.toml +++ b/util/gen-types/Cargo.toml @@ -16,11 +16,7 @@ default = ["std"] calc-hash = ["blake2b-ref"] check-data = [] serialized-size = ["calc-hash"] -std = [ - "calc-hash", - "check-data", - "serialized-size", - "molecule/std", "ckb-fixed-hash", "numext-fixed-uint", "ckb-error", "ckb-occupied-capacity", "ckb-hash" ] +std = ["calc-hash", "check-data", "serialized-size", "molecule/std", "ckb-fixed-hash", "numext-fixed-uint", "ckb-error", "ckb-occupied-capacity", "ckb-hash"] [dependencies] molecule = { version = "0.7.5", default-features = false } diff --git a/util/gen-types/src/core/mod.rs b/util/gen-types/src/core/mod.rs index d8cb2ed194f..651e657622f 100644 --- a/util/gen-types/src/core/mod.rs +++ b/util/gen-types/src/core/mod.rs @@ -1,3 +1,5 @@ +//! The essential rust types for CKB contracts. + #![allow(clippy::from_over_into)] #[cfg(feature = "std")] diff --git a/util/gen-types/src/extension/shortcut.rs b/util/gen-types/src/extension/shortcut.rs index 644ef55ff46..983c500199d 100644 --- a/util/gen-types/src/extension/shortcut.rs +++ b/util/gen-types/src/extension/shortcut.rs @@ -293,6 +293,7 @@ impl AsRef<[u8]> for packed::TransactionKey { } impl packed::HeaderDigest { + /// Checks if the `HeaderDigest` is the default value. pub fn is_default(&self) -> bool { let default = Self::default(); self.as_slice() == default.as_slice() diff --git a/util/gen-types/src/lib.rs b/util/gen-types/src/lib.rs index b33637004fd..6fb919cab79 100644 --- a/util/gen-types/src/lib.rs +++ b/util/gen-types/src/lib.rs @@ -9,10 +9,11 @@ extern crate alloc; mod conversion; pub mod core; -pub mod extension; +mod extension; mod generated; pub mod prelude; pub use generated::packed; +#[allow(missing_docs)] pub mod util; //re-exports diff --git a/util/types/src/prelude.rs b/util/types/src/prelude.rs index d8c59b2901f..f9c2a228b66 100644 --- a/util/types/src/prelude.rs +++ b/util/types/src/prelude.rs @@ -16,21 +16,33 @@ pub use ckb_gen_types::prelude::*; use std::collections::HashSet; +/// Trait for converting types into `TransactionView`. pub trait IntoTransactionView { + /// Converts the implementing type into a `TransactionView`. fn into_view(self) -> TransactionView; } +/// Trait for converting types into `HeaderView`. pub trait IntoHeaderView { + /// Converts the implementing type into a `HeaderView`. fn into_view(self) -> HeaderView; } +/// Trait for converting types into `UncleBlockView`. pub trait IntoUncleBlockView { + /// Converts the implementing type into an `UncleBlockView`. fn into_view(self) -> UncleBlockView; } +/// Trait for converting types into `BlockView`. pub trait IntoBlockView { + /// Converts the implementing type into a `BlockView` without resetting the header. fn into_view_without_reset_header(self) -> BlockView; + + /// Converts the implementing type into a `BlockView`. fn into_view(self) -> BlockView; + + /// Converts a packed block and associated data into a `BlockView`. fn block_into_view_internal( block: packed::Block, tx_hashes: Vec, @@ -38,33 +50,54 @@ pub trait IntoBlockView { ) -> BlockView; } +/// Trait for obtaining an advanced builder for `BlockView`. pub trait AsBlockBuilder { + /// Creates a new advanced builder for `BlockView`. fn new_advanced_builder() -> BlockBuilder; + + /// Gets an advanced builder from the implementing type. fn as_advanced_builder(&self) -> BlockBuilder; } + +/// Trait for obtaining an advanced builder for `TransactionView`. pub trait AsTransactionBuilder { + /// Gets an advanced builder for `TransactionView` from the implementing type. fn as_advanced_builder(&self) -> TransactionBuilder; } +/// Trait for obtaining an advanced builder for `HeaderView`. pub trait AsHeaderBuilder { + /// Gets an advanced builder for `HeaderView` from the implementing type. fn as_advanced_builder(&self) -> HeaderBuilder; } +/// Trait for calculating difficulty. pub trait Difficulty { + /// Calculates and returns the difficulty value as a `U256`. fn difficulty(&self) -> U256; } +/// Trait for building a compact block from a `BlockView`. pub trait BuildCompactBlock { + /// Builds a compact block from a `BlockView` and a set of prefilled transaction indexes. fn build_from_block( block: &BlockView, prefilled_transactions_indexes: &HashSet, ) -> packed::CompactBlock; + + /// Returns the short IDs of the transactions in the compact block. fn block_short_ids(&self) -> Vec>; + + /// Returns the indexes of the short IDs in the compact block. fn short_id_indexes(&self) -> Vec; } +/// Trait for resetting the header of a packed block. pub trait ResetBlock { + /// Resets the header of the packed block. fn reset_header(self) -> packed::Block; + + /// Resets the header of the packed block with given transaction hashes and witness hashes. fn reset_header_with_hashes( self, tx_hashes: &[packed::Byte32], @@ -72,6 +105,8 @@ pub trait ResetBlock { ) -> packed::Block; } +/// Trait for calculating the extra hash of a block. pub trait CalcExtraHash { + /// Calculates and returns the extra hash of the block as an `ExtraHashView`. fn calc_extra_hash(&self) -> ExtraHashView; } diff --git a/util/types/src/utilities/merkle_mountain_range.rs b/util/types/src/utilities/merkle_mountain_range.rs index 7085fd3b8ac..3c80b894fb1 100644 --- a/util/types/src/utilities/merkle_mountain_range.rs +++ b/util/types/src/utilities/merkle_mountain_range.rs @@ -58,7 +58,9 @@ impl core::HeaderView { } } +/// Trait for representing a header digest. pub trait HeaderDigest { + /// Verify the MMR header digest fn verify(&self) -> Result<(), String>; }