fix(dpp)!: propertyConstraints compare identifier properties that declare refersTo (PV14)

[QuantumExplorer]

Basic explanation

What this does: A data contract can declare rules (propertyConstraints) that compare a document's identifier fields: "the payment token is this one", "the buyer is not the seller", "the author is the owner". An identifier field can also say what it points at with refersTo (for example "this is an existing identity"). Until now a field that declared refersTo could not appear in any of those comparisons: the contract was refused at registration with a confusing message claiming the field was a string or a number. This makes such a field compare exactly like any other identifier field.

Value: Contract authors can use both keywords on the same field, which is the natural thing to want: a buyerId that must point at an existing identity and must also differ from sellerId. Before, there was no workaround: dropping refersTo loses the existence check, and dropping the rule loses the comparison.

Risks: Low. The change only accepts declarations that were refused before; every contract that registered before parses and behaves exactly as it did. Protocol version 14 has not been released, so no production network runs it. A devnet already running a 4.2 prerelease at protocol version 14 (for example one on 4.2.0-beta.4) does see a consensus change: an upgraded node accepts such a contract where an older node refuses it, so upgrade that devnet all at once, or reset it, rather than node by node. Checking a document against the rules is unchanged: it already read identifiers the same way whatever the field declared.

Issue being fixed or feature implemented

propertyConstraints gained identifier comparisons in #5047 and $ownerId in #5048. An identifier property that declares refersTo parses to DocumentPropertyType::IdentifierWithReference(_), but apply_property_constraints_v0 matched only DocumentPropertyType::Identifier:

• the property_kind closure, which tells the parser whether a path names a string, an identifier or neither, returned None for it, so the parser read a const or an in list beside it as strings, and a comparison with another identifier property or $ownerId as integer arithmetic; both were then refused;
• the PropertyRead::Identifier check would have refused it too, with "compares "buyerId" with an identifier, but it has type identifier, not identifier" (DocumentPropertyType::name() names both variants "identifier"). The closure hid this one; fixing the closure alone would have exposed it.

Everywhere else in that file the pattern Identifier | IdentifierWithReference(_) was already used.

What was done?

• New DocumentPropertyType::is_identifier() (next to is_integer()): true for Identifier and IdentifierWithReference(_), false for a typed array of identifiers.
• apply_property_constraints_v0 (packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs): three matches that named only Identifier now test is_identifier():
  • the property_kind closure, so the parser classifies such a path as an identifier;
  • the PropertyRead::Identifier check, so it accepts it;
  • the hint given when an identifier is read as a number, so a refersTo property used in arithmetic gets the same explanation as a plain one (still refused, only the message changes).
• Other variants checked:
  • KeyIdWithReference (a u32 key id with refersTo) already reads as an integer through is_integer().
  • A typed array of identifiers, with or without refersTo on its items, is an array, which no comparison reads, so nothing changes there.
  • The SDK pre-checks (wasm-dpp2, rs-sdk-ffi for Swift, the JNI shim for Kotlin) run this same parser, so they get the fix without changes.
• Evaluation is unchanged: identifier_value reads with Value::to_identifier() whatever the declared type.
• Docs: the book's property constraints section and note 39 in v14.rs now say that identifier properties declaring refersTo are included.

Before / after

An order type whose buyerId points at an identity (sellerId is a plain identifier):

"buyerId": {
  "type": "array",
  "byteArray": true,
  "minItems": 32,
  "maxItems": 32,
  "contentMediaType": "application/x.dash.dpp.identifier",
  "refersTo": { "type": "identity" },
  "position": 11
}

Each rule below, on both parse paths (registration with full validation, and reading a stored contract):

{ "equal": ["buyerId", { "const": "<base58>" }] }
  before: invalid contract structure: document type "order" propertyConstraints rule "rule"
          compares "buyerId" with a string, but it has type identifier, not string
  after:  registers; holds when buyerId is that identifier

{ "in": ["buyerId", ["<base58>", "<base58>"]] }
  before: invalid contract structure: document type "order" propertyConstraints rule "rule"
          compares "buyerId" with a string, but it has type identifier, not string
  after:  registers; holds when buyerId is one of the listed identifiers

{ "notEqual": ["buyerId", "sellerId"] }
  before: invalid contract structure: document type "order" propertyConstraints rule "rule"
          reads "buyerId", which has type identifier, not integer or boolean
  after:  registers; holds when the two differ

{ "equal": ["buyerId", "$ownerId"] }
  before: invalid contract structure: document type "order" propertyConstraints rule "rule"
          reads "buyerId", which has type identifier, not integer or boolean
  after:  registers; holds when buyerId is the owner, and is judged again on a transfer or a
          purchase like any rule reading $ownerId

