hotshot_types/

data.rs

// Copyright (c) 2021-2024 Espresso Systems (espressosys.com)
// This file is part of the HotShot repository.

// You should have received a copy of the MIT License
// along with the HotShot repository. If not, see <https://mit-license.org/>.

//! Provides types useful for representing `HotShot`'s data structures
//!
//! This module provides types for representing consensus internal state, such as leaves,
//! `HotShot`'s version of a block, and proposals, messages upon which to reach the consensus.

use std::{
    fmt::{Debug, Display},
    hash::Hash,
    marker::PhantomData,
    sync::Arc,
    time::Duration,
};

use async_lock::RwLock;
use bincode::Options;
use committable::{Commitment, CommitmentBoundsArkless, Committable, RawCommitmentBuilder};
use hotshot_utils::anytrace::*;
use jf_advz::VidScheme;
use rand::Rng;
use serde::{Deserialize, Serialize};
use tagged_base64::{TaggedBase64, Tb64Error};
use thiserror::Error;
use vbs::version::Version;
use vec1::Vec1;
use versions::{Upgrade, EPOCH_VERSION, VID2_UPGRADE_VERSION};

use crate::{
    drb::DrbResult,
    epoch_membership::EpochMembershipCoordinator,
    message::{convert_proposal, Proposal, UpgradeLock},
    simple_certificate::{
        LightClientStateUpdateCertificateV1, LightClientStateUpdateCertificateV2,
        NextEpochQuorumCertificate2, QuorumCertificate, QuorumCertificate2, TimeoutCertificate,
        TimeoutCertificate2, UpgradeCertificate, ViewSyncFinalizeCertificate,
        ViewSyncFinalizeCertificate2,
    },
    simple_vote::{HasEpoch, QuorumData, QuorumData2, UpgradeProposalData, VersionedVoteData},
    traits::{
        block_contents::{BlockHeader, BuilderFee, EncodeBytes, TestableBlock},
        node_implementation::NodeType,
        signature_key::SignatureKey,
        states::TestableState,
        BlockPayload,
    },
    utils::{
        bincode_opts, genesis_epoch_from_version, option_epoch_from_block_number,
        EpochTransitionIndicator,
    },
    vid::{
        advz::{advz_scheme, ADVZScheme},
        avidm::{init_avidm_param, AvidMScheme},
        avidm_gf2::{init_avidm_gf2_param, AvidmGf2Scheme},
    },
    vote::{Certificate, HasViewNumber},
};

/// Implements `Display`, `Add`, `AddAssign`, `Deref` and `Sub`
/// for the given thing wrapper type around u64.
macro_rules! impl_u64_wrapper {
    ($t:ty, $genesis_val:expr) => {
        impl $t {
            /// Create a genesis number
            pub fn genesis() -> Self {
                Self($genesis_val)
            }
            /// Create a new number with the given value.
            pub fn new(n: u64) -> Self {
                Self(n)
            }
            /// Return the u64 format
            pub fn u64(&self) -> u64 {
                self.0
            }
        }

        impl From<u64> for $t {
            fn from(n: u64) -> Self {
                Self(n)
            }
        }

        impl From<$t> for u64 {
            fn from(n: $t) -> Self {
                n.0
            }
        }

        impl Display for $t {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                write!(f, "{}", self.0)
            }
        }

        impl std::ops::Add<u64> for $t {
            type Output = $t;

            fn add(self, rhs: u64) -> Self::Output {
                Self(self.0 + rhs)
            }
        }

        impl std::ops::AddAssign<u64> for $t {
            fn add_assign(&mut self, rhs: u64) {
                self.0 += rhs;
            }
        }

        impl std::ops::Deref for $t {
            type Target = u64;

            fn deref(&self) -> &Self::Target {
                &self.0
            }
        }

        impl std::ops::Sub<u64> for $t {
            type Output = $t;
            fn sub(self, rhs: u64) -> Self::Output {
                Self(self.0 - rhs)
            }
        }
    };
}

/// Type-safe wrapper around `u64` so we know the thing we're talking about is a view number.
#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub struct ViewNumber(u64);

impl Committable for ViewNumber {
    fn commit(&self) -> Commitment<Self> {
        let builder = RawCommitmentBuilder::new("View Number Commitment");
        builder.u64(self.0).finalize()
    }
}

impl_u64_wrapper!(ViewNumber, 0u64);

/// Type-safe wrapper around `u64` so we know the thing we're talking about is a epoch number.
#[derive(
    Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
pub struct EpochNumber(u64);

impl Committable for EpochNumber {
    fn commit(&self) -> Commitment<Self> {
        let builder = RawCommitmentBuilder::new("Epoch Number Commitment");
        builder.u64(self.0).finalize()
    }
}

impl_u64_wrapper!(EpochNumber, 1u64);

/// A proposal to start providing data availability for a block.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound = "TYPES: NodeType")]
pub struct DaProposal<TYPES: NodeType> {
    /// Encoded transactions in the block to be applied.
    pub encoded_transactions: Arc<[u8]>,
    /// Metadata of the block to be applied.
    pub metadata: <TYPES::BlockPayload as BlockPayload<TYPES>>::Metadata,
    /// View this proposal applies to
    pub view_number: ViewNumber,
}

/// A proposal to start providing data availability for a block.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound = "TYPES: NodeType")]
pub struct DaProposal2<TYPES: NodeType> {
    /// Encoded transactions in the block to be applied.
    pub encoded_transactions: Arc<[u8]>,
    /// Metadata of the block to be applied.
    pub metadata: <TYPES::BlockPayload as BlockPayload<TYPES>>::Metadata,
    /// View this proposal applies to
    pub view_number: ViewNumber,
    /// Epoch this proposal applies to
    pub epoch: Option<EpochNumber>,
    /// Indicates whether we are in epoch transition
    /// In epoch transition the next epoch payload commit should be calculated additionally
    pub epoch_transition_indicator: EpochTransitionIndicator,
}

impl<TYPES: NodeType> From<DaProposal<TYPES>> for DaProposal2<TYPES> {
    fn from(da_proposal: DaProposal<TYPES>) -> Self {
        Self {
            encoded_transactions: da_proposal.encoded_transactions,
            metadata: da_proposal.metadata,
            view_number: da_proposal.view_number,
            epoch: None,
            epoch_transition_indicator: EpochTransitionIndicator::NotInTransition,
        }
    }
}

impl<TYPES: NodeType> From<DaProposal2<TYPES>> for DaProposal<TYPES> {
    fn from(da_proposal2: DaProposal2<TYPES>) -> Self {
        Self {
            encoded_transactions: da_proposal2.encoded_transactions,
            metadata: da_proposal2.metadata,
            view_number: da_proposal2.view_number,
        }
    }
}

/// A proposal to upgrade the network
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
pub struct UpgradeProposal {
    /// The information about which version we are upgrading to.
    pub upgrade_proposal: UpgradeProposalData,
    /// View this proposal applies to
    pub view_number: ViewNumber,
}

/// Type aliases for different versions of VID commitments
pub type VidCommitment0 = crate::vid::advz::ADVZCommitment;
pub type VidCommitment1 = crate::vid::avidm::AvidMCommitment;
pub type VidCommitment2 = crate::vid::avidm_gf2::AvidmGf2Commitment;

/// VID Commitment type
#[derive(Clone, Copy, Eq, PartialEq, Hash, Serialize, Deserialize, Ord, PartialOrd)]
#[serde(
    try_from = "tagged_base64::TaggedBase64",
    into = "tagged_base64::TaggedBase64"
)]
pub enum VidCommitment {
    V0(VidCommitment0),
    V1(VidCommitment1),
    V2(VidCommitment2),
}

impl Default for VidCommitment {
    fn default() -> Self {
        Self::V0(Default::default())
    }
}

impl Display for VidCommitment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        std::write!(f, "{}", TaggedBase64::from(self))
    }
}

impl Debug for VidCommitment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        std::fmt::Display::fmt(self, f)
    }
}

impl From<VidCommitment> for TaggedBase64 {
    fn from(val: VidCommitment) -> Self {
        match val {
            VidCommitment::V0(comm) => comm.into(),
            VidCommitment::V1(comm) => comm.into(),
            VidCommitment::V2(comm) => comm.into(),
        }
    }
}

impl From<&VidCommitment> for TaggedBase64 {
    fn from(val: &VidCommitment) -> Self {
        match val {
            VidCommitment::V0(comm) => comm.into(),
            VidCommitment::V1(comm) => comm.into(),
            VidCommitment::V2(comm) => comm.into(),
        }
    }
}

impl TryFrom<TaggedBase64> for VidCommitment {
    type Error = tagged_base64::Tb64Error;

    fn try_from(value: TaggedBase64) -> std::result::Result<Self, Self::Error> {
        match value.tag().as_str() {
            "HASH" => VidCommitment0::try_from(value).map(Self::V0),
            "AvidMCommit" => VidCommitment1::try_from(value).map(Self::V1),
            "AvidmGf2Commit" => VidCommitment2::try_from(value).map(Self::V2),
            _ => Err(Tb64Error::InvalidTag),
        }
    }
}

impl<'a> TryFrom<&'a TaggedBase64> for VidCommitment {
    type Error = tagged_base64::Tb64Error;

    fn try_from(value: &'a TaggedBase64) -> std::result::Result<Self, Self::Error> {
        match value.tag().as_str() {
            "HASH" => VidCommitment0::try_from(value).map(Self::V0),
            "AvidMCommit" => VidCommitment1::try_from(value).map(Self::V1),
            "AvidmGf2Commit" => VidCommitment2::try_from(value).map(Self::V2),
            _ => Err(Tb64Error::InvalidTag),
        }
    }
}

impl std::str::FromStr for VidCommitment {
    type Err = tagged_base64::Tb64Error;
    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        use core::convert::TryFrom;
        Self::try_from(TaggedBase64::from_str(s)?)
            .map_err(|_| tagged_base64::Tb64Error::InvalidData)
    }
}

