docs(protocol-ref): audit updates#137
Merged
thephez merged 16 commits intodashpay:3.1.0from Apr 1, 2026
Merged
Conversation
…on audit Address 30+ findings from the protocol-ref audit including swapped state transition type IDs, wrong HRP values, incorrect enum names, missing error codes, and outdated constraints across 11 documentation files.
- errors.md: add 22 data contract errors (10254-10275), address basic errors section (10800-10825), fix token state codes (40700-40721) - data-contract.md: add 6 timestamp/epoch metadata fields - data-contract-token.md: fix max supply (i64::MAX), add distribution types table, fix StepDecreasingAmount params - token.md: fix purchase field names, fix note length unit (bytes), add client-side action code note - data-trigger.md: add Dashpay and MasternodeRewards triggers - document.md: add $creatorId field - protocol-constants.md: add missing processing fee row
Replace entropy with identity nonces on data contract transitions, fix max state transition size to 20 KB, move entropy generation to document.md, add keywords field, and update various source links.
📝 WalkthroughWalkthroughUpdated multiple protocol reference documents to align with rs-dpp v3.1-dev: changed Platform address HRPs to Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Add $schema enrichment note, token description property, document transition types, signing method clarifications, and fix source links.
Correct field types, version numbers, constraints, and descriptions across 11 protocol reference pages based on audit against platform v3.1-dev branch.
- Fix addPublicKeys max from 10 to 6 in state-transition.md (F-002) - Clarify min_identity_funding_amount unit/scope in identity.md (F-001) - Add reserved/unassigned rows for error codes 10823-10824 in errors.md (F-004) - Expand fee example labels for clarity in data-contract.md (F-007) - Clarify canBeDeleted applies to contract not documents in data-contract.md (F-008)
- Fix $version description: FeatureVersion (0/1), not platform protocol version (12) - Fix $dataContractId description: identity nonce, not entropy (document.md x2) - Fix data contract id prose: identity_nonce, not entropy (data-contract.md) - Fix min_identity_funding_amount unit: credits, not duffs (identity.md) - Clarify group power limits: u32 field capped at u16::MAX (data-contract.md) - Remove $action from base transition fields table; note wire-format discriminator role - Add note: type 9 uses identity signing, not address witness signing - Remove stale draft notice from protocol-constants.md
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
docs/protocol-ref/data-contract-document.md (1)
290-290: Prefer version-pinned source links for this release branch.Line 290 still references
master, while the rest of this update is pinned tov3.1-dev. Switching these links tov3.1-devwill keep references stable for the3.1.0docs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/protocol-ref/data-contract-document.md` at line 290, Update the two source links that currently point to the repository default branch to the v3.1-dev branch: replace the Rust DPP implementation link (the URL ending with packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) and the document meta-schema link (the URL ending with packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json) so both use the v3.1-dev branch instead of master.
🤖 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-document.md`:
- Line 309: The table row describing `tokenCost` is missing the `update_price`
operation; update the `tokenCost` definition to list all operations consistently
with the Token Costs section by including `update_price` alongside create,
replace, delete, transfer, and purchase so that the `tokenCost` object covers
create, replace, update_price, delete, transfer, and purchase operations (refer
to `tokenCost` and `update_price` symbols when making the change).
In `@docs/protocol-ref/data-contract.md`:
- Line 96: Fix the typo in the sentence referencing the schema: change "defined
is rs-dpp" to "defined in rs-dpp" in the docs/protocol-ref/data-contract.md
content where the paragraph mentions the full schema and GitHub links so the
sentence correctly reads that the full schema is defined in rs-dpp.
In `@docs/protocol-ref/data-trigger.md`:
- Around line 21-31: The lead-in sentence "All DPNS document types have
constraints on replacing or deleting" is too broad relative to the action matrix
which only shows rejections for the DPNS `domain` document; update the sentence
to specifically mention `domain` (e.g., "The DPNS `domain` document has
constraints on replacing or deleting") or alternatively expand the table rows to
include other DPNS document types that actually have REPLACE/DELETE rules;
update the text near the existing table header and ensure consistency with the
table rows referencing the DPNS `domain` triggers.
- Line 45: The table row containing the `domain | CREATE | ...
subdomainRules.allowSubdomains` entry uses "non top level domains"; update that
phrase to use hyphenation and read "non-top-level domains" so the compound
modifier is correct in the `domain`/`CREATE` table cell.
In `@docs/protocol-ref/document.md`:
- Around line 17-18: The documentation currently contradicts itself about
$action: decide whether $action is (A) only a JSON wire-format discriminator and
not a stored field of the base transition, or (B) an actual stored required
field of the base transition; then update all references to be consistent — if
you choose (A), remove $action from the “Required By” tables and add a
clarifying note in the “Document Transition Action” section that $action is
derived from the variant and not persisted; if you choose (B), state explicitly
in the base transition description that $action is a stored required field and
update the “Document Transition Action” section and the tables at the referenced
spots (including the other occurrences noted) to reflect that decision.
In `@docs/protocol-ref/protocol-constants.md`:
- Line 149: The markdown link in the "Unique index per property fee" table row
is malformed because the fragment "#L11" is placed outside the link parentheses;
update the link target by moving the fragment inside the URL so the link becomes
[rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L11),
ensuring the anchor resolves correctly for the "Unique index per property fee"
entry.
In `@docs/protocol-ref/token.md`:
- Around line 215-216: Update the two field names in the table from camelCase to
snake_case to match the rs-dpp implementation: replace tokenCount with
token_count and replace totalAgreedPrice with total_agreed_price; also update
the inline reference inside the description that mentions `tokenCount` to
`token_count` so the doc text and table entries (token_count,
total_agreed_price) are consistent with the rs-dpp v3.1-dev symbols.
---
Nitpick comments:
In `@docs/protocol-ref/data-contract-document.md`:
- Line 290: Update the two source links that currently point to the repository
default branch to the v3.1-dev branch: replace the Rust DPP implementation link
(the URL ending with packages/rs-dpp/src/data_contract/document_type/mod.rs#L41)
and the document meta-schema link (the URL ending with
packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json) so both use
the v3.1-dev branch instead of master.
🪄 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: ce1718ab-cabf-4053-a896-2819105156df
📒 Files selected for processing (12)
docs/protocol-ref/address-system.mddocs/protocol-ref/data-contract-document.mddocs/protocol-ref/data-contract-token.mddocs/protocol-ref/data-contract.mddocs/protocol-ref/data-trigger.mddocs/protocol-ref/document.mddocs/protocol-ref/errors.mddocs/protocol-ref/identity.mddocs/protocol-ref/overview.mddocs/protocol-ref/protocol-constants.mddocs/protocol-ref/state-transition.mddocs/protocol-ref/token.md
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/protocol-ref/data-trigger.md (1)
21-21: Pin source links to an immutable revision (avoid branch+line anchors).These links use
v3.1-devplus line numbers, which can drift and break over time. For protocol-reference docs, prefer a stable tag/commit URL (and ideally file-level links over line anchors) so references remain valid.Suggested edit pattern
- https://github.com/dashpay/platform/blob/v3.1-dev/.../reject/v0/mod.rs#L25 + https://github.com/dashpay/platform/blob/<3.1.0-tag-or-commit>/.../reject/v0/mod.rsAlso applies to: 25-25, 27-31
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/protocol-ref/data-trigger.md` at line 21, The link to the data trigger bindings in docs/protocol-ref/data-trigger.md uses a branch name and line anchors ("v3.1-dev" + line numbers) which can drift; update the URL(s) (including the ones at the other occurrences flagged: lines ~25 and ~27-31) to point to a stable tag or commit SHA and remove line anchors so the link targets the file-level view (e.g., replace the current https://github.com/.../blob/v3.1-dev/.../mod.rs#L... form with a blob URL that uses a fixed tag or commit hash and omits `#L`...); ensure you update all occurrences in that file so the docs reference an immutable revision.docs/protocol-ref/data-contract.md (1)
863-863: Note the field name asymmetry between Create and Update transitions.Data Contract Create uses
identityNonce(line 863), while Data Contract Update usesidentityContractNonce(line 887). This asymmetry also exists indocs/protocol-ref/state-transition.md(per context snippets). While this appears intentional and matches the underlying implementation, developers may find it confusing. Consider adding a brief note explaining why different field names are used for similar replay-protection purposes, or verify this naming difference is necessary.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/protocol-ref/data-contract.md` at line 863, The docs show an asymmetric field name between Data Contract Create (identityNonce) and Data Contract Update (identityContractNonce); add a short clarifying note near the table entries (around the identityNonce and identityContractNonce lines) stating whether the naming difference is intentional and why (e.g., historical reasons, differing semantic meaning, or implementation constraints) or update the docs to use consistent field names if this was unintentional—refer to the symbols identityNonce and identityContractNonce and mirror the same clarification in the corresponding state-transition documentation.
🤖 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-trigger.md`:
- Line 58: Heading text "Dashpay" in docs/protocol-ref/data-trigger.md uses
inconsistent capitalization; update the product name to "DashPay" wherever that
heading or instances appear (search for the exact string "Dashpay") to match the
canonical contract/product naming across the docs and ensure capitalization
consistency.
---
Nitpick comments:
In `@docs/protocol-ref/data-contract.md`:
- Line 863: The docs show an asymmetric field name between Data Contract Create
(identityNonce) and Data Contract Update (identityContractNonce); add a short
clarifying note near the table entries (around the identityNonce and
identityContractNonce lines) stating whether the naming difference is
intentional and why (e.g., historical reasons, differing semantic meaning, or
implementation constraints) or update the docs to use consistent field names if
this was unintentional—refer to the symbols identityNonce and
identityContractNonce and mirror the same clarification in the corresponding
state-transition documentation.
In `@docs/protocol-ref/data-trigger.md`:
- Line 21: The link to the data trigger bindings in
docs/protocol-ref/data-trigger.md uses a branch name and line anchors
("v3.1-dev" + line numbers) which can drift; update the URL(s) (including the
ones at the other occurrences flagged: lines ~25 and ~27-31) to point to a
stable tag or commit SHA and remove line anchors so the link targets the
file-level view (e.g., replace the current
https://github.com/.../blob/v3.1-dev/.../mod.rs#L... form with a blob URL that
uses a fixed tag or commit hash and omits `#L`...); ensure you update all
occurrences in that file so the docs reference an immutable revision.
🪄 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: 7780d649-0f88-425e-8891-81dbce57ec38
📒 Files selected for processing (4)
docs/protocol-ref/data-contract.mddocs/protocol-ref/data-trigger.mddocs/protocol-ref/document.mddocs/protocol-ref/protocol-constants.md
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/protocol-ref/data-contract-document.md (1)
290-290: Use a versioned rs-dpp link instead ofmasterfor release-doc stability.This section now targets v3.1-dev elsewhere, but this link still points to
master, which can drift and desync from the documented protocol version.Suggested diff
- This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) and the [document meta-schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json). + This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) and the [document meta-schema](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/protocol-ref/data-contract-document.md` at line 290, Replace the unstable "master" branch links in the sentence referencing the Rust DPP implementation and document meta-schema with the versioned rs-dpp branch/tag used elsewhere (e.g., v3.1-dev) so the docs point to a stable release; locate the two links in the sentence (the rs-dpp GitHub URL to src/data_contract/document_type/mod.rs and the document-meta.json URL) and update their paths to the matching versioned tag/branch used by the rest of the docs.
🤖 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-document.md`:
- Around line 7-9: Update the usable-properties table entry for the `$schema`
property to match the note: change the table cell so it explicitly states that
`$schema` is platform-injected during contract enrichment and must not be
included in user submissions (e.g., "platform-injected during enrichment; not
accepted in user submissions") — ensure this change is applied to the table
row(s) mentioned (including the rows around lines 295-296) and that the
`$schema` term matches the note text so readers see consistent guidance.
---
Nitpick comments:
In `@docs/protocol-ref/data-contract-document.md`:
- Line 290: Replace the unstable "master" branch links in the sentence
referencing the Rust DPP implementation and document meta-schema with the
versioned rs-dpp branch/tag used elsewhere (e.g., v3.1-dev) so the docs point to
a stable release; locate the two links in the sentence (the rs-dpp GitHub URL to
src/data_contract/document_type/mod.rs and the document-meta.json URL) and
update their paths to the matching versioned tag/branch used by the rest of the
docs.
🪄 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: 7ef3b5d6-9279-4a3f-a614-e83b79035534
📒 Files selected for processing (2)
docs/protocol-ref/data-contract-document.mddocs/protocol-ref/document.md
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/protocol-ref/data-contract-document.md (1)
221-222: Clarify applicability of array-index limits when array indices are disallowed.The current wording is internally confusing: it says array indices are not allowed, then immediately lists indexed-array limits. Consider explicitly marking these as schema-level limits that are currently non-applicable in practice.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/protocol-ref/data-contract-document.md` around lines 221 - 222, Edit the table rows that currently show the "Note: Dash Platform does not allow indices for arrays" followed by "Maximum length of indexed byte array property" and "Maximum number of indexed array items" to clarify these are schema-level limits that are not currently applicable; explicitly prepend or append a phrase like "Schema-level limit (not applicable: array indices disallowed)" to the two items "Maximum length of indexed byte array property" and "Maximum number of indexed array items" so readers see the limits but understand they are not enforceable while array indices are disallowed.
🤖 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-document.md`:
- Line 290: The current Rust DPP reference link in the sentence points to the
repository's master branch which can drift; update the URL that links to
packages/rs-dpp/src/data_contract/document_type/mod.rs so it uses the v3.1-dev
tag instead of master (i.e., change the link target from .../blob/master/... to
.../blob/v3.1-dev/...) to match the rest of the document's version-pinned
references.
---
Nitpick comments:
In `@docs/protocol-ref/data-contract-document.md`:
- Around line 221-222: Edit the table rows that currently show the "Note: Dash
Platform does not allow indices for arrays" followed by "Maximum length of
indexed byte array property" and "Maximum number of indexed array items" to
clarify these are schema-level limits that are not currently applicable;
explicitly prepend or append a phrase like "Schema-level limit (not applicable:
array indices disallowed)" to the two items "Maximum length of indexed byte
array property" and "Maximum number of indexed array items" so readers see the
limits but understand they are not enforceable while array indices are
disallowed.
🪄 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: 9aa23dca-11eb-4922-b6de-03dc5d412354
📒 Files selected for processing (1)
docs/protocol-ref/data-contract-document.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updates the protocol reference documentation to align with the v3.1-dev branch of the platform repository. Changes were driven by a systematic audit of protocol-ref docs against the v3.1-dev source code, correcting inaccuracies, updating stale source links, and adding newly documented features.
Highlights
v3.0.0tov3.1-devbranch references across all protocol-ref pagesevo/tevo→dash/tdash), corrected hash algorithm to double-SHA256, updated fee strategy detailsasc-only constraint note, corrected property tables, added token cost sectionPreview build: https://dash-docs-platform--137.org.readthedocs.build/en/137/
Summary by CodeRabbit