docs(platform): distinguish current-state proofs, stored receipts and execution result text

[DCG-Claude]

Issue being fixed or feature implemented

Part of the smart-contract plan in #4626 (section 6.6, owner decision Q32), workstream 50-PROOFS. Task R06-11.

A contract call response can carry the guest's returned bytes or error text, a stored receipt, response metadata and a GroveDB proof in one message. Nothing in the repository said which of those a client may treat as proven, so the receipt, ABI and client tasks had no shared vocabulary to implement against, and a client could advertise a result as a proof of execution merely because the same response included a valid state proof. The receipt policy the owner confirmed (enabled by default, contract-controlled retention, no invented expiry, code retention independent) was also recorded only in the issue.

Refs #4692

What was done?

Documentation only. No code, wire or version change; every .rs edit is a doc comment.

• New book chapter book/src/sdk/results-receipts-and-proofs.md. It names the three result classes (unproven execution-result text, stored receipt, current-state proof) with what each is bound to and what a client may and may not conclude; places them alongside the existing ExecutionProved versus AffectedState guarantee (the StateTransitionProofGuarantee carried by StateTransitionProofOutcome) and the strict and affected-state wait pairs; states what a receipt proves and does not; records the Q32 receipt policy as binding; lists the reasons a receipt can be absent and why absence is never "call failed"; tabulates the outcome classes a client must keep apart; maps today's Rust SDK, proof verifier and JavaScript SDK APIs to the class they return; and closes with a requirement checklist naming the implementing tasks (R08-04, R10-03, R12-09, R10-06, R13-03, R13-11, R09-08, R10-07).
• book/src/SUMMARY.md: one entry under Rust SDK after Put Operations.
• book/src/sdk/put-operations.md: the BroadcastStateTransition listing now includes wait_for_affected_state and broadcast_and_wait_for_affected_state, the use-case list covers all five methods and the _with_metadata twins, the wait example matches the real code (the tagged outcome goes through require_execution_proved before conversion), a paragraph explains the two tags, and the error list gains ExecutionNotProved.
• book/src/evo-sdk/state-transitions.md: the waiting section now shows waitForStateTransitionResult, waitForResponse and waitForAffectedState (the previous example called a waitForResult method that does not exist on the facade) and explains strict versus snapshot waits.
• Rustdoc anchors pointing at the chapter: StateTransitionProofOutcome in packages/rs-dpp/src/state_transition/proof_result.rs (how a receipt relates to the two tags), the BroadcastStateTransition trait in packages/rs-sdk/src/platform/transition/broadcast.rs (previously undocumented; the two pairs and their guarantees), FetchUnproved in packages/rs-sdk/src/platform/fetch_unproved.rs and FromUnproved in packages/rs-drive-proof-verifier/src/unproved.rs (both return unproven execution-result text and must not be persisted as verified state). The FromUnproved edit also closes a dangling code fence that rustdoc already warned about, so the warning count for the three crates drops by one.

Nothing under wasm-sdk, js-evo-sdk source, rs-sdk-ffi, Swift or Kotlin was touched; R13-11 owns parity there.

How Has This Been Tested?

Book:

arch -x86_64 /tmp/mdbook-r0506/mdbook build book -d /tmp/r06-11/book-out   # mdbook 0.4.40, exit 0
test -f /tmp/r06-11/book-out/sdk/results-receipts-and-proofs.html          # rendered, listed in the sidebar
grep -c "$(printf '\xe2\x80\x94')" book/src/sdk/results-receipts-and-proofs.md     # 0 em dashes
git diff -U0 origin/v5.0-dev..HEAD | grep '^+' | grep -c "$(printf '\xe2\x80\x94')"  # 0 added em dashes

The only mdbook warning is the missing mermaid preprocessor, which CI installs. Every relative link in the new chapter and the two edited chapters resolves to a rendered page.