// TODO(Chengyu): cannot have this because of `impl<H> From<Output<H>> for HasherNode<H>`.
// impl From<VidCommitment1> for VidCommitment {
//     fn from(comm: VidCommitment1) -> Self {
//         Self::V1(comm)
//     }
// }

impl From<VidCommitment1> for VidCommitment {
    fn from(comm: VidCommitment1) -> Self {
        Self::V1(comm)
    }
}

impl From<VidCommitment2> for VidCommitment {
    fn from(comm: VidCommitment2) -> Self {
        Self::V2(comm)
    }
}

impl AsRef<[u8]> for VidCommitment {
    fn as_ref(&self) -> &[u8] {
        match self {
            Self::V0(comm) => comm.as_ref(),
            Self::V1(comm) => comm.as_ref(),
            Self::V2(comm) => comm.as_ref(),
        }
    }
}

impl AsRef<[u8; 32]> for VidCommitment {
    fn as_ref(&self) -> &[u8; 32] {
        match self {
            Self::V0(comm) => comm.as_ref().as_ref(),
            Self::V1(comm) => comm.as_ref(),
            Self::V2(comm) => comm.as_ref(),
        }
    }
}

/// Compute the VID payload commitment.
/// TODO(Gus) delete this function?
/// # Panics
/// If the VID computation fails.
#[must_use]
#[allow(clippy::panic)]
pub fn vid_commitment(
    encoded_transactions: &[u8],
    metadata: &[u8],
    total_weight: usize,
    version: Version,
) -> VidCommitment {
    if version < EPOCH_VERSION {
        let encoded_tx_len = encoded_transactions.len();
        advz_scheme(total_weight)
            .commit_only(encoded_transactions)
            .map(VidCommitment::V0)
            .unwrap_or_else(|err| {
                panic!(
                    "VidScheme::commit_only \
                     failure:(total_weight,payload_byte_len)=({total_weight},{encoded_tx_len}) \
                     error: {err}"
                )
            })
    } else if version < VID2_UPGRADE_VERSION {
        let param = init_avidm_param(total_weight).unwrap();
        let encoded_tx_len = encoded_transactions.len();
        AvidMScheme::commit(
            &param,
            encoded_transactions,
            ns_table::parse_ns_table(encoded_tx_len, metadata),
        )
        .map(VidCommitment::V1)
        .unwrap()
    } else {
        let param = init_avidm_gf2_param(total_weight).unwrap();
        let encoded_tx_len = encoded_transactions.len();
        AvidmGf2Scheme::commit(
            &param,
            encoded_transactions,
            ns_table::parse_ns_table(encoded_tx_len, metadata),
        )
        .map(|(comm, _)| VidCommitment::V2(comm))
        .unwrap()
    }
}

/// Type aliases for different versions of VID commons
pub type VidCommon0 = crate::vid::advz::ADVZCommon;
pub type VidCommon1 = crate::vid::avidm::AvidMCommon;
pub type VidCommon2 = crate::vid::avidm_gf2::AvidmGf2Common;

/// VID Common type to be shared among parties.
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub enum VidCommon {
    V0(VidCommon0),
    V1(VidCommon1),
    V2(VidCommon2),
}

impl From<VidCommon1> for VidCommon {
    fn from(comm: VidCommon1) -> Self {
        Self::V1(comm)
    }
}

impl From<VidCommon2> for VidCommon {
    fn from(comm: VidCommon2) -> Self {
        Self::V2(comm)
    }
}

