[shumkov]

Basic explanation

What this does: Document actions paid with tokens respect pause and the token issuer's policy for transfers to frozen accounts from protocol version 14.

Value: Applies the issuer's movement restrictions to all seven document action paths, including payments using another contract's token.

Risks: Changes consensus acceptance and validation fees in unreleased PV14. Older protocol tables and validator generations remain unchanged; retained beta-PV14 histories need a separately coordinated activation/replay decision. No deployment or recovery action is included.

Issue being fixed or feature implemented

Token-cost document payments checked the payer's freeze state and balance but omitted movement policy. This addresses the token audit's T1 finding; group-burn proof/result work is a separate PR.

What was done?

• Add document-base state_v2, selected by PV14's existing V10 slot. Preserve the shielded-payment branch and existing payer freeze/balance precedence.
• For actual transfers and burns, bill pause validation next. For transfers, then bill recipient info; consult token metadata and the actual issuer's current configuration only if the recipient is frozen. Reject only when allowTransferToFrozenBalance is false (default true). Missing/inconsistent issuer metadata is an internal corruption error.
• Retain elided transparent transfer payments to the payer itself: no movement, existing payer checks, no new pause or recipient checks. Changing this policy has not been separately authorized. Owner burn payments move tokens and still check pause.
• Update the long-term token-cost book page and PV14 changelog entry 84; cover the seven paths: create, replace, stored delete, transfer, update-price, purchase, index-only delete.

In-place changes to shipped generations

None. Document-base state_v0 and state_v1, native burn policy, and pre-PV14 tables are unchanged. The dispatcher gains version 2, and only the unreleased PV14 V10 slot selects it.

How Has This Been Tested?

• Real red before green on macOS with sccache, two Cargo jobs: cargo test -p drive-abci --lib token_cost_policy -j 2 -- --nocapture compiled and ran on the unfixed validator: 4 passed / 9 failed. Both seven-path tests observed SuccessfulExecution for every restricted payment. After the fix: 13 passed / 0 failed; the final suite with review-requested burn controls: 15 passed / 0 failed / 0 ignored.
• Two review-requested mutation checks also failed at runtime: dropping the transfer-effect owner-elision guard gave two reads instead of three; dropping the burn early return rejected a burn because the contract owner was frozen. Restoring the validator gave the 15-test green result, including owner balance/supply and no-recipient-read controls.
• The same suite covers issuer default true, external issuer policy opposing the document contract's own token policy, exact charged read order, payer/recipient error precedence, same-transaction pause, optional credits, active/paused burn, elided self-payment, and PV13 acceptance controls.
• cargo test -p drive-abci --lib 'batch::tests::document::' -j 2 -- --test-threads=2: 519 passed / 0 failed / 0 ignored, at the initial implementation head, including the policy suite and surrounding document/sponsorship tests. The review follow-up changes tests and documentation only; production logic is identical.
• cargo test -p drive-abci --lib document_shielded_token_payment_tests -j 2 -- --test-threads=2: 4 passed / 0 failed / 0 ignored, preserving pool transfer/burn, amount agreement, and pre-PV14 rejection behavior.
• cargo fmt --all -- --check: passed.
• cargo clippy -p drive-abci --all-features --all-targets -j 2 -- -D warnings: passed, repeated after the review follow-up. Independent Opus review agreed on signed head 2a6a0343c435b51a5884c912de014154a6eff462 with no unresolved must-fix. No live network transactions or workspace-wide local test run.
• Final-head Tests CI, attempt 2: passed. Workspace nextest: 18,660 passed / 0 failed / 1,381 configured skips, including all 15 token policy tests. Shielded cargo summaries: 935 passed / 0 failed / 3 ignored / 13,690 filtered out. Workspace formatting/clippy, dependency and feature checks passed. Downstream Swift build/tests passed: 800 tests, 16 skipped, 0 failures. JS build and all nine JS test suites, Kotlin SDK build/emulator tests, and book preview passed.
• Attempt-1 Rust CI hit the runner's 90-minute infrastructure timeout during compilation/linking, with no reported test failure. One coordinator-authorized scoped Rust retry and its dependent Swift job succeeded on the same head. Doctests, coverage generation/uploads, full chain simulation, wallet, Docker, ARM64 validation, E2E checks and JS linting were configured skips; these are not counted as passes. GitHub review threads are empty; PR Hygiene awaits Ivan's personal self-review attestation.

Breaking Changes

PV14 rejects previously accepted restricted token-cost movements and charges the added validation reads. Mixed binaries using this same protocol version can disagree; activation on an existing beta network is a separate campaign decision. PV13 and earlier behavior is preserved.

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
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

PR Hygiene · 2a6a034

