Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions book/src/data-model/documents.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down
16 changes: 16 additions & 0 deletions packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
53 changes: 53 additions & 0 deletions packages/rs-dpp/src/data_contract/document_type/accessors/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> = BTreeSet::new();

impl DocumentTypeV2Getters for DocumentType {
fn documents_countable(&self) -> bool {
match self {
Expand Down Expand Up @@ -980,6 +985,22 @@ impl DocumentTypeV2Getters for DocumentType {
DocumentType::V2(v2) => v2.index_only(),
}
}

fn immutable_fields(&self) -> &BTreeSet<String> {
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<String> {
match self {
DocumentType::V0(_) => &NO_IMMUTABLE_FIELDS,
DocumentType::V1(_) => &NO_IMMUTABLE_FIELDS,
DocumentType::V2(v2) => v2.immutable_fields_allow_setting(),
}
}
}

impl DocumentTypeV2Setters for DocumentType {
Expand Down Expand Up @@ -1056,6 +1077,22 @@ impl DocumentTypeV2Getters for DocumentTypeRef<'_> {
DocumentTypeRef::V2(v2) => v2.index_only(),
}
}

fn immutable_fields(&self) -> &BTreeSet<String> {
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<String> {
match self {
DocumentTypeRef::V0(_) => &NO_IMMUTABLE_FIELDS,
DocumentTypeRef::V1(_) => &NO_IMMUTABLE_FIELDS,
DocumentTypeRef::V2(v2) => v2.immutable_fields_allow_setting(),
}
}
}

impl DocumentTypeV2Getters for DocumentTypeMutRef<'_> {
Expand Down Expand Up @@ -1098,6 +1135,22 @@ impl DocumentTypeV2Getters for DocumentTypeMutRef<'_> {
DocumentTypeMutRef::V2(v2) => v2.index_only(),
}
}

fn immutable_fields(&self) -> &BTreeSet<String> {
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<String> {
match self {
DocumentTypeMutRef::V0(_) => &NO_IMMUTABLE_FIELDS,
DocumentTypeMutRef::V1(_) => &NO_IMMUTABLE_FIELDS,
DocumentTypeMutRef::V2(v2) => v2.immutable_fields_allow_setting(),
}
}
}

#[cfg(test)]
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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<String>;

/// 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<String>;
}

/// Trait providing setters for DocumentTypeV2-specific fields.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1971,6 +1971,148 @@ pub(super) fn parse_index_only_keyword(schema: &Value) -> Result<bool, ProtocolE
.unwrap_or(false))
}

/// Reads a doctype-level array of top-level property names (`immutable`, the
/// properties frozen at document creation on a mutable type, or
/// `immutableAllowSetting`, the frozen properties a replace may still set
/// while absent) before the core parse consumes `schema`, same shape as
/// [`parse_index_only_keyword`]. Only the generation-3 driver calls this;
/// earlier generations ignore both keywords exactly as they ignore every
/// doctype-level keyword they predate (their meta-schemas still reject them
/// under `full_validation`).
///
/// Every entry must be a string. The meta-schema enforces that under full
/// validation and a stored contract can only ever have passed it, so a
/// non-string entry is a malformed schema on either path and is refused
/// rather than silently dropped: dropping it would record a smaller set than
/// the author declared.
pub(super) fn parse_property_name_list_keyword(
schema: &Value,
name: &str,
keyword: &str,
) -> Result<BTreeSet<String>, 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<String>,
immutable_fields_allow_setting: BTreeSet<String>,
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}"
)));
}
Comment on lines +2073 to +2084

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Reject transient properties in the immutable list

The parser accepts a property listed in required, transient, and immutable. Creation discards its value, so every replacement supplying it fails the immutable check—even when unchanged—while omitting it fails required-field validation. This makes the accepted document type permanently uneditable, and the grow-only rule prevents removing the restriction afterward. Reject immutable/transient overlap during full schema validation. Both replacement failures reproduce end-to-end.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d6f3c1a. The parser refuses a property listed under both transient and immutable under full validation ("a transient property is never stored, so every replace that supplies it would be refused as changing an immutable property"). Unit test rejects_a_transient_property; meta-schema description and the book bullet updated.

// 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.
Expand Down
Loading
Loading