/// Borrowed view of [`VidCommon`] that avoids cloning large common data.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VidCommonRef<'a> {
    V0(&'a VidCommon0),
    V1(&'a VidCommon1),
    V2(&'a VidCommon2),
}

impl<'a> VidCommonRef<'a> {
    pub fn is_consistent(&self, comm: &VidCommitment) -> bool {
        match (self, comm) {
            (Self::V0(common), VidCommitment::V0(comm)) => {
                ADVZScheme::is_consistent(comm, common).is_ok()
            },
            (Self::V1(_), VidCommitment::V1(_)) => true,
            (Self::V2(common), VidCommitment::V2(comm)) => {
                AvidmGf2Scheme::is_consistent(comm, common)
            },
            _ => false,
        }
    }
}

impl VidCommon {
    pub fn as_ref(&self) -> VidCommonRef<'_> {
        match self {
            Self::V0(c) => VidCommonRef::V0(c),
            Self::V1(c) => VidCommonRef::V1(c),
            Self::V2(c) => VidCommonRef::V2(c),
        }
    }

    pub fn is_consistent(&self, comm: &VidCommitment) -> bool {
        self.as_ref().is_consistent(comm)
    }
}

/// Type aliases for different versions of VID shares
pub type VidShare0 = crate::vid::advz::ADVZShare;
pub type VidShare1 = crate::vid::avidm::AvidMShare;
pub type VidShare2 = crate::vid::avidm_gf2::AvidmGf2Share;

/// VID share type
#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)]
pub enum VidShare {
    V0(VidShare0),
    V1(VidShare1),
    V2(VidShare2),
}

// TODO(Chengyu): cannot have this
// impl From<VidShare0> for VidShare {
//     fn from(share: VidShare0) -> Self {
//         Self::V0(share)
//     }
// }

impl From<VidShare1> for VidShare {
    fn from(share: VidShare1) -> Self {
        Self::V1(share)
    }
}

impl From<VidShare2> for VidShare {
    fn from(share: VidShare2) -> Self {
        Self::V2(share)
    }
}

pub mod ns_table;
pub mod vid_disperse;

/// A helper struct to hold the disperse data and the time it took to calculate the disperse
pub struct VidDisperseAndDuration<TYPES: NodeType> {
    /// The disperse data
    pub disperse: VidDisperse<TYPES>,
    /// The time it took to calculate the disperse
    pub duration: Duration,
}

/// Type aliases for different versions of VID disperse
pub type VidDisperse0<TYPES> = vid_disperse::ADVZDisperse<TYPES>;
pub type VidDisperse1<TYPES> = vid_disperse::AvidMDisperse<TYPES>;
pub type VidDisperse2<TYPES> = vid_disperse::AvidmGf2Disperse<TYPES>;

/// VID dispersal data
///
/// Like [`DaProposal`].
///
/// TODO move to vid.rs?
#[derive(Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound = "TYPES: NodeType")]
pub enum VidDisperse<TYPES: NodeType> {
    /// Disperse type for first VID version
    V0(VidDisperse0<TYPES>),
    /// Disperse type for AvidM Scheme
    V1(VidDisperse1<TYPES>),
    /// Disperse type for AvidmGf2 Scheme
    V2(VidDisperse2<TYPES>),
}

impl<TYPES: NodeType> From<VidDisperse0<TYPES>> for VidDisperse<TYPES> {
    fn from(disperse: VidDisperse0<TYPES>) -> Self {
        Self::V0(disperse)
    }
}

impl<TYPES: NodeType> From<VidDisperse1<TYPES>> for VidDisperse<TYPES> {
    fn from(disperse: VidDisperse1<TYPES>) -> Self {
        Self::V1(disperse)
    }
}

impl<TYPES: NodeType> From<VidDisperse2<TYPES>> for VidDisperse<TYPES> {
    fn from(disperse: VidDisperse2<TYPES>) -> Self {
        Self::V2(disperse)
    }
}

impl<TYPES: NodeType> HasViewNumber for VidDisperse<TYPES> {
    fn view_number(&self) -> ViewNumber {
        match self {
            Self::V0(disperse) => disperse.view_number(),
            Self::V1(disperse) => disperse.view_number(),
            Self::V2(disperse) => disperse.view_number(),
        }
    }
}

impl<TYPES: NodeType> HasEpoch for VidDisperse<TYPES> {
    fn epoch(&self) -> Option<EpochNumber> {
        match self {
            Self::V0(disperse) => disperse.epoch(),
            Self::V1(disperse) => disperse.epoch(),
            Self::V2(disperse) => disperse.epoch(),
        }
    }
}

impl<TYPES: NodeType> VidDisperse<TYPES> {
    /// Calculate the vid disperse information from the payload given a view, epoch and membership,
    /// If the sender epoch is missing, it means it's the same as the target epoch.
    ///
    /// # Errors
    /// Returns an error if the disperse or commitment calculation fails
    #[allow(clippy::panic)]
    pub async fn calculate_vid_disperse(
        payload: &TYPES::BlockPayload,
        membership: &EpochMembershipCoordinator<TYPES>,
        view: ViewNumber,
        target_epoch: Option<EpochNumber>,
        data_epoch: Option<EpochNumber>,
        metadata: &<TYPES::BlockPayload as BlockPayload<TYPES>>::Metadata,
        upgrade_lock: &UpgradeLock<TYPES>,
    ) -> Result<VidDisperseAndDuration<TYPES>> {
        let epochs_enabled = upgrade_lock.epochs_enabled(view).await;
        let upgraded_vid2 = upgrade_lock.upgraded_vid2(view).await;
        if upgraded_vid2 {
            VidDisperse2::calculate_vid_disperse(
                payload,
                membership,
                view,
                target_epoch,
                data_epoch,
                metadata,
            )
            .await
            .map(|(disperse, duration)| VidDisperseAndDuration {
                disperse: Self::V2(disperse),
                duration,
            })
        } else if epochs_enabled {
            VidDisperse1::calculate_vid_disperse(
                payload,
                membership,
                view,
                target_epoch,
                data_epoch,
                metadata,
            )
            .await
            .map(|(disperse, duration)| VidDisperseAndDuration {
                disperse: Self::V1(disperse),
                duration,
            })
        } else {
            VidDisperse0::calculate_vid_disperse(
                payload,
                membership,
                view,
                target_epoch,
                data_epoch,
            )
            .await
            .map(|(disperse, duration)| VidDisperseAndDuration {
                disperse: Self::V0(disperse),
                duration,
            })
        }
    }

    /// Return the internal payload commitment
    pub fn payload_commitment(&self) -> VidCommitment {
        match self {
            Self::V0(disperse) => VidCommitment::V0(disperse.payload_commitment),
            Self::V1(disperse) => disperse.payload_commitment.into(),
            Self::V2(disperse) => disperse.payload_commitment.into(),
        }
    }

    /// Return a slice reference to the payload commitment. Should be used for signature.
    pub fn payload_commitment_ref(&self) -> &[u8] {
        match self {
            Self::V0(disperse) => disperse.payload_commitment.as_ref(),
            Self::V1(disperse) => disperse.payload_commitment.as_ref(),
            Self::V2(disperse) => disperse.payload_commitment.as_ref(),
        }
    }

    /// Set the view number
    pub fn set_view_number(&mut self, view_number: ViewNumber) {
        match self {
            Self::V0(share) => share.view_number = view_number,
            Self::V1(share) => share.view_number = view_number,
            Self::V2(share) => share.view_number = view_number,
        }
    }

    pub fn to_shares(self) -> Vec<VidDisperseShare<TYPES>> {
        match self {
            VidDisperse::V0(disperse) => disperse
                .to_shares()
                .into_iter()
                .map(|share| VidDisperseShare::V0(share))
                .collect(),
            VidDisperse::V1(disperse) => disperse
                .to_shares()
                .into_iter()
                .map(|share| VidDisperseShare::V1(share))
                .collect(),
            VidDisperse::V2(disperse) => disperse
                .to_shares()
                .into_iter()
                .map(|share| VidDisperseShare::V2(share))
                .collect(),
        }
    }

    /// Split a VID share proposal into a proposal for each recipient.
    pub fn to_share_proposals(
        proposal: Proposal<TYPES, Self>,
    ) -> Vec<Proposal<TYPES, VidDisperseShare<TYPES>>> {
        match proposal.data {
            VidDisperse::V0(disperse) => disperse
                .to_share_proposals(&proposal.signature)
                .into_iter()
                .map(|proposal| convert_proposal(proposal))
                .collect(),
            VidDisperse::V1(disperse) => disperse
                .to_share_proposals(&proposal.signature)
                .into_iter()
                .map(|proposal| convert_proposal(proposal))
                .collect(),
            VidDisperse::V2(disperse) => disperse
                .to_share_proposals(&proposal.signature)
                .into_iter()
                .map(|proposal| convert_proposal(proposal))
                .collect(),
        }
    }
}

/// Type aliases for different versions of VID disperse shares
pub type VidDisperseShare0<TYPES> = vid_disperse::ADVZDisperseShare<TYPES>;
pub type VidDisperseShare1<TYPES> = vid_disperse::AvidMDisperseShare<TYPES>;
pub type VidDisperseShare2<TYPES> = vid_disperse::AvidmGf2DisperseShare<TYPES>;

/// VID share and associated metadata for a single node
#[derive(Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound = "TYPES: NodeType")]
pub enum VidDisperseShare<TYPES: NodeType> {
    /// VID disperse share type for first version VID
    V0(VidDisperseShare0<TYPES>),
    /// VID disperse share type after epoch upgrade and VID upgrade
    V1(VidDisperseShare1<TYPES>),
    /// VID disperse share type for AvidmGf2 Scheme
    V2(VidDisperseShare2<TYPES>),
}

impl<TYPES: NodeType> From<VidDisperseShare0<TYPES>> for VidDisperseShare<TYPES> {
    fn from(share: VidDisperseShare0<TYPES>) -> Self {
        Self::V0(share)
    }
}

impl<TYPES: NodeType> From<VidDisperseShare1<TYPES>> for VidDisperseShare<TYPES> {
    fn from(share: VidDisperseShare1<TYPES>) -> Self {
        Self::V1(share)
    }
}

impl<TYPES: NodeType> From<VidDisperseShare2<TYPES>> for VidDisperseShare<TYPES> {
    fn from(share: VidDisperseShare2<TYPES>) -> Self {
        Self::V2(share)
    }
}

impl<TYPES: NodeType> VidDisperseShare<TYPES> {
    /// Consume `self` and return a `Proposal`
    pub fn to_proposal(
        self,
        private_key: &<TYPES::SignatureKey as SignatureKey>::PrivateKey,
    ) -> Option<Proposal<TYPES, Self>> {
        let payload_commitment_ref: &[u8] = match &self {
            Self::V0(share) => share.payload_commitment.as_ref(),
            Self::V1(share) => share.payload_commitment.as_ref(),
            Self::V2(share) => share.payload_commitment.as_ref(),
        };
        let Ok(signature) = TYPES::SignatureKey::sign(private_key, payload_commitment_ref) else {
            tracing::error!("VID: failed to sign dispersal share payload");
            return None;
        };
        Some(Proposal {
            signature,
            _pd: PhantomData,
            data: self,
        })
    }

    /// Return the internal `recipient_key`
    pub fn recipient_key(&self) -> &TYPES::SignatureKey {
        match self {
            Self::V0(share) => &share.recipient_key,
            Self::V1(share) => &share.recipient_key,
            Self::V2(share) => &share.recipient_key,
        }
    }

    /// Return the payload length in bytes.
    pub fn payload_byte_len(&self) -> u32 {
        match self {
            Self::V0(share) => share.payload_byte_len(),
            Self::V1(share) => share.payload_byte_len(),
            Self::V2(share) => share.payload_byte_len(),
        }
    }

    /// Return a reference to the internal payload VID commitment
    pub fn payload_commitment_ref(&self) -> &[u8] {
        match self {
            Self::V0(share) => share.payload_commitment.as_ref(),
            Self::V1(share) => share.payload_commitment.as_ref(),
            Self::V2(share) => share.payload_commitment.as_ref(),
        }
    }

    /// Return the internal payload VID commitment
    pub fn payload_commitment(&self) -> VidCommitment {
        match self {
            Self::V0(share) => VidCommitment::V0(share.payload_commitment),
            Self::V1(share) => share.payload_commitment.into(),
            Self::V2(share) => share.payload_commitment.into(),
        }
    }

    /// Return the target epoch
    pub fn target_epoch(&self) -> Option<EpochNumber> {
        match self {
            Self::V0(_) => None,
            Self::V1(share) => share.target_epoch,
            Self::V2(share) => share.target_epoch,
        }
    }

    /// Return a borrowed view of the VID common data.
    pub fn common(&self) -> VidCommonRef<'_> {
        match self {
            Self::V0(share) => VidCommonRef::V0(&share.common),
            Self::V1(share) => VidCommonRef::V1(&share.common),
            Self::V2(share) => VidCommonRef::V2(&share.common),
        }
    }

    /// Check if vid common is consistent with the commitment.
    pub fn is_consistent(&self) -> bool {
        match self {
            Self::V0(share) => share.is_consistent(),
            Self::V1(share) => share.is_consistent(),
            Self::V2(share) => share.is_consistent(),
        }
    }

    /// Verify share assuming common data is already verified consistent.
    /// Caller MUST call `is_consistent()` first.
    pub fn verify_with_verified_common(&self) -> bool {
        match self {
            Self::V0(share) => share.verify_with_verified_common(),
            Self::V1(share) => share.verify_with_verified_common(),
            Self::V2(share) => share.verify_with_verified_common(),
        }
    }

    /// Internally verify the share given necessary information
    pub fn verify(&self, total_nodes: usize) -> bool {
        match self {
            Self::V0(share) => share.verify(total_nodes),
            Self::V1(share) => share.verify(total_nodes),
            Self::V2(share) => share.verify(total_nodes),
        }
    }

    /// Set the view number
    pub fn set_view_number(&mut self, view_number: ViewNumber) {
        match self {
            Self::V0(share) => share.view_number = view_number,
            Self::V1(share) => share.view_number = view_number,
            Self::V2(share) => share.view_number = view_number,
        }
    }
}

impl<TYPES: NodeType> HasViewNumber for VidDisperseShare<TYPES> {
    fn view_number(&self) -> ViewNumber {
        match self {
            Self::V0(disperse) => disperse.view_number(),
            Self::V1(disperse) => disperse.view_number(),
            Self::V2(disperse) => disperse.view_number(),
        }
    }
}

impl<TYPES: NodeType> HasEpoch for VidDisperseShare<TYPES> {
    fn epoch(&self) -> Option<EpochNumber> {
        match self {
            Self::V0(_) => None,
            Self::V1(share) => share.epoch(),
            Self::V2(share) => share.epoch(),
        }
    }
}

/// Helper type to encapsulate the various ways that proposal certificates can be captured and
/// stored.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub enum ViewChangeEvidence<TYPES: NodeType> {
    /// Holds a timeout certificate.
    Timeout(TimeoutCertificate<TYPES>),
    /// Holds a view sync finalized certificate.
    ViewSync(ViewSyncFinalizeCertificate<TYPES>),
}

impl<TYPES: NodeType> ViewChangeEvidence<TYPES> {
    /// Check that the given ViewChangeEvidence is relevant to the current view.
    pub fn is_valid_for_view(&self, view: &ViewNumber) -> bool {
        match self {
            ViewChangeEvidence::Timeout(timeout_cert) => timeout_cert.data().view == *view - 1,
            ViewChangeEvidence::ViewSync(view_sync_cert) => view_sync_cert.view_number == *view,
        }
    }

    /// Convert to ViewChangeEvidence2
    pub fn to_evidence2(self) -> ViewChangeEvidence2<TYPES> {
        match self {
            ViewChangeEvidence::Timeout(timeout_cert) => {
                ViewChangeEvidence2::Timeout(timeout_cert.to_tc2())
            },
            ViewChangeEvidence::ViewSync(view_sync_cert) => {
                ViewChangeEvidence2::ViewSync(view_sync_cert.to_vsc2())
            },
        }
    }
}

/// Helper type to encapsulate the various ways that proposal certificates can be captured and
/// stored.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub enum ViewChangeEvidence2<TYPES: NodeType> {
    /// Holds a timeout certificate.
    Timeout(TimeoutCertificate2<TYPES>),
    /// Holds a view sync finalized certificate.
    ViewSync(ViewSyncFinalizeCertificate2<TYPES>),
}

impl<TYPES: NodeType> ViewChangeEvidence2<TYPES> {
    /// Check that the given ViewChangeEvidence2 is relevant to the current view.
    pub fn is_valid_for_view(&self, view: &ViewNumber) -> bool {
        match self {
            ViewChangeEvidence2::Timeout(timeout_cert) => timeout_cert.data().view == *view - 1,
            ViewChangeEvidence2::ViewSync(view_sync_cert) => view_sync_cert.view_number == *view,
        }
    }

    /// Convert to ViewChangeEvidence
    pub fn to_evidence(self) -> ViewChangeEvidence<TYPES> {
        match self {
            ViewChangeEvidence2::Timeout(timeout_cert) => {
                ViewChangeEvidence::Timeout(timeout_cert.to_tc())
            },
            ViewChangeEvidence2::ViewSync(view_sync_cert) => {
                ViewChangeEvidence::ViewSync(view_sync_cert.to_vsc())
            },
        }
    }
}

/// Proposal to append a block.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub struct QuorumProposal<TYPES: NodeType> {
    /// The block header to append
    pub block_header: TYPES::BlockHeader,

    /// CurView from leader when proposing leaf
    pub view_number: ViewNumber,

    /// Per spec, justification
    pub justify_qc: QuorumCertificate<TYPES>,

    /// Possible upgrade certificate, which the leader may optionally attach.
    pub upgrade_certificate: Option<UpgradeCertificate<TYPES>>,

    /// Possible timeout or view sync certificate.
    /// - A timeout certificate is only present if the justify_qc is not for the preceding view
    /// - A view sync certificate is only present if the justify_qc and timeout_cert are not
    ///   present.
    pub proposal_certificate: Option<ViewChangeEvidence<TYPES>>,
}

/// Proposal to append a block.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub struct QuorumProposal2<TYPES: NodeType> {
    /// The block header to append
    pub block_header: TYPES::BlockHeader,

    /// view number for the proposal
    pub view_number: ViewNumber,

    /// The epoch number corresponding to the block number. Can be `None` for pre-epoch version.
    pub epoch: Option<EpochNumber>,

    /// certificate that the proposal is chaining from
    pub justify_qc: QuorumCertificate2<TYPES>,

    /// certificate that the proposal is chaining from formed by the next epoch nodes
    pub next_epoch_justify_qc: Option<NextEpochQuorumCertificate2<TYPES>>,

    /// Possible upgrade certificate, which the leader may optionally attach.
    pub upgrade_certificate: Option<UpgradeCertificate<TYPES>>,

    /// Possible timeout or view sync certificate. If the `justify_qc` is not for a proposal in the immediately preceding view, then either a timeout or view sync certificate must be attached.
    pub view_change_evidence: Option<ViewChangeEvidence2<TYPES>>,

    /// The DRB result for the next epoch.
    ///
    /// This is required only for the last block of the epoch. Nodes will verify that it's
    /// consistent with the result from their computations.
    #[serde(with = "serde_bytes")]
    pub next_drb_result: Option<DrbResult>,

    /// The light client state update certificate for the next epoch.
    /// This is required for the epoch root.
    pub state_cert: Option<LightClientStateUpdateCertificateV2<TYPES>>,
}

/// Legacy version of `QuorumProposal2` corresponding to consensus protocol version V3.
///
/// `QuorumProposal2` state_cert field was updated to use new
/// `LightClientStateUpdateCertificateV2`.
/// This legacy version uses the older `LightClientStateUpdateCertificateV1`
/// format for backward compatibility.
///
/// It is used only for deserializing previously stored quorum proposals.
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub struct QuorumProposal2Legacy<TYPES: NodeType> {
    /// The block header to append
    pub block_header: TYPES::BlockHeader,

    /// view number for the proposal
    pub view_number: ViewNumber,

    /// The epoch number corresponding to the block number. Can be `None` for pre-epoch version.
    pub epoch: Option<EpochNumber>,

    /// certificate that the proposal is chaining from
    pub justify_qc: QuorumCertificate2<TYPES>,

    /// certificate that the proposal is chaining from formed by the next epoch nodes
    pub next_epoch_justify_qc: Option<NextEpochQuorumCertificate2<TYPES>>,

    /// Possible upgrade certificate, which the leader may optionally attach.
    pub upgrade_certificate: Option<UpgradeCertificate<TYPES>>,

    /// Possible timeout or view sync certificate. If the `justify_qc` is not for a proposal in the immediately preceding view, then either a timeout or view sync certificate must be attached.
    pub view_change_evidence: Option<ViewChangeEvidence2<TYPES>>,

    /// The DRB result for the next epoch.
    ///
    /// This is required only for the last block of the epoch. Nodes will verify that it's
    /// consistent with the result from their computations.
    #[serde(with = "serde_bytes")]
    pub next_drb_result: Option<DrbResult>,

    /// The light client state update certificate for the next epoch.
    /// This is required for the epoch root.
    /// Uses the legacy V1 certificate format.
    pub state_cert: Option<LightClientStateUpdateCertificateV1<TYPES>>,
}

impl<TYPES: NodeType> From<QuorumProposal2Legacy<TYPES>> for QuorumProposal2<TYPES> {
    fn from(quorum_proposal2: QuorumProposal2Legacy<TYPES>) -> Self {
        Self {
            block_header: quorum_proposal2.block_header,
            view_number: quorum_proposal2.view_number,
            epoch: quorum_proposal2.epoch,
            justify_qc: quorum_proposal2.justify_qc,
            next_epoch_justify_qc: quorum_proposal2.next_epoch_justify_qc,
            upgrade_certificate: quorum_proposal2.upgrade_certificate,
            view_change_evidence: quorum_proposal2.view_change_evidence,
            next_drb_result: quorum_proposal2.next_drb_result,
            state_cert: quorum_proposal2.state_cert.map(Into::into),
        }
    }
}

impl<TYPES: NodeType> From<QuorumProposal2<TYPES>> for QuorumProposal2Legacy<TYPES> {
    fn from(quorum_proposal2: QuorumProposal2<TYPES>) -> Self {
        Self {
            block_header: quorum_proposal2.block_header,
            view_number: quorum_proposal2.view_number,
            epoch: quorum_proposal2.epoch,
            justify_qc: quorum_proposal2.justify_qc,
            next_epoch_justify_qc: quorum_proposal2.next_epoch_justify_qc,
            upgrade_certificate: quorum_proposal2.upgrade_certificate,
            view_change_evidence: quorum_proposal2.view_change_evidence,
            next_drb_result: quorum_proposal2.next_drb_result,
            state_cert: quorum_proposal2.state_cert.map(Into::into),
        }
    }
}

/// Wrapper type for a legacy quorum proposal.
///
/// This is used to encapsulate a [`QuorumProposal2Legacy`] when working with
/// data from older consensus protocol versions (e.g., V3).
/// Primarily used for deserialization of legacy proposals
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub struct QuorumProposalWrapperLegacy<TYPES: NodeType> {
    /// The wrapped proposal
    pub proposal: QuorumProposal2Legacy<TYPES>,
}

/// Wrapper around a proposal to append a block
#[derive(derive_more::Debug, Serialize, Deserialize, Clone, Eq, PartialEq, Hash)]
#[serde(bound(deserialize = ""))]
pub struct QuorumProposalWrapper<TYPES: NodeType> {
    /// The wrapped proposal
    pub proposal: QuorumProposal2<TYPES>,
}

impl<TYPES: NodeType> From<QuorumProposalWrapperLegacy<TYPES>> for QuorumProposalWrapper<TYPES> {
    fn from(v3: QuorumProposalWrapperLegacy<TYPES>) -> Self {
        Self {
            proposal: v3.proposal.into(),
        }
    }
}

impl<TYPES: NodeType> QuorumProposal2<TYPES> {
    /// Validates whether the epoch is consistent with the version and the block number
    /// # Errors
    /// Returns an error if the epoch is inconsistent with the version or the block number
    pub async fn validate_epoch(
        &self,
        upgrade_lock: &UpgradeLock<TYPES>,
        epoch_height: u64,
    ) -> Result<()> {
        let calculated_epoch = option_epoch_from_block_number(
            upgrade_lock.epochs_enabled(self.view_number()).await,
            self.block_header.block_number(),
            epoch_height,
        );
        ensure!(
            calculated_epoch == self.epoch(),
            "Quorum proposal invalid: inconsistent epoch."
        );
        Ok(())
    }
}

impl<TYPES: NodeType> QuorumProposalWrapper<TYPES> {
    /// Helper function to get the proposal's block_header
    pub fn block_header(&self) -> &TYPES::BlockHeader {
        &self.proposal.block_header
    }

    /// Helper function to get the proposal's view_number
    pub fn view_number(&self) -> ViewNumber {
        self.proposal.view_number
    }

    /// Helper function to get the proposal's justify_qc
    pub fn justify_qc(&self) -> &QuorumCertificate2<TYPES> {
        &self.proposal.justify_qc
    }

    /// Helper function to get the proposal's next_epoch_justify_qc
    pub fn next_epoch_justify_qc(&self) -> &Option<NextEpochQuorumCertificate2<TYPES>> {
        &self.proposal.next_epoch_justify_qc
    }

    /// Helper function to get the proposal's upgrade_certificate
    pub fn upgrade_certificate(&self) -> &Option<UpgradeCertificate<TYPES>> {
        &self.proposal.upgrade_certificate
    }

    /// Helper function to get the proposal's view_change_evidence
    pub fn view_change_evidence(&self) -> &Option<ViewChangeEvidence2<TYPES>> {
        &self.proposal.view_change_evidence
    }

    /// Helper function to get the proposal's next_drb_result
    pub fn next_drb_result(&self) -> &Option<DrbResult> {
        &self.proposal.next_drb_result
    }

