refactor(platform-wallet): wake the SPV readiness wait on events instead of polling

[Claudius-Maginificent]

TL;DR

When the app starts with a transaction waiting to be re-sent, the wallet now sends it as soon as it connects to the Dash network, instead of noticing the connection up to a quarter of a second later.

User story

As a wallet user whose pending transaction is re-sent when the app starts, I want it sent the moment the wallet connects to the network, without an extra delay.

Scenario

Actual behavior

The wallet checks four times a second whether it is connected and only sends after the next check, so sending can lag the connection by up to 250 ms.

Expected behavior

The wallet reacts to the connection itself and sends immediately. The visible effect is small: up to 250 ms less delay, and no repeated checks while waiting.

Detailed discussion

Issue being fixed or feature implemented

Raised by the dash-spv author on #5307 (comment, point 6): SpvRuntime::wait_until_ready sleep-polled is_broadcast_ready() (client started and peer snapshot non-empty) every 250 ms.

What was done?

• wait_until_ready now waits on a tokio::sync::Notify. It is woken by the only two transitions that can make the client ready:
  • start() stores the client;
  • PeerTracker stores a dash-spv PeersUpdated snapshot.
• Before each check, the waiter registers for the next notification, so a transition that races the check is never missed.
• The wait stays inside tokio::time::timeout, so an unrestricted timeout from FFI still saturates instead of panicking. Cancelling the wait is safe.
• Transitions away from readiness wake no one. During the window where stop has removed the client but not yet cleared the peer tracker, the wait stays parked instead of rechecking every 250 ms.
• SPV_READINESS_POLL_INTERVAL is removed.

The return contract is unchanged: true once ready, false at timeout.

How Has This Been Tested?

• New tests use paused tokio time:

  • a parked wait resolves with no virtual time passed on the first PeersUpdated event;
  • a parked wait resolves with no virtual time passed when the client starts;
  • with nothing changing, readiness is checked at most twice in 30 s (121 times before).

  All three failed before the change. The existing readiness tests still pass.

• cargo test -p platform-wallet passes. Clippy --all-features --all-targets -D warnings is clean.

Breaking Changes

None.

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

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01PSi8cX229kW2fmLxKW6ir4

PR Hygiene · 76c6a1a

• Bots — coderabbitai skipped after the window · thepastaclaw ✓
• Self-review — not asked of a bot author
• Build green
• Approvals
  • files with no dedicated owner (CHANGELOG.md) — QuantumExplorer or shumkov
  • rs-platform-wallet (packages/rs-platform-wallet/src/spv/peers.rs, packages/rs-platform-wallet/src/spv/runtime.rs) — approved by llbartekll

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]

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: f7c579a2-b5a4-4bea-965f-a89e9f1a9f03

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

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

[thepastaclaw]

✅ Final review complete — no blockers (commit 76c6a1a) · triage: low

[thepastaclaw]

Final validation — Phase 1 + Phase 2

Verified the supplied findings against head 76c6a1a and found no actionable in-scope defects. The readiness waiter registers before checking state, and both readiness-producing transitions notify after storing their updates; the reported constructor concern is speculative, while the fixture duplication is routine cleanup. Validation was static only: the supplied CI snapshot shows Rust wallet and workspace tests skipped, with other checks queued or pending, so the author's reported test results remain independently unconfirmed.

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); reviewer 2: glm-5.3-flash (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: rust-quality); reviewer 6: gpt-6.1-sol (agent: phase2-reviewer, role: security-auditor); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

• Triage: low by gpt-6.1-sol (effort low) — The diff is a small, contained replacement of readiness polling with notifications and focused tests, without changing transaction processing or other critical surfaces.
• Phase 1 reviewers: glm-5.3-flash — general (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 98% left, weekly 93% left; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 14% left, 5h 100% left)
• Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
• Phase 2 reviewers: gpt-6.1-sol — general (completed, effort medium); agent phase2-reviewer, gpt-6.1-sol — architecture-layering (completed, effort medium); agent phase2-reviewer, gpt-6.1-sol — rust-quality (completed, effort medium); agent phase2-reviewer, gpt-6.1-sol — security-auditor (completed, effort medium); agent phase2-reviewer

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

[github-actions]

@coderabbitai review

No review for 76c6a1a0 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.
Full checklist in the description.