dpp/data_contract/

mod.rs

use crate::serialization::{
    PlatformDeserializableWithBytesLenFromVersionedStructureTrusted,
    PlatformDeserializableWithBytesLenFromVersionedStructureUntrusted,
    PlatformDeserializableWithPotentialValidationFromVersionedStructureTrusted,
    PlatformDeserializableWithPotentialValidationFromVersionedStructureUntrusted,
    PlatformLimitDeserializableFromVersionedStructureTrusted,
    PlatformLimitDeserializableFromVersionedStructureUntrusted,
    PlatformSerializableWithPlatformVersion,
};
use std::collections::BTreeMap;

use derive_more::From;

use bincode::config::{BigEndian, Config, Configuration, Limit, NoLimit, Varint};
use once_cell::sync::Lazy;

pub mod errors;
pub mod extra;

mod generate_data_contract;

#[cfg(any(feature = "state-transitions", feature = "factories"))]
pub mod created_data_contract;
pub mod document_type;

pub mod v0;
pub mod v1;

#[cfg(feature = "factories")]
pub mod factory;
#[cfg(feature = "factories")]
pub use factory::*;
#[cfg(any(
    feature = "value-conversion",
    feature = "data-contract-cbor-conversion",
    feature = "json-conversion",
    feature = "serde-conversion"
))]
pub mod conversion;
#[cfg(feature = "client")]
mod data_contract_facade;
#[cfg(feature = "client")]
pub use data_contract_facade::DataContractFacade;
mod methods;
pub mod serialized_version;
pub use methods::*;
pub mod accessors;
pub mod associated_token;
pub mod change_control_rules;
pub mod config;
pub mod group;
pub mod storage_requirements;

use crate::data_contract::serialized_version::{
    DataContractInSerializationFormat, CONTRACT_DESERIALIZATION_LIMIT,
};
use crate::util::hash::hash_double_to_vec;

use crate::version::{FeatureVersion, PlatformVersion};
use crate::ProtocolError;
use crate::ProtocolError::{PlatformDeserializationError, PlatformSerializationError};

pub use crate::data_contract::associated_token::token_configuration::TokenConfiguration;
use crate::data_contract::group::Group;
use crate::data_contract::v0::DataContractV0;
use crate::data_contract::v1::DataContractV1;
use platform_version::TryIntoPlatformVersioned;
use platform_versioning::PlatformVersioned;
pub use serde_json::Value as JsonValue;

type JsonSchema = JsonValue;
type DefinitionName = String;
pub type DocumentName = String;
pub type TokenName = String;
pub type GroupContractPosition = u16;
pub type TokenContractPosition = u16;
pub type DataContractWithSerialization = (DataContract, Vec<u8>);
type PropertyPath = String;

pub const INITIAL_DATA_CONTRACT_VERSION: u32 = 1;

// Define static empty BTreeMaps and Vecs
static EMPTY_GROUPS: Lazy<BTreeMap<GroupContractPosition, Group>> = Lazy::new(BTreeMap::new);
static EMPTY_TOKENS: Lazy<BTreeMap<TokenContractPosition, TokenConfiguration>> =
    Lazy::new(BTreeMap::new);
static EMPTY_KEYWORDS: Lazy<Vec<String>> = Lazy::new(Vec::new);

/// Understanding Data Contract versioning
/// Data contract versioning is both for the code structure and for serialization.
///
/// The code structure is what is used in code to verify documents and is used in memory
/// There is generally only one code structure running at any given time, except in the case we
/// are switching protocol versions.
///
/// There can be a lot of serialization versions that are active, and serialization versions
/// should generally always be supported. This is because when we store something as version 1.
/// 10 years down the line when we unserialize this contract it will still be in version 1.
/// Deserialization of a data contract serialized in that version should be translated to the
/// current code structure version.
///
/// There are some scenarios to consider,
///
/// One such scenario is that the serialization version does not contain enough information for the
/// current code structure version.
///
/// Depending on the situation one of the following occurs:
/// - the contract structure can imply missing parts based on default behavior
/// - the contract structure can disable certain features dependant on missing information
/// - the contract might be unusable until it is updated by the owner
#[derive(Debug, Clone, PartialEq, From, PlatformVersioned)]
pub enum DataContract {
    V0(DataContractV0),
    V1(DataContractV1),
}

