feat(sdk): add scanAll() unified cross-chain scanner (#122)

[ZeePearl56]

Summary

Implements scanAll() — a unified cross-chain scanner that fans out stealth address scanning across EVM, Stellar, Solana, and CKB chains concurrently and merges matched results into a single AsyncIterable with chain-discriminated types.

Changes

New: src/scanner/unified.ts

• scanAll(input: ScanAllInput) — AsyncGenerator<MatchedAnnouncement> that fans out per-chain scanning concurrently
• MatchedAnnouncement — discriminated union type with chain, timestamp, seq, and announcement fields for downstream ordering
• windowedScan() — generic windowed scanner (WINDOW_SIZE=64) processes async iterables in batches for memory efficiency
• Concurrent merge via Promise.race — slow chains never block fast chains; each chain's results are yielded as they arrive
• Per-chain cleanup — finally block calls iter.return() on all active per-chain iterators when the consumer closes the iterator or breaks from the for-await loop
• Types: ScanAllInput, EvmChainInput, StellarChainInput, SolanaChainInput, CkbChainInput, SupportedChain

Updated: src/index.ts

• Exports scanAll function and all scanner types from the root entry point

New: test/scanner/unified.test.ts (13 tests)

• Single chain — EVM and Stellar each correctly identify matching announcements
• Two chains — concurrent scan finds matches from both chains
• Empty / no-match / mixed — empty input returns no results; unmatched announcements filtered correctly
• Backpressure — slow chain (500ms delay) does not stall fast chain output; 3 fast results arrive before the slow chain completes
• Cleanup on close — both iter.return() and for-await break trigger per-chain generator cleanup (verified via finally flag)
• Seq tracking — per-chain seq is monotonically increasing and independent across chains
• Windowed scanning — 150 announcements processed across 3 windows (64+64+22)

Design

User input (per-chain sources + keys)
         |
         v
  +------------------------------+
  |        scanAll()             |
  |                              |
  |  +------+ +------+ +------+ |
  |  | EVM  | |Stell.| |Solana| |  <- concurrent via Promise.race
  |  |window| |window| |window| |
  |  |  scan| |  scan| |  scan| |
  |  +--+---+ +--+---+ +--+---+ |
  |     |        |        |      |
  |     +---+----+----+---+      |
  |         |  merge  |          |  <- yielded in arrival order
  |         +---------+          |
  +------------------------------+
         |
         v
  MatchedAnnouncement { chain, timestamp, seq, announcement }

Testing

All 13 tests pass:

• single chain (evm) — finds matching announcements
• single chain (stellar) — finds matching announcements
• empty input — returns no results
• two chains (evm + stellar) — finds matches from both
• no matches — returns empty array
• mixed matches — filters correctly
• backpressure: slow chain does not stall fast chain output
• iterator close performs per-chain cleanup
• break from for-await loop cleans up all chains
• per-chain seq is monotonically increasing
• each chain has independent seq counter
• windowed scanning: processes more than WINDOW_SIZE announcements (150 across 3 windows)

Labels

• feature — new scanAll() cross-chain unified scanner
• dx — single AsyncIterable with chain discriminator replaces manual fan-out

Closes #122

[drips-wave]

@ZeePearl56 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits