Settle contract declarations and the Rust author API

Parent: #4626 · Complete tracking register

Proposed target: 4.4-dev. This is a workstream tracking issue, not a claim that the release branch exists or the implementation is done. Owner: QuantumExplorer. Dates and effort remain unset.

Scope

Specify persistent structs, free functions and impl methods, indexes/rules, typed builders, stable IDs and named-module manifests. Preserve explicit persistence and native index-update validation. Keep declarations and authority boundaries reviewable against the actual native types.

Specification

DVM-04 · DVM-05 · DVM-11 · DVM-12

The current parent acceptance and module/capability appendices remain authoritative; these DIP drafts add proposed engineering detail without silently approving open allocations.

Completion criteria

These two tasks specify the model and API; generated persistence, production macros, independent host enforcement and worked-runtime acceptance remain SDK-02/03/04 and CAP-03 onward in 5.0. Private fields or ACLs do not imply encryption, and unspecified private capabilities remain disabled.

Early work-package prerequisites: 43-PLAN, 44-CODEC, 44-GROVE. These are separate from the 234 task-level links.

Task acceptance

CAP-02

• Specify typed capability declarations and contract authority

Choose document-schema extensions versus a typed collection interface; define namespace, rules, read/write methods, limits and privacy model. No raw system paths. Q36 (confirmed): Use simple persistence/index/rule attributes plus typed builders for advanced native features, producing one canonical manifest. Reject unsupported/conflicting declarations; native validation remains the authority. No unrestricted database paths. Q38 (confirmed): Private Rust fields and ACL checks are not encryption. Keep the private capability in the catalogue while encryption, key control, query visibility and proof behavior are separately specified before enabling its interface.

Prerequisites: None recorded.

Dependents: CAP-03, CAP-05, CAP-06, CAP-07, CAP-08, CAP-09.

Modules: ABI, AUTH, COLLECTIONS. Original task context. Capabilities: T01, T02, T03, T13, T14, T15, T16, T17, R01, R03, R04, Q06, Q14. Refinements (not extra dependency edges): SDK-01, STUB-ACL, STUB-RNG.

SDK-01

• Specify persistent structs, indexes, rules and entry annotations

Review exact developer API; stable collection/property/method identity, bounded fields, full typed-manifest escape for compatible native features, strict diagnostics and independent host validation. Q18 (confirmed): Reuse existing versioned DPP/Drive index-update rules exactly. Do not introduce a new index-backfill/migration subsystem. The inspected v1 validator rejects adding, removing or changing indexes on existing document types; new types may declare indexes through normal validation. Q35 (confirmed): Detached Rust values do not save automatically. Explicit insert/edit operations and successful exported persistent-receiver wrappers stage writes in the outer transaction. No save on Drop. Q36 (confirmed): Use simple persistence/index/rule attributes plus typed builders for advanced native features, producing one canonical manifest. Reject unsupported/conflicting declarations; native validation remains the authority. No unrestricted database paths. Q38 (confirmed): Private Rust fields and ACL checks are not encryption. Keep the private capability in the catalogue while encryption, key control, query visibility and proof behavior are separately specified before enabling its interface. Native award acceptance: supported parameter validation; no guest/custom-guard execution on winner award; ordinary action guards remain enforced; internal native authority cannot be forged; native lifecycle/atomicity and existing index-update rules remain enforced. Named-module scope: Specify a multi-module guest package and module/interface declarations, with stable contract-wide method/type/index IDs independent of source-module names. Persistence attributes and free/impl entry functions remain supported. Confirmed crate layout: Use packages/rs-dash-sdk-contract, Cargo package dash-sdk-contract and Rust import dash_sdk_contract for the contract-author API, examples and dependency declarations. Keep native execution integration in the separate rs-drive-contracts crate; native storage and validation continue to use Drive/DPP.

Prerequisites: None recorded.

Dependents: SDK-02, SDK-04, STUB-ACL, STUB-RNG.

Modules: AUTHOR, ABI, BUILD. Original task context.

Coordination and dependencies

Task-level prerequisites above govern order. Workstreams contain multiple stages, so a cross-link is not a claim that the entire other issue must close first. These are Markdown relationships, not native GitHub blocked-by edges. The parent dependency register preserves all 234 links, reasons and explicit/inferred labels.

• CAP-02 → CAP-03 (inferred): Implementation dependency between the specified adapters and their integration checks.
• CAP-02 → CAP-05 (inferred): Implementation dependency between the specified adapters and their integration checks.
• CAP-02 → CAP-06 (inferred): Implementation dependency between the specified adapters and their integration checks.
• CAP-02 → CAP-07 (inferred): Implementation dependency between the specified adapters and their integration checks.
• CAP-02 → CAP-08 (inferred): Implementation dependency between the specified adapters and their integration checks.
• CAP-02 → CAP-09 (inferred): Implementation dependency between the specified adapters and their integration checks.
• SDK-01 → SDK-02 (inferred): Implement the reviewed persistence and entry API.
• SDK-01 → SDK-04 (inferred): Stable schema/method declarations are needed for compatibility diffs.
• SDK-01 → STUB-ACL (inferred): The declaration grammar includes a required ACL capability.
• SDK-01 → STUB-RNG (inferred): The declaration grammar includes a required randomness capability.

PR and evidence tracking

Create focused PRs against the chosen development branch. Link this issue with Refs #<issue-number> for partial work. Do not use Fixes for the whole workstream until every listed full task and acceptance criterion is complete.

For a PR that completes an entire task, add a standalone line in its actual PR body: Dash-Tasks: <completed task IDs>. Replace the placeholder with only fully completed IDs. Preparation PRs use ordinary references and omit the completion marker for their broader parent tasks. The site reads this marker on PRs in dashpay/platform and dashpay/grovedb: draft = red, ready for review = yellow, merged with no linked open PR = green. Closed-unmerged is not completion. This does not automatically close issue checkboxes and does not prove acceptance tests passed; reviewers must record the evidence.