    /// Validates whether the epoch is consistent with the version and the block number
    /// # Errors
    /// Returns an error if the epoch is inconsistent with the version or the block number
    pub async fn validate_epoch(
        &self,
        upgrade_lock: &UpgradeLock<TYPES>,
        epoch_height: u64,
    ) -> Result<()> {
        self.proposal
            .validate_epoch(upgrade_lock, epoch_height)
            .await
    }

    /// Helper function to get the proposal's light client state update certificate
    pub fn state_cert(&self) -> &Option<LightClientStateUpdateCertificateV2<TYPES>> {
        &self.proposal.state_cert
    }
}

impl<TYPES: NodeType> From<QuorumProposal<TYPES>> for QuorumProposalWrapper<TYPES> {
    fn from(quorum_proposal: QuorumProposal<TYPES>) -> Self {
        Self {
            proposal: quorum_proposal.into(),
        }
    }
}

impl<TYPES: NodeType> From<QuorumProposal2Legacy<TYPES>> for QuorumProposalWrapper<TYPES> {
    fn from(quorum_proposal: QuorumProposal2Legacy<TYPES>) -> Self {
        Self {
            proposal: quorum_proposal.into(),
        }
    }
}

impl<TYPES: NodeType> From<QuorumProposal2<TYPES>> for QuorumProposalWrapper<TYPES> {
    fn from(quorum_proposal2: QuorumProposal2<TYPES>) -> Self {
        Self {
            proposal: quorum_proposal2,
        }
    }
}

impl<TYPES: NodeType> From<QuorumProposalWrapper<TYPES>> for QuorumProposal<TYPES> {
    fn from(quorum_proposal_wrapper: QuorumProposalWrapper<TYPES>) -> Self {
        quorum_proposal_wrapper.proposal.into()
    }
}

impl<TYPES: NodeType> From<QuorumProposalWrapper<TYPES>> for QuorumProposal2Legacy<TYPES> {
    fn from(quorum_proposal_wrapper: QuorumProposalWrapper<TYPES>) -> Self {
        quorum_proposal_wrapper.proposal.into()
    }
}

impl<TYPES: NodeType> From<QuorumProposalWrapper<TYPES>> for QuorumProposal2<TYPES> {
    fn from(quorum_proposal_wrapper: QuorumProposalWrapper<TYPES>) -> Self {
        quorum_proposal_wrapper.proposal
    }
}

impl<TYPES: NodeType> From<QuorumProposal<TYPES>> for QuorumProposal2<TYPES> {
    fn from(quorum_proposal: QuorumProposal<TYPES>) -> Self {
        Self {
            block_header: quorum_proposal.block_header,
            view_number: quorum_proposal.view_number,
            epoch: None,
            justify_qc: quorum_proposal.justify_qc.to_qc2(),
            next_epoch_justify_qc: None,
            upgrade_certificate: quorum_proposal.upgrade_certificate,
            view_change_evidence: quorum_proposal
                .proposal_certificate
                .map(ViewChangeEvidence::to_evidence2),
            next_drb_result: None,
            state_cert: None,
        }
    }
}

impl<TYPES: NodeType> From<QuorumProposal2<TYPES>> for QuorumProposal<TYPES> {
    fn from(quorum_proposal2: QuorumProposal2<TYPES>) -> Self {
        Self {
            block_header: quorum_proposal2.block_header,
            view_number: quorum_proposal2.view_number,
            justify_qc: quorum_proposal2.justify_qc.to_qc(),
            upgrade_certificate: quorum_proposal2.upgrade_certificate,
            proposal_certificate: quorum_proposal2
                .view_change_evidence
                .map(ViewChangeEvidence2::to_evidence),
        }
    }
}

impl<TYPES: NodeType> From<Leaf<TYPES>> for Leaf2<TYPES> {
    fn from(leaf: Leaf<TYPES>) -> Self {
        let bytes: [u8; 32] = leaf.parent_commitment.into();

        Self {
            view_number: leaf.view_number,
            justify_qc: leaf.justify_qc.to_qc2(),
            next_epoch_justify_qc: None,
            parent_commitment: Commitment::from_raw(bytes),
            block_header: leaf.block_header,
            upgrade_certificate: leaf.upgrade_certificate,
            block_payload: leaf.block_payload,
            view_change_evidence: None,
            next_drb_result: None,
            with_epoch: false,
        }
    }
}

impl<TYPES: NodeType> HasViewNumber for DaProposal<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for DaProposal2<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for QuorumProposal<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for QuorumProposal2<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for QuorumProposal2Legacy<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for QuorumProposalWrapper<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.proposal.view_number
    }
}

impl<TYPES: NodeType> HasViewNumber for QuorumProposalWrapperLegacy<TYPES> {
    fn view_number(&self) -> ViewNumber {
        self.proposal.view_number
    }
}

impl HasViewNumber for UpgradeProposal {
    fn view_number(&self) -> ViewNumber {
        self.view_number
    }
}

impl<NODE: NodeType> HasEpoch for QuorumProposal2<NODE> {
    fn epoch(&self) -> Option<EpochNumber> {
        self.epoch
    }
}

impl<NODE: NodeType> HasEpoch for DaProposal2<NODE> {
    fn epoch(&self) -> Option<EpochNumber> {
        self.epoch
    }
}

impl<NODE: NodeType> HasEpoch for QuorumProposal2Legacy<NODE> {
    fn epoch(&self) -> Option<EpochNumber> {
        self.epoch
    }
}

impl HasEpoch for UpgradeProposal {
    fn epoch(&self) -> Option<EpochNumber> {
        None
    }
}

impl<NODE: NodeType> HasEpoch for QuorumProposal<NODE> {
    fn epoch(&self) -> Option<EpochNumber> {
        None
    }
}

impl<NODE: NodeType> HasEpoch for DaProposal<NODE> {
    fn epoch(&self) -> Option<EpochNumber> {
        None
    }
}

impl<NODE: NodeType> HasEpoch for QuorumProposalWrapper<NODE> {
    /// Return an underlying proposal's epoch
    #[allow(clippy::panic)]
    fn epoch(&self) -> Option<EpochNumber> {
        self.proposal.epoch()
    }
}

impl<TYPES: NodeType> HasEpoch for QuorumProposalWrapperLegacy<TYPES> {
    /// Return an underlying proposal's epoch
    #[allow(clippy::panic)]
    fn epoch(&self) -> Option<EpochNumber> {
        self.proposal.epoch()
    }
}

/// The error type for block and its transactions.
#[derive(Error, Debug, Serialize, Deserialize)]
pub enum BlockError {
    /// The block header is invalid
    #[error("Invalid block header: {0}")]
    InvalidBlockHeader(String),

    /// The payload commitment does not match the block header's payload commitment
    #[error("Inconsistent payload commitment")]
    InconsistentPayloadCommitment,

    /// The block header apply failed
    #[error("Failed to apply block header: {0}")]
    FailedHeaderApply(String),
}

/// Additional functions required to use a [`Leaf`] with hotshot-testing.
pub trait TestableLeaf {
    /// Type of nodes participating in the network.
    type NodeType: NodeType;

    /// Create a transaction that can be added to the block contained in this leaf.
    fn create_random_transaction(
        &self,
        rng: &mut dyn rand::RngCore,
        padding: u64,
    ) -> <<Self::NodeType as NodeType>::BlockPayload as BlockPayload<Self::NodeType>>::Transaction;
}

/// This is the consensus-internal analogous concept to a block, and it contains the block proper,
/// as well as the hash of its parent `Leaf`.
/// NOTE: `State` is constrained to implementing `BlockContents`, is `TypeMap::BlockPayload`
#[derive(Serialize, Deserialize, Clone, Debug, Eq)]
#[serde(bound(deserialize = ""))]
pub struct Leaf<TYPES: NodeType> {
    /// CurView from leader when proposing leaf
    view_number: ViewNumber,

    /// Per spec, justification
    justify_qc: QuorumCertificate<TYPES>,

    /// The hash of the parent `Leaf`
    /// So we can ask if it extends
    parent_commitment: Commitment<Self>,

    /// Block header.
    block_header: TYPES::BlockHeader,

    /// Optional upgrade certificate, if one was attached to the quorum proposal for this view.
    upgrade_certificate: Option<UpgradeCertificate<TYPES>>,

    /// Optional block payload.
    ///
    /// It may be empty for nodes not in the DA committee.
    block_payload: Option<TYPES::BlockPayload>,
}

/// This is the consensus-internal analogous concept to a block, and it contains the block proper,
/// as well as the hash of its parent `Leaf`.
#[derive(Serialize, Deserialize, Clone, Debug, Eq)]
#[serde(bound(deserialize = ""))]
pub struct Leaf2<TYPES: NodeType> {
    /// CurView from leader when proposing leaf
    view_number: ViewNumber,

    /// Per spec, justification
    justify_qc: QuorumCertificate2<TYPES>,

    /// certificate that the proposal is chaining from formed by the next epoch nodes
    next_epoch_justify_qc: Option<NextEpochQuorumCertificate2<TYPES>>,

    /// The hash of the parent `Leaf`
    /// So we can ask if it extends
    parent_commitment: Commitment<Self>,

    /// Block header.
    block_header: TYPES::BlockHeader,

    /// Optional upgrade certificate, if one was attached to the quorum proposal for this view.
    upgrade_certificate: Option<UpgradeCertificate<TYPES>>,

    /// Optional block payload.
    ///
    /// It may be empty for nodes not in the DA committee.
    block_payload: Option<TYPES::BlockPayload>,

    /// Possible timeout or view sync certificate. If the `justify_qc` is not for a proposal in the immediately preceding view, then either a timeout or view sync certificate must be attached.
    pub view_change_evidence: Option<ViewChangeEvidence2<TYPES>>,

    /// The DRB result for the next epoch.
    ///
    /// This is required only for the last block of the epoch. Nodes will verify that it's
    /// consistent with the result from their computations.
    #[serde(with = "serde_bytes")]
    pub next_drb_result: Option<DrbResult>,

