Merge branch 'feat/cardano-blockchain-types' into fix/rust-test-doc

Author: bkioshn

.github/workflows/semantic_pull_request.yml

@@ -26,6 +26,7 @@ jobs:
         rust/cbork
         rust/hermes-ipfs
         rust/rbac-registration
+        rust/cardano-blockchain-types
         dart
         docs
         general

docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl

@@ -8,20 +8,19 @@ block = [
 ]
 
 block-header = [
-    chain-id: ULID,
+    chain-id: UUID, ; UUID v7
     height: int,
     timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time
     prev-block-id: hash-bytes, ; hash of the previous block
-    ?ledger-type: UUID,
-    ?purpose-id: ULID / UUID,
+    ?ledger-type: UUID, ; UUID v4
+    ?purpose-id: UUID, ; UUID v7
     ?validator,
     ~metadata,
 ]
 
 block-data = encoded-cbor
 
 UUID = #6.37(bytes) ; UUID type
-ULID = #6.32780(bytes) ; ULID type
 
 kid = hash-bytes ; hash of the x509/c509 certificate
 

docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl

@@ -2,15 +2,14 @@
 ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06
 
 genesis-to-prev-hash = [
-    chain-id: ULID,
+    chain-id: UUID, ; UUID v7
     timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time
-    ledger-type: UUID,
-    purpose-id: ULID / UUID,
+    ledger-type: UUID, ; UUID v4
+    purpose-id: UUID, ; UUID v7
     validator,
 ]
 
 UUID = #6.37(bytes) ; UUID type
-ULID = #6.32780(bytes) ; ULID type
 
 validator = (kid / [2* kid])
 kid = hash-bytes ; hash of the x509/c509 certificate

rust/Earthfile

@@ -51,12 +51,12 @@ check:
 # build : Build crates.
 build:
     FROM +builder-src
-
+    RUN rm -rf ~/build/target/release
     DO rust-ci+EXECUTE \
         --cmd="/scripts/std_build.py" \
         --args1="--libs=c509-certificate --libs=cardano-blockchain-types --libs=cardano-chain-follower --libs=hermes-ipfs" \
         --args2="--libs=cbork-cddl-parser --libs=cbork-abnf-parser" \
-        --args3="--libs=catalyst-voting --libs=vote-tx-v1 --libs=vote-tx-v2" \
+        --args3="--libs=catalyst-voting --libs=immutable-ledger --libs=vote-tx-v1 --libs=vote-tx-v2" \
         --args4="--bins=cbork/cbork --libs=rbac-registration --libs=signed_doc" \
         --args5="--cov_report=$HOME/build/coverage-report.info" \
         --output="release/[^\./]+" \

rust/cardano-blockchain-types/deps.tmp

@@ -1,4 +1,3 @@
-
 rbac-registration = { version = "0.0.2", git = "https://github.com/input-output-hk/catalyst-libs.git", tag = "v0.0.8" }
 
 thiserror = "1.0.64"

rust/cardano-blockchain-types/src/auxdata/aux_data.rs

@@ -9,7 +9,7 @@ use super::{
     scripts::{MutableTransactionScriptsMap, ScriptArray, ScriptType, TransactionScripts},
 };
 