Still refused, now with the same hint a plain identifier gets:

{ "equal": ["buyerId", "price"] }
  before: ... rule "rule" reads "buyerId", which has type identifier, not integer or boolean
  after:  ... rule "rule" reads "buyerId", which has type identifier, not integer or boolean:
          an identifier property is compared, by equal or notEqual, with a { "const": base58 }
          or another identifier property, or with the identifiers an in lists

The "before" messages were captured by running the new test against the unfixed parser.

How Has This Been Tested?

• New dpp test should_compare_identifier_properties_that_declare_refers_to (try_from_schema/v3/property_constraints_tests.rs): with refersTo: { "type": "identity" } on buyerId, on sellerId, and on both, a const comparison, a comparison of the two properties, a $ownerId comparison and an in all register on both paths (full validation on and off), read their paths as identifier reads, and judge documents as they would for plain identifiers, each rule seen both holding and failing. Reading such a property as a number, comparing it with a string property, and ordering identifiers stay refused. Before the fix the test failed at the first registration with the "compares "buyerId" with a string" message above.
• New drive-abci test should_compare_an_identifier_property_that_declares_refers_to (batch/tests/document/property_constraints.rs): the owned offer type with sellerId declaring refersTo: { "type": "identity" } registers. A create naming another existing identity as seller is refused with DocumentPropertyConstraintViolatedError (10422, rule sellerIsOwner), one naming the owner is accepted, and a transfer to another identity is refused.
• New drive-abci test should_judge_const_in_and_pair_rules_over_refers_to_identifiers: payerId, refundTo and paymentToken all declare refersTo: { "type": "identity" }, and every identity the rules name exists. A create paying in an unlisted identity (in), one naming the banned payer (notEqual with a const) and one refunding someone other than the payer (two properties) are each refused with 10422 naming their rule; a create meeting all three, and all three references, is accepted.
• cargo test -p dpp --lib property_constraints: 59 passed
• cargo test -p dpp --lib try_from_schema: 477 passed
• cargo test -p drive-abci --lib property_constraints: 20 passed
• cargo clippy -p dpp --all-features --all-targets -- -D warnings: clean

Breaking Changes

Consensus, from protocol version 14 (not yet released): contracts whose propertyConstraints compare an identifier property that declares refersTo are now accepted at registration instead of refused. Nodes on either side of the change would disagree on such a registration, hence the !. Nothing changes before protocol version 14, and no contract that registered before is affected. A devnet already running a 4.2 prerelease at protocol version 14 should upgrade all its nodes together.

In-place changes

apply_property_constraints_v0 is edited in place rather than copied into a new generation, which is safe because:

• It is selected only by parse_property_constraints: Some(0), which only CONTRACT_VERSIONS_V6 (protocol version 14) sets. Every earlier table has None, which skips the keyword entirely. Protocol version 14 has not shipped, so this generation is not frozen.
• The edit only widens what registers. Before it, every rule reading an IdentifierWithReference path as an identifier was refused, so no registered contract holds one. Every declaration that parsed before takes the same branch of each widened match and parses to the same rules, and the evaluation code is untouched, so every document is judged as before.
• The only other observable difference is the text of one refusal message (the hint above) for a declaration that is refused either way.
• Networks already running a 4.2 prerelease at protocol version 14 (devnets) are the exception: for them this is a consensus change between old and new builds, so they upgrade all nodes together or reset, as they do for every prerelease.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · f6b5f3f

• Bots — coderabbitai not yet · thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
• Self-review — post /self-reviewed once the bots are done
• Within your 5 open PRs
• Build running
• Approvals — you own every area touched; none needed

When every box is checked the PR Hygiene check passes and this can merge.

[coderabbitai]

Warning

Review limit reached

Next included review available in 22 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: dashpay/platform/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: b1eee09c-3ed6-40d4-8b51-a5d89c1caca1

📥 Commits

Reviewing files that changed from the base of the PR and between e090ae2 and f6b5f3f.

📒 Files selected for processing (6)

• book/src/data-model/documents.md
• packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs
• packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/property_constraints_tests.rs
• packages/rs-dpp/src/data_contract/document_type/property/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/property_constraints.rs
• packages/rs-platform-version/src/version/v14.rs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📖 Book Preview built successfully.

Download the preview from the workflow artifacts.
To view locally: download the artifact, unzip, and open index.html.

Updated at 2026-09-27T18:01:52.377Z

[thepastaclaw]

🕓 Queued for automated review — 3rd in line, estimated start in ~10 min (commit f6b5f3f)
Estimated review time once started: ~1.3 h (two-phase automated review; median of recent runs).

• Request priority review — click to move this review to the front of the queue.