Worker pool for parallel multichain scanning

[truthixify]

Labels: Stellar Wave, stellar, perf, feature, drips, help-wanted
Tier: L (1–2 weeks)
Type: perf / feature

Context

A multichain Spectre agent or a multichain wallet has to scan EVM, Stellar, Solana, and CKB. Today those happen sequentially. The four scans don't share data or depend on each other — they're embarrassingly parallel. A worker pool that fans them out can cut wall-clock time by 4×.

Scope

Build sdk/src/scanner-pool.ts:

1. API:

   const pool = new MultichainScannerPool({
     chains: ['evm', 'stellar', 'solana'],
     concurrency: 4,
   })
   
   const results = await pool.scanAll({
     evm:    { viewingKey, spendingPubKey, ... },
     stellar:{ viewingKey, spendingPubKey, ... },
     solana: { viewingKey, spendingPubKey, ... },
   })
   // → { evm: MatchedAnnouncement[], stellar: ..., solana: ... }

2. Implementation:
   • In browser / Worker environment: spawn one Web Worker per chain.
   • In Node: use worker_threads for ≥ 2 chains, run inline otherwise (worker overhead isn't worth it for one chain).
   • In React Native: pool size = 1 (no Worker support yet); fall back to sequential.
3. Progress reporting:

   pool.on('progress', ({ chain, processed, total }) => { ... })

4. Cancellation: an AbortSignal cancels all workers cleanly.
5. Result merging: the pool returns once all chains complete, or short-circuits on first error (configurable).

Constraints

• Each worker must run the streaming scan (#09) internally for memory safety.
• The pool must NOT serialize private keys across worker boundaries unencrypted (use structuredClone carefully — private keys are Uint8Array which structuredClone handles, but document the threat model).
• Bundle size: the pool implementation itself ≤ 3 KB gzipped.

Acceptance criteria

• Pool implementation with tests in browser (vitest + happy-dom + Worker shim), Node, and a smoke test in RN.
• Benchmark showing 3-4× speedup for a 4-chain scan vs. sequential.
• Documentation page explaining when to use the pool (and when not to).
• Spectre follow-up issue filed for migrating the background scanner to use this.

Why this matters

A multichain wallet's "refresh" button is the user's most-used interaction. Making it 4× faster is the difference between "this app feels modern" and "this app feels slow."

[Nonso-Eze]

@Nonso-Eze has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi maintainers! I’d love to help out with this issue. I’ve checked the current codebase/documentation and know exactly what needs to be updated to make this clearer. I will ensure everything aligns perfectly with your existing contribution guidelines.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Nonso-Eze to this issue.

[drips-wave]

Congratulations, @Nonso-Eze! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Nonso-Eze: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