// Note: DataContract intentionally does NOT implement JsonConvertible / ValueConvertible.
// Round-tripping goes through the manual `Serialize` / `Deserialize` impls in
// `data_contract/conversion/serde/mod.rs`, which thread `DataContractInSerializationFormat`
// at the *currently active* `PlatformVersion` (see Critical-4 doc there).
//
// The two version-aware conversion traits are:
//   * `DataContractJsonConversionMethodsV0::from_json(value, full_validation, pv)` —
//     deserialize from JSON, running full schema validation when `full_validation` is
//     `true` (use on trust boundaries). Pass `false` to reconstruct already-trusted data
//     (e.g. storage reads) without re-validating. The canonical
//     `serde_json::from_value::<DataContract>` path also validates (it routes through
//     this with `full_validation = true`) — see the Critical-4 doc.
//   * `DataContractValueConversionMethodsV0::from_value(value, full_validation, pv)` —
//     same shape for `platform_value::Value`.
//
// For non-validating *serialization* to `platform_value::Value`, prefer
// `DataContractValueConversionMethodsV0::to_value(&dc, pv)` whenever a `PlatformVersion` is
// in hand — it selects the serialization format from the passed version. The serde-based
// alternatives (`serde_json::to_value(&dc)?` / `platform_value::to_value(&dc)?`) select the
// format from the *process-global* current platform version, which other threads may mutate
// concurrently (e.g. parallel tests building platforms at older protocol versions) — only
// use them where no explicit version is available.
// `DataContractInSerializationFormat` (the underlying serialization shape) DOES implement the
// canonical traits — see `data_contract/serialized_version/mod.rs`.

impl PlatformSerializableWithPlatformVersion for DataContract {
    type Error = ProtocolError;

    fn serialize_to_bytes_with_platform_version(
        &self,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<u8>, ProtocolError> {
        let serialization_format: DataContractInSerializationFormat =
            self.try_into_platform_versioned(platform_version)?;
        let config = bincode::config::standard()
            .with_big_endian()
            .with_no_limit();
        bincode::encode_to_vec(serialization_format, config).map_err(|e| {
            PlatformSerializationError(format!("unable to serialize DataContract: {}", e))
        })
    }

    fn serialize_consume_to_bytes_with_platform_version(
        self,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<u8>, ProtocolError> {
        let serialization_format: DataContractInSerializationFormat =
            self.try_into_platform_versioned(platform_version)?;
        let config = bincode::config::standard()
            .with_big_endian()
            .with_no_limit();
        bincode::encode_to_vec(serialization_format, config).map_err(|e| {
            PlatformSerializationError(format!("unable to serialize consume DataContract: {}", e))
        })
    }
}

/// Decodes the stored serialization format with the ordinary decoder: bytes
/// this node wrote itself (Drive state, wallet storage).
fn decode_serialization_format_trusted<C: Config>(
    data: &[u8],
    config: C,
    what: &str,
) -> Result<(DataContractInSerializationFormat, usize), ProtocolError> {
    bincode::borrow_decode_from_slice(data, config)
        .map_err(|e| PlatformDeserializationError(format!("unable to deserialize {}: {}", what, e)))
}

/// Decodes the serialization format with the untrusted decoder: bytes from a
/// peer, a client, a proof or a host caller.
fn decode_serialization_format_untrusted<C: Config>(
    data: &[u8],
    config: C,
    what: &str,
) -> Result<(DataContractInSerializationFormat, usize), ProtocolError> {
    bincode::borrow_decode_from_slice_untrusted(data, config)
        .map_err(|e| PlatformDeserializationError(format!("unable to deserialize {}: {}", what, e)))
}

fn no_limit_config() -> Configuration<BigEndian, Varint, NoLimit> {
    bincode::config::standard()
        .with_big_endian()
        .with_no_limit()
}

fn contract_limit_config() -> Configuration<BigEndian, Varint, Limit<CONTRACT_DESERIALIZATION_LIMIT>>
{
    bincode::config::standard()
        .with_big_endian()
        .with_limit::<CONTRACT_DESERIALIZATION_LIMIT>()
}

impl PlatformDeserializableWithPotentialValidationFromVersionedStructureTrusted for DataContract {
    fn versioned_deserialize_trusted(
        data: &[u8],
        full_validation: bool,
        platform_version: &PlatformVersion,
    ) -> Result<Self, ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, _) =
            decode_serialization_format_trusted(data, no_limit_config(), "DataContract")?;
        DataContract::try_from_platform_versioned(
            data_contract_in_serialization_format,
            full_validation,
            &mut vec![],
            platform_version,
        )
    }
}

