Skip to content

feat: eager init Spark wallet and add stream recovery#3358

Merged
TaprootFreak merged 3 commits intodevelopfrom
feat/spark-wallet-eager-init-stream-recovery
Mar 5, 2026
Merged

feat: eager init Spark wallet and add stream recovery#3358
TaprootFreak merged 3 commits intodevelopfrom
feat/spark-wallet-eager-init-stream-recovery

Conversation

@TaprootFreak
Copy link
Collaborator

@TaprootFreak TaprootFreak commented Mar 5, 2026

Problem

The SparkWallet is initialized lazily (only on first access). This means:

  1. The SDK's internal background stream (setupBackgroundStream()) doesn't start until the wallet is first used
  2. Incoming transfers are not automatically claimed until the wallet is actively accessed
  3. If the background stream dies after 10 reconnect attempts, there is no recovery mechanism
  4. Outgoing transfers are only considered complete after the receiver claims, blocking payouts unnecessarily

Solution

  • Eager initialization: Initialize SparkWallet immediately at boot via AsyncField eager mode, so the SDK background stream starts right away and incoming transfers are automatically claimed
  • Stream recovery: Register a stream:disconnected event handler that re-initializes the wallet with a fresh background stream after the SDK exhausts its 10 internal reconnect attempts
  • Exponential backoff: Reconnect attempts use increasing delays (1s, 2s, 4s, ... capped at 60s) to avoid hammering the Spark API during outages
  • Auto-retry on failure: If re-initialization fails, the next attempt is scheduled automatically instead of leaving the wallet permanently broken
  • Logging: All disconnect, reconnect, and failure events are logged via DfxLogger for production observability
  • Outgoing tx completion: Treat TRANSFER_STATUS_SENDER_KEY_TWEAKED as confirmed for outgoing transfers, since funds have already left the wallet at that point — no need to wait for the receiver to claim

Test plan

  • Deploy to DEV and verify Spark wallet initializes at boot (check logs for SDK init messages)
  • Send an incoming Spark transfer and verify it is auto-claimed without any prior wallet access
  • Simulate stream disconnect and verify wallet re-initializes with a new background stream
  • Verify reconnect logs appear with correct backoff timing
  • Send an outgoing Spark transfer and verify isTxComplete returns true after SENDER_KEY_TWEAKED (without waiting for receiver claim)
  • Verify getIncomingTransfers() returns incoming transfers as COMPLETED

Initialize SparkWallet eagerly at boot so the background stream starts
immediately, enabling automatic claiming of incoming transfers without
waiting for the first API call.

Register a stream:disconnected handler that re-initializes the wallet
with a fresh background stream after the SDK exhausts its 10 reconnect
attempts.
@TaprootFreak TaprootFreak marked this pull request as ready for review March 5, 2026 04:57
- Add DfxLogger for observability on disconnect/reconnect events
- Use exponential backoff (1s, 2s, 4s, ... up to 60s) between
  reconnect attempts to avoid hammering the Spark API
- Retry initialization on failure instead of leaving the wallet
  in a permanently broken state
Consider TRANSFER_STATUS_SENDER_KEY_TWEAKED as confirmed for outgoing
transfers since funds have already left the wallet at that point.
Waiting for COMPLETED would block until the receiver claims.
@TaprootFreak TaprootFreak merged commit 7ced83a into develop Mar 5, 2026
8 checks passed
@TaprootFreak TaprootFreak deleted the feat/spark-wallet-eager-init-stream-recovery branch March 5, 2026 08:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants