docs(protocol-ref): audit corrections for v3.1 protocol reference

[thephez]

Summary

Applies findings from two audit passes of docs/protocol-ref/ against the v3.1-dev platform source, correcting factual errors and omissions across the protocol reference pages. The changes fix incorrect field sizes, outdated constants, missing content, and misleading constraint descriptions.

Highlights

Correctness fixes

• Fix $version field size from 32 to 16 bits in Data Contract Create/Update state transition tables (matches FeatureVersion = u16)
• Fix credit transfer fee note to include per-recipient output cost (500K base + 6M per recipient, not a flat 500K)
• Fix minimum withdrawal amount (~181K → ~190K credits)
• Fix token contract keywords limit ("20 at creation; 50 on update" → 50 for both)
• Fix Group Action Info field names to match actual serde serialization

Missing content

• Add marketplaceRules to token configuration full example JSON
• Add preProgrammedDistribution to distribution properties table
• Add minimum group size (2) and member power constraint to group constants
• Add Size column to Data Contract Update table
• Add signed/unsigned type note for distribution function parameters a and m

Clarifications

• Clarify DPNS trigger ownerId check is currently a no-op due to v1 schema field name mismatch
• Add JSON field name aliases (start_step, starting_amount, start_moment) alongside formula variables in distribution function parameter descriptions
• Update source links from v1.rs to v3.rs for address transaction limits
• Fix source link line ranges for token burn/freeze transitions

Preview build: https://dash-docs-platform--140.org.readthedocs.build/en/140/

Summary by CodeRabbit

Documentation

• Clarified identity credit transfer fee: added formula for base + per-recipient fee and example.
• Added scheduled (pre-programmed) token distribution configuration and clarified distribution parameter names and sign rules.
• Unified keyword limits to a single maximum (50) across docs; expanded token example with marketplace rules.
• Documented ownerId trigger as a no-op for DPNS domain CREATE.
• Reordered publicKeys field documentation for clarity.
• Updated version field sizes, batch limits, and withdrawal minimum calculation wording.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fc1b0ec2-ab55-40e4-9a28-ec5e8ea61591

📥 Commits

Reviewing files that changed from the base of the PR and between e4bc7dc and 8846df6.

📒 Files selected for processing (1)

• docs/protocol-ref/data-trigger.md

✅ Files skipped from review due to trivial changes (1)

• docs/protocol-ref/data-trigger.md

---

📝 Walkthrough

Walkthrough

Documentation updates across protocol reference files: clarified constraints (keywords, group sizes, field bit widths), introduced token distribution field and parameter aliases, updated fee formulas and source links, reordered identity/publicKeys docs, and corrected trigger/schema notes and transition/table metadata.

Changes

Cohort / File(s)	Summary
Keywords & Version / Token distribution docs/protocol-ref/data-contract-token.md, docs/protocol-ref/data-contract.md	Normalized keywords limit to [50]; added preProgrammedDistribution to token config; introduced parameter alias names (start_step, starting_amount, start_moment) and sign/unsigned notes; expanded token example with marketplaceRules. Also changed $version field size (32 → 16 bits) in related docs.
Fees & Protocol constants docs/protocol-ref/address-system.md, docs/protocol-ref/protocol-constants.md	Replaced static Identity Credit Transfer fee text with formula 500,000 credits base + 6,000,000 credits per recipient and example; updated Min withdrawal amount to explicit 190,000 credits with formula and adjusted transaction limits source references.
Schema / Trigger / Identity / State transitions / Token refs docs/protocol-ref/data-trigger.md, docs/protocol-ref/identity.md, docs/protocol-ref/state-transition.md, docs/protocol-ref/token.md	Documented DPNS ownerId trigger check as a permanent no-op given v1 schema; reordered publicKeys table entries and typography tweak; changed Batch transitions to reflect max 1 object and adjusted Data Contract Update layout metadata (explicit sizes); tightened rs-dpp line-range links for token transitions.
Minor/metadata edits docs/protocol-ref/...	Small source link updates and layout/description tweaks across protocol-ref docs (line-range, wording, and table metadata corrections).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• fix(dpp): keyword max count mismatch between schema validation (20) and update validation (50) platform#3420: The change consolidating the data contract keywords limit to 50 directly addresses the keyword-count discrepancy noted in that issue.

Possibly related PRs

• docs(protocol-ref): audit updates #137: Modifies overlapping protocol-ref documentation (keyword limits, token distribution, identity/address notes) and appears strongly related.

Poem

🐇 I hop through docs with ink so bright,
I tweak the rules by moonlit byte,
Keywords counted, fees spelled true,
Versions trimmed and examples new,
A rabbit's cheer for protocol light ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the primary objective of the PR: applying audit corrections to documentation in the protocol reference section for v3.1.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/protocol-ref/data-contract.md`:
- Line 83: The docs state a max of 50 keywords but the embedded JSON Schema
limits keywords.maxItems to 20; update the schema snippet so keywords.maxItems
matches the prose (set to 50) or alternatively add an explicit version/caveat
clarifying the two limits; ensure the referenced field name "keywords" and the
schema property "keywords.maxItems" are changed together and any example or
validation rules in the same document are updated to remain consistent.

In `@docs/protocol-ref/data-trigger.md`:
- Line 42: Update the table row for domain `CREATE` to remove the incorrect
claim that `records.dashUniqueIdentityId`/`records.dashAliasIdentityId` are
absent from the v1 schema and instead state the real cause: verify whether the
trigger logic (the CREATE trigger) is checking the wrong field names or running
pre-validation before schema constraints are applied; reference the DPNS v1
schema properties `records.dashUniqueIdentityId` and
`records.dashAliasIdentityId` and clarify that the schema does include these
fields and enforces the one-or-the-other constraint via max/min properties, or
explicitly note a version mismatch or trigger bug if that is the true issue
(e.g., mismatch between trigger code and schema). Also shorten the long table
cell by moving the detailed explanation into a short note or a follow-up
paragraph below the table for readability.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1406622d-f6fa-4ab3-9c76-ed9a6c520411

📥 Commits

Reviewing files that changed from the base of the PR and between 74992af and e4bc7dc.

📒 Files selected for processing (8)

• docs/protocol-ref/address-system.md
• docs/protocol-ref/data-contract-token.md
• docs/protocol-ref/data-contract.md
• docs/protocol-ref/data-trigger.md
• docs/protocol-ref/identity.md
• docs/protocol-ref/protocol-constants.md
• docs/protocol-ref/state-transition.md
• docs/protocol-ref/token.md