impl PlatformDeserializableWithPotentialValidationFromVersionedStructureUntrusted for DataContract {
    fn versioned_deserialize_untrusted(
        data: &[u8],
        full_validation: bool,
        platform_version: &PlatformVersion,
    ) -> Result<Self, ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, _) =
            decode_serialization_format_untrusted(data, no_limit_config(), "DataContract")?;
        DataContract::try_from_platform_versioned(
            data_contract_in_serialization_format,
            full_validation,
            &mut vec![],
            platform_version,
        )
    }
}

impl PlatformDeserializableWithBytesLenFromVersionedStructureTrusted for DataContract {
    fn versioned_deserialize_with_bytes_len_trusted(
        data: &[u8],
        full_validation: bool,
        platform_version: &PlatformVersion,
    ) -> Result<(Self, usize), ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, len) =
            decode_serialization_format_trusted(data, no_limit_config(), "DataContract")?;
        Ok((
            DataContract::try_from_platform_versioned(
                data_contract_in_serialization_format,
                full_validation,
                &mut vec![],
                platform_version,
            )?,
            len,
        ))
    }
}

impl PlatformDeserializableWithBytesLenFromVersionedStructureUntrusted for DataContract {
    fn versioned_deserialize_with_bytes_len_untrusted(
        data: &[u8],
        full_validation: bool,
        platform_version: &PlatformVersion,
    ) -> Result<(Self, usize), ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, len) =
            decode_serialization_format_untrusted(data, no_limit_config(), "DataContract")?;
        Ok((
            DataContract::try_from_platform_versioned(
                data_contract_in_serialization_format,
                full_validation,
                &mut vec![],
                platform_version,
            )?,
            len,
        ))
    }
}

impl PlatformLimitDeserializableFromVersionedStructureTrusted for DataContract {
    fn versioned_limit_deserialize_trusted(
        data: &[u8],
        platform_version: &PlatformVersion,
    ) -> Result<Self, ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, _) = decode_serialization_format_trusted(
            data,
            contract_limit_config(),
            "DataContract with limit",
        )?;
        // we always want to validate when we have a limit, because limit means the data isn't coming from Drive
        DataContract::try_from_platform_versioned(
            data_contract_in_serialization_format,
            true,
            &mut vec![],
            platform_version,
        )
    }
}

impl PlatformLimitDeserializableFromVersionedStructureUntrusted for DataContract {
    fn versioned_limit_deserialize_untrusted(
        data: &[u8],
        platform_version: &PlatformVersion,
    ) -> Result<Self, ProtocolError>
    where
        Self: Sized,
    {
        let (data_contract_in_serialization_format, _) = decode_serialization_format_untrusted(
            data,
            contract_limit_config(),
            "DataContract with limit",
        )?;
        // we always want to validate when we have a limit, because limit means the data isn't coming from Drive
        DataContract::try_from_platform_versioned(
            data_contract_in_serialization_format,
            true,
            &mut vec![],
            platform_version,
        )
    }
}

impl DataContract {
    pub fn as_v0(&self) -> Option<&DataContractV0> {
        match self {
            DataContract::V0(v0) => Some(v0),
            _ => None,
        }
    }