    /// Indicates whether or not epochs were enabled.
    pub with_epoch: bool,
}

impl<TYPES: NodeType> Leaf2<TYPES> {
    /// Create a new leaf from its components.
    ///
    /// # Panics
    ///
    /// Panics if the genesis payload (`TYPES::BlockPayload::genesis()`) is malformed (unable to be
    /// interpreted as bytes).
    #[must_use]
    pub async fn genesis(
        validated_state: &TYPES::ValidatedState,
        instance_state: &TYPES::InstanceState,
        version: Version,
    ) -> Self {
        let epoch = genesis_epoch_from_version(version);

        let (payload, metadata) =
            TYPES::BlockPayload::from_transactions([], validated_state, instance_state)
                .await
                .unwrap();

        let genesis_view = ViewNumber::genesis();

        let block_header =
            TYPES::BlockHeader::genesis(instance_state, payload.clone(), &metadata, version);

        let block_number = if version < EPOCH_VERSION {
            None
        } else {
            Some(0u64)
        };

        let null_quorum_data = QuorumData2 {
            leaf_commit: Commitment::<Leaf2<TYPES>>::default_commitment_no_preimage(),
            epoch,
            block_number,
        };

        let justify_qc = QuorumCertificate2::new(
            null_quorum_data.clone(),
            null_quorum_data.commit(),
            genesis_view,
            None,
            PhantomData,
        );

        Self {
            view_number: genesis_view,
            justify_qc,
            next_epoch_justify_qc: None,
            parent_commitment: null_quorum_data.leaf_commit,
            upgrade_certificate: None,
            block_header: block_header.clone(),
            block_payload: Some(payload),
            view_change_evidence: None,
            next_drb_result: None,
            with_epoch: epoch.is_some(),
        }
    }
    /// Time when this leaf was created.
    pub fn view_number(&self) -> ViewNumber {
        self.view_number
    }
    /// Epoch in which this leaf was created.
    pub fn epoch(&self, epoch_height: u64) -> Option<EpochNumber> {
        option_epoch_from_block_number(
            self.with_epoch,
            self.block_header.block_number(),
            epoch_height,
        )
    }
    /// Height of this leaf in the chain.
    ///
    /// Equivalently, this is the number of leaves before this one in the chain.
    pub fn height(&self) -> u64 {
        self.block_header.block_number()
    }
    /// The QC linking this leaf to its parent in the chain.
    pub fn justify_qc(&self) -> QuorumCertificate2<TYPES> {
        self.justify_qc.clone()
    }
    /// The QC linking this leaf to its parent in the chain, signed by the next epoch's quorum.
    ///
    /// Only available for QCs that are part of an epoch transition.
    pub fn next_epoch_justify_qc(&self) -> Option<NextEpochQuorumCertificate2<TYPES>> {
        self.next_epoch_justify_qc.clone()
    }
    /// The QC linking this leaf to its parent in the chain.
    pub fn upgrade_certificate(&self) -> Option<UpgradeCertificate<TYPES>> {
        self.upgrade_certificate.clone()
    }
    /// Commitment to this leaf's parent.
    pub fn parent_commitment(&self) -> Commitment<Self> {
        self.parent_commitment
    }
    /// The block header contained in this leaf.
    pub fn block_header(&self) -> &<TYPES as NodeType>::BlockHeader {
        &self.block_header
    }

    /// Get a mutable reference to the block header contained in this leaf.
    pub fn block_header_mut(&mut self) -> &mut <TYPES as NodeType>::BlockHeader {
        &mut self.block_header
    }
    /// Fill this leaf with the block payload.
    ///
    /// # Errors
    ///
    /// Fails if the payload commitment doesn't match `self.block_header.payload_commitment()`
    /// or if the transactions are of invalid length
    pub fn fill_block_payload(
        &mut self,
        block_payload: TYPES::BlockPayload,
        num_storage_nodes: usize,
        version: Version,
    ) -> std::result::Result<(), BlockError> {
        let encoded_txns = block_payload.encode();
        let commitment = vid_commitment(
            &encoded_txns,
            &self.block_header.metadata().encode(),
            num_storage_nodes,
            version,
        );
        if commitment != self.block_header.payload_commitment() {
            return Err(BlockError::InconsistentPayloadCommitment);
        }
        self.block_payload = Some(block_payload);
        Ok(())
    }

    /// Take the block payload from the leaf and return it if it is present
    pub fn unfill_block_payload(&mut self) -> Option<TYPES::BlockPayload> {
        self.block_payload.take()
    }

    /// Fill this leaf with the block payload, without checking
    /// header and payload consistency
    pub fn fill_block_payload_unchecked(&mut self, block_payload: TYPES::BlockPayload) {
        self.block_payload = Some(block_payload);
    }

    /// Optional block payload.
    pub fn block_payload(&self) -> Option<TYPES::BlockPayload> {
        self.block_payload.clone()
    }

    /// A commitment to the block payload contained in this leaf.
    pub fn payload_commitment(&self) -> VidCommitment {
        self.block_header().payload_commitment()
    }

    /// Validate that a leaf has the right upgrade certificate to be the immediate child of another leaf
    ///
    /// This may not be a complete function. Please double-check that it performs the checks you expect before substituting validation logic with it.
    ///
    /// # Errors
    /// Returns an error if the certificates are not identical, or that when we no longer see a
    /// cert, it's for the right reason.
    pub async fn extends_upgrade(
        &self,
        parent: &Self,
        decided_upgrade_certificate: &Arc<RwLock<Option<UpgradeCertificate<TYPES>>>>,
    ) -> Result<()> {
        match (self.upgrade_certificate(), parent.upgrade_certificate()) {
            // Easiest cases are:
            //   - no upgrade certificate on either: this is the most common case, and is always fine.
            //   - if the parent didn't have a certificate, but we see one now, it just means that we have begun an upgrade: again, this is always fine.
            (None | Some(_), None) => {},
            // If we no longer see a cert, we have to make sure that we either:
            //    - no longer care because we have passed new_version_first_view, or
            //    - no longer care because we have passed `decide_by` without deciding the certificate.
            (None, Some(parent_cert)) => {
                let decided_upgrade_certificate_read = decided_upgrade_certificate.read().await;
                ensure!(
                    self.view_number() > parent_cert.data.new_version_first_view
                        || (self.view_number() > parent_cert.data.decide_by
                            && decided_upgrade_certificate_read.is_none()),
                    "The new leaf is missing an upgrade certificate that was present in its \
                     parent, and should still be live."
                );
            },
            // If we both have a certificate, they should be identical.
            // Technically, this prevents us from initiating a new upgrade in the view immediately following an upgrade.
            // I think this is a fairly lax restriction.
            (Some(cert), Some(parent_cert)) => {
                ensure!(
                    cert == parent_cert,
                    "The new leaf does not extend the parent leaf, because it has attached a \
                     different upgrade certificate."
                );
            },
        }

        // This check should be added once we sort out the genesis leaf/justify_qc issue.
        // ensure!(self.parent_commitment() == parent_leaf.commit(), "The commitment of the parent leaf does not match the specified parent commitment.");

        Ok(())
    }

    /// Converts a `Leaf2` to a `Leaf`. This operation is fundamentally unsafe and should not be used.
    pub fn to_leaf_unsafe(self) -> Leaf<TYPES> {
        let bytes: [u8; 32] = self.parent_commitment.into();

        Leaf {
            view_number: self.view_number,
            justify_qc: self.justify_qc.to_qc(),
            parent_commitment: Commitment::from_raw(bytes),
            block_header: self.block_header,
            upgrade_certificate: self.upgrade_certificate,
            block_payload: self.block_payload,
        }
    }
}

impl<TYPES: NodeType> Committable for Leaf2<TYPES> {
    fn commit(&self) -> committable::Commitment<Self> {
        let Leaf2 {
            view_number,
            justify_qc,
            next_epoch_justify_qc,
            parent_commitment,
            block_header,
            upgrade_certificate,
            block_payload: _,
            view_change_evidence,
            next_drb_result,
            with_epoch,
        } = self;

        let mut cb = RawCommitmentBuilder::new("leaf commitment")
            .u64_field("view number", **view_number)
            .field("parent leaf commitment", *parent_commitment)
            .field("block header", block_header.commit())
            .field("justify qc", justify_qc.commit())
            .optional("upgrade certificate", upgrade_certificate);

        if *with_epoch {
            cb = cb
                .constant_str("with_epoch")
                .optional("next_epoch_justify_qc", next_epoch_justify_qc);

            if let Some(next_drb_result) = next_drb_result {
                cb = cb
                    .constant_str("next_drb_result")
                    .fixed_size_bytes(next_drb_result);
            }

            match view_change_evidence {
                Some(ViewChangeEvidence2::Timeout(cert)) => {
                    cb = cb.field("timeout cert", cert.commit());
                },
                Some(ViewChangeEvidence2::ViewSync(cert)) => {
                    cb = cb.field("viewsync cert", cert.commit());
                },
                None => {},
            }
        }

        cb.finalize()
    }
}

impl<TYPES: NodeType> Leaf<TYPES> {
    #[allow(clippy::unused_async)]
    /// Calculate the leaf commitment,
    /// which is gated on the version to include the block header.
    pub async fn commit(&self, _upgrade_lock: &UpgradeLock<TYPES>) -> Commitment<Self> {
        <Self as Committable>::commit(self)
    }
}

impl<TYPES: NodeType> PartialEq for Leaf<TYPES> {
    fn eq(&self, other: &Self) -> bool {
        self.view_number == other.view_number
            && self.justify_qc == other.justify_qc
            && self.parent_commitment == other.parent_commitment
            && self.block_header == other.block_header
    }
}

