diff --git a/book/src/data-model/documents.md b/book/src/data-model/documents.md index 7ea45c75ff2..26e2bad0428 100644 --- a/book/src/data-model/documents.md +++ b/book/src/data-model/documents.md @@ -250,6 +250,43 @@ pub const INITIAL_REVISION: u64 = 1; Revision 0 is never used for active documents. This allows `0` to serve as a sentinel value meaning "no revision" in some contexts. +## Immutable Properties on Mutable Document Types + +A document type either allows replaces (`documentsMutable: true`, the default) or freezes its documents entirely. Protocol version 14 adds a middle ground: the doctype-level `immutable` keyword lists top-level properties that are frozen at creation while the rest of the document stays replaceable. + +```json +"post": { + "type": "object", + "documentsMutable": true, + "properties": { + "author": { "type": "string", "maxLength": 63, "position": 0 }, + "body": { "type": "string", "maxLength": 500, "position": 1 } + }, + "required": ["author", "body"], + "immutable": ["author"], + "additionalProperties": false +} +``` + +A second list, `immutableAllowSetting`, relaxes the first for optional properties that are not known at creation: a property listed there may still be set by a replace while the stored document has no value for it, and is frozen from then on (it can neither change nor be removed). Every entry must also be in `immutable`. + +```json +"immutable": ["author", "mood"], +"immutableAllowSetting": ["mood"] +``` + +The parser (generation 3, meta-schema v3) checks both lists when a contract enters the chain: + +- Every `immutable` entry names a declared top-level property. System properties (`$`-prefixed) are refused because the platform manages them, and nested paths are refused: list the containing object to freeze it whole, nested values included. A `transient` property is refused too: it is never stored, so once frozen it could never be written, and combined with `required` no replace could pass at all. +- The replace compares stored and supplied values by underlying data, recursing into objects regardless of member order and into arrays position by position, with integer widths ignored. Storage reorders object members by schema position and narrows integers, so a byte-for-byte comparison would flag an untouched object as changed. +- The lists are only allowed when `documentsMutable` is true. On an immutable document type every property is already frozen. +- Every `immutableAllowSetting` entry is also in `immutable`; on its own the allowance means nothing. +- On contract update `immutable` may gain entries but never lose one, and `immutableAllowSetting` may lose entries but only gain one for a property that becomes immutable in the same update (`DocumentTypeUpdateError` otherwise). Each rule keeps the promise documents were created under: nothing frozen becomes editable, and nothing already frozen starts accepting a late set. The schema compatibility differ strips both keys, like `indices` and `required`, so `validate_update` v1 is the single judge. + +Enforcement lives in the replace action's state validation (generation 1). The action already records which top-level properties differ from the stored document in `changed_data_fields` (the same set that scopes `refersTo` re-validation), and alongside it which of those the stored document had no value for (`added_data_fields`). A changed property in the type's `immutable_fields()` fails the replace with `DocumentImmutablePropertyChangedError` (state code 40128) unless it is in `immutable_fields_allow_setting()` and was absent before. "Differ" covers a changed value, a property the stored document lacked, and a property the replace dropped. Transfers, price updates and purchases carry no property data and are unaffected. + +In Rust the lists are `DocumentTypeV2Getters::immutable_fields()` and `immutable_fields_allow_setting()`. Earlier document type generations return empty sets. + ## Rules and Guidelines **Do:** diff --git a/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json b/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json index e4c2462dc19..a70bcd2c137 100644 --- a/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json +++ b/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json @@ -933,6 +933,22 @@ "type": "string" } }, + "immutable": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "description": "Names of top-level properties whose values are frozen at document creation on a mutable document type: a replace that changes, adds or removes any of them is rejected (DocumentImmutablePropertyChangedError, code 40128), unless the property is listed under immutableAllowSetting and the stored document has no value for it yet. Only allowed when documentsMutable is true (the default), where the other properties stay replaceable; on an immutable document type every property is already frozen. Every entry must name a declared top-level property that is not transient: system properties ($-prefixed) are excluded because the platform manages them, nested paths are not accepted (list the containing object to freeze it whole), and a transient property is never stored so it could never be written once frozen. On contract update the list may gain entries but never lose one. Available from protocol version 14." + }, + "immutableAllowSetting": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "description": "The subset of the immutable properties a replace may still set while the stored document has no value for them: a first-time set is accepted, after which the property is frozen like the rest of the immutable list (it can neither change nor be removed). Every entry must also appear in immutable; it is only meaningful for optional properties, since a required one always has a value from creation. On contract update an entry may be dropped (tightening) at any time, but may only be added for a property that becomes immutable in the same update: an already-immutable property cannot start allowing a set. Available from protocol version 14." + }, "additionalProperties": { "type": "boolean", "const": false diff --git a/packages/rs-dpp/src/data_contract/document_type/accessors/mod.rs b/packages/rs-dpp/src/data_contract/document_type/accessors/mod.rs index 6ea4e0cb2a8..4581a528e4d 100644 --- a/packages/rs-dpp/src/data_contract/document_type/accessors/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/accessors/mod.rs @@ -940,6 +940,11 @@ impl DocumentTypeV1Getters for DocumentTypeMutRef<'_> { } } +/// What `immutable_fields` returns for the document type generations that +/// predate the keyword: V0 and V1 have no field to borrow from, and the +/// getter hands out a reference. +static NO_IMMUTABLE_FIELDS: BTreeSet = BTreeSet::new(); + impl DocumentTypeV2Getters for DocumentType { fn documents_countable(&self) -> bool { match self { @@ -980,6 +985,22 @@ impl DocumentTypeV2Getters for DocumentType { DocumentType::V2(v2) => v2.index_only(), } } + + fn immutable_fields(&self) -> &BTreeSet { + match self { + DocumentType::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentType::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentType::V2(v2) => v2.immutable_fields(), + } + } + + fn immutable_fields_allow_setting(&self) -> &BTreeSet { + match self { + DocumentType::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentType::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentType::V2(v2) => v2.immutable_fields_allow_setting(), + } + } } impl DocumentTypeV2Setters for DocumentType { @@ -1056,6 +1077,22 @@ impl DocumentTypeV2Getters for DocumentTypeRef<'_> { DocumentTypeRef::V2(v2) => v2.index_only(), } } + + fn immutable_fields(&self) -> &BTreeSet { + match self { + DocumentTypeRef::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeRef::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeRef::V2(v2) => v2.immutable_fields(), + } + } + + fn immutable_fields_allow_setting(&self) -> &BTreeSet { + match self { + DocumentTypeRef::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeRef::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeRef::V2(v2) => v2.immutable_fields_allow_setting(), + } + } } impl DocumentTypeV2Getters for DocumentTypeMutRef<'_> { @@ -1098,6 +1135,22 @@ impl DocumentTypeV2Getters for DocumentTypeMutRef<'_> { DocumentTypeMutRef::V2(v2) => v2.index_only(), } } + + fn immutable_fields(&self) -> &BTreeSet { + match self { + DocumentTypeMutRef::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeMutRef::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeMutRef::V2(v2) => v2.immutable_fields(), + } + } + + fn immutable_fields_allow_setting(&self) -> &BTreeSet { + match self { + DocumentTypeMutRef::V0(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeMutRef::V1(_) => &NO_IMMUTABLE_FIELDS, + DocumentTypeMutRef::V2(v2) => v2.immutable_fields_allow_setting(), + } + } } #[cfg(test)] diff --git a/packages/rs-dpp/src/data_contract/document_type/accessors/v2/mod.rs b/packages/rs-dpp/src/data_contract/document_type/accessors/v2/mod.rs index 68017106e45..c577979d8f0 100644 --- a/packages/rs-dpp/src/data_contract/document_type/accessors/v2/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/accessors/v2/mod.rs @@ -1,3 +1,5 @@ +use std::collections::BTreeSet; + /// Trait providing getters for DocumentTypeV2-specific fields. pub trait DocumentTypeV2Getters { /// Returns whether documents of this type are countable. @@ -30,6 +32,22 @@ pub trait DocumentTypeV2Getters { /// each terminating in an `Item` keyed by the index's `terminal` /// property. Only what is in the indexes exists and is recoverable. fn index_only(&self) -> bool; + + /// The top-level properties frozen at document creation on a mutable + /// document type (the `immutable` keyword, protocol version 14). A + /// replace that changes, adds or removes any of them is rejected with + /// `DocumentImmutablePropertyChangedError`. Empty on document types + /// that predate the keyword and on types whose documents are not + /// mutable, where every property is already immutable. + fn immutable_fields(&self) -> &BTreeSet; + + /// The subset of [`Self::immutable_fields`] a replace may still set while + /// the stored document has no value for them (the + /// `immutableAllowSetting` keyword, protocol version 14). Once present + /// they are frozen like the rest of the list. Always a subset of + /// [`Self::immutable_fields`]; empty on document types that predate the + /// keyword. + fn immutable_fields_allow_setting(&self) -> &BTreeSet; } /// Trait providing setters for DocumentTypeV2-specific fields. diff --git a/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs index 13a346b7790..551111c66a5 100644 --- a/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs @@ -1971,6 +1971,148 @@ pub(super) fn parse_index_only_keyword(schema: &Value) -> Result Result, ProtocolError> { + let structure_error = |message: String| { + consensus_or_protocol_data_contract_error(DataContractError::InvalidContractStructure( + message, + )) + }; + + let Ok(schema_map) = schema.to_map() else { + return Ok(BTreeSet::new()); + }; + let Some(value) = Value::get_optional_from_map(schema_map, keyword) else { + return Ok(BTreeSet::new()); + }; + let Value::Array(entries) = value else { + return Err(structure_error(format!( + "document type \"{name}\": `{keyword}` must be an array of top-level property names" + ))); + }; + + entries + .iter() + .map(|entry| { + entry.as_text().map(str::to_owned).ok_or_else(|| { + structure_error(format!( + "document type \"{name}\": every `{keyword}` entry must be a property name \ + (a string)" + )) + }) + }) + .collect() +} + +/// Write the `immutable` and `immutableAllowSetting` property lists onto the +/// parsed document type and, under full validation, check them against the +/// rest of the type. +/// +/// The checks are schema lints rather than storage-layout invariants: an +/// entry naming an unknown property could never match a changed field, and a +/// list on a non-mutable type is unreachable because replaces of such +/// documents are refused before any property is compared. So, like the +/// keep-history/delete check in the generation-3 driver, they only run for +/// contracts entering the chain. Stored contracts bypass them, which keeps a +/// later tightening of these rules from ever making a committed contract +/// unreadable. +/// +/// Entries are top-level property names only. A nested path is refused with +/// a hint to list the containing object instead: the replace action compares +/// top-level properties, so freezing an object freezes everything inside it. +/// Every `immutableAllowSetting` entry must also be in `immutable`: the +/// second list only relaxes the first (a frozen property may still be set +/// while the stored document has no value for it), so on its own it means +/// nothing. +pub(super) fn apply_immutable_fields( + document_type: &mut DocumentTypeV2, + immutable_fields: BTreeSet, + immutable_fields_allow_setting: BTreeSet, + name: &str, + full_validation: bool, +) -> Result<(), ProtocolError> { + let structure_error = |message: String| { + consensus_or_protocol_data_contract_error(DataContractError::InvalidContractStructure( + message, + )) + }; + + if full_validation { + if !immutable_fields.is_empty() && !document_type.documents_mutable { + return Err(structure_error(format!( + "document type \"{name}\" lists `immutable` properties but its documents are not \ + mutable (documentsMutable: false), so every property is already immutable; \ + remove the `immutable` list or set documentsMutable: true" + ))); + } + + for property in &immutable_fields { + if property.starts_with('$') { + return Err(structure_error(format!( + "document type \"{name}\" lists system property \"{property}\" as immutable: \ + system properties are managed by the platform and cannot be listed" + ))); + } + if !document_type.properties.contains_key(property) { + let hint = if property.contains('.') { + "; nested paths are not accepted, list the top-level property that contains \ + it to freeze it whole" + } else { + "" + }; + return Err(structure_error(format!( + "document type \"{name}\" lists \"{property}\" as immutable, but it is not a \ + top-level property of the document type{hint}" + ))); + } + // A transient property is never stored, so the stored document + // always lacks it and any replace that supplies it counts as + // setting it. Frozen at "absent", it could never be written; if + // it is also required, no replace could ever pass at all. + if document_type.transient_fields.contains(property) { + return Err(structure_error(format!( + "document type \"{name}\" lists \"{property}\" as both transient and \ + immutable: a transient property is never stored, so every replace that \ + supplies it would be refused as changing an immutable property; remove it \ + from one of the two lists" + ))); + } + } + + for property in &immutable_fields_allow_setting { + if !immutable_fields.contains(property) { + return Err(structure_error(format!( + "document type \"{name}\" lists \"{property}\" in `immutableAllowSetting`, but \ + it is not in `immutable`: only an immutable property can be allowed to be \ + set while absent" + ))); + } + } + } + + document_type.immutable_fields = immutable_fields; + document_type.immutable_fields_allow_setting = immutable_fields_allow_setting; + + Ok(()) +} + /// Write the `indexOnly` flag onto the parsed document type, normalize each /// index's `terminal` (an omitted terminal defaults to `$ownerId`), and run /// the structural cross-checks the index-only on-disk layout depends on. diff --git a/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/immutable_tests.rs b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/immutable_tests.rs new file mode 100644 index 00000000000..f2e65b14608 --- /dev/null +++ b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/immutable_tests.rs @@ -0,0 +1,427 @@ +//! The `immutable` doctype keyword: parser-generation gating and the +//! structural rules. +//! +//! `immutable` joined the grammar at generation 3 (meta-schema v3, protocol +//! version 14) next to `indexOnly`. It is a doctype-level keyword, with the +//! loose-grammar gating that implies on the pre-PV14 side: ignored by earlier +//! generations on the non-validating path (how they treat every doctype +//! keyword they predate) and rejected by their meta-schemas under +//! `full_validation`. +//! +//! The rules themselves (`apply_immutable_fields`) are schema lints, so unlike +//! the indexOnly matrix they only run under `full_validation`; the +//! non-validating path, which stored contracts take, records the list as +//! declared. Only the array shape (an array of strings) is enforced on both +//! paths. + +use super::*; +use crate::consensus::basic::BasicError; +use crate::consensus::ConsensusError; +use crate::data_contract::document_type::accessors::DocumentTypeV2Getters; +use crate::data_contract::errors::DataContractError; +use platform_value::platform_value; +use std::collections::BTreeSet; + +/// Parse through this generation with validation mode spelled out. +fn parse_with( + schema: Value, + platform_version: &PlatformVersion, + full_validation: bool, +) -> Result { + let config = DataContractConfig::default_for_version(platform_version) + .expect("default config available on this platform version"); + try_from_schema_generation_3( + Identifier::new([1; 32]), + 1, + config.version(), + "post", + schema, + None, + &BTreeMap::new(), + &config, + full_validation, + &mut vec![], + platform_version, + ) +} + +/// Parse through the real dispatcher, which picks the parser generation out +/// of the platform version's `try_from_schema` table value (generation 2 at +/// PV13, generation 3 at PV14). +fn parse_dispatched( + schema: Value, + platform_version: &PlatformVersion, + full_validation: bool, +) -> Result { + let config = DataContractConfig::default_for_version(platform_version) + .expect("default config available on this platform version"); + DocumentType::try_from_schema( + Identifier::new([1; 32]), + 1, + config.version(), + "post", + schema, + None, + &BTreeMap::new(), + &config, + full_validation, + &mut vec![], + platform_version, + ) +} + +/// A mutable `post` type whose `author` is frozen at creation: `body` stays +/// editable, and `meta` is a nested object so the nested-path rule has +/// something to point at. +fn post_schema() -> Value { + platform_value!({ + "type": "object", + "documentsMutable": true, + "properties": { + "author": { "type": "string", "maxLength": 63, "position": 0 }, + "body": { "type": "string", "maxLength": 500, "position": 1 }, + "meta": { + "type": "object", + "position": 2, + "properties": { + "tag": { "type": "string", "maxLength": 30, "position": 0 } + }, + "additionalProperties": false + } + }, + "required": ["author", "body"], + "immutable": ["author"], + "additionalProperties": false + }) +} + +/// The base schema with one doctype-level key set (added or replaced). +fn post_schema_with(key: &str, value: Value) -> Value { + let mut schema = post_schema(); + schema.set_value(key, value).expect("doctype key applies"); + schema +} + +fn names(entries: &[&str]) -> BTreeSet { + entries.iter().map(|entry| entry.to_string()).collect() +} + +/// The lints surface as `InvalidContractStructure` either directly or, with +/// the `validation` feature on, wrapped as the basic `ContractError`. +fn expect_structure_error(result: Result, needle: &str) { + let message = match result { + Err(ProtocolError::DataContractError(DataContractError::InvalidContractStructure( + message, + ))) => message, + Err(ProtocolError::ConsensusError(boxed)) => match *boxed { + ConsensusError::BasicError(BasicError::ContractError( + DataContractError::InvalidContractStructure(message), + )) => message, + other => { + panic!("expected InvalidContractStructure containing {needle:?}, got {other:?}") + } + }, + Err(other) => { + panic!("expected InvalidContractStructure containing {needle:?}, got {other}") + } + Ok(parsed) => { + panic!("expected rejection containing {needle:?}, but the schema parsed: {parsed:?}") + } + }; + assert!( + message.contains(needle), + "expected structure error containing {needle:?}, got: {message}" + ); +} + +// ── the happy path ────────────────────────────────────────────────────── + +#[test] +fn immutable_list_parses_on_both_validation_modes() { + let platform_version = PlatformVersion::latest(); + + for full_validation in [false, true] { + let document_type = parse_with(post_schema(), platform_version, full_validation) + .unwrap_or_else(|error| { + panic!("post schema should parse (full_validation: {full_validation}): {error}") + }); + + assert!(document_type.documents_mutable); + assert_eq!(document_type.immutable_fields(), &names(&["author"])); + } +} + +#[test] +fn omitted_keyword_means_nothing_is_frozen() { + let mut schema = post_schema(); + let _ = schema.remove_optional_value("immutable"); + + let document_type = parse_with(schema, PlatformVersion::latest(), true).expect("schema parses"); + + assert!(document_type.immutable_fields().is_empty()); +} + +#[test] +fn accepts_an_object_property_listed_whole() { + let schema = post_schema_with("immutable", platform_value!(["author", "meta"])); + + let document_type = + parse_with(schema, PlatformVersion::latest(), true).expect("object property accepted"); + + assert_eq!( + document_type.immutable_fields(), + &names(&["author", "meta"]) + ); +} + +// ── the lints (full validation only) ──────────────────────────────────── + +#[test] +fn rejects_an_unknown_property() { + let schema = post_schema_with("immutable", platform_value!(["author", "nope"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "\"nope\" as immutable, but it is not a top-level property", + ); +} + +#[test] +fn rejects_a_nested_path_with_a_hint() { + let schema = post_schema_with("immutable", platform_value!(["meta.tag"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "nested paths are not accepted", + ); +} + +#[test] +fn rejects_a_system_property() { + let schema = post_schema_with("immutable", platform_value!(["$ownerId"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "system property \"$ownerId\"", + ); +} + +/// A transient property is never stored, so frozen it could never be +/// written, and required as well it would leave the type permanently +/// uneditable (supplying it fails the immutable check, omitting it fails +/// required-field validation). The grow-only update rule would then keep +/// it that way, so the overlap is refused at registration. +#[test] +fn rejects_a_transient_property() { + let schema = post_schema_with("transient", platform_value!(["author"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "\"author\" as both transient and immutable", + ); +} + +#[test] +fn rejects_the_list_on_a_non_mutable_document_type() { + let schema = post_schema_with("documentsMutable", Value::Bool(false)); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "documentsMutable: false", + ); +} + +#[test] +fn non_mutable_document_type_without_the_list_still_parses() { + let mut schema = post_schema_with("documentsMutable", Value::Bool(false)); + let _ = schema.remove_optional_value("immutable"); + + let document_type = parse_with(schema, PlatformVersion::latest(), true) + .expect("an immutable document type without the keyword is the normal case"); + + assert!(document_type.immutable_fields().is_empty()); +} + +#[test] +fn rejects_duplicate_entries_under_full_validation() { + // `uniqueItems` in meta-schema v3. + let schema = post_schema_with("immutable", platform_value!(["author", "author"])); + assert!( + parse_with(schema, PlatformVersion::latest(), true).is_err(), + "meta-schema v3 must reject a duplicated immutable entry" + ); +} + +// ── the array shape (both validation modes) ───────────────────────────── + +#[test] +fn rejects_a_non_array_value_on_both_modes() { + for full_validation in [false, true] { + let schema = post_schema_with("immutable", Value::Text("author".to_string())); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), full_validation), + "must be an array of top-level property names", + ); + } +} + +#[test] +fn rejects_a_non_string_entry_on_both_modes() { + for full_validation in [false, true] { + let schema = post_schema_with("immutable", platform_value!(["author", 7])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), full_validation), + "every `immutable` entry must be a property name", + ); + } +} + +// ── the stored-contract path ──────────────────────────────────────────── + +/// Pins that the lints are validation-only: a stored contract is re-parsed +/// without validation and must come back exactly as declared, so a future +/// tightening of the rules can never make a committed contract unreadable. +#[test] +fn non_validating_parse_records_the_list_as_declared() { + let schema = post_schema_with("immutable", platform_value!(["author", "nope"])); + + let document_type = parse_with(schema, PlatformVersion::latest(), false) + .expect("the non-validating path records the declaration without judging it"); + + assert_eq!( + document_type.immutable_fields(), + &names(&["author", "nope"]) + ); +} + +// ── generation gating ─────────────────────────────────────────────────── + +#[test] +fn immutable_keyword_is_inert_below_generation_3_without_validation() { + let platform_version_13 = PlatformVersion::get(13).expect("PV13 exists"); + + // Generation 2 ignores unknown doctype keys on the non-validating path, + // exactly how it treats every keyword it predates, so the parse succeeds + // and nothing is frozen. + let document_type = parse_dispatched(post_schema(), platform_version_13, false) + .expect("generation 2 ignores unknown doctype-level keywords when not validating"); + assert!( + document_type.immutable_fields().is_empty(), + "generation 2 must not record immutable properties" + ); + + // Under full validation the v2 meta-schema rejects the unknown key. + assert!( + parse_dispatched(post_schema(), platform_version_13, true).is_err(), + "meta-schema v2 must reject the immutable keyword" + ); +} + +#[test] +fn immutable_list_survives_the_dispatcher_at_latest() { + let document_type = parse_dispatched(post_schema(), PlatformVersion::latest(), true) + .expect("post schema parses through the dispatcher at PV14"); + assert_eq!(document_type.immutable_fields(), &names(&["author"])); +} + +// ── immutableAllowSetting ─────────────────────────────────────────────── + +/// `post_schema` with `meta` frozen as well and allowed to be set once. +fn post_schema_allowing_meta_once() -> Value { + let mut schema = post_schema_with("immutable", platform_value!(["author", "meta"])); + schema + .set_value("immutableAllowSetting", platform_value!(["meta"])) + .expect("doctype key applies"); + schema +} + +#[test] +fn allow_setting_list_parses_on_both_validation_modes() { + let platform_version = PlatformVersion::latest(); + + for full_validation in [false, true] { + let document_type = parse_with( + post_schema_allowing_meta_once(), + platform_version, + full_validation, + ) + .unwrap_or_else(|error| { + panic!( + "allow-setting schema should parse (full_validation: {full_validation}): \ + {error}" + ) + }); + + assert_eq!( + document_type.immutable_fields(), + &names(&["author", "meta"]) + ); + assert_eq!( + document_type.immutable_fields_allow_setting(), + &names(&["meta"]) + ); + } +} + +#[test] +fn omitted_allow_setting_keyword_means_nothing_may_be_set_late() { + let document_type = + parse_with(post_schema(), PlatformVersion::latest(), true).expect("schema parses"); + + assert!(document_type.immutable_fields_allow_setting().is_empty()); +} + +#[test] +fn rejects_an_allow_setting_entry_that_is_not_immutable() { + // `body` is a real property, but not in `immutable`. + let schema = post_schema_with("immutableAllowSetting", platform_value!(["body"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "\"body\" in `immutableAllowSetting`, but it is not in `immutable`", + ); +} + +#[test] +fn rejects_an_allow_setting_entry_naming_an_unknown_property() { + // Unknown to the type, so also absent from `immutable`. + let schema = post_schema_with("immutableAllowSetting", platform_value!(["nope"])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), true), + "\"nope\" in `immutableAllowSetting`, but it is not in `immutable`", + ); +} + +#[test] +fn rejects_a_non_string_allow_setting_entry_on_both_modes() { + for full_validation in [false, true] { + let schema = post_schema_with("immutableAllowSetting", platform_value!(["author", 7])); + expect_structure_error( + parse_with(schema, PlatformVersion::latest(), full_validation), + "every `immutableAllowSetting` entry must be a property name", + ); + } +} + +#[test] +fn non_validating_parse_records_the_allow_setting_list_as_declared() { + // Not in `immutable`; the lint is validation-only. + let schema = post_schema_with("immutableAllowSetting", platform_value!(["body"])); + + let document_type = parse_with(schema, PlatformVersion::latest(), false) + .expect("the non-validating path records the declaration without judging it"); + + assert_eq!( + document_type.immutable_fields_allow_setting(), + &names(&["body"]) + ); +} + +#[test] +fn allow_setting_keyword_is_inert_below_generation_3_without_validation() { + let platform_version_13 = PlatformVersion::get(13).expect("PV13 exists"); + + let document_type = + parse_dispatched(post_schema_allowing_meta_once(), platform_version_13, false) + .expect("generation 2 ignores unknown doctype-level keywords when not validating"); + assert!(document_type.immutable_fields_allow_setting().is_empty()); + + assert!( + parse_dispatched(post_schema_allowing_meta_once(), platform_version_13, true).is_err(), + "meta-schema v2 must reject the immutableAllowSetting keyword" + ); +} diff --git a/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/mod.rs b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/mod.rs index 7fdc47f9faf..62158a78546 100644 --- a/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/mod.rs @@ -1,7 +1,8 @@ //! Document-type parser **generation 3** — protocol version 14 and later. //! //! Generation 3 is generation 2 plus the ranked index keywords -//! (`rankedCountable` / `rankedSummable` / `rankedAverageable`). +//! (`rankedCountable` / `rankedSummable` / `rankedAverageable`), the +//! indexOnly grammar, and the doctype-level `immutable` property list. //! //! It exists as its own generation — rather than as a version gate inside the //! shipped ones — because that is what keeps a historical block from ever @@ -23,6 +24,7 @@ use crate::data_contract::document_type::index::Index; use crate::data_contract::document_type::index::IndexGrammarAdmissions; #[cfg(feature = "validation")] use crate::data_contract::document_type::property::DocumentPropertyType; +use crate::data_contract::document_type::property_names; use crate::data_contract::document_type::v2::DocumentTypeV2; use crate::data_contract::document_type::DocumentType; use crate::data_contract::errors::DataContractError; @@ -248,6 +250,13 @@ fn try_from_schema_generation_3( // consumes `schema`. let aggregates = common::parse_doctype_aggregate_keywords(&schema, name)?; let index_only = common::parse_index_only_keyword(&schema)?; + let immutable_fields = + common::parse_property_name_list_keyword(&schema, name, property_names::IMMUTABLE)?; + let immutable_fields_allow_setting = common::parse_property_name_list_keyword( + &schema, + name, + property_names::IMMUTABLE_ALLOW_SETTING, + )?; let v1 = common::parse_document_type_core( data_contract_id, @@ -316,6 +325,15 @@ fn try_from_schema_generation_3( // aggregate flags (they describe the primary-key tree, which an // indexOnly type does not have), so it has to see them already applied. common::apply_index_only(&mut v2, index_only, name)?; + // After the core parse: the lints read the resolved `documentsMutable` + // flag (contract default applied) and the parsed top-level properties. + common::apply_immutable_fields( + &mut v2, + immutable_fields, + immutable_fields_allow_setting, + name, + full_validation, + )?; // The flags are read from the parsed result (not the raw schema) so // the check sees `canBeDeleted` resolved against the contract config @@ -368,6 +386,8 @@ impl DocumentType { } } +#[cfg(test)] +mod immutable_tests; #[cfg(test)] mod index_only_tests; diff --git a/packages/rs-dpp/src/data_contract/document_type/methods/validate_update/v1/mod.rs b/packages/rs-dpp/src/data_contract/document_type/methods/validate_update/v1/mod.rs index 9f8b980f842..a3b2d2fb71b 100644 --- a/packages/rs-dpp/src/data_contract/document_type/methods/validate_update/v1/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/methods/validate_update/v1/mod.rs @@ -23,7 +23,10 @@ use crate::consensus::basic::data_contract::{ DataContractInvalidIndexDefinitionUpdateError, DataContractInvalidRequiredFieldsUpdateError, }; -use crate::data_contract::document_type::accessors::DocumentTypeV0Getters; +use crate::consensus::state::data_contract::document_type_update_error::DocumentTypeUpdateError; +use crate::data_contract::document_type::accessors::{ + DocumentTypeV0Getters, DocumentTypeV2Getters, +}; use crate::data_contract::document_type::DocumentTypeRef; use crate::validation::SimpleConsensusValidationResult; use crate::ProtocolError; @@ -77,6 +80,15 @@ impl DocumentTypeRef<'_> { return Ok(result); } + // Validate immutable-property changes (the schema compatibility + // differ has the top-level `immutable` key stripped, so this is the + // only place those changes are judged) + let result = self.validate_immutable_fields_update(new_document_type); + + if !result.is_valid() { + return Ok(result); + } + // Validate schema compatibility self.validate_schema_with_options(new_document_type, platform_version, &options) } @@ -164,6 +176,66 @@ impl DocumentTypeRef<'_> { SimpleConsensusValidationResult::new() } + /// The `immutable` property list may only grow. Removing an entry would + /// let a later replace change a property that documents were created + /// under the promise of never changing; adding one only narrows what + /// future replaces may touch and invalidates no stored document (the + /// parser has already checked that every new entry names a top-level + /// property of the new type). + /// + /// `immutableAllowSetting` may only shrink, with one exception: a + /// property that becomes immutable in this very update may arrive with + /// the allowance. Dropping an entry is a tightening (a still-absent + /// property can no longer be set). Adding one for a property that was + /// already immutable would relax a promise the documents were created + /// under, exactly like removing it from `immutable`. + /// + /// Judged here because both top-level keys are stripped from the schema + /// compatibility diff, exactly like `indices` and `required`. + fn validate_immutable_fields_update( + &self, + new_document_type: DocumentTypeRef, + ) -> SimpleConsensusValidationResult { + let old_immutable = self.immutable_fields(); + let new_immutable = new_document_type.immutable_fields(); + + for property in old_immutable { + if !new_immutable.contains(property) { + return SimpleConsensusValidationResult::new_with_error( + DocumentTypeUpdateError::new( + self.data_contract_id(), + self.name(), + format!( + "document type can not remove immutable property '{property}': the \ + immutable list may only grow" + ), + ) + .into(), + ); + } + } + + let old_allow_setting = self.immutable_fields_allow_setting(); + for property in new_document_type.immutable_fields_allow_setting() { + if !old_allow_setting.contains(property) && old_immutable.contains(property) { + return SimpleConsensusValidationResult::new_with_error( + DocumentTypeUpdateError::new( + self.data_contract_id(), + self.name(), + format!( + "document type can not allow setting immutable property '{property}' \ + once it is already immutable: only a property that becomes \ + immutable in this update may be listed in immutableAllowSetting" + ), + ) + .into(), + ); + } + } + + SimpleConsensusValidationResult::new() + } + /// Index definitions are immutable once a document type is registered: /// Drive lays out the index trees at contract creation and never /// backfills them, so an added index would silently miss every @@ -221,6 +293,7 @@ impl DocumentTypeRef<'_> { #[cfg(test)] mod tests { use crate::consensus::basic::BasicError; + use crate::consensus::state::state_error::StateError; use crate::consensus::ConsensusError; use crate::data_contract::config::DataContractConfig; use crate::data_contract::document_type::DocumentType; @@ -268,6 +341,232 @@ mod tests { ) } + /// A mutable document type with three string properties and the given + /// `immutable` list. + fn doc_type_with_immutable( + immutable: Value, + platform_version: &PlatformVersion, + ) -> DocumentType { + let schema = platform_value!({ + "type": "object", + "documentsMutable": true, + "properties": { + "a": {"type": "string", "position": 0, "maxLength": 60_u32}, + "b": {"type": "string", "position": 1, "maxLength": 60_u32}, + "c": {"type": "string", "position": 2, "maxLength": 60_u32}, + }, + "immutable": immutable, + "additionalProperties": false, + }); + let config = DataContractConfig::default_for_version(platform_version) + .expect("should create a default config"); + DocumentType::try_from_schema( + Identifier::new([1; 32]), + 1, + config.version(), + "test", + schema, + None, + &BTreeMap::new(), + &config, + true, + &mut Vec::new(), + platform_version, + ) + .expect("failed to create document type") + } + + // The `immutable` list may only grow: removing an entry would let a + // later replace change a property documents were created under the + // promise of never changing. + #[test] + fn should_reject_removing_an_immutable_property() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable(platform_value!(["a", "b"]), platform_version); + let new = doc_type_with_immutable(platform_value!(["a"]), platform_version); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert_matches!( + result.errors.as_slice(), + [ConsensusError::StateError(StateError::DocumentTypeUpdateError(e))] + if e.additional_message() + == "document type can not remove immutable property 'b': the immutable list may only grow" + ); + } + + // Adding an entry narrows what future replaces may touch and invalidates + // no stored document. This runs the whole v1 pipeline, so it also pins + // that the compatibility differ ignores the top-level `immutable` key + // instead of hard-erroring on a keyword it has no rule for. + #[test] + fn should_accept_adding_an_immutable_property() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable(platform_value!(["a"]), platform_version); + let new = doc_type_with_immutable(platform_value!(["a", "c"]), platform_version); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert!( + result.is_valid(), + "growing the immutable list must be accepted, got {:?}", + result.errors + ); + } + + #[test] + fn should_accept_an_unchanged_immutable_list() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable(platform_value!(["a", "b"]), platform_version); + let new = doc_type_with_immutable(platform_value!(["b", "a"]), platform_version); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert!( + result.is_valid(), + "an unchanged (reordered) immutable list must be accepted, got {:?}", + result.errors + ); + } + + /// Like `doc_type_with_immutable`, with an `immutableAllowSetting` list + /// as well. + fn doc_type_with_immutable_lists( + immutable: Value, + allow_setting: Value, + platform_version: &PlatformVersion, + ) -> DocumentType { + let schema = platform_value!({ + "type": "object", + "documentsMutable": true, + "properties": { + "a": {"type": "string", "position": 0, "maxLength": 60_u32}, + "b": {"type": "string", "position": 1, "maxLength": 60_u32}, + "c": {"type": "string", "position": 2, "maxLength": 60_u32}, + }, + "immutable": immutable, + "immutableAllowSetting": allow_setting, + "additionalProperties": false, + }); + let config = DataContractConfig::default_for_version(platform_version) + .expect("should create a default config"); + DocumentType::try_from_schema( + Identifier::new([1; 32]), + 1, + config.version(), + "test", + schema, + None, + &BTreeMap::new(), + &config, + true, + &mut Vec::new(), + platform_version, + ) + .expect("failed to create document type") + } + + // Dropping an allow-setting entry only tightens: a still-absent property + // can no longer be set. + #[test] + fn should_accept_removing_an_allow_setting_entry() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable_lists( + platform_value!(["a", "b"]), + platform_value!(["b"]), + platform_version, + ); + let new = doc_type_with_immutable_lists( + platform_value!(["a", "b"]), + platform_value!([]), + platform_version, + ); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert!( + result.is_valid(), + "dropping an allow-setting entry must be accepted, got {:?}", + result.errors + ); + } + + // An already-immutable property cannot start allowing a set: that would + // relax the promise its documents were created under. + #[test] + fn should_reject_allowing_setting_of_an_already_immutable_property() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable_lists( + platform_value!(["a", "b"]), + platform_value!([]), + platform_version, + ); + let new = doc_type_with_immutable_lists( + platform_value!(["a", "b"]), + platform_value!(["b"]), + platform_version, + ); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert_matches!( + result.errors.as_slice(), + [ConsensusError::StateError(StateError::DocumentTypeUpdateError(e))] + if e.additional_message().starts_with( + "document type can not allow setting immutable property 'b' once it is already immutable" + ) + ); + } + + // A property that becomes immutable in this update may arrive with the + // allowance: nothing was promised about it before. + #[test] + fn should_accept_a_newly_immutable_property_that_allows_setting() { + let platform_version = PlatformVersion::latest(); + + let old = doc_type_with_immutable_lists( + platform_value!(["a"]), + platform_value!([]), + platform_version, + ); + let new = doc_type_with_immutable_lists( + platform_value!(["a", "c"]), + platform_value!(["c"]), + platform_version, + ); + + let result = old + .as_ref() + .validate_update(new.as_ref(), 2, platform_version) + .expect("validate_update should not error"); + + assert!( + result.is_valid(), + "a newly immutable property may allow setting, got {:?}", + result.errors + ); + } + // The v0 regression this generation fixes: the outcome of adding an // index must not depend on where its name sorts relative to the // document type's existing indexes. Under v0, adding "i" on [a] was diff --git a/packages/rs-dpp/src/data_contract/document_type/mod.rs b/packages/rs-dpp/src/data_contract/document_type/mod.rs index 3f9ca299a6c..f9e2f70126e 100644 --- a/packages/rs-dpp/src/data_contract/document_type/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/mod.rs @@ -69,6 +69,17 @@ pub(crate) mod property_names { pub const REQUIRED: &str = "required"; pub const REQUIRED_SINCE: &str = "requiredSince"; pub const TRANSIENT: &str = "transient"; + /// Doctype-level array naming the top-level properties of a **mutable** + /// document type whose values are frozen at creation: a replace that + /// changes, adds or removes any of them is rejected. Meta-schema v3+ + /// (protocol version 14). See `apply_immutable_fields` in + /// `try_from_schema::common` for the structural rules. + pub const IMMUTABLE: &str = "immutable"; + /// Doctype-level array naming the [`IMMUTABLE`] properties a replace may + /// still set when the stored document has no value for them. Once set + /// they are frozen like the rest of the list. Every entry must also be in + /// [`IMMUTABLE`]. Meta-schema v3+ (protocol version 14). + pub const IMMUTABLE_ALLOW_SETTING: &str = "immutableAllowSetting"; pub const TYPE: &str = "type"; pub const REF: &str = "$ref"; pub const CREATED_AT: &str = "$createdAt"; diff --git a/packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/v1/mod.rs b/packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/v1/mod.rs index b1bbcbca3cb..c5091476767 100644 --- a/packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/v1/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/v1/mod.rs @@ -24,6 +24,11 @@ //! added as required with `requiredSince` equal to the version the update //! creates. Nested `required` arrays (under `/properties//required`) //! remain frozen by the differ. +//! +//! The top-level `immutable` key (protocol version 14) is stripped as well: +//! the differ has no rule for it, and `validate_update` v1's +//! `validate_immutable_fields_update` judges it (the list may grow, never +//! shrink). use crate::data_contract::document_type::schema::IncompatibleJsonSchemaOperation; use crate::data_contract::errors::{DataContractError, JsonSchemaError}; @@ -56,35 +61,50 @@ static OPTIONS: Lazy = Lazy::new(|| { } }); -/// Strips the two top-level keys whose changes are validated by dedicated -/// checks in `validate_update` v1 instead of the JSON diff: `indices` -/// (index definitions compared by name) and `required` +/// The document type's own top-level keys whose changes are validated by +/// dedicated checks in `validate_update` v1 instead of the JSON diff: +/// `indices` (index definitions compared by name), `required` /// (`validate_required_fields_update`, which admits new-property additions -/// annotated with `requiredSince`). Only the document type's own top-level -/// keys are removed; a nested object property's `required` array lives under +/// annotated with `requiredSince`), and `immutable` together with +/// `immutableAllowSetting` (`validate_immutable_fields_update`: the first may +/// only grow, the second may only shrink except for newly immutable +/// properties). The differ has no rule for the last three at all and would +/// hard-error on any change to them. +const TOP_LEVEL_VALIDATED_KEYS: [&str; 4] = + ["indices", "required", "immutable", "immutableAllowSetting"]; + +/// Strips [`TOP_LEVEL_VALIDATED_KEYS`] from a document type schema before it +/// is diffed. Only the document type's own top-level keys are removed; a +/// nested object property's `required` array lives under /// `/properties//required` and stays governed by the differ's frozen -/// `required` rule, as do properties named `indices` or `required`. +/// `required` rule, as do properties named `indices`, `required` or +/// `immutable`. fn without_top_level_validated_keys(schema: &JsonValue) -> Cow<'_, JsonValue> { match schema { - JsonValue::Object(map) if map.contains_key("indices") || map.contains_key("required") => { + JsonValue::Object(map) + if TOP_LEVEL_VALIDATED_KEYS + .iter() + .any(|key| map.contains_key(*key)) => + { let mut map = map.clone(); - map.remove("indices"); - map.remove("required"); + for key in TOP_LEVEL_VALIDATED_KEYS { + map.remove(key); + } Cow::Owned(JsonValue::Object(map)) } _ => Cow::Borrowed(schema), } } -/// Pairing invariant: stripping `indices` and top-level `required` -/// unconditionally is only safe because every `PlatformVersion` that selects -/// this generation (`validate_schema_compatibility: 1`) also selects a -/// `validate_update` generation of at least 1 +/// Pairing invariant: stripping `indices`, top-level `required` and +/// `immutable` unconditionally is only safe because every `PlatformVersion` +/// that selects this generation (`validate_schema_compatibility: 1`) also +/// selects a `validate_update` generation of at least 1 /// (`dpp.validation.document_type.validate_update`), which rejects every -/// real index change and every disallowed required-set change before this -/// check runs. A future version table that bumps one without the other -/// would let index or required changes bypass compatibility validation -/// entirely. +/// real index change, every disallowed required-set change and every +/// shrinking of the immutable list before this check runs. A future version +/// table that bumps one without the other would let those changes bypass +/// compatibility validation entirely. pub(super) fn validate_schema_compatibility_v1( original_schema: &JsonValue, new_schema: &JsonValue, @@ -161,6 +181,44 @@ mod tests { ); } + // The differ has no rule for `immutable`; a change to the list is judged + // by `validate_update` v1 and must be invisible here rather than a + // hard error. + #[test] + fn should_ignore_immutable_list_change() { + let platform_version = PlatformVersion::latest(); + + let original_schema = json!({ + "type": "object", + "properties": { + "a": {"type": "string", "position": 0}, + "b": {"type": "string", "position": 1}, + }, + "immutable": ["a"], + "additionalProperties": false, + }); + + let new_schema = json!({ + "type": "object", + "properties": { + "a": {"type": "string", "position": 0}, + "b": {"type": "string", "position": 1}, + }, + "immutable": ["a", "b"], + "immutableAllowSetting": ["b"], + "additionalProperties": false, + }); + + let result = validate_schema_compatibility(&original_schema, &new_schema, platform_version) + .expect("an immutable-only diff must not error"); + + assert!( + result.is_valid(), + "an immutable-only diff must be ignored, got {:?}", + result.errors + ); + } + // Stripping `indices` must not mask incompatible changes elsewhere in // the schema. #[test] diff --git a/packages/rs-dpp/src/data_contract/document_type/v2/accessors.rs b/packages/rs-dpp/src/data_contract/document_type/v2/accessors.rs index 3964010b1d9..a2db7cfb9af 100644 --- a/packages/rs-dpp/src/data_contract/document_type/v2/accessors.rs +++ b/packages/rs-dpp/src/data_contract/document_type/v2/accessors.rs @@ -230,6 +230,14 @@ impl DocumentTypeV2Getters for DocumentTypeV2 { fn index_only(&self) -> bool { self.index_only } + + fn immutable_fields(&self) -> &BTreeSet { + &self.immutable_fields + } + + fn immutable_fields_allow_setting(&self) -> &BTreeSet { + &self.immutable_fields_allow_setting + } } impl DocumentTypeV2Setters for DocumentTypeV2 { diff --git a/packages/rs-dpp/src/data_contract/document_type/v2/mod.rs b/packages/rs-dpp/src/data_contract/document_type/v2/mod.rs index 07242298e31..a49c5bb12d9 100644 --- a/packages/rs-dpp/src/data_contract/document_type/v2/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/v2/mod.rs @@ -43,6 +43,17 @@ pub struct DocumentTypeV2 { pub(in crate::data_contract) required_fields: BTreeSet, /// The transient fields on the document type pub(in crate::data_contract) transient_fields: BTreeSet, + /// The top-level properties frozen at document creation on a mutable + /// document type (`immutable` keyword, protocol version 14): a replace + /// that changes, adds or removes any of them is rejected. Always empty + /// when `documents_mutable` is false, where every property is already + /// immutable. + pub(in crate::data_contract) immutable_fields: BTreeSet, + /// The subset of `immutable_fields` a replace may still set while the + /// stored document has no value for them (`immutableAllowSetting` + /// keyword, protocol version 14). Once present they are frozen like the + /// rest of the list. Every entry is also in `immutable_fields`. + pub(in crate::data_contract) immutable_fields_allow_setting: BTreeSet, /// Should documents keep history? pub(in crate::data_contract) documents_keep_history: bool, /// Should transfers of documents of this type be recorded in the document @@ -154,6 +165,8 @@ impl From for DocumentTypeV2 { binary_paths: value.binary_paths, required_fields: value.required_fields, transient_fields: value.transient_fields, + immutable_fields: BTreeSet::new(), + immutable_fields_allow_setting: BTreeSet::new(), documents_keep_history: value.documents_keep_history, documents_keep_transfer_history: value.documents_keep_transfer_history, documents_keep_purchase_history: value.documents_keep_purchase_history, @@ -194,6 +207,8 @@ impl From for DocumentTypeV2 { binary_paths: value.binary_paths, required_fields: value.required_fields, transient_fields: value.transient_fields, + immutable_fields: BTreeSet::new(), + immutable_fields_allow_setting: BTreeSet::new(), documents_keep_history: value.documents_keep_history, documents_keep_transfer_history: value.documents_keep_transfer_history, documents_keep_purchase_history: value.documents_keep_purchase_history, diff --git a/packages/rs-dpp/src/errors/consensus/codes.rs b/packages/rs-dpp/src/errors/consensus/codes.rs index e62d630a3f4..4bbb1de013c 100644 --- a/packages/rs-dpp/src/errors/consensus/codes.rs +++ b/packages/rs-dpp/src/errors/consensus/codes.rs @@ -342,6 +342,7 @@ impl ErrorWithCode for StateError { Self::ReferencedKeyIdPropertyInvalidError(_) => 40125, Self::ReferencedDocumentPropertyAgreementInvalidError(_) => 40126, Self::ReferencedDocumentPropertyMismatchError(_) => 40127, + Self::DocumentImmutablePropertyChangedError(_) => 40128, // Identity Errors: 40200-40299 Self::IdentityAlreadyExistsError(_) => 40200, diff --git a/packages/rs-dpp/src/errors/consensus/state/document/document_immutable_property_changed_error.rs b/packages/rs-dpp/src/errors/consensus/state/document/document_immutable_property_changed_error.rs new file mode 100644 index 00000000000..f2a0d6ed9ab --- /dev/null +++ b/packages/rs-dpp/src/errors/consensus/state/document/document_immutable_property_changed_error.rs @@ -0,0 +1,68 @@ +use crate::consensus::state::state_error::StateError; +use crate::consensus::ConsensusError; +use crate::ProtocolError; +use bincode::{Decode, DecodeUntrusted, Encode}; +use platform_serialization_derive::{ + PlatformDeserializeTrusted, PlatformDeserializeUntrusted, PlatformSerialize, +}; +use platform_value::Identifier; +use thiserror::Error; + +/// A document replace changed, added or removed a property the document type +/// lists under its `immutable` keyword (protocol version 14). Only the +/// properties outside that list may change between revisions. +#[derive( + Error, + Debug, + Clone, + PartialEq, + Eq, + Encode, + Decode, + PlatformSerialize, + PlatformDeserializeTrusted, + PlatformDeserializeUntrusted, + DecodeUntrusted, +)] +#[error("property '{property}' of document {document_id} (type '{document_type_name}') is immutable and cannot be changed by a replace")] +#[platform_serialize(unversioned)] +pub struct DocumentImmutablePropertyChangedError { + /* + + DO NOT CHANGE ORDER OF FIELDS WITHOUT INTRODUCING OF NEW VERSION + + */ + document_id: Identifier, + document_type_name: String, + property: String, +} + +impl DocumentImmutablePropertyChangedError { + pub fn new(document_id: Identifier, document_type_name: String, property: String) -> Self { + Self { + document_id, + document_type_name, + property, + } + } + + pub fn document_id(&self) -> Identifier { + self.document_id + } + + pub fn document_type_name(&self) -> &str { + &self.document_type_name + } + + /// The first immutable property (in name order) the replace tried to + /// change. + pub fn property(&self) -> &str { + &self.property + } +} + +impl From for ConsensusError { + fn from(err: DocumentImmutablePropertyChangedError) -> Self { + Self::StateError(StateError::DocumentImmutablePropertyChangedError(err)) + } +} diff --git a/packages/rs-dpp/src/errors/consensus/state/document/mod.rs b/packages/rs-dpp/src/errors/consensus/state/document/mod.rs index ae4d8306606..aff6df94032 100644 --- a/packages/rs-dpp/src/errors/consensus/state/document/mod.rs +++ b/packages/rs-dpp/src/errors/consensus/state/document/mod.rs @@ -6,6 +6,7 @@ pub mod document_contest_index_mismatch_error; pub mod document_contest_not_joinable_error; pub mod document_contest_not_paid_for_error; pub mod document_contest_not_required_error; +pub mod document_immutable_property_changed_error; pub mod document_incorrect_purchase_price_error; pub mod document_not_for_sale_error; pub mod document_not_found_error; diff --git a/packages/rs-dpp/src/errors/consensus/state/state_error.rs b/packages/rs-dpp/src/errors/consensus/state/state_error.rs index 5cbcfc9c4bc..548674af99e 100644 --- a/packages/rs-dpp/src/errors/consensus/state/state_error.rs +++ b/packages/rs-dpp/src/errors/consensus/state/state_error.rs @@ -63,6 +63,7 @@ use crate::consensus::state::identity::identity_public_key_already_exists_for_un use crate::consensus::state::identity::identity_public_key_already_expired_error::IdentityPublicKeyAlreadyExpiredError; use crate::consensus::state::identity::identity_public_key_budget_exceeded_error::IdentityPublicKeyBudgetExceededError; use crate::consensus::state::identity::identity_public_key_limit_not_raised_error::IdentityPublicKeyLimitNotRaisedError; +use crate::consensus::state::document::document_immutable_property_changed_error::DocumentImmutablePropertyChangedError; use crate::consensus::state::identity::identity_public_key_limit_not_set_error::IdentityPublicKeyLimitNotSetError; use crate::consensus::state::identity::identity_to_freeze_does_not_exist_error::IdentityToFreezeDoesNotExistError; use crate::consensus::state::identity::invalid_identity_contract_nonce_error::InvalidIdentityNonceError; @@ -442,6 +443,10 @@ pub enum StateError { #[error(transparent)] IdentityPublicKeyLimitNotRaisedError(IdentityPublicKeyLimitNotRaisedError), + + // Immutable document properties (protocol version 14). + #[error(transparent)] + DocumentImmutablePropertyChangedError(DocumentImmutablePropertyChangedError), } impl From for ConsensusError { @@ -643,5 +648,16 @@ mod tests { )), 108 ); + // Immutable document properties (protocol version 14): the tail of the enum. + assert_eq!( + discriminant_of(StateError::DocumentImmutablePropertyChangedError( + DocumentImmutablePropertyChangedError::new( + identity_id, + "post".to_string(), + "author".to_string() + ) + )), + 109 + ); } } diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_replace_transition_action/state_v1/mod.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_replace_transition_action/state_v1/mod.rs index d1122c02bee..444cb4f4e06 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_replace_transition_action/state_v1/mod.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_replace_transition_action/state_v1/mod.rs @@ -1,8 +1,12 @@ use dpp::block::block_info::BlockInfo; +use dpp::consensus::state::document::document_immutable_property_changed_error::DocumentImmutablePropertyChangedError; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; use dpp::identifier::Identifier; use dpp::validation::SimpleConsensusValidationResult; use dpp::version::PlatformVersion; use drive::grovedb::TransactionArg; +use drive::state_transition_action::batch::batched_transition::document_transition::document_base_transition_action::DocumentBaseTransitionActionAccessorsV0; use drive::state_transition_action::batch::batched_transition::document_transition::document_replace_transition_action::{ DocumentReplaceTransitionAction, DocumentReplaceTransitionActionAccessorsV0, }; @@ -48,6 +52,41 @@ impl DocumentReplaceTransitionActionStateValidationV1 for DocumentReplaceTransit return Ok(validation_result); } + // Immutable properties (protocol version 14). The action already + // knows which top-level properties differ from the stored document + // (a changed value, a property added, or a property removed), so the + // check is an intersection with the type's `immutable` list. The one + // allowed difference is a first-time set of a property listed under + // `immutableAllowSetting`: the stored document had no value for it + // (`added_data_fields`), so nothing was frozen yet. It reads no + // state, so it runs before the reference validation, which does. + // `changed_data_fields` is name-ordered, so the reported property is + // deterministic. + let contract_fetch_info = self.base().data_contract_fetch_info(); + let document_type_name = self.base().document_type_name(); + // V0 above has already refused an unknown document type. + let document_type = contract_fetch_info + .contract + .document_type_for_name(document_type_name)?; + let immutable_fields = document_type.immutable_fields(); + if !immutable_fields.is_empty() { + let allow_setting = document_type.immutable_fields_allow_setting(); + let added_fields = self.added_data_fields(); + if let Some(property) = self.changed_data_fields().iter().find(|field| { + immutable_fields.contains(*field) + && !(allow_setting.contains(*field) && added_fields.contains(*field)) + }) { + return Ok(SimpleConsensusValidationResult::new_with_error( + DocumentImmutablePropertyChangedError::new( + self.base().id(), + document_type_name.clone(), + property.clone(), + ) + .into(), + )); + } + } + let reference_result = self.base().validate_document_references( self.data(), Some(self.changed_data_fields()), diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/immutable.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/immutable.rs new file mode 100644 index 00000000000..3df7914cb4b --- /dev/null +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/immutable.rs @@ -0,0 +1,713 @@ +//! End-to-end coverage for the `immutable` document-type keyword (protocol +//! version 14): on a mutable document type the listed top-level properties +//! are frozen at creation. A replace that leaves them alone succeeds; one +//! that changes, adds or removes any of them is consensus-rejected and leaves +//! the stored document untouched; and a contract update may add to the list +//! but never remove from it. + +use super::*; + +mod immutable_tests { + use super::*; + use crate::rpc::core::MockCoreRPCLike; + use crate::test::helpers::setup::TempPlatform; + use dpp::data_contract::accessors::v0::DataContractV0Setters; + use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; + use dpp::data_contract::schema::DataContractSchemaMethodsV0; + use dpp::document::Document; + use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; + use dpp::identity::{Identity, IdentityPublicKey}; + use dpp::platform_value::platform_value; + use dpp::prelude::{DataContract, IdentityNonce}; + use dpp::state_transition::data_contract_update_transition::methods::DataContractUpdateTransitionMethodsV0; + use dpp::state_transition::data_contract_update_transition::DataContractUpdateTransition; + use dpp::state_transition::StateTransition; + use dpp::tests::fixtures::get_data_contract_fixture; + use drive::util::storage_flags::StorageFlags; + use simple_signer::signer::SimpleSigner; + use std::collections::BTreeSet; + + /// A mutable `post` type: `author` and `body` required, `mood` an + /// optional string, `meta` an optional nested object, and the given + /// `immutable` and `immutableAllowSetting` lists. + fn post_schema(immutable: Value, allow_setting: Value) -> Value { + platform_value!({ + "type": "object", + "documentsMutable": true, + "properties": { + "author": {"type": "string", "position": 0, "maxLength": 63_u32}, + "body": {"type": "string", "position": 1, "maxLength": 500_u32}, + "mood": {"type": "string", "position": 2, "maxLength": 30_u32}, + "meta": { + "type": "object", + "position": 3, + "properties": { + "tag": {"type": "string", "position": 0, "maxLength": 30_u32}, + "rank": {"type": "integer", "position": 1, "minimum": 0, "maximum": 1000} + }, + "additionalProperties": false + } + }, + "required": ["author", "body"], + "immutable": immutable, + "immutableAllowSetting": allow_setting, + "additionalProperties": false + }) + } + + /// The scenario every test starts from: one identity, one contract whose + /// `post` type lists `immutable` as given, and one stored post with + /// `author` and `body` set plus whatever `fill` adds. + struct PostFixture { + platform: TempPlatform, + identity: Identity, + signer: SimpleSigner, + key: IdentityPublicKey, + contract: DataContract, + /// The post as last accepted by the chain. + post: Document, + /// The identity contract nonce the next transition uses. Every + /// processed transition consumes one, including the ones that fail + /// with a paid consensus error. + next_nonce: IdentityNonce, + } + + impl PostFixture { + async fn new(immutable: Value, fill: impl FnOnce(&mut Document)) -> Self { + Self::new_with_lists(immutable, platform_value!([]), fill).await + } + + async fn new_with_lists( + immutable: Value, + allow_setting: Value, + fill: impl FnOnce(&mut Document), + ) -> Self { + let platform_version = PlatformVersion::latest(); + let mut platform = TestPlatformBuilder::new() + .build_with_mock_rpc() + .set_initial_state_structure(); + + let (identity, signer, key) = setup_identity(&mut platform, 958, dash_to_credits!(0.5)); + + let mut contract = get_data_contract_fixture( + Some(identity.id()), + 0, + platform_version.protocol_version, + ) + .data_contract_owned(); + contract + .set_document_schema( + "post", + post_schema(immutable, allow_setting), + true, + &mut Vec::new(), + platform_version, + ) + .expect("expected to add the post document type"); + platform + .drive + .apply_contract( + &contract, + BlockInfo::default(), + true, + StorageFlags::optional_default_as_cow(), + None, + platform_version, + ) + .expect("expected to apply the contract"); + + let post_type = contract + .document_type_for_name("post") + .expect("expected the post document type"); + + let mut rng = StdRng::seed_from_u64(433); + let entropy = Bytes32::random_with_rng(&mut rng); + let mut post = post_type + .random_document_with_identifier_and_entropy( + &mut rng, + identity.id(), + entropy, + DocumentFieldFillType::DoNotFillIfNotRequired, + DocumentFieldFillSize::AnyDocumentFillSize, + platform_version, + ) + .expect("expected a random post"); + post.set("author", "alice".into()); + post.set("body", "first draft".into()); + fill(&mut post); + + let transition = BatchTransition::new_document_creation_transition_from_document( + post.clone(), + post_type, + entropy.0, + &key, + 1, + 0, + None, + &signer, + platform_version, + None, + ) + .await + .expect("expected the create transition"); + + let fixture = Self { + platform, + identity, + signer, + key, + contract, + post, + next_nonce: 2, + }; + assert_matches!( + fixture.process(&transition), + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "creating the post must succeed" + ); + fixture + } + + fn process(&self, transition: &StateTransition) -> StateTransitionExecutionResult { + let platform_version = PlatformVersion::latest(); + let platform_state = self.platform.state.load(); + let serialized = transition + .serialize_to_bytes() + .expect("expected the transition to serialize"); + let transaction = self.platform.drive.grove.start_transaction(); + let processing_result = self + .platform + .platform + .process_raw_state_transitions( + &[serialized], + &platform_state, + &BlockInfo::default(), + &transaction, + platform_version, + false, + None, + ) + .expect("expected to process the state transition"); + self.platform + .drive + .grove + .commit_transaction(transaction) + .unwrap() + .expect("expected to commit the transaction"); + processing_result.into_execution_results().remove(0) + } + + /// Replaces the stored post with `mutate` applied to a copy of it and + /// the revision bumped. On success the fixture's post becomes the + /// accepted version. + async fn replace( + &mut self, + mutate: impl FnOnce(&mut Document), + ) -> StateTransitionExecutionResult { + let platform_version = PlatformVersion::latest(); + let mut replacement = self.post.clone(); + mutate(&mut replacement); + replacement + .increment_revision() + .expect("expected the revision to increment"); + + let transition = { + let post_type = self + .contract + .document_type_for_name("post") + .expect("expected the post document type"); + BatchTransition::new_document_replacement_transition_from_document( + replacement.clone(), + post_type, + &self.key, + self.next_nonce, + 0, + None, + &self.signer, + platform_version, + None, + ) + .await + .expect("expected the replace transition") + }; + self.next_nonce += 1; + + let result = self.process(&transition); + if matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. } + ) { + self.post = replacement; + } + result + } + + /// Re-registers the contract one version up with the `post` type's + /// `immutable` list replaced. On success the fixture's contract + /// becomes the new version. + async fn update_immutable_list( + &mut self, + immutable: Value, + ) -> StateTransitionExecutionResult { + self.update_lists(immutable, platform_value!([])).await + } + + /// Like `update_immutable_list`, replacing the `immutableAllowSetting` + /// list as well. + async fn update_lists( + &mut self, + immutable: Value, + allow_setting: Value, + ) -> StateTransitionExecutionResult { + let platform_version = PlatformVersion::latest(); + let mut updated = self.contract.clone(); + updated.set_version(self.contract.version() + 1); + updated + .set_document_schema( + "post", + post_schema(immutable, allow_setting), + true, + &mut Vec::new(), + platform_version, + ) + .expect("expected to update the post document type"); + + let transition = DataContractUpdateTransition::new_from_data_contract( + updated.clone(), + &self.identity.clone().into_partial_identity_info(), + self.key.id(), + self.next_nonce, + 0, + &self.signer, + platform_version, + None, + ) + .await + .expect("expected the contract update transition"); + self.next_nonce += 1; + + let result = self.process(&transition); + if matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. } + ) { + self.contract = updated; + } + result + } + + /// The one stored post, read back from Drive. + fn stored_post(&self) -> Document { + let platform_version = PlatformVersion::latest(); + let query = DriveDocumentQuery::from_sql_expr( + "select * from post", + &self.contract, + Some(&self.platform.config.drive), + platform_version, + ) + .expect("expected a document query"); + let mut documents = self + .platform + .drive + .query_documents(query, None, false, None, None) + .expect("expected a query result") + .documents() + .to_vec(); + assert_eq!(documents.len(), 1, "exactly one post is stored"); + documents.remove(0) + } + } + + fn expect_immutable_property_error( + result: StateTransitionExecutionResult, + expected_property: &str, + fixture: &PostFixture, + ) { + let StateTransitionExecutionResult::PaidConsensusError { error, .. } = result else { + panic!("expected a paid consensus error, got {result:?}"); + }; + let ConsensusError::StateError(StateError::DocumentImmutablePropertyChangedError(error)) = + error + else { + panic!("expected DocumentImmutablePropertyChangedError, got {error:?}"); + }; + assert_eq!(error.property(), expected_property); + assert_eq!(error.document_type_name(), "post"); + assert_eq!(error.document_id(), fixture.post.id()); + } + + fn text(value: &str) -> Value { + Value::Text(value.to_string()) + } + + #[tokio::test] + async fn should_replace_mutable_properties_while_the_immutable_one_stays() { + let mut fixture = PostFixture::new(platform_value!(["author"]), |_| {}).await; + + let result = fixture + .replace(|post| post.set("body", "second draft".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "changing only mutable properties must succeed" + ); + + let stored = fixture.stored_post(); + assert_eq!(stored.properties().get("body"), Some(&text("second draft"))); + assert_eq!(stored.properties().get("author"), Some(&text("alice"))); + assert_eq!(stored.revision(), Some(2)); + } + + #[tokio::test] + async fn should_reject_a_replace_that_changes_an_immutable_property() { + let mut fixture = PostFixture::new(platform_value!(["author"]), |_| {}).await; + + let result = fixture + .replace(|post| { + post.set("author", "mallory".into()); + post.set("body", "hijacked".into()); + }) + .await; + expect_immutable_property_error(result, "author", &fixture); + + // Nothing of the rejected replace reached storage. + let stored = fixture.stored_post(); + assert_eq!(stored.properties().get("author"), Some(&text("alice"))); + assert_eq!(stored.properties().get("body"), Some(&text("first draft"))); + assert_eq!(stored.revision(), Some(1)); + } + + #[tokio::test] + async fn should_reject_a_replace_that_removes_an_optional_immutable_property() { + let mut fixture = PostFixture::new(platform_value!(["mood"]), |post| { + post.set("mood", "cheerful".into()) + }) + .await; + + let result = fixture + .replace(|post| { + post.remove("mood"); + }) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } + + #[tokio::test] + async fn should_reject_a_replace_that_adds_an_absent_immutable_property() { + let mut fixture = PostFixture::new(platform_value!(["mood"]), |_| {}).await; + + let result = fixture + .replace(|post| post.set("mood", "cheerful".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } + + #[tokio::test] + async fn should_freeze_an_immutable_object_property_whole() { + // Members deliberately in the opposite order to their schema + // positions, and the integer as a wide variant: storage reorders + // members by position and narrows integers, so the stored object + // is not byte-identical to what the client keeps sending. The + // comparison has to see through both (review finding on #4815). + let mut fixture = PostFixture::new(platform_value!(["meta"]), |post| { + post.set( + "meta", + Value::Map(vec![ + (Value::Text("rank".to_string()), Value::U64(7)), + ( + Value::Text("tag".to_string()), + Value::Text("intro".to_string()), + ), + ]), + ) + }) + .await; + + // Leaving the object alone keeps the replace valid, even though the + // object round-trips through serialization on both sides of the + // comparison. + let result = fixture + .replace(|post| post.set("body", "second draft".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "an unchanged immutable object must not block the replace" + ); + assert_eq!(fixture.stored_post().revision(), Some(2)); + + // Changing a nested value, integer or string, changes the top-level + // object. + let result = fixture + .replace(|post| post.set("meta", platform_value!({"tag": "intro", "rank": 8_u64}))) + .await; + expect_immutable_property_error(result, "meta", &fixture); + + let result = fixture + .replace(|post| post.set("meta", platform_value!({"tag": "outro", "rank": 7_u64}))) + .await; + expect_immutable_property_error(result, "meta", &fixture); + } + + #[tokio::test] + async fn should_name_the_first_changed_immutable_property_in_name_order() { + let mut fixture = PostFixture::new(platform_value!(["author", "mood"]), |post| { + post.set("mood", "cheerful".into()) + }) + .await; + + let result = fixture + .replace(|post| { + post.set("mood", "gloomy".into()); + post.set("author", "mallory".into()); + }) + .await; + expect_immutable_property_error(result, "author", &fixture); + } + + #[tokio::test] + async fn should_reject_a_contract_update_that_removes_an_immutable_property() { + let mut fixture = PostFixture::new(platform_value!(["author", "mood"]), |_| {}).await; + + let result = fixture + .update_immutable_list(platform_value!(["author"])) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::PaidConsensusError { + error: ConsensusError::StateError(StateError::DocumentTypeUpdateError(_)), + .. + }, + "shrinking the immutable list must be refused" + ); + + // The list is unchanged, so `mood` is still frozen (here: absent). + let result = fixture + .replace(|post| post.set("mood", "cheerful".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } + + #[tokio::test] + async fn should_enforce_an_immutable_property_added_by_a_contract_update() { + let mut fixture = PostFixture::new(platform_value!(["author"]), |post| { + post.set("mood", "cheerful".into()) + }) + .await; + + // Before the update `mood` is editable. + let result = fixture + .replace(|post| post.set("mood", "curious".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "mood is editable before the update" + ); + + let result = fixture + .update_immutable_list(platform_value!(["author", "mood"])) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "growing the immutable list must be accepted" + ); + let expected: BTreeSet = ["author", "mood"].into_iter().map(String::from).collect(); + assert_eq!( + fixture + .contract + .document_type_for_name("post") + .expect("expected the post document type") + .immutable_fields(), + &expected + ); + + // After it, `mood` is frozen at its current value while `body` stays + // editable. + let result = fixture + .replace(|post| post.set("mood", "gloomy".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + + let result = fixture + .replace(|post| post.set("body", "third draft".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "body stays editable after the update" + ); + assert_eq!( + fixture.stored_post().properties().get("mood"), + Some(&text("curious")) + ); + } + + // ── immutableAllowSetting ─────────────────────────────────────────── + + #[tokio::test] + async fn should_allow_setting_an_absent_allow_setting_property_once() { + // `mood` is immutable but may be set while absent; created without it. + let mut fixture = PostFixture::new_with_lists( + platform_value!(["author", "mood"]), + platform_value!(["mood"]), + |_| {}, + ) + .await; + + // The first-time set is accepted and stored. + let result = fixture + .replace(|post| post.set("mood", "cheerful".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "setting an absent allow-setting property must succeed" + ); + assert_eq!( + fixture.stored_post().properties().get("mood"), + Some(&text("cheerful")) + ); + + // From here on it is frozen: neither a change nor a removal passes. + let result = fixture + .replace(|post| post.set("mood", "gloomy".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + + let result = fixture + .replace(|post| { + post.remove("mood"); + }) + .await; + expect_immutable_property_error(result, "mood", &fixture); + + // The rest of the document stays editable throughout. + let result = fixture + .replace(|post| post.set("body", "second draft".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. } + ); + assert_eq!( + fixture.stored_post().properties().get("mood"), + Some(&text("cheerful")) + ); + } + + #[tokio::test] + async fn should_keep_an_allow_setting_property_frozen_when_set_at_creation() { + // Created WITH `mood`: the allowance never applies because the stored + // document always had a value. + let mut fixture = PostFixture::new_with_lists( + platform_value!(["mood"]), + platform_value!(["mood"]), + |post| post.set("mood", "cheerful".into()), + ) + .await; + + let result = fixture + .replace(|post| post.set("mood", "gloomy".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + + let result = fixture + .replace(|post| { + post.remove("mood"); + }) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } + + #[tokio::test] + async fn should_not_let_allow_setting_relax_a_different_immutable_property() { + // Only `mood` may be set late; `author` is fully frozen, and an absent + // immutable property outside the allowance (`meta`) still cannot be + // added. + let mut fixture = PostFixture::new_with_lists( + platform_value!(["author", "mood", "meta"]), + platform_value!(["mood"]), + |_| {}, + ) + .await; + + let result = fixture + .replace(|post| post.set("author", "mallory".into())) + .await; + expect_immutable_property_error(result, "author", &fixture); + + let result = fixture + .replace(|post| post.set("meta", platform_value!({"tag": "intro"}))) + .await; + expect_immutable_property_error(result, "meta", &fixture); + } + + #[tokio::test] + async fn should_reject_a_contract_update_that_allows_setting_an_already_immutable_property() { + let mut fixture = PostFixture::new(platform_value!(["author", "mood"]), |_| {}).await; + + let result = fixture + .update_lists( + platform_value!(["author", "mood"]), + platform_value!(["mood"]), + ) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::PaidConsensusError { + error: ConsensusError::StateError(StateError::DocumentTypeUpdateError(_)), + .. + }, + "an already-immutable property must not start allowing a set" + ); + + // Still fully frozen. + let result = fixture + .replace(|post| post.set("mood", "cheerful".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } + + #[tokio::test] + async fn should_accept_a_contract_update_adding_a_newly_immutable_property_that_allows_setting() + { + let mut fixture = PostFixture::new(platform_value!(["author"]), |_| {}).await; + + let result = fixture + .update_lists( + platform_value!(["author", "mood"]), + platform_value!(["mood"]), + ) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "a newly immutable property may arrive with the allowance" + ); + let expected: BTreeSet = ["mood"].into_iter().map(String::from).collect(); + assert_eq!( + fixture + .contract + .document_type_for_name("post") + .expect("expected the post document type") + .immutable_fields_allow_setting(), + &expected + ); + + // Set once, then frozen. + let result = fixture + .replace(|post| post.set("mood", "cheerful".into())) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. } + ); + let result = fixture + .replace(|post| post.set("mood", "gloomy".into())) + .await; + expect_immutable_property_error(result, "mood", &fixture); + } +} diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/mod.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/mod.rs index a1a23bbcbe9..f8d73da794e 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/mod.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/mod.rs @@ -1,6 +1,7 @@ mod creation; mod deletion; mod dpns; +mod immutable; mod index_only; mod keep_history; mod nft; diff --git a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/mod.rs b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/mod.rs index 21836bef237..6c0c889deac 100644 --- a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/mod.rs +++ b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/mod.rs @@ -115,6 +115,12 @@ impl DocumentReplaceTransitionActionAccessorsV0 for DocumentReplaceTransitionAct } } + fn added_data_fields(&self) -> &BTreeSet { + match self { + DocumentReplaceTransitionAction::V0(v0) => &v0.added_data_fields, + } + } + fn data_owned(self) -> BTreeMap { match self { DocumentReplaceTransitionAction::V0(v0) => v0.data, diff --git a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/mod.rs b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/mod.rs index ac82cd6d4f7..a23e67ff0ca 100644 --- a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/mod.rs +++ b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/mod.rs @@ -40,6 +40,11 @@ pub struct DocumentReplaceTransitionActionV0 { pub data: BTreeMap, /// Updated fields pub changed_data_fields: BTreeSet, + /// The subset of `changed_data_fields` the stored document had no value + /// for: properties this replace supplies for the first time. Read by the + /// immutable-property check, which lets a property listed under + /// `immutableAllowSetting` through exactly when it is set from absent. + pub added_data_fields: BTreeSet, /// Creator id pub creator_id: Option, } @@ -81,6 +86,9 @@ pub trait DocumentReplaceTransitionActionAccessorsV0 { /// The fields that have changed fn changed_data_fields(&self) -> &BTreeSet; + /// The changed fields the stored document had no value for (set for the + /// first time by this replace) + fn added_data_fields(&self) -> &BTreeSet; /// data owned fn data_owned(self) -> BTreeMap; diff --git a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/transformer.rs b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/transformer.rs index 21c3d4150ec..61f46c7b562 100644 --- a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/transformer.rs +++ b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_replace_transition_action/v0/transformer.rs @@ -108,6 +108,16 @@ impl DocumentReplaceTransitionActionV0 { let original_creator_id = original_document.creator_id(); + // The fields the stored document had no value for: this replace sets + // them for the first time. A subset of the changed fields below, kept + // apart because the immutable-property check treats a first-time set + // differently from a change or a removal. + let added_fields: BTreeSet = data + .keys() + .filter(|key| !original_document.properties().contains_key(*key)) + .cloned() + .collect(); + // Determine which fields have changed between the original document and the new data let changed_fields: BTreeSet = data .iter() @@ -153,6 +163,7 @@ impl DocumentReplaceTransitionActionV0 { original_document_transferred_at_core_block_height, data: data.clone(), changed_data_fields: changed_fields, + added_data_fields: added_fields, creator_id: original_creator_id, } .into(), diff --git a/packages/rs-drive/src/state_transition_action/batch/tests.rs b/packages/rs-drive/src/state_transition_action/batch/tests.rs index a0ca46adf81..63260bb40d7 100644 --- a/packages/rs-drive/src/state_transition_action/batch/tests.rs +++ b/packages/rs-drive/src/state_transition_action/batch/tests.rs @@ -396,6 +396,7 @@ fn make_replace_v0() -> DocumentReplaceTransitionActionV0 { transferred_at_core_block_height: Some(300), data: BTreeMap::from([("field".to_string(), Value::U64(42))]), changed_data_fields: BTreeSet::from(["field".to_string()]), + added_data_fields: BTreeSet::new(), creator_id: Some(Identifier::from([0xCC; 32])), } } @@ -2965,6 +2966,7 @@ fn stamp_test_replace_action(protocol_version: u32) -> DocumentReplaceTransition transferred_at_core_block_height: Some(300), data: BTreeMap::from([("field".to_string(), Value::U64(42))]), changed_data_fields: BTreeSet::from(["field".to_string()]), + added_data_fields: BTreeSet::new(), creator_id: Some(Identifier::from([0xCC; 32])), }) } diff --git a/packages/rs-platform-value/src/eq.rs b/packages/rs-platform-value/src/eq.rs index d048fb5a4be..f32943f1a70 100644 --- a/packages/rs-platform-value/src/eq.rs +++ b/packages/rs-platform-value/src/eq.rs @@ -152,8 +152,13 @@ impl Value { /// sequences match. /// * All integer variants (`U*`, `I*`) compare equal when they /// represent the same numeric value. + /// * Two `Map`s compare equal when they hold the same keys, in any + /// order, each with equal underlying data; two `Array`s when they + /// have the same length and equal underlying data position by + /// position. Both recurse with the same rules, so a nested integer + /// stored at a narrower width, or an object whose members were + /// reordered by schema position, still compares equal. /// * Otherwise falls back to normal `==` (`PartialEq`) behaviour. - #[inline] pub fn equal_underlying_data(&self, other: &Value) -> bool { // 1) bytes-like cross-variant equality if let (Ok(a), Ok(b)) = (self.as_bytes_slice(), other.as_bytes_slice()) { @@ -165,8 +170,154 @@ impl Value { return a == b; } - // 3) default - self == other + // 3) containers, recursively and (for maps) regardless of member order + match (self, other) { + (Value::Map(this), Value::Map(that)) => { + if this.len() != that.len() { + return false; + } + // One-to-one: a map is a list of pairs, so a duplicated key + // on one side must not be satisfied twice by a single entry + // on the other. Each matched entry is consumed. + let mut consumed = vec![false; that.len()]; + for (key, value) in this { + let matched = + that.iter() + .enumerate() + .find(|(index, (other_key, other_value))| { + !consumed[*index] + && key.equal_underlying_data(other_key) + && value.equal_underlying_data(other_value) + }); + match matched { + Some((index, _)) => consumed[index] = true, + None => return false, + } + } + true + } + (Value::Array(this), Value::Array(that)) => { + this.len() == that.len() + && this + .iter() + .zip(that) + .all(|(value, other_value)| value.equal_underlying_data(other_value)) + } + // 4) default + _ => self == other, + } + } +} + +#[cfg(test)] +mod underlying_data_tests { + use crate::Value; + + fn map(entries: Vec<(&str, Value)>) -> Value { + Value::Map( + entries + .into_iter() + .map(|(key, value)| (Value::Text(key.to_string()), value)) + .collect(), + ) + } + + /// The two ways storage rewrites an object a client sent: integer + /// widths shrink to the smallest fitting variant and members are + /// reordered by schema position. + #[test] + fn maps_compare_equal_across_member_order_and_integer_width() { + let sent = map(vec![ + ("rank", Value::U64(7)), + ("tag", Value::Text("intro".into())), + ]); + let stored = map(vec![ + ("tag", Value::Text("intro".into())), + ("rank", Value::U8(7)), + ]); + + assert!(sent.equal_underlying_data(&stored)); + assert!(stored.equal_underlying_data(&sent)); + } + + #[test] + fn maps_differ_on_a_changed_nested_value() { + let before = map(vec![ + ("rank", Value::U64(7)), + ("tag", Value::Text("intro".into())), + ]); + let after = map(vec![ + ("tag", Value::Text("intro".into())), + ("rank", Value::U8(8)), + ]); + + assert!(!before.equal_underlying_data(&after)); + } + + #[test] + fn maps_differ_on_a_missing_or_extra_member() { + let one = map(vec![("tag", Value::Text("intro".into()))]); + let two = map(vec![ + ("tag", Value::Text("intro".into())), + ("rank", Value::U8(7)), + ]); + + assert!(!one.equal_underlying_data(&two)); + assert!(!two.equal_underlying_data(&one)); + } + + #[test] + fn nested_maps_recurse() { + let sent = map(vec![( + "meta", + map(vec![ + ("rank", Value::I64(7)), + ("tag", Value::Text("a".into())), + ]), + )]); + let stored = map(vec![( + "meta", + map(vec![ + ("tag", Value::Text("a".into())), + ("rank", Value::U8(7)), + ]), + )]); + + assert!(sent.equal_underlying_data(&stored)); + } + + #[test] + fn arrays_compare_position_by_position_with_integer_leniency() { + let sent = Value::Array(vec![Value::U64(1), Value::U64(2)]); + let stored = Value::Array(vec![Value::U8(1), Value::U8(2)]); + let reordered = Value::Array(vec![Value::U8(2), Value::U8(1)]); + let shorter = Value::Array(vec![Value::U8(1)]); + + assert!(sent.equal_underlying_data(&stored)); + assert!(!sent.equal_underlying_data(&reordered)); + assert!(!sent.equal_underlying_data(&shorter)); + } + + /// A map is a list of pairs, so a key can in principle appear twice. + /// Two entries on one side must not both be satisfied by the single + /// entry they match on the other. + #[test] + fn maps_match_entries_one_to_one() { + let doubled = map(vec![("tag", Value::U8(1)), ("tag", Value::U8(1))]); + let single_plus_other = map(vec![("tag", Value::U8(1)), ("rank", Value::U8(1))]); + let doubled_too = map(vec![("tag", Value::U64(1)), ("tag", Value::U64(1))]); + + assert!(!doubled.equal_underlying_data(&single_plus_other)); + assert!(!single_plus_other.equal_underlying_data(&doubled)); + assert!(doubled.equal_underlying_data(&doubled_too)); + } + + #[test] + fn a_map_never_equals_a_non_map() { + let a_map = map(vec![("tag", Value::Text("a".into()))]); + + assert!(!a_map.equal_underlying_data(&Value::Text("a".into()))); + assert!(!a_map.equal_underlying_data(&Value::Array(vec![]))); } } diff --git a/packages/wasm-dpp/src/errors/consensus/consensus_error.rs b/packages/wasm-dpp/src/errors/consensus/consensus_error.rs index f5d17fdcb2a..9a2cb0b0b52 100644 --- a/packages/wasm-dpp/src/errors/consensus/consensus_error.rs +++ b/packages/wasm-dpp/src/errors/consensus/consensus_error.rs @@ -124,6 +124,7 @@ use dpp::consensus::state::document::referenced_identity_key_disabled_error::Ref use dpp::consensus::state::document::referenced_identity_key_not_found_error::ReferencedIdentityKeyNotFoundError; use dpp::consensus::state::document::referenced_document_property_agreement_invalid_error::ReferencedDocumentPropertyAgreementInvalidError; use dpp::consensus::state::document::referenced_document_property_mismatch_error::ReferencedDocumentPropertyMismatchError; +use dpp::consensus::state::document::document_immutable_property_changed_error::DocumentImmutablePropertyChangedError; use dpp::consensus::state::document::referenced_key_id_property_invalid_error::ReferencedKeyIdPropertyInvalidError; use dpp::consensus::state::document::referenced_document_type_not_found_error::ReferencedDocumentTypeNotFoundError; use dpp::consensus::state::shielded::insufficient_pool_notes_error::InsufficientPoolNotesError; @@ -554,6 +555,9 @@ pub fn from_state_error(state_error: &StateError) -> JsValue { StateError::IdentityPublicKeyLimitNotRaisedError(e) => { generic_consensus_error!(IdentityPublicKeyLimitNotRaisedError, e).into() } + StateError::DocumentImmutablePropertyChangedError(e) => { + generic_consensus_error!(DocumentImmutablePropertyChangedError, e).into() + } } }