    pub fn as_v0_mut(&mut self) -> Option<&mut DataContractV0> {
        match self {
            DataContract::V0(v0) => Some(v0),
            _ => None,
        }
    }

    pub fn into_v0(self) -> Option<DataContractV0> {
        match self {
            DataContract::V0(v0) => Some(v0),
            _ => None,
        }
    }

    pub fn as_v1(&self) -> Option<&DataContractV1> {
        match self {
            DataContract::V1(v1) => Some(v1),
            _ => None,
        }
    }

    pub fn as_v1_mut(&mut self) -> Option<&mut DataContractV1> {
        match self {
            DataContract::V1(v1) => Some(v1),
            _ => None,
        }
    }

    pub fn into_v1(self) -> Option<DataContractV1> {
        match self {
            DataContract::V1(v1) => Some(v1),
            _ => None,
        }
    }

    /// This should only ever be used in tests, as it will change
    #[cfg(test)]
    pub fn into_latest(self) -> Option<DataContractV1> {
        self.into_v1()
    }

    /// This should only ever be used in tests, as it will change
    #[cfg(test)]
    pub fn as_latest(&self) -> Option<&DataContractV1> {
        match self {
            DataContract::V1(v1) => Some(v1),
            _ => None,
        }
    }

    /// This should only ever be used in tests, as it will change
    #[cfg(test)]
    pub fn as_latest_mut(&mut self) -> Option<&mut DataContractV1> {
        match self {
            DataContract::V1(v1) => Some(v1),
            _ => None,
        }
    }

    pub fn check_version_is_active(
        protocol_version: u32,
        data_contract_system_version: FeatureVersion,
    ) -> Result<bool, ProtocolError> {
        let platform_version = PlatformVersion::get(protocol_version)?;
        Ok(platform_version
            .dpp
            .contract_versions
            .contract_structure_version
            == data_contract_system_version)
    }

    pub fn hash(&self, platform_version: &PlatformVersion) -> Result<Vec<u8>, ProtocolError> {
        Ok(hash_double_to_vec(
            self.serialize_to_bytes_with_platform_version(platform_version)?,
        ))
    }
}

#[cfg(test)]
mod tests {
    use crate::data_contract::accessors::v0::DataContractV0Getters;
    use crate::data_contract::config::v0::DataContractConfigGettersV0;
    use crate::data_contract::document_type::accessors::DocumentTypeV0Getters;
    use crate::data_contract::storage_requirements::keys_for_document_type::StorageKeyRequirements;
    use crate::data_contract::DataContract;
    use crate::serialization::{
        PlatformDeserializableWithBytesLenFromVersionedStructureTrusted,
        PlatformDeserializableWithBytesLenFromVersionedStructureUntrusted,
        PlatformDeserializableWithPotentialValidationFromVersionedStructureTrusted,
        PlatformDeserializableWithPotentialValidationFromVersionedStructureUntrusted,
        PlatformLimitDeserializableFromVersionedStructureTrusted,
        PlatformLimitDeserializableFromVersionedStructureUntrusted,
        PlatformSerializableWithPlatformVersion,
    };
    use crate::system_data_contracts::load_system_data_contract;
    use crate::tests::fixtures::{
        get_dashpay_contract_fixture, get_dashpay_contract_with_generalized_encryption_key_fixture,
    };
    use crate::version::PlatformVersion;
    use crate::ProtocolError;
    use data_contracts::SystemDataContract::Dashpay;

    #[test]
    fn test_contract_serialization() {
        let platform_version = PlatformVersion::latest();
        let data_contract = load_system_data_contract(Dashpay, platform_version)
            .expect("expected dashpay contract");
        let serialized = data_contract
            .serialize_to_bytes_with_platform_version(platform_version)
            .expect("expected to serialize data contract");
        assert_eq!(
            serialized[0],
            platform_version
                .dpp
                .contract_versions
                .contract_serialization_version
                .default_current_version as u8
        );

        let unserialized =
            DataContract::versioned_deserialize_untrusted(&serialized, true, platform_version)
                .expect("expected to deserialize data contract");

        assert_eq!(data_contract, unserialized);
    }