impl<TYPES: NodeType> PartialEq for Leaf2<TYPES> {
    fn eq(&self, other: &Self) -> bool {
        let Leaf2 {
            view_number,
            justify_qc,
            next_epoch_justify_qc,
            parent_commitment,
            block_header,
            upgrade_certificate,
            block_payload: _,
            view_change_evidence,
            next_drb_result,
            with_epoch,
        } = self;

        *view_number == other.view_number
            && *justify_qc == other.justify_qc
            && *next_epoch_justify_qc == other.next_epoch_justify_qc
            && *parent_commitment == other.parent_commitment
            && *block_header == other.block_header
            && *upgrade_certificate == other.upgrade_certificate
            && *view_change_evidence == other.view_change_evidence
            && *next_drb_result == other.next_drb_result
            && *with_epoch == other.with_epoch
    }
}

impl<TYPES: NodeType> Hash for Leaf<TYPES> {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.view_number.hash(state);
        self.justify_qc.hash(state);
        self.parent_commitment.hash(state);
        self.block_header.hash(state);
    }
}

impl<TYPES: NodeType> Hash for Leaf2<TYPES> {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.commit().hash(state);
        self.view_number.hash(state);
        self.justify_qc.hash(state);
        self.parent_commitment.hash(state);
        self.block_header.hash(state);
    }
}

impl<TYPES: NodeType> Display for Leaf<TYPES> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "view: {:?}, height: {:?}, justify: {}",
            self.view_number,
            self.height(),
            self.justify_qc
        )
    }
}

impl<TYPES: NodeType> QuorumCertificate<TYPES> {
    /// Creat the Genesis certificate
    #[must_use]
    pub async fn genesis(
        validated_state: &TYPES::ValidatedState,
        instance_state: &TYPES::InstanceState,
        upgrade: Upgrade,
    ) -> Self {
        // since this is genesis, we should never have a decided upgrade certificate.
        let upgrade_lock = UpgradeLock::<TYPES>::new(upgrade);

        let genesis_view = ViewNumber::genesis();

        let data = QuorumData {
            leaf_commit: Leaf::genesis(validated_state, instance_state, upgrade.base)
                .await
                .commit(&upgrade_lock)
                .await,
        };

        let versioned_data =
            VersionedVoteData::<_, _>::new_infallible(data.clone(), genesis_view, &upgrade_lock)
                .await;

        let bytes: [u8; 32] = versioned_data.commit().into();

        Self::new(
            data,
            Commitment::from_raw(bytes),
            genesis_view,
            None,
            PhantomData,
        )
    }
}

impl<TYPES: NodeType> QuorumCertificate2<TYPES> {
    /// Create the Genesis certificate
    #[must_use]
    pub async fn genesis(
        validated_state: &TYPES::ValidatedState,
        instance_state: &TYPES::InstanceState,
        upgrade: Upgrade,
    ) -> Self {
        // since this is genesis, we should never have a decided upgrade certificate.
        let upgrade_lock = UpgradeLock::<TYPES>::new(upgrade);

        let genesis_view = ViewNumber::genesis();

        let genesis_leaf = Leaf2::genesis(validated_state, instance_state, upgrade.base).await;
        let block_number = if upgrade_lock.epochs_enabled(genesis_view).await {
            Some(genesis_leaf.height())
        } else {
            None
        };
        let data = QuorumData2 {
            leaf_commit: genesis_leaf.commit(),
            epoch: genesis_epoch_from_version(upgrade.base), // #3967 make sure this is enough of a gate for epochs
            block_number,
        };

        let versioned_data =
            VersionedVoteData::<_, _>::new_infallible(data.clone(), genesis_view, &upgrade_lock)
                .await;

        let bytes: [u8; 32] = versioned_data.commit().into();

        Self::new(
            data,
            Commitment::from_raw(bytes),
            genesis_view,
            None,
            PhantomData,
        )
    }
}

impl<TYPES: NodeType> Leaf<TYPES> {
    /// Create a new leaf from its components.
    ///
    /// # Panics
    ///
    /// Panics if the genesis payload (`TYPES::BlockPayload::genesis()`) is malformed (unable to be
    /// interpreted as bytes).
    #[must_use]
    pub async fn genesis(
        validated_state: &TYPES::ValidatedState,
        instance_state: &TYPES::InstanceState,
        version: Version,
    ) -> Self {
        let (payload, metadata) =
            TYPES::BlockPayload::from_transactions([], validated_state, instance_state)
                .await
                .unwrap();

        let genesis_view = ViewNumber::genesis();

        let block_header =
            TYPES::BlockHeader::genesis(instance_state, payload.clone(), &metadata, version);

        let null_quorum_data = QuorumData {
            leaf_commit: Commitment::<Leaf<TYPES>>::default_commitment_no_preimage(),
        };

        let justify_qc = QuorumCertificate::new(
            null_quorum_data.clone(),
            null_quorum_data.commit(),
            genesis_view,
            None,
            PhantomData,
        );

        Self {
            view_number: genesis_view,
            justify_qc,
            parent_commitment: null_quorum_data.leaf_commit,
            upgrade_certificate: None,
            block_header: block_header.clone(),
            block_payload: Some(payload),
        }
    }

    /// Time when this leaf was created.
    pub fn view_number(&self) -> ViewNumber {
        self.view_number
    }
    /// Height of this leaf in the chain.
    ///
    /// Equivalently, this is the number of leaves before this one in the chain.
    pub fn height(&self) -> u64 {
        self.block_header.block_number()
    }
    /// The QC linking this leaf to its parent in the chain.
    pub fn justify_qc(&self) -> QuorumCertificate<TYPES> {
        self.justify_qc.clone()
    }
    /// The QC linking this leaf to its parent in the chain.
    pub fn upgrade_certificate(&self) -> Option<UpgradeCertificate<TYPES>> {
        self.upgrade_certificate.clone()
    }
    /// Commitment to this leaf's parent.
    pub fn parent_commitment(&self) -> Commitment<Self> {
        self.parent_commitment
    }
    /// The block header contained in this leaf.
    pub fn block_header(&self) -> &<TYPES as NodeType>::BlockHeader {
        &self.block_header
    }

    /// Get a mutable reference to the block header contained in this leaf.
    pub fn block_header_mut(&mut self) -> &mut <TYPES as NodeType>::BlockHeader {
        &mut self.block_header
    }
    /// Fill this leaf with the block payload.
    ///
    /// # Errors
    ///
    /// Fails if the payload commitment doesn't match `self.block_header.payload_commitment()`
    /// or if the transactions are of invalid length
    pub fn fill_block_payload(
        &mut self,
        block_payload: TYPES::BlockPayload,
        num_storage_nodes: usize,
        version: Version,
    ) -> std::result::Result<(), BlockError> {
        let encoded_txns = block_payload.encode();
        let commitment = vid_commitment(
            &encoded_txns,
            &self.block_header.metadata().encode(),
            num_storage_nodes,
            version,
        );
        if commitment != self.block_header.payload_commitment() {
            return Err(BlockError::InconsistentPayloadCommitment);
        }
        self.block_payload = Some(block_payload);
        Ok(())
    }

    /// Take the block payload from the leaf and return it if it is present
    pub fn unfill_block_payload(&mut self) -> Option<TYPES::BlockPayload> {
        self.block_payload.take()
    }

    /// Fill this leaf with the block payload, without checking
    /// header and payload consistency
    pub fn fill_block_payload_unchecked(&mut self, block_payload: TYPES::BlockPayload) {
        self.block_payload = Some(block_payload);
    }

    /// Optional block payload.
    pub fn block_payload(&self) -> Option<TYPES::BlockPayload> {
        self.block_payload.clone()
    }

    /// A commitment to the block payload contained in this leaf.
    pub fn payload_commitment(&self) -> VidCommitment {
        self.block_header().payload_commitment()
    }

    /// Validate that a leaf has the right upgrade certificate to be the immediate child of another leaf
    ///
    /// This may not be a complete function. Please double-check that it performs the checks you expect before substituting validation logic with it.
    ///
    /// # Errors
    /// Returns an error if the certificates are not identical, or that when we no longer see a
    /// cert, it's for the right reason.
    pub async fn extends_upgrade(
        &self,
        parent: &Self,
        decided_upgrade_certificate: &Arc<RwLock<Option<UpgradeCertificate<TYPES>>>>,
    ) -> Result<()> {
        match (self.upgrade_certificate(), parent.upgrade_certificate()) {
            // Easiest cases are:
            //   - no upgrade certificate on either: this is the most common case, and is always fine.
            //   - if the parent didn't have a certificate, but we see one now, it just means that we have begun an upgrade: again, this is always fine.
            (None | Some(_), None) => {},
            // If we no longer see a cert, we have to make sure that we either:
            //    - no longer care because we have passed new_version_first_view, or
            //    - no longer care because we have passed `decide_by` without deciding the certificate.
            (None, Some(parent_cert)) => {
                let decided_upgrade_certificate_read = decided_upgrade_certificate.read().await;
                ensure!(
                    self.view_number() > parent_cert.data.new_version_first_view
                        || (self.view_number() > parent_cert.data.decide_by
                            && decided_upgrade_certificate_read.is_none()),
                    "The new leaf is missing an upgrade certificate that was present in its \
                     parent, and should still be live."
                );
            },
            // If we both have a certificate, they should be identical.
            // Technically, this prevents us from initiating a new upgrade in the view immediately following an upgrade.
            // I think this is a fairly lax restriction.
            (Some(cert), Some(parent_cert)) => {
                ensure!(
                    cert == parent_cert,
                    "The new leaf does not extend the parent leaf, because it has attached a \
                     different upgrade certificate."
                );
            },
        }

        // This check should be added once we sort out the genesis leaf/justify_qc issue.
        // ensure!(self.parent_commitment() == parent_leaf.commit(), "The commitment of the parent leaf does not match the specified parent commitment.");

        Ok(())
    }
}

