CI: load a corpus of real registered data contracts on every PR, and flag changes that break stored contracts #5271

Could Platform CI load a corpus of real registered data contracts on every PR? The corpus would hold the mainnet and testnet contract versions plus contracts that app teams volunteer, and a PR that makes any of them unloadable would fail CI or carry a "breaks stored contracts" label that the release notes surface. During the protocol version 14 betas, #5197 and #5217 each made contracts that were already registered on devnets fail to load. Nothing in CI could notice, because no test loads third-party contracts.

We hit this building Dash Forge, a git forge that runs on Platform. A companion issue, #5270, asks that a retired contract keyword be refused only at registration and update. This issue is about catching such changes before they merge.

Expected Behavior

• A test, in rs-dpp or as a CI job, loads every contract in a checked-in corpus at PlatformVersion::latest(), with and without full validation. It also loads each contract at the protocol version it was registered at.
• The corpus holds:
  • every contract version on mainnet and testnet, which is public chain data;
  • contracts that app teams submit, including ones registered on devnets that run the unreleased protocol version.
• If a PR makes a corpus contract fail to load, CI fails. The PR can still go in if it carries a label (for example breaks-stored-contracts). The release notes and the CHANGELOG then get a fixed heading such as "Breaks stored contracts", which lists the affected keywords and the replacement.

Current Behavior

• The 2026-09-20 census behind generation 3 decoded every contract create and update on mainnet and testnet. It then loaded each contract at protocol versions 11, 13 and 14 (test(dpp): guard doctype keyword names against stray keys of contracts admitted under meta-schema v0 #4855). It ran once, from the transaction list of a third-party explorer, and only its conclusion was checked in: the lists of stray doctype keys (meta_schema_v0_stray_keyword_tests.rs#L15-L26). test(dpp): guard doctype keyword names against stray keys of contracts admitted under meta-schema v0 #4855 itself suggests running the scan again over a node state snapshot during the protocol version 14 upgrade rehearsal. As far as we can tell, no test at v5.0.0-beta.1 loads registered third-party contracts. The fixtures are system contracts and hand-written test contracts.
• Our own snapshots would have caught both changes. We parsed the bytes we had fetched from two devnets with the published SDKs. Contracts registered on 4.2.0-beta.6 fail in 4.2.0-beta.7 and 5.0.0-beta.1 with refersTo lookup was replaced by findBy … and refersTo propertyAgreement was replaced by where …. A contract registered on 4.2.0-beta.7 fails in 5.0.0-beta.1 with document type "checkRun": `immutableAllowSetting` is replaced by a conditional `immutable` entry …. The snapshots, and Retiring a contract keyword makes already-registered contracts unloadable; refuse it only on registration and update #5270's reproduction, are devnet-moutai.json @ 1cc5792a and devnet-bonsia.json @ 4d6bd0aa.
• In the CHANGELOG you cannot tell which breaking change breaks stored contracts:
  • 4.2.0-beta.7 lists ten breaking changes, and only feat(dpp)!: refersTo finds a document with findBy and checks it with where #5197 made stored contracts unloadable (CHANGELOG.md#L52-L63).
  • 5.0.0-beta.1 lists ten, and only feat(platform)!: immutable properties frozen under a condition (PV14) #5217 did (#L5-L16).
  • The GitHub release notes did say it, in one sentence each. That is how we found out, and we are grateful for it. But it depends on whoever writes the release notes noticing.

Possible Solution

1. Check in the census contracts. These are the mainnet and testnet contract versions, as serialized bytes plus the protocol version each was registered at, deduplicated by content if size is a concern. Add a test that loads them at the latest version in both validation modes. Re-running the census becomes refreshing a directory.
2. Accept contracts from app teams through a directory with a short README: bytes, registering protocol version, and an owner to contact. We volunteer our three contracts (forge-core, forge-collab and forge-community, 14 to 19 KB each serialized) as registered on each devnet. We also have about 500 document accept/refuse cases against them, if document-level checks would help too.
3. Add a label and a release-note heading. A PR that breaks a corpus contract on purpose needs the label, and the label decides what goes under a "Breaks stored contracts" heading. The PR description could gain a "Stored contracts affected" section, next to the existing "In-place changes to shipped generations" convention.
4. Optionally, check updates too. For each corpus contract, check that an update to itself still passes validate_update. An owner who wants to repair a contract needs that path to work.

Alternatives Considered

• Each app testing its own contracts against every Platform build. We do this: our CI validates our contracts with rs-dpp at the Platform tag we pin. But we only find out after a release is tagged, and often after a devnet has upgraded. The work is also repeated by every app team.
• A one-off census before each release, like the 2026-09-20 one. It catches changes late, and it does not cover devnet contracts on the unreleased version, which is where app teams try Platform first.
• The contract configuration vectors in feat: pin contract configuration vectors and mirror them in wasm-dpp2 and the sdk ffi #4794 (open). They pin the config block across the SDK mirrors. The mechanism is similar, but they do not cover document schemas and they are synthetic, not registered contracts.

Additional Context

• Related: test(dpp): guard doctype keyword names against stray keys of contracts admitted under meta-schema v0 #4855 (census and stray-key guard), feat: pin contract configuration vectors and mirror them in wasm-dpp2 and the sdk ffi #4794 (configuration vectors), feat(dpp)!: refersTo finds a document with findBy and checks it with where #5197 and feat(platform)!: immutable properties frozen under a condition (PV14) #5217 (the two grammar changes), and Retiring a contract keyword makes already-registered contracts unloadable; refuse it only on registration and update #5270 (refusing retired keywords only at registration and update).
• Environment: Platform 5.0.0-beta.1 on a devnet (sakura); earlier devnets ran 4.2.0-beta.5 to beta.7. Our app uses @dashevo/evo-sdk and @dashevo/wasm-sdk 5.0.0-beta.1 from npm, and rs-sdk / rs-dpp at tag v5.0.0-beta.1. We parsed the snapshots with @dashevo/wasm-sdk 4.2.0-beta.5, 4.2.0-beta.7 and 5.0.0-beta.1 from npm.