    /// The trusted twins run the ordinary decoder over the same serialization
    /// format, so on well-formed bytes they must agree with the untrusted
    /// entry points exactly, consumed length included.
    #[test]
    fn trusted_and_untrusted_versioned_deserialize_agree() {
        let platform_version = PlatformVersion::latest();
        let data_contract = load_system_data_contract(Dashpay, platform_version)
            .expect("expected dashpay contract");
        let serialized = data_contract
            .serialize_to_bytes_with_platform_version(platform_version)
            .expect("expected to serialize data contract");

        let trusted =
            DataContract::versioned_deserialize_trusted(&serialized, true, platform_version)
                .expect("trusted deserialize");
        let untrusted =
            DataContract::versioned_deserialize_untrusted(&serialized, true, platform_version)
                .expect("untrusted deserialize");
        assert_eq!(trusted, untrusted);
        assert_eq!(trusted, data_contract);

        let (trusted, trusted_len) = DataContract::versioned_deserialize_with_bytes_len_trusted(
            &serialized,
            true,
            platform_version,
        )
        .expect("trusted deserialize with bytes len");
        let (untrusted, untrusted_len) =
            DataContract::versioned_deserialize_with_bytes_len_untrusted(
                &serialized,
                true,
                platform_version,
            )
            .expect("untrusted deserialize with bytes len");
        assert_eq!(trusted, untrusted);
        assert_eq!(trusted_len, untrusted_len);
        assert_eq!(trusted_len, serialized.len());

        let trusted =
            DataContract::versioned_limit_deserialize_trusted(&serialized, platform_version)
                .expect("trusted limit deserialize");
        let untrusted =
            DataContract::versioned_limit_deserialize_untrusted(&serialized, platform_version)
                .expect("untrusted limit deserialize");
        assert_eq!(trusted, untrusted);
        assert_eq!(trusted, data_contract);
    }

    #[test]
    fn trusted_versioned_deserialize_rejects_malformed_input() {
        let platform_version = PlatformVersion::latest();
        for input in [vec![0xFFu8; 16], vec![]] {
            assert!(matches!(
                DataContract::versioned_deserialize_trusted(&input, true, platform_version),
                Err(ProtocolError::PlatformDeserializationError(_))
            ));
            assert!(matches!(
                DataContract::versioned_deserialize_with_bytes_len_trusted(
                    &input,
                    true,
                    platform_version
                ),
                Err(ProtocolError::PlatformDeserializationError(_))
            ));
            assert!(matches!(
                DataContract::versioned_limit_deserialize_trusted(&input, platform_version),
                Err(ProtocolError::PlatformDeserializationError(_))
            ));
        }
    }

    #[test]
    fn test_contract_can_have_specialized_contract_encryption_decryption_keys() {
        let data_contract =
            get_dashpay_contract_with_generalized_encryption_key_fixture(None, 0, 1)
                .data_contract_owned();
        assert_eq!(
            data_contract
                .config()
                .requires_identity_decryption_bounded_key(),
            Some(StorageKeyRequirements::Unique)
        );
        assert_eq!(
            data_contract
                .config()
                .requires_identity_encryption_bounded_key(),
            Some(StorageKeyRequirements::Unique)
        );
    }

    #[test]
    fn test_contract_document_type_can_have_specialized_contract_encryption_decryption_keys() {
        let data_contract = get_dashpay_contract_fixture(None, 0, 1).data_contract_owned();
        assert_eq!(
            data_contract
                .document_type_for_name("contactRequest")
                .expect("expected document type")
                .requires_identity_decryption_bounded_key(),
            Some(StorageKeyRequirements::MultipleReferenceToLatest)
        );
        assert_eq!(
            data_contract
                .document_type_for_name("contactRequest")
                .expect("expected document type")
                .requires_identity_encryption_bounded_key(),
            Some(StorageKeyRequirements::MultipleReferenceToLatest)
        );
    }
}