feat(rs-sdk): backport incremental address balance synchronization

[lklimek]

Issue being fixed or feature implemented

Backport of the incremental address balance synchronization API from feat/zk (commit 28cc30f, PR #3152) into a standalone branch based on v3.1-dev, excluding all shielded/ZK changes.

This enables dash-evo-tool (v1.0-dev) to use the simplified SDK sync API without pulling in the entire ZK/shielded pool feature set. The client-side apply_recent_balance_changes() (~250 lines), PlatformSyncMode enum, and manual checkpoint tracking can all be replaced with a single sdk.sync_address_balances() call.

What was done?

Clean cherry-pick of 28cc30f — 6 files, +542/-83 lines, zero shielded contamination:

SDK API changes (packages/rs-sdk/):

• sync_address_balances() gains last_sync_timestamp: Option<u64> parameter (None = full sync, Some = incremental from that time)
• AddressProvider trait: new current_balances() and last_sync_height() default methods for providing incremental baseline state
• AddressSyncResult: new new_sync_height and new_sync_timestamp fields to persist and pass back on subsequent syncs
• AddressSyncConfig: new full_rescan_after_time_s field (default: 7 days)
• Internally implements full_tree_scan() and incremental_catch_up() (compacted + recent two-phase loop)

FFI changes (packages/rs-sdk-ffi/):

• Updated C FFI function signatures and structs to expose the new parameter and result fields

Excluded: All shielded/ZK code — verified with grep (0 matches for shielded, nullifier, orchard, zip32, commitment_tree in the diff).

How Has This Been Tested?

• cargo check -p dash-sdk passes clean on the backport branch
• Cherry-pick applied with zero conflicts
• Commit includes 3 unit tests added by the original PR (feat(rs-sdk): implement incremental address balance synchronization #3152)
• Server-side note: incremental mode requires platform nodes supporting getRecentAddressBalanceChanges and getRecentCompactedAddressBalanceChanges gRPC endpoints

Breaking Changes

• sync_address_balances() signature adds a new last_sync_timestamp parameter — callers must add None as the fourth argument to maintain existing full-sync behavior
• FFI functions gain last_sync_timestamp: u64 parameter (0 = full scan)

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

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[coderabbitai]

Important

Review skipped

Draft detected.

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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch backport/incremental-address-sync

---

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

[github-actions]

✅ gRPC Query Coverage Report

================================================================================
gRPC Query Coverage Report - NEW QUERIES ONLY
================================================================================

Total queries in proto: 53
Previously known queries: 47
New queries found: 6

================================================================================

New Query Implementation Status:
--------------------------------------------------------------------------------
✓ getAddressInfo                                /home/runner/work/platform/platform/packages/rs-sdk/src/platform/query.rs
✓ getAddressesBranchState                       /home/runner/work/platform/platform/packages/rs-sdk/src/platform/address_sync/mod.rs
✓ getAddressesInfos                             /home/runner/work/platform/platform/packages/rs-sdk/src/platform/fetch_many.rs
✓ getAddressesTrunkState                        /home/runner/work/platform/platform/packages/rs-sdk/src/platform/query.rs
✓ getRecentAddressBalanceChanges                /home/runner/work/platform/platform/packages/rs-sdk/src/platform/query.rs
✓ getRecentCompactedAddressBalanceChanges       /home/runner/work/platform/platform/packages/rs-sdk/src/platform/query.rs

================================================================================
Summary:
--------------------------------------------------------------------------------
New queries implemented: 6 (100.0%)
New queries missing: 0 (0.0%)

Total known queries: 53
  - Implemented: 50
  - Not implemented: 2
  - Excluded: 1

Not implemented queries:
  - getConsensusParams
  - getTokenPreProgrammedDistributions

[lklimek]

not needed, already in v3.1-dev