• Bots — coderabbitai skipped after its own rate limit · thepastaclaw ✓
• Self-review — post /self-reviewed
• Build green
• Approvals — you own every area touched; none needed

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: dashpay/platform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: dc2102ea-76cd-458e-a53e-0e0d1cae7c70

📥 Commits

Reviewing files that changed from the base of the PR and between 1742775 and 7e16fa1.

📒 Files selected for processing (7)

• book/src/contract-keywords/token-cost.md
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_base_transaction_action/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_base_transaction_action/state_v2/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/token_cost_policy.rs
• packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v10.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Validation version 2 adds pause checks and issuer-configured frozen-recipient checks for transparent document-token payments. The change preserves separate shielded-pool validation and adds tests and documentation for the policy, its read order, and its exceptions.

Changes

Document token payment policy

Layer / File(s)	Summary
Versioned validation dispatch packages/rs-platform-version/.../drive_abci_validation_versions/v10.rs, packages/rs-drive-abci/.../document_base_transaction_action/mod.rs	The document base transition validation version advances from 1 to 2. Version 2 dispatches to its new validation implementation.
Transparent payment policy checks packages/rs-drive-abci/.../document_base_transaction_action/state_v2/mod.rs	Version 2 runs V0 checks for non-shielded actions. It checks pause status for remaining payments and checks recipient and issuer policy for transfers to frozen recipients.
Policy tests and documentation packages/rs-drive-abci/.../action_validation/document/mod.rs, packages/rs-drive-abci/.../tests/document/*, book/src/contract-keywords/token-cost.md	Tests cover payment policies, validation read order, error precedence, document actions, and protocol versions. The documentation describes pause and frozen-recipient checks, read charges, and exceptions.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant DocumentBaseTransitionAction
  participant validate_state_v2
  participant V0Validation
  participant TokenState
  participant RecipientAccount
  participant IssuerConfiguration
  DocumentBaseTransitionAction->>validate_state_v2: dispatch validation version 2
  validate_state_v2->>V0Validation: validate non-shielded action
  V0Validation-->>validate_state_v2: validation result
  validate_state_v2->>TokenState: read token pause status
  TokenState-->>validate_state_v2: pause status
  validate_state_v2->>RecipientAccount: read recipient account for transfer
  RecipientAccount-->>validate_state_v2: account freeze status
  validate_state_v2->>IssuerConfiguration: read issuer policy when recipient is frozen
  IssuerConfiguration-->>validate_state_v2: allowTransferToFrozenBalance

Loading

Suggested reviewers: quantumexplorer

Merge Risk: ⚪ Minimal · up to 7e16f

No identified policy regression remains; the change is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 48.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 27 functions across 6 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: enforcing token policy on document payments.

Full details: Docstring Coverage

Explanation

Docstring coverage is 48.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 27 functions across 6 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[thepastaclaw]

✅ Final review complete — no blockers (commit 2a6a034) · triage: critical

[github-actions]

Waiting for bot review — coderabbitai ✓ · thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

[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-10-07T17:10:47.191Z

[github-actions]

Waiting for bot review — coderabbitai not yet · thepastaclaw ✓. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

[thepastaclaw]

Final validation — Phase 1 + Phase 2

Static verification found no actionable in-scope defects. The PV14-only validator preserves historical behavior, matches execution's transfer-elision and burn semantics, and meters the added policy reads; the documentation nitpick is not substantiated when read with the surrounding transfer-versus-burn explanation. No builds or tests were run; the supplied CI snapshot still had Rust workspace tests queued and the JS build in progress.

Review provenance

Source: reviewer 1: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: architecture-layering); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: platform-versioning); reviewer 4: gpt-6.1-sol (agent: phase2-reviewer, role: rust-quality); reviewer 5: gpt-6.1-sol (agent: phase2-reviewer, role: security-auditor); reviewer 6: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 7: muse-spark-1.3-contributor (agent: phase1-reviewer, role: rust-quality); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

• Triage: critical by gpt-6.1-sol (effort low) — The new document_base_transaction_action/state_v2/mod.rs validator changes consensus acceptance and charged validation reads for token transfers and burns through intricate payer, pause, recipient, issuer-policy, and self-payment branches shared by seven document action paths.
• Phase 1 reviewers: muse-spark-1.3-contributor — general (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — rust-quality (completed, effort xhigh); agent phase1-reviewer
• Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 15% left, 5h 100% left), glm-5.3-flash (not used above high effort; tier asks max)
• Single stage: Phase 1 and Phase 2 reviewed this head side by side, with no blocker gate between them (triage tier)
• Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
• Phase 2 reviewers: gpt-6.1-sol — general (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — architecture-layering (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — platform-versioning (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — rust-quality (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — security-auditor (completed, effort xhigh); agent phase2-reviewer

[github-actions]

Bots are done — your move: post /self-reviewed.
Full checklist in the description.