feat: add block issuer feature

sdk/src/types/block/error.rs

@@ -12,8 +12,9 @@ use primitive_types::U256;
 use crate::types::block::{
     input::UtxoInput,
     output::{
-        feature::FeatureCount, unlock_condition::UnlockConditionCount, AccountId, ChainId, MetadataFeatureLength,
-        NativeTokenCount, NftId, OutputIndex, StateMetadataLength, TagFeatureLength,
+        feature::block_issuer::PublicKeyCount, feature::FeatureCount, unlock_condition::UnlockConditionCount,
+        AccountId, ChainId, MetadataFeatureLength, NativeTokenCount, NftId, OutputIndex, StateMetadataLength,
+        TagFeatureLength,
     },
     payload::{InputCount, OutputCount, TagLength, TaggedDataLength},
     unlock::{UnlockCount, UnlockIndex},
@@ -65,6 +66,7 @@ pub enum Error {
     InvalidParentCount,
     InvalidPayloadKind(u32),
     InvalidPayloadLength { expected: usize, actual: usize },
+    InvalidPublicKeyCount(<PublicKeyCount as TryFrom<usize>>::Error),
     InvalidReferenceIndex(<UnlockIndex as TryFrom<u16>>::Error),
     InvalidSignature,
     InvalidSignatureKind(u8),
@@ -214,6 +216,7 @@ impl fmt::Display for Error {
                 write!(f, "invalid transaction native tokens count: {count}")
             }
             Self::InvalidUnlockCount(count) => write!(f, "invalid unlock count: {count}"),
+            Self::InvalidPublicKeyCount(count) => write!(f, "invalid public key count: {count}"),
             Self::InvalidUnlockKind(k) => write!(f, "invalid unlock kind: {k}"),
             Self::InvalidUnlockReference(index) => {
                 write!(f, "invalid unlock reference: {index}")

sdk/src/types/block/output/feature/block_issuer.rs

@@ -0,0 +1,113 @@
+// Copyright 2021 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use packable::{bounded::BoundedU8, prefix::BoxedSlicePrefix};
+
+use crate::types::block::{public_key::PublicKey, slot::SlotIndex, Error};
+
+pub type PublicKeyCount = BoundedU8<0, { u8::MAX }>;
+
+/// This feature defines the public keys with which a signature to burn Mana from
+/// the containing account's Block Issuance Credit can be verified.
+#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, packable::Packable)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[packable(unpack_error = Error)]
+pub struct BlockIssuerFeature {
+    /// The slot index at which the Block Issuer Feature expires and can be removed.
+    expiry_slot: SlotIndex,
+    /// The number of Block Issuer Keys.
+    keys_count: u8,
+    /// The Block Issuer Keys.
+    #[packable(unpack_error_with = |e| e.unwrap_item_err_or_else(|p| Error::InvalidPublicKeyCount(p.into())))]
+    keys: BoxedSlicePrefix<PublicKey, PublicKeyCount>,
+}
+
+impl BlockIssuerFeature {
+    /// The [`Feature`](crate::types::block::output::Feature) kind of an [`BlockIssuerFeature`].
+    pub const KIND: u8 = 4;
+
+    /// Creates a new [`BlockIssuerFeature`].
+    #[inline(always)]
+    pub fn new(expiry_slot: impl Into<SlotIndex>, keys: impl Into<Box<[PublicKey]>>) -> Result<Self, Error> {
+        let keys: Box<[PublicKey]> = keys.into();
+
+        Ok(Self {
+            expiry_slot: expiry_slot.into(),
+            keys_count: keys.len() as u8,
+            keys: keys.try_into().map_err(Error::InvalidPublicKeyCount)?,
+        })
+    }
+
+    /// Returns the Slot Index at which the Block Issuer Feature expires and can be removed.
+    pub fn expiry_slot(&self) -> SlotIndex {
+        self.expiry_slot
+    }
+
+    /// Returns the number of Block Issuer Keys.
+    pub fn keys_count(&self) -> u8 {
+        self.keys_count
+    }
+
+    /// Returns the Block Issuer Keys.
+    pub fn keys(&self) -> &[PublicKey] {
+        &self.keys
+    }
+}
+
+pub(crate) mod dto {
+    use crate::{
+        types::block::{
+            public_key::{dto::PublicKeyDto, PublicKey},
+            Error,
+        },
+        utils::serde::string,
+    };
+    use packable::bounded::TryIntoBoundedU8Error;
+    use serde::{Deserialize, Serialize};
+
+    use super::BlockIssuerFeature;
+
+    #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+    pub struct BlockIssuerFeatureDto {
+        #[serde(rename = "type")]
+        pub kind: u8,
+        #[serde(with = "string")]
+        pub expiry_slot: u64,
+        pub keys_count: u8,
+        #[serde(skip_serializing_if = "Vec::is_empty", default)]
+        pub keys: Vec<PublicKeyDto>,
+    }
+
+    impl From<&BlockIssuerFeature> for BlockIssuerFeatureDto {
+        fn from(value: &BlockIssuerFeature) -> Self {
+            Self {
+                kind: BlockIssuerFeature::KIND,
+                expiry_slot: value.expiry_slot.into(),
+                keys_count: value.keys_count,
+                keys: value.keys.iter().map(|key| key.into()).collect(),
+            }
+        }
+    }
+
+    impl TryFrom<BlockIssuerFeatureDto> for BlockIssuerFeature {
+        type Error = Error;
+
+        fn try_from(value: BlockIssuerFeatureDto) -> Result<Self, Self::Error> {
+            let keys = value
+                .keys
+                .into_iter()
+                .map(|key| PublicKey::try_from(key))
+                .collect::<Result<Vec<PublicKey>, Error>>()?;
+
+            if value.keys_count != keys.len() as u8 {
+                return Err(Error::InvalidPublicKeyCount(TryIntoBoundedU8Error::Invalid(
+                    value.keys_count,
+                )));
+            }
+
+            Self::new(value.expiry_slot, keys)
+        }
+    }
+
+    impl_serde_typed_dto!(BlockIssuerFeature, BlockIssuerFeatureDto, "block issuer feature");
+}

sdk/src/types/block/output/feature/mod.rs

@@ -1,6 +1,7 @@
 // Copyright 2021-2022 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+pub mod block_issuer;
 mod issuer;
 mod metadata;
 mod sender;
@@ -14,6 +15,7 @@ use derive_more::{Deref, From};
 use iterator_sorted::is_unique_sorted;
 use packable::{bounded::BoundedU8, prefix::BoxedSlicePrefix, Packable};
 
+use self::block_issuer::BlockIssuerFeature;
 pub use self::{
     issuer::IssuerFeature, metadata::MetadataFeature, sender::SenderFeature, staking::StakingFeature, tag::TagFeature,
 };
@@ -41,6 +43,9 @@ pub enum Feature {
     /// A staking feature.
     #[packable(tag = StakingFeature::KIND)]
     Staking(StakingFeature),
+    /// A block issuer feature.
+    #[packable(tag = BlockIssuerFeature::KIND)]
+    BlockIssuer(BlockIssuerFeature),
 }
 
 impl PartialOrd for Feature {
@@ -63,6 +68,7 @@ impl core::fmt::Debug for Feature {
             Self::Metadata(feature) => feature.fmt(f),
             Self::Tag(feature) => feature.fmt(f),
             Self::Staking(feature) => feature.fmt(f),
+            Self::BlockIssuer(feature) => feature.fmt(f),
         }
     }
 }
@@ -76,6 +82,7 @@ impl Feature {
             Self::Metadata(_) => MetadataFeature::KIND,
             Self::Tag(_) => TagFeature::KIND,
             Self::Staking(_) => StakingFeature::KIND,
+            Self::BlockIssuer(_) => BlockIssuerFeature::KIND,
         }
     }
 