impl<TYPES: NodeType> TestableLeaf for Leaf<TYPES>
where
    TYPES::ValidatedState: TestableState<TYPES>,
    TYPES::BlockPayload: TestableBlock<TYPES>,
{
    type NodeType = TYPES;

    fn create_random_transaction(
        &self,
        rng: &mut dyn rand::RngCore,
        padding: u64,
    ) -> <<Self::NodeType as NodeType>::BlockPayload as BlockPayload<Self::NodeType>>::Transaction
    {
        TYPES::ValidatedState::create_random_transaction(None, rng, padding)
    }
}
impl<TYPES: NodeType> TestableLeaf for Leaf2<TYPES>
where
    TYPES::ValidatedState: TestableState<TYPES>,
    TYPES::BlockPayload: TestableBlock<TYPES>,
{
    type NodeType = TYPES;

    fn create_random_transaction(
        &self,
        rng: &mut dyn rand::RngCore,
        padding: u64,
    ) -> <<Self::NodeType as NodeType>::BlockPayload as BlockPayload<Self::NodeType>>::Transaction
    {
        TYPES::ValidatedState::create_random_transaction(None, rng, padding)
    }
}
/// Fake the thing a genesis block points to. Needed to avoid infinite recursion
#[must_use]
pub fn fake_commitment<S: Committable>() -> Commitment<S> {
    RawCommitmentBuilder::new("Dummy commitment for arbitrary genesis").finalize()
}

/// create a random commitment
#[must_use]
pub fn random_commitment<S: Committable>(rng: &mut dyn rand::RngCore) -> Commitment<S> {
    let random_array: Vec<u8> = (0u8..100u8).map(|_| rng.gen_range(0..255)).collect();
    RawCommitmentBuilder::new("Random Commitment")
        .constant_str("Random Field")
        .var_size_bytes(&random_array)
        .finalize()
}

/// Serialization for the QC assembled signature
/// # Panics
/// if serialization fails
pub fn serialize_signature2<TYPES: NodeType>(
    signatures: &<TYPES::SignatureKey as SignatureKey>::QcType,
) -> Vec<u8> {
    let mut signatures_bytes = vec![];
    signatures_bytes.extend("Yes".as_bytes());

    let (sig, proof) = TYPES::SignatureKey::sig_proof(signatures);
    let proof_bytes = bincode_opts()
        .serialize(&proof.as_bitslice())
        .expect("This serialization shouldn't be able to fail");
    signatures_bytes.extend("bitvec proof".as_bytes());
    signatures_bytes.extend(proof_bytes.as_slice());
    let sig_bytes = bincode_opts()
        .serialize(&sig)
        .expect("This serialization shouldn't be able to fail");
    signatures_bytes.extend("aggregated signature".as_bytes());
    signatures_bytes.extend(sig_bytes.as_slice());
    signatures_bytes
}

impl<TYPES: NodeType> Committable for Leaf<TYPES> {
    fn commit(&self) -> committable::Commitment<Self> {
        RawCommitmentBuilder::new("leaf commitment")
            .u64_field("view number", *self.view_number)
            .field("parent leaf commitment", self.parent_commitment)
            .field("block header", self.block_header.commit())
            .field("justify qc", self.justify_qc.commit())
            .optional("upgrade certificate", &self.upgrade_certificate)
            .finalize()
    }
}

impl<TYPES: NodeType> Leaf2<TYPES> {
    /// Constructs a leaf from a given quorum proposal.
    pub fn from_quorum_proposal(quorum_proposal: &QuorumProposalWrapper<TYPES>) -> Self {
        // WARNING: Do NOT change this to a wildcard match, or reference the fields directly in the construction of the leaf.
        // The point of this match is that we will get a compile-time error if we add a field without updating this.
        let QuorumProposalWrapper {
            proposal:
                QuorumProposal2 {
                    view_number,
                    epoch,
                    justify_qc,
                    next_epoch_justify_qc,
                    block_header,
                    upgrade_certificate,
                    view_change_evidence,
                    next_drb_result,
                    state_cert: _,
                },
        } = quorum_proposal;

        Self {
            view_number: *view_number,
            justify_qc: justify_qc.clone(),
            next_epoch_justify_qc: next_epoch_justify_qc.clone(),
            parent_commitment: justify_qc.data().leaf_commit,
            block_header: block_header.clone(),
            upgrade_certificate: upgrade_certificate.clone(),
            block_payload: None,
            view_change_evidence: view_change_evidence.clone(),
            next_drb_result: *next_drb_result,
            with_epoch: epoch.is_some(),
        }
    }
}

impl<TYPES: NodeType> Leaf<TYPES> {
    /// Constructs a leaf from a given quorum proposal.
    pub fn from_quorum_proposal(quorum_proposal: &QuorumProposal<TYPES>) -> Self {
        // WARNING: Do NOT change this to a wildcard match, or reference the fields directly in the construction of the leaf.
        // The point of this match is that we will get a compile-time error if we add a field without updating this.
        let QuorumProposal {
            view_number,
            justify_qc,
            block_header,
            upgrade_certificate,
            proposal_certificate: _,
        } = quorum_proposal;

        Self {
            view_number: *view_number,
            justify_qc: justify_qc.clone(),
            parent_commitment: justify_qc.data().leaf_commit,
            block_header: block_header.clone(),
            upgrade_certificate: upgrade_certificate.clone(),
            block_payload: None,
        }
    }
}

pub mod null_block {
    #![allow(missing_docs)]

    use jf_advz::VidScheme;
    use vbs::version::Version;
    use versions::EPOCH_VERSION;

    use crate::{
        data::VidCommitment,
        traits::{
            block_contents::BuilderFee, node_implementation::NodeType,
            signature_key::BuilderSignatureKey, BlockPayload,
        },
        vid::advz::advz_scheme,
    };

    /// The commitment for a null block payload.
    ///
    /// Note: the commitment depends on the network (via `num_storage_nodes`),
    /// and may change (albeit rarely) during execution.
    ///
    /// We memoize the result to avoid having to recalculate it.
    // TODO(Chengyu): fix it. Empty commitment must be computed at every upgrade.
    // #[memoize(SharedCache, Capacity: 10)]
    #[must_use]
    pub fn commitment(num_storage_nodes: usize) -> Option<VidCommitment> {
        let vid_result = advz_scheme(num_storage_nodes).commit_only(Vec::new());

        match vid_result {
            Ok(r) => Some(VidCommitment::V0(r)),
            Err(_) => None,
        }
    }

    /// Builder fee data for a null block payload
    #[must_use]
    pub fn builder_fee<TYPES: NodeType>(
        num_storage_nodes: usize,
        version: Version,
    ) -> Option<BuilderFee<TYPES>> {
        /// Arbitrary fee amount, this block doesn't actually come from a builder
        const FEE_AMOUNT: u64 = 0;

        let (pub_key, priv_key) =
            <TYPES::BuilderSignatureKey as BuilderSignatureKey>::generated_from_seed_indexed(
                [0_u8; 32], 0,
            );

        if version >= EPOCH_VERSION {
            let (_null_block, null_block_metadata) =
                <TYPES::BlockPayload as BlockPayload<TYPES>>::empty();

            match TYPES::BuilderSignatureKey::sign_fee(&priv_key, FEE_AMOUNT, &null_block_metadata)
            {
                Ok(sig) => Some(BuilderFee {
                    fee_amount: FEE_AMOUNT,
                    fee_account: pub_key,
                    fee_signature: sig,
                }),
                Err(_) => None,
            }
        } else {
            let (_null_block, null_block_metadata) =
                <TYPES::BlockPayload as BlockPayload<TYPES>>::empty();

            match TYPES::BuilderSignatureKey::sign_fee_with_vid_commitment(
                &priv_key,
                FEE_AMOUNT,
                &null_block_metadata,
                &commitment(num_storage_nodes)?,
            ) {
                Ok(sig) => Some(BuilderFee {
                    fee_amount: FEE_AMOUNT,
                    fee_account: pub_key,
                    fee_signature: sig,
                }),
                Err(_) => None,
            }
        }
    }
}

/// A packed bundle constructed from a sequence of bundles.
#[derive(Debug, Eq, PartialEq, Clone)]
pub struct PackedBundle<TYPES: NodeType> {
    /// The combined transactions as bytes.
    pub encoded_transactions: Arc<[u8]>,

    /// The metadata of the block.
    pub metadata: <TYPES::BlockPayload as BlockPayload<TYPES>>::Metadata,

    /// The view number that this block is associated with.
    pub view_number: ViewNumber,

    /// The view number that this block is associated with.
    pub epoch_number: Option<EpochNumber>,

    /// The sequencing fee for submitting bundles.
    pub sequencing_fees: Vec1<BuilderFee<TYPES>>,
}

impl<TYPES: NodeType> PackedBundle<TYPES> {
    /// Create a new [`PackedBundle`].
    pub fn new(
        encoded_transactions: Arc<[u8]>,
        metadata: <TYPES::BlockPayload as BlockPayload<TYPES>>::Metadata,
        view_number: ViewNumber,
        epoch_number: Option<EpochNumber>,
        sequencing_fees: Vec1<BuilderFee<TYPES>>,
    ) -> Self {
        Self {
            encoded_transactions,
            metadata,
            view_number,
            epoch_number,
            sequencing_fees,
        }
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_vid_commitment_display() {
        let vc = VidCommitment::V0(VidCommitment0::default());
        assert_eq!(
            format!("{vc}"),
            "HASH~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI"
        );
        assert_eq!(
            format!("{vc:?}"),
            "HASH~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI"
        );

        let vc = VidCommitment::V1(VidCommitment1::default());
        assert_eq!(
            format!("{vc}"),
            "AvidMCommit~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADr"
        );
        assert_eq!(
            format!("{vc:?}"),
            "AvidMCommit~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADr"
        );

        let vc = VidCommitment::V2(VidCommitment2::default());
        assert_eq!(
            format!("{vc}"),
            "AvidmGf2Commit~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACq"
        );
        assert_eq!(
            format!("{vc:?}"),
            "AvidmGf2Commit~AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACq"
        );
    }
}