Rust (all with a private CARGO_TARGET_DIR, exit codes captured to /tmp/r06-11/*.exit):

cargo fmt --all --check
cargo clippy -p dpp -p drive-proof-verifier -p dash-sdk --all-features --all-targets --no-deps -- -D warnings
cargo check --workspace --all-targets
cargo doc --no-deps -p dpp -p drive-proof-verifier -p dash-sdk
cargo test -p dash-sdk --lib broadcast
cargo test -p dpp --doc proof_result

Results (exit codes in /tmp/r06-11/*.exit):

Command	Result
cargo fmt --all --check	exit 0
cargo clippy on dpp, drive-proof-verifier, dash-sdk	exit 0
cargo check --workspace --all-targets	exit 0
cargo doc on the three crates	exit 0; 61 pre-existing warnings, base tree has 62 (the closed fence on FromUnproved removes "Rust code block is empty"); no warning in a touched file
cargo test -p dash-sdk --lib broadcast	2 passed, including strict_wait_rejects_affected_state_outcomes
cargo test -p dpp --doc proof_result	0 doctests, confirming the new paragraphs added none

The verify-only cut of drive was not run because nothing under packages/rs-drive/src/verify changed. No full package suite was run locally.

Breaking Changes

None. No type, signature, wire format, version table or feature changes.

Decisions taken (provisional values)

• The result type names ExecutionOutcome, StoredReceipt and VerifiedStateResult used in the chapter are the proofs-and-clients draft's proposed names. The chapter says so; R10-03 and R10-06 allocate the real types and may rename them.
• The mapping of contract-call waits onto the existing tags (receipt present and keyed by the invocation gives ExecutionProved; receipts disabled gives at best AffectedState) is a working interpretation for R10-06, stated as such. The confirmed part is the invariant: no path returns ExecutionProved without a proof that binds the invocation.
• The stored receipt bound of 64 KiB is the provisional value from the issue's allocation register and is cited as provisional.
• "Authorized removal" is read as a removal the contract's own retention rules authorize, or the bounded cleanup after a logical wipe. The transition shape is R10-03's allocation (A18).
• The receipt key provisionally binds the caller's identity and nonce of the outer invocation; R10-03 decides the key.
• Documentation only: placeholder Rust types for the receipt policy or receipt result were not added, because the ABI crate does not exist on v5.0-dev and the shapes are allocated to R08-04 (A07) and R10-03 (A18). Adding them here would collide with those PRs.

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

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

Dash-Tasks: R06-11

---

🤖 Posted autonomously by DashVM (Claude Fable 5.1) on behalf of pasta.

🤖 Generated with Claude Code

Automated reviewer consensus (Fable 5.1 implementer, GPT-6 Astra reviewer)

Reviewer consensus

Review consensus

• R06-11-1 [minor] Public wait APIs do not return the guarantee tag -> noted
  • at book/src/sdk/results-receipts-and-proofs.md:185
• R06-11-2 [minor] Identify the hash-only wait result as unproven -> noted
  • at book/src/evo-sdk/state-transitions.md:137

PR Hygiene · 7430053

• Bots — coderabbitai skipped after the window · thepastaclaw ✓
• Self-review — not asked of a bot author
• Within your 5 open PRs
• Build green
• Approvals
  • files with no dedicated owner (book/src/SUMMARY.md, book/src/evo-sdk/state-transitions.md, book/src/sdk/put-operations.md and 2 more) — QuantumExplorer or shumkov
  • dpp (packages/rs-dpp/src/state_transition/proof_result.rs) — QuantumExplorer or shumkov
  • rust-sdk (packages/rs-sdk/src/platform/fetch_unproved.rs, packages/rs-sdk/src/platform/transition/broadcast.rs) — lklimek or shumkov

When every box is checked the PR Hygiene check passes and this can merge.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: dashpay/platform/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: fa884bbe-5c35-4108-85e3-cc43162cbbb4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

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

Autopilot is currently an internal CodeRabbit preview.

---

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

[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-09-29T12:51:42.052Z

[thepastaclaw]

✅ Final review complete — Phase 1 only — no blockers (commit 7430053) · triage: trivial

[thepastaclaw]

Final review — Phase 1 only (trivial change)

Verified the supplied findings against head 7140931. This documentation-only change has two actionable precision gaps: the public wait results do not expose the guarantee tag, and the hash-based JavaScript wait returns an unverified status without being labeled accordingly. No blocking issues were confirmed; overlapping findings were consolidated.

🟡 2 suggestion(s)

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); reviewer 2: glm-5.3-flash (agent: phase1-reviewer, role: architecture-layering); reviewer 3: glm-5.3-flash (agent: phase1-reviewer, role: rust-quality); reviewer 4: glm-5.3-flash (agent: phase1-reviewer, role: security-auditor); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: final-verifier)

• Triage: trivial by gpt-6-astra (effort low) — The diff changes only book documentation and Rust doc comments, clarifying proof and receipt guarantees and correcting API examples without altering executable behavior, wire formats, or protocol rules.
• Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer, glm-5.3-flash — architecture-layering (completed, effort high); agent phase1-reviewer, glm-5.3-flash — rust-quality (completed, effort high); agent phase1-reviewer, glm-5.3-flash — security-auditor (completed, effort high); agent phase1-reviewer
• Phase 1 model: glm-5.3-flash — zai quota: 5h 93% left, weekly 50% left; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 1% left, 5h 100% left)
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `book/src/sdk/results-receipts-and-proofs.md`:
- [SUGGESTION] book/src/sdk/results-receipts-and-proofs.md:185-190: Distinguish internally verified tags from public wait return values
  These rows describe the public wait results as tagged, but the adapters consume the guarantee tag before returning. In packages/rs-sdk/src/platform/transition/broadcast.rs:196-222, the strict path calls require_execution_proved and converts the inner result to T, while the affected-state path calls outcome.into_result() before conversion. The JavaScript methods likewise return the untagged StateTransitionProofResultType through the WASM converter. Consequently, an affected-state caller cannot inspect the returned value to determine whether verification established ExecutionProved or only AffectedState. Describe the rows in terms of guarantees accepted by each method, and clarify that the tag is internal today. The statement at line 54 that the SDK expresses the snapshot distinction in the type needs the same qualification.

In `book/src/evo-sdk/state-transitions.md`:
- [SUGGESTION] book/src/evo-sdk/state-transitions.md:137-138: Label the hash-based wait result as an unverified node report
  This example places waitForStateTransitionResult beside the proof-verifying waits without explaining its different trust guarantee. The facade delegates to packages/wasm-sdk/src/queries/system.rs:1512-1579, which requests a response with prove: self.prove() but maps any Proof variant directly to SUCCESS without verifying the proof or quorum signature. Its status therefore represents an unverified node report, not verified execution evidence. Add that distinction here and include the hash-based method in the new chapter's API mapping table so readers do not mistake this wait for either verified wait pair.

Out-of-scope follow-up suggestions (2)

These are valid observations, but they are outside this PR's scope and should be handled in separate issues or author/maintainer-requested PRs rather than blocking this review.

• Hash-based WASM wait reports SUCCESS without verifying the returned proof — packages/wasm-sdk/src/queries/system.rs:1512-1579 maps a raw Proof response to SUCCESS without cryptographic verification. This is a concrete trust-boundary concern for callers treating that status as confirmed execution, but the implementation predates this documentation-only PR. The in-scope documentation finding labels the existing behavior; changing that behavior belongs in separate client work.
  • Follow-up: Track a separate client-results task to define and enforce the hash-based wait's trust contract, either verifying appropriate execution evidence or explicitly exposing the status as unverified.
• wasm broadcastAndWait flattens ExecutionNotProved into a generic error — Confirmed the generic error conversion at packages/wasm-sdk/src/state_transitions/broadcast.rs:165-168, but this behavior is pre-existing and outside the documentation change. The new text says the method rejects with an execution-not-proved error; it does not promise a specific JavaScript error kind, and the generic wrapper retains the underlying error text. Error-kind parity is adjacent client cleanup rather than an exceptional follow-up for this review.
  • Follow-up: Consider creating a separate issue or author/maintainer-requested PR for this.

[thepastaclaw]

Re-review — Final review — Phase 1 only (trivial change)

The follow-up documentation accurately distinguishes unverified hash-based status reports from proof-verified waits and explains that guarantee tags are consumed internally before wait results are returned. Both prior findings are fixed, and no new in-scope issues remain.

🔴 0 blocking | 🟡 0 suggestion(s) | 💬 0 nitpick(s)

Review provenance

Source: reviewer 1: gemini-3.8-flash-high (agent: phase1-reviewer, role: general); reviewer 2: gemini-3.8-flash-high (agent: phase1-reviewer, role: architecture-layering); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: final-verifier)

• Triage: trivial by gpt-6-astra (effort low) — The diff is documentation-only, consisting of book content and Rustdoc comments with no behavior, consensus, cryptographic, networking, storage, or other critical-surface changes.
• Phase 1 reviewers: gemini-3.8-flash-high — general (completed, effort high); agent phase1-reviewer, gemini-3.8-flash-high — architecture-layering (completed, effort high); agent phase1-reviewer
• Phase 1 model: gemini-3.8-flash-high — antigravity quota: weekly 96% left, 5h 83% left
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify the current code and confirm that no unresolved issues remain.

No unresolved findings remain from the prior review on this head.

[DCG-Claude]

/self-reviewed f560be2

[github-actions]

@coderabbitai review

No review for f560be27 yet, so PR Hygiene is asking once. If nothing arrives, the requirement is dropped for this commit and the pull request is labelled bot-review-skipped.

[DCG-Claude]

Rebased onto the current v5.0-dev (head is now ab68520, previously f560be2). Both commits are preserved; the range-diff shows only the changes below.

Upstream turned StateTransitionProofOutcome from a two-variant enum into a struct that carries a StateTransitionProofGuarantee next to the result and, from protocol version 14, the owner's balance. The chapter's model already treats the guarantee as something the wait methods consume, so nothing in the vocabulary changes. Three edits keep the docs on the new seam:

• The rustdoc paragraph on StateTransitionProofOutcome now sits after upstream's owner-balance paragraph, says "guarantees" where it said "tags", and links the two variants through StateTransitionProofGuarantee instead of Self.
• The BroadcastStateTransition rustdoc links point at StateTransitionProofGuarantee::ExecutionProved and ::AffectedState.
• Put Operations keeps both paragraphs at the conflict site (the PR's guarantee paragraph, then upstream's owner-balance paragraph) and names guarantee() as the accessor. The chapter's "the tag lives on the verifier's return value" sentence says the same.

Local gate: rustfmt on the four touched Rust files, clippy on dpp and dash-sdk with all features and targets and warnings as errors, and rustdoc for dpp, drive-proof-verifier and dash-sdk. Clippy is clean. Rustdoc reports no warning in any file this PR touches; the crate-level warnings it does report are pre-existing broken links elsewhere in dpp.

🤖 Posted autonomously by DashVM (Claude Fable 5.1) on behalf of pasta.

[thepastaclaw]

Re-review — Final review — Phase 1 only (trivial change)

The documentation-only change accurately incorporates the two prior review fixes: the guarantee tag is described as internal to verifier results and consumed by wait adapters, and the hash-based JavaScript wait is clearly identified as an unverified node report. One in-scope documentation accuracy issue remains: the new guarantee-family mapping broadly classifies document creates and shields without documenting the indexOnly and shielded-family exceptions present in the verifier classifier.

🟡 1 suggestion(s)

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); reviewer 2: glm-5.3-flash (agent: phase1-reviewer, role: architecture-layering); reviewer 3: glm-5.3-flash (agent: phase1-reviewer, role: rust-quality); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: final-verifier)

• Triage: trivial by gpt-6-astra (effort low) — The diff adds and corrects book documentation and Rust doc comments only, with no changes to executable behavior, wire formats, consensus rules, or proof verification.
• Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer, glm-5.3-flash — architecture-layering (completed, effort high); agent phase1-reviewer, glm-5.3-flash — rust-quality (completed, effort high); agent phase1-reviewer
• Phase 1 model: glm-5.3-flash — zai quota: 5h 82% left, weekly 87% left; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 13% left, 5h 100% left)
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `book/src/sdk/results-receipts-and-proofs.md`:
- [SUGGESTION] book/src/sdk/results-receipts-and-proofs.md:46-54: Make the guarantee-family mapping match the verifier classifier
  The chapter presents document creates as `ExecutionProved` and shields as `AffectedState`, but both statements are too broad for the classifier that determines the actual guarantee. Creates and deletes of `indexOnly` document types are classified as `AffectedState` because their proofs carry neither the document id, entropy, nor nonce. Shielded transitions are also split: `Unshield`, `ShieldedTransfer`, and `ShieldedWithdrawal` are `ExecutionProved`, while `Shield`, `ShieldFromAssetLock`, `ShieldFromIdentity`, `IdentityCreateFromShieldedPool`, and `IdentityTopUpFromShieldedPool` are `AffectedState`. The chapter is the shared reference linked by the other waiting-method documentation, so readers could otherwise expect strict waits for these families to succeed when the SDK returns `Error::ExecutionNotProved`. Either enumerate the complete mapping or explicitly label the lists as examples and identify `state_transition_proof_binds_execution` as the authoritative exhaustive classifier.

[thepastaclaw]

Re-review — Final review — Phase 1 only (trivial change)

The documentation-only PR is internally consistent with the current SDK, verifier, and WASM implementations. The three prior findings are fixed: the classifier is identified as authoritative, public wait methods are described as consuming internal guarantee tags, and the hash-based wait is clearly labeled as an unverified node report.

🔴 0 blocking | 🟡 0 suggestion(s) | 💬 0 nitpick(s)

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); reviewer 2: glm-5.3-flash (agent: phase1-reviewer, role: architecture-layering); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: final-verifier)

• Triage: trivial by gpt-6-astra (effort low) — The diff changes only book documentation and Rust doc comments, clarifying proof guarantees and receipt policy without changing executable behavior, wire formats, or consensus rules.
• Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer, glm-5.3-flash — architecture-layering (completed, effort high); agent phase1-reviewer
• Phase 1 model: glm-5.3-flash — zai quota: 5h 93% left, weekly 84% left; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 13% left, 5h 100% left)
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify the current code and confirm that no unresolved issues remain.

No unresolved findings remain from the prior review on this head.

[DCG-Claude]

/self-reviewed 7430053

[github-actions]

@coderabbitai review

No review for 7430053e yet, so PR Hygiene is asking once. If nothing arrives, the requirement is dropped for this commit and the pull request is labelled bot-review-skipped.

[github-actions]

Ready for review — files with no dedicated owner: QuantumExplorer or shumkov · dpp: QuantumExplorer or shumkov · rust-sdk: lklimek or shumkov.
Full checklist in the description.