feat(platform)!: contract references may require the referenced contract to declare elected moderation

[QuantumExplorer]

Issue being fixed or feature implemented

Part of #4865 (decentralized moderation teams). The charter system contract (#4898) points at the contract a team applies to moderate with a refersTo: { "type": "contract" } reference, which proves the contract exists. It cannot say that the contract must declare an elected moderation team; that check was left to the seating PR as custom code.

What was done?

A contract reference may now carry requirements on the referenced contract:

"targetContractId": {
  "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32,
  "contentMediaType": "application/x.dash.dpp.identifier",
  "refersTo": { "type": "contract", "contractRequirements": { "moderation": "elected" } }
}

• Shape. contractRequirements is an object under the reference: each key names an aspect of the referenced contract and its value the requirement on it, a closed set per key. moderation: "elected" is the first and only one: the contract must declare ContractModerators::Elected, whatever its interim and whether a team is seated. The next requirement is another key inside the object, not another reference type. contractRequirements is refused on every other reference type, an empty object is refused, and so are unknown keys and values (parser and meta-schema v3).
• Types. DocumentPropertyReferenceTarget::Contract became a struct variant carrying ContractReferenceRequirements { moderation: Option<ContractReferenceModeration> }; the serde form omits the field when it requires nothing, so an existing { "type": "contract" } round-trips unchanged. first_unmet_by(&contract) answers which requirement a contract fails.
• Check. The document reference validation already fetches the referenced contract for the existence check; it now asks the declaration's requirements of that contract, at no further read, and refuses an unmet one, paid, with the new state error ReferencedContractRequirementNotMetError { contract_id, field, required, path } (40135, document state band, StateError discriminant 143). A missing contract stays 40120.
• Update. A changed contractRequirements is an incompatible schema change on a document type update, like every other change under refersTo (pinned by a test).
• Clients. wasm-dpp maps the error; wasm-dpp2's reference surface reports contractRequirements (absent when the declaration carries none) and mirrors the code in DocumentReferenceErrorCode.
• Docs: the book's elected moderation section, the v14 changelog (item 24).

Once this merges, #4898's charter declares the requirement on targetContractId.

How Has This Been Tested?

• rs-dpp: the parser accepts the declaration, refuses contractRequirements that are empty, unknown, mistyped or on another reference type; the reference target's Display and mirror tests; the StateError discriminant pin; the update test.
• drive-abci: a document referencing an existing contract without elected moderation is refused with 40135 naming the contract, the field and the path; a missing contract is still 40120; a document referencing a contract that declares an elected team succeeds.
• wasm-dpp2: the code mirror test; cargo check on wasm-dpp and wasm-dpp2.

Breaking Changes

Consensus: a new refersTo sub-keyword in the v3 document meta-schema and a new state error, both at protocol version 14 (unreleased).

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

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 14 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: fa22bb4d-39b4-423a-b055-1a0c545f2d59

📥 Commits

Reviewing files that changed from the base of the PR and between f7bfcbc and cdd7b0e.

📒 Files selected for processing (17)

• book/src/data-model/contract-moderation.md
• packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json
• packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs
• packages/rs-dpp/src/data_contract/document_type/methods/validate_update/common/mod.rs
• packages/rs-dpp/src/data_contract/document_type/mod.rs
• packages/rs-dpp/src/data_contract/document_type/property/mod.rs
• packages/rs-dpp/src/errors/consensus/codes.rs
• packages/rs-dpp/src/errors/consensus/state/document/mod.rs
• packages/rs-dpp/src/errors/consensus/state/document/referenced_contract_requirement_not_met_error.rs
• packages/rs-dpp/src/errors/consensus/state/state_error.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/creation.rs
• packages/rs-drive-abci/tests/supporting_files/contract/reference-validation/reference-validation-contract-elected-contract-ref.json
• packages/rs-platform-version/src/version/v14.rs
• packages/wasm-dpp/src/errors/consensus/consensus_error.rs
• packages/wasm-dpp2/src/consensus_error.rs
• packages/wasm-dpp2/src/data_contract/document_type_reference.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-22T04:46:41.964Z

[thepastaclaw]

⚠️ DEGRADED — Queued for automated review — 17th in line, estimated start in ~15 h (commit cdd7b0e)
Estimated review time once started: ~1.8 h (two-phase automated review; median of recent runs).
The primary review models are currently out of quota; this review will run on stand-in models and be marked as degraded.

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

[QuantumExplorer]

Reviewed