-/// Auxiliary Data (Metadata) for a single Transaction in a block
+/// Auxiliary Data (Metadata) for a single transaction in a block
 #[derive(Clone, Debug)]
 #[allow(clippy::module_name_repetitions)]
 pub struct TransactionAuxData {
@@ -58,7 +58,7 @@ impl TransactionAuxData {
         self.metadata.get(label)
     }
 
-    /// Decode a Shelley-MA Auxiliary Data Array
+    /// Decode a Shelley-MA auxiliary data array
     fn decode_shelley_ma_array(d: &mut minicbor::Decoder) -> Result<Self, minicbor::decode::Error> {
         match d.array() {
             Ok(Some(entries)) => {
@@ -158,9 +158,9 @@ impl TransactionAuxData {
 
             let script_array = ScriptArray::decode(d, &mut ctx)?;
             if scripts.insert(script_type, script_array).is_some() {
-                return Err(minicbor::decode::Error::message(
+                return Err(minicbor::decode::Error::message(format!(
                     "Multiple Alonzo+ Script entries of type {script_type} found. Invalid.",
-                ));
+                )));
             }
         }
 

rust/cardano-blockchain-types/src/auxdata/block.rs

@@ -9,7 +9,7 @@ use pallas::ledger::traverse::MultiEraBlock;
 use super::aux_data::TransactionAuxData;
 use crate::txn_index::TxnIndex;
 
-/// Auxiliary Data for every transaction within a block.
+/// Auxiliary data for every transaction within a block.
 #[derive(Debug)]
 #[allow(clippy::module_name_repetitions)]
 pub struct BlockAuxData(Arc<dashmap::ReadOnlyView<TxnIndex, TransactionAuxData>>);

rust/cardano-blockchain-types/src/auxdata/metadatum.rs

@@ -14,7 +14,7 @@ use crate::conversion::from_saturating;
 pub struct Metadata(Arc<MetadataInner>);
 
 #[derive(Clone, Debug)]
-/// Transaction Metadata - Inner
+/// Transaction Metadata - inner
 /// See: <https://github.com/IntersectMBO/cardano-ledger/blob/78b32d585fd4a0340fb2b184959fb0d46f32c8d2/eras/conway/impl/cddl-files/conway.cddl#L519>
 pub struct MetadataInner {
     /// Sequence the metadatum labels appear in the metadata.
@@ -88,8 +88,8 @@ impl Decode<'_, ()> for Metadata {
             sequence.push(label);
             let _unused = metadata.insert(label, value);
 
-            // Look for End Sentinel IF its an indefinite MAP
-            //   (which we know because entries is u64::MAX).
+            // Look for end sentinel IF its an indefinite MAP
+            // (which we know because entries is u64::MAX).
             if entries == u64::MAX {
                 match d.datatype() {
                     Ok(minicbor::data::Type::Break) => {

rust/cardano-blockchain-types/src/conversion.rs

@@ -2,7 +2,7 @@
 
 use anyhow::bail;
 
-/// Convert an `<T>` to `<R>`. (saturate if out of range.)
+/// Convert an `<T>` to `<R>` (saturate if out of range).
 /// Note can convert any int to float, or f32 to f64 as well.
 /// can not convert from float to int, or f64 to f32.
 pub(crate) fn from_saturating<

rust/cardano-blockchain-types/src/fork.rs

@@ -9,11 +9,11 @@
 use crate::conversion::from_saturating;
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd)]
-/// Counter that is incremented every time there is a roll-back in live-chain
+/// Counter that is incremented every time there is a roll-back in live-chain.
 pub struct Fork(u64);
 
 impl Fork {
-    /// Convert an `<T>` to Fork. (saturate if out of range.)
+    /// Convert an `<T>` to `Fork` (saturate if out of range).
     pub fn from_saturating<
         T: Copy
             + TryInto<u64>
@@ -29,12 +29,12 @@ impl Fork {
 
     /// Increment the fork count.
     pub fn incr(&mut self) {
-        self.0 += 1;
+        self.0 = self.0.saturating_add(1);
     }
 
     /// Decrement the fork count.
     pub fn decr(&mut self) {
-        self.0 -= 1;
+        self.0 = self.0.saturating_sub(1);
     }
 }
 

rust/cardano-blockchain-types/src/hashes.rs

@@ -8,16 +8,19 @@ use pallas_crypto::hash::Hash;
 
 /// Number of bytes in a blake2b 224 hash.
 pub const BLAKE_2B224_SIZE: usize = 224 / 8;
-/// `Blake2B` 224bit Hash
+
+/// `Blake2B` 224bit Hash.
 pub type Blake2b224Hash = Blake2bHash<BLAKE_2B224_SIZE>;
 
 /// Number of bytes in a blake2b 256 hash.
 pub const BLAKE_2B256_SIZE: usize = 256 / 8;
+
 /// `Blake2B` 256bit Hash
 pub type Blake2b256Hash = Blake2bHash<BLAKE_2B256_SIZE>;
 
 /// Number of bytes in a blake2b 128 hash.
 pub const BLAKE_2B128_SIZE: usize = 128 / 8;
+
 /// `Blake2B` 128bit Hash
 pub type Blake2b128Hash = Blake2bHash<BLAKE_2B128_SIZE>;
 
@@ -68,6 +71,7 @@ impl<const BYTES: usize> From<Blake2bHash<BYTES>> for Vec<u8> {
     }
 }
 
+/// Convert hash in a form of byte array into the `Blake2bHash` type.
 impl<const BYTES: usize> TryFrom<&[u8]> for Blake2bHash<BYTES> {
     type Error = anyhow::Error;
 
@@ -133,12 +137,8 @@ impl<'a, C, const BYTES: usize> minicbor::Decode<'a, C> for Blake2bHash<BYTES> {
         d: &mut minicbor::Decoder<'a>, _ctx: &mut C,
     ) -> Result<Self, minicbor::decode::Error> {
         let bytes = d.bytes()?;
-        if bytes.len() == BYTES {
-            let mut hash = [0; BYTES];
-            hash.copy_from_slice(bytes);
-            Ok(hash.into())
-        } else {
-            Err(minicbor::decode::Error::message("Invalid hash size"))
-        }
+        bytes.try_into().map_err(|_| {
+            minicbor::decode::Error::message("Invalid hash size for Blake2bHash cbor decode")
+        })
     }
 }

rust/cardano-blockchain-types/src/multi_era_block_data.rs

@@ -45,9 +45,8 @@ struct SelfReferencedMultiEraBlock {
 /// Multi-era block - inner.
 #[derive(Debug)]
 struct MultiEraBlockInner {
-    /// What blockchain was the block produced on.
-    //#[allow(dead_code)]
-    pub chain: Network,
+    /// What blockchain network was the block produced on.
+    network: Network,
     /// The Point on the blockchain this block can be found.
     point: Point,
     /// The previous point on the blockchain before this block.
@@ -93,7 +92,7 @@ impl MultiEraBlock {
     ///
     /// If the given bytes cannot be decoded as a multi-era block, an error is returned.
     fn new_block(
-        chain: Network, raw_data: Vec<u8>, previous: &Point, fork: Fork,
+        network: Network, raw_data: Vec<u8>, previous: &Point, fork: Fork,
     ) -> anyhow::Result<Self> {
         let builder = SelfReferencedMultiEraBlockTryBuilder {
             raw_data,
@@ -127,7 +126,7 @@ impl MultiEraBlock {
             // Special case, when the previous block is actually UNKNOWN, we can't check it.
             if !previous.is_unknown()
                     // Otherwise, we make sure the hash chain is intact
-                    && !previous.cmp_hash(&decoded_block.header().previous_hash())
+                    && previous != &decoded_block.header().previous_hash()
             {
                 debug!("{}, {:?}", previous, decoded_block.header().previous_hash());
 
@@ -140,7 +139,7 @@ impl MultiEraBlock {
         Ok(Self {
             fork,
             inner: Arc::new(MultiEraBlockInner {
-                chain,
+                network,
                 point,
                 previous: previous.clone(),
                 data: self_ref_block,
@@ -156,9 +155,9 @@ impl MultiEraBlock {
     ///
     /// If the given bytes cannot be decoded as a multi-era block, an error is returned.
     pub fn new(
-        chain: Network, raw_data: Vec<u8>, previous: &Point, fork: Fork,
+        network: Network, raw_data: Vec<u8>, previous: &Point, fork: Fork,
     ) -> anyhow::Result<Self> {
-        MultiEraBlock::new_block(chain, raw_data, previous, fork)
+        MultiEraBlock::new_block(network, raw_data, previous, fork)
     }
 
     /// Remake the block on a new fork.
@@ -169,6 +168,7 @@ impl MultiEraBlock {
     /// Decodes the data into a multi-era block.
     ///
     /// # Returns
+    ///
     /// The decoded block data, which can easily be processed by a consumer.
     #[must_use]
     #[allow(clippy::missing_panics_doc)]
@@ -179,6 +179,7 @@ impl MultiEraBlock {
     /// Decodes the data into a multi-era block.
     ///
     /// # Returns
+    ///
     /// The raw byte data of the block.
     #[must_use]
     #[allow(clippy::missing_panics_doc)]
@@ -189,6 +190,7 @@ impl MultiEraBlock {
     /// Returns the block point of this block.
     ///
     /// # Returns
+    ///
     /// The block point of this block.
     #[must_use]
     pub fn point(&self) -> Point {
@@ -198,6 +200,7 @@ impl MultiEraBlock {
     /// Returns the block point of the previous block.
     ///
     /// # Returns
+    ///
     /// The previous blocks `Point`
     #[must_use]
     pub fn previous(&self) -> Point {
@@ -210,9 +213,10 @@ impl MultiEraBlock {
     /// (Immutable Database) of the Node.
     ///
     /// # Returns
+    ///
     /// `true` if the block is immutable, `false` otherwise.
     #[must_use]
-    pub fn immutable(&self) -> bool {
+    pub fn is_immutable(&self) -> bool {
         self.fork == 0.into()
     }
 
@@ -225,28 +229,32 @@ impl MultiEraBlock {
     /// - 2+ - for each subsequent rollback detected while reading live blocks.
     ///
     /// # Returns
+    ///
     /// The fork the block was found on.
     #[must_use]
     pub fn fork(&self) -> Fork {
         self.fork
     }
 
-    /// What chain was the block from
+    /// What blockchain network was the block from
     ///
     /// # Returns
-    /// - The chain that this block originated on.
+    ///
+    /// - The network that this block originated on.
     #[must_use]
-    pub fn chain(&self) -> Network {
-        self.inner.chain
+    pub fn network(&self) -> Network {
+        self.inner.network
     }
 
     /// Get The Metadata fora a transaction and known label from the block
     ///
     /// # Parameters
+    ///
     /// - `txn_idx` - Index of the Transaction in the Block
     /// - `label` - The label of the transaction
     ///
     /// # Returns
+    ///
     /// - Metadata for the given label in the transaction.
     /// - Or None if the label requested isn't present.
     #[must_use]
@@ -262,7 +270,7 @@ impl MultiEraBlock {
         self.inner.witness_map.as_ref()
     }
 
-    /// If the Witness exists for a given transaction then return its public key.
+    /// If the witness exists for a given transaction then return its public key.
     #[must_use]
     pub fn witness_for_tx(&self, vkey_hash: &VKeyHash, tx_num: TxnIndex) -> Option<VerifyingKey> {
         if let Some(witnesses) = self.witness_map() {
@@ -286,7 +294,7 @@ impl Display for MultiEraBlock {
         let txns = block.tx_count();
         let aux_data = block.has_aux_data();
 
-        let fork = if self.immutable() {
+        let fork = if self.is_immutable() {
             "Immutable".to_string()
         } else {
             format!("Fork: {fork:?}")
@@ -461,6 +469,10 @@ pub(crate) mod tests {
             );
 
             assert!(block.is_err());
+            assert!(block
+                .unwrap_err()
+                .to_string()
+                .contains("Previous slot is not less than current slot"));
         }
 
         Ok(())