@@ -87,6 +94,7 @@ impl Feature {
             Self::Metadata(_) => FeatureFlags::METADATA,
             Self::Tag(_) => FeatureFlags::TAG,
             Self::Staking(_) => FeatureFlags::STAKING,
+            Self::BlockIssuer(_) => FeatureFlags::BLOCK_ISSUER,
         }
     }
 
@@ -164,6 +172,21 @@ impl Feature {
             panic!("invalid downcast of non-StakingFeature");
         }
     }
+
+    /// Checks whether the feature is a [`BlockIssuerFeature`].
+    pub fn is_block_issuer(&self) -> bool {
+        matches!(self, Self::BlockIssuer(_))
+    }
+
+    /// Gets the feature as an actual [`BlockIssuerFeature`].
+    /// NOTE: Will panic if the feature is not a [`BlockIssuerFeature`].
+    pub fn as_block_issuer(&self) -> &BlockIssuerFeature {
+        if let Self::BlockIssuer(feature) = self {
+            feature
+        } else {
+            panic!("invalid downcast of non-BlockIssuerFeature");
+        }
+    }
 }
 
 create_bitflags!(
@@ -176,6 +199,7 @@ create_bitflags!(
         (METADATA, MetadataFeature),
         (TAG, TagFeature),
         (STAKING, StakingFeature),
+        (BLOCK_ISSUER, BlockIssuerFeature),
     ]
 );
 
