[llbartekll]

Issue being fixed or feature implemented

Prepares the platform wallet for #4897.

From protocol version 14 (#4887) the proof of a document batch carries the owner's credit balance next to the document. The platform wallet ignores it, so after a DPNS registration the apps still query the balance again (refresh_identity_balance, #4799).

This PR makes the wallet take the balance from the proof whenever the proof carries one:

• Until protocol version 14 activates: the proof carries no balance and nothing changes. The post-registration refresh in dashwallet-ios stays.
• Once it activates: the wallet already keeps the proved balance, without a new SDK or app release.

Refs #4897. The issue stays open, because two steps still wait for the activation:

• dropping the apps' automatic refresh;
• treating a missing balance as an error.

What was done?

rs-sdk (additive; no existing signature or behaviour changes)

• New PutDocument::put_to_platform_and_wait_for_response_with_owner_balance_and_metadata. It returns three things:
  • the confirmed document;
  • the owner's balance after the write (None for a proof made before protocol version 14);
  • the verified response metadata, whose height is the block the balance is a snapshot at.
• The new method checks the proof as strictly as put_to_platform_and_wait_for_response: the write must be proved executed unless the document type is indexOnly. By contrast, put_to_platform_and_wait_for_response_with_owner_balance accepts an affected-state snapshot for any document type; it is left as is.
• New Sdk::register_dpns_name_with_owner_balance_and_metadata. It returns the registration result together with the balance and metadata of the domain's proof. The domain is the registration's last write, so that balance already includes the preorder's cost. register_dpns_name delegates to it and is unchanged for its callers (rs-sdk-ffi, wasm-sdk).
• The step from a verified outcome to the document and balance is now a pure function with unit tests. wait_for_document_and_owner_balance runs through it with unchanged behaviour.
• The SDK book's put-operations chapter mentions the new calls.

rs-platform-wallet

• New IdentityWallet::persist_proven_owner_balance. It keeps a proof-carried balance through the existing persist_confirmed_balance, using the proof's block as the balance watermark. This is the same path that transfers, withdrawals and top-ups use since fix(sdk): fetch and persist managed identity credit balances #4799:
  • an older snapshot never replaces a newer one;
  • a cache failure is logged and retained for retry, and never fails the write.
• None leaves the balance untouched.
• Only identities owned by the wallet take the balance:
  • the FFI persists the watermark only for those;
  • an identity removed while the write was in flight is not recreated.
• The helper is wired into every wallet document write that goes through PutDocument:
  • DPNS registration (register_name_with_external_signer, the variant the FFI and JNI expose);
  • create_document_with_signer;
  • DashPay profile create and update, and contactInfo publish (SdkWriter::put_document).

There is no FFI, Swift, Kotlin, network or consensus change.

Follow-ups, not in this PR

• Contact requests (Sdk::send_contact_request).
• Document replace, delete, transfer, set-price and purchase. The SDK's document transition builders do not return the balance.
• Contract creates and identity updates.
• Treating a missing balance as an error, once no supported network runs a version below 14.

How Has This Been Tested?

• cargo test -p dash-sdk --lib platform::transition::waitable: 6 new tests pass. They cover an execution proof with and without the balance, the strict and lenient handling of an affected-state outcome, an outcome missing the sent document, and a non-document result.
• cargo test -p platform-wallet --lib wallet::identity::network::balance: 26 tests pass, 4 of them new:
  • the proved balance is persisted with its block watermark and reloads;
  • None writes nothing;
  • an older proof does not overwrite a newer balance;
  • an observed identity is ignored.
• cargo clippy -p dash-sdk -p platform-wallet -p platform-wallet-ffi --all-targets --all-features --locked -- --no-deps -D warnings passes, and so does cargo check -p dash-sdk --no-default-features --locked.
• End-to-end was not run. Only devnets run protocol version 14 today, and on testnet and mainnet the new code takes the None path, which is the current behaviour. The Some path is covered by the unit tests above.

Breaking Changes

None. The new APIs are additive, and SdkWriter::put_document is crate-private.

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

🤖 Generated with Claude Code

PR Hygiene · 20f6d08

• Bots — coderabbitai skipped after its own rate limit · thepastaclaw ✓
• Self-review — posted; again after any push
• Build green
• Approvals
  • files with no dedicated owner (book/src/sdk/put-operations.md) — QuantumExplorer or shumkov
  • rs-platform-wallet — you own it
  • rust-sdk (packages/rs-sdk/src/platform/dpns_usernames/mod.rs, packages/rs-sdk/src/platform/transition/put_document.rs, packages/rs-sdk/src/platform/transition/waitable.rs) — approved by lklimek

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]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 54 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: dashpay/platform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5240a402-0308-41e7-abbb-b6de950db74e

📥 Commits

Reviewing files that changed from the base of the PR and between 5cbe01e and 20f6d08.

📒 Files selected for processing (10)

• book/src/sdk/put-operations.md
• packages/rs-platform-wallet/src/wallet/identity/network/balance.rs
• packages/rs-platform-wallet/src/wallet/identity/network/contact_info.rs
• packages/rs-platform-wallet/src/wallet/identity/network/document.rs
• packages/rs-platform-wallet/src/wallet/identity/network/dpns.rs
• packages/rs-platform-wallet/src/wallet/identity/network/profile.rs
• packages/rs-platform-wallet/src/wallet/identity/network/sdk_writer.rs
• packages/rs-sdk/src/platform/dpns_usernames/mod.rs
• packages/rs-sdk/src/platform/transition/put_document.rs
• packages/rs-sdk/src/platform/transition/waitable.rs

• Autofix · 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.}

[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-13T11:28:53.178Z

[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 review complete — no blockers (commit 20f6d08) · triage: normal

[thepastaclaw]

Final validation — Phase 1 + Phase 2

Static verification of the complete PR range found no actionable in-scope defects. The additive SDK APIs preserve existing proof guarantees and return the authenticated balance and metadata; wallet updates reuse ownership checks, height-ordered persistence, and failure-retry behavior without changing consensus or historical version tables. No local builds or tests were run: the supplied CI snapshot reports successful Rust workspace and Swift/Kotlin checks, while dedicated Rust wallet tests and E2E checks were skipped and PR Hygiene remained pending.

Review provenance

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

• Triage: normal by gpt-6.1-sol (effort low) — The diff adds SDK proof-result plumbing and wallet balance-cache persistence across document-write paths, but does not itself change funds movement, consensus, cryptography, or storage migrations.
• 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 14% left, 5h 100% left), glm-5.3-flash (not used above high effort; tier asks max)
• Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
• Phase 2 reviewers: gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — architecture-layering (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — platform-versioning (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — rust-quality (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — security-auditor (completed, effort high); agent phase2-reviewer

[llbartekll]

/self-reviewed

[github-actions]

Ready for review — files with no dedicated owner: QuantumExplorer or shumkov.
Full checklist in the description.