@@ -274,6 +298,11 @@ impl Features {
     pub fn staking(&self) -> Option<&StakingFeature> {
         self.get(StakingFeature::KIND).map(Feature::as_staking)
     }
+
+    /// Gets a reference to a [`BlockIssuerFeature`], if any.
+    pub fn block_issuer(&self) -> Option<&BlockIssuerFeature> {
+        self.get(BlockIssuerFeature::KIND).map(Feature::as_block_issuer)
+    }
 }
 
 #[inline]
@@ -311,7 +340,8 @@ mod test {
                 FeatureFlags::ISSUER,
                 FeatureFlags::METADATA,
                 FeatureFlags::TAG,
-                FeatureFlags::STAKING
+                FeatureFlags::STAKING,
+                FeatureFlags::BLOCK_ISSUER
             ]
         );
     }

sdk/src/types/block/public_key/mod.rs

@@ -9,6 +9,7 @@ pub use self::ed25519::Ed25519PublicKey;
 use crate::types::block::Error;
 
 #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, From, packable::Packable)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[packable(unpack_error = Error)]
 #[packable(tag_type = u8, with_error = Error::InvalidPublicKeyKind)]
 pub enum PublicKey {

sdk/src/types/block/rand/mod.rs

@@ -21,6 +21,8 @@ pub mod output;
 pub mod parents;
 /// Module providing random payload generation utilities.
 pub mod payload;
+/// Module providing random public key generation utilities.
+pub mod public_key;
 /// Module providing random signature generation utilities.
 pub mod signature;
 /// Module providing random slot generation utilities.

sdk/src/types/block/rand/output/feature.rs

@@ -5,12 +5,14 @@ use alloc::vec::Vec;
 
 use crate::types::block::{
     output::feature::{
-        Feature, FeatureFlags, IssuerFeature, MetadataFeature, SenderFeature, StakingFeature, TagFeature,
+        block_issuer::BlockIssuerFeature, Feature, FeatureFlags, IssuerFeature, MetadataFeature, SenderFeature,
+        StakingFeature, TagFeature,
     },
     rand::{
         address::rand_address,
         bytes::rand_bytes,
         number::{rand_number, rand_number_range},
+        public_key::rand_public_key,
     },
 };
 
@@ -41,13 +43,19 @@ pub fn rand_staking_feature() -> StakingFeature {
     StakingFeature::new(rand_number(), rand_number(), rand_number(), rand_number())
 }
 
+/// Generates a random [`BlockIssuerFeature`].
+pub fn rand_block_issuer_feature() -> BlockIssuerFeature {
+    BlockIssuerFeature::new(rand_number::<u64>(), vec![rand_public_key()]).unwrap()
+}
+
 fn rand_feature_from_flag(flag: &FeatureFlags) -> Feature {
     match *flag {
         FeatureFlags::SENDER => Feature::Sender(rand_sender_feature()),
         FeatureFlags::ISSUER => Feature::Issuer(rand_issuer_feature()),
         FeatureFlags::METADATA => Feature::Metadata(rand_metadata_feature()),
         FeatureFlags::TAG => Feature::Tag(rand_tag_feature()),
         FeatureFlags::STAKING => Feature::Staking(rand_staking_feature()),
+        FeatureFlags::BLOCK_ISSUER => Feature::BlockIssuer(rand_block_issuer_feature()),
         _ => unreachable!(),
     }
 }

sdk/src/types/block/rand/public_key.rs

@@ -0,0 +1,15 @@
+// Copyright 2020-2021 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::types::block::public_key::{Ed25519PublicKey, PublicKey};
+
+/// Generates a valid random Ed25519 public key.
+pub fn rand_ed25519_public_key() -> Ed25519PublicKey {
+    let key = crypto::signatures::ed25519::SecretKey::generate().unwrap();
+    key.public_key().into()
+}
+
+/// Generates a valid random public key.
+pub fn rand_public_key() -> PublicKey {
+    rand_ed25519_public_key().into()
+}

sdk/src/types/block/slot/index.rs

@@ -6,7 +6,7 @@ use derive_more::{Deref, Display, From};
 /// Timeline is divided into slots, and each slot has a corresponding slot index.
 /// To calculate the slot index of a timestamp, `genesisTimestamp` and the duration of a slot are needed.
 /// The slot index of timestamp `ts` is `(ts - genesisTimestamp)/duration + 1`.
-#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, From, Deref, Display, packable::Packable)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, From, Deref, Display, PartialOrd, Ord, packable::Packable)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct SlotIndex(u64);
 
@@ -16,3 +16,9 @@ impl SlotIndex {
         Self::from(index)
     }
 }
+
+impl From<SlotIndex> for u64 {
+    fn from(slot_index: SlotIndex) -> Self {
+        *slot_index
+    }
+}