fix(stellar): query announcer buckets via Soroban RPC topic filters

[wheval]

Summary

Updates the Wraith Stellar SDK event ingestion path to use Soroban RPC topic filters for the v2 announcer schema, while continuing to read the legacy v1 announcer stream during the migration window.

Purpose / Motivation

The current fetchAnnouncements() implementation downloads every event from the v1 announcer contract and filters client-side. As announcement volume grows, that wastes bandwidth and RPC cost. Soroban supports indexed topic filters via getEvents; the v2 announcer schema (contracts #24) exposes view_tag_bucket as topic slot 2 so clients can request only the buckets they need.

Changes Made

• Added event-filters.ts with helpers to build v1 and v2 Soroban RPC filters:
  • v1: ("announce", *, *) on contracts.announcer
  • v2 bucket: ("announce", 2, view_tag_bucket, *) on contracts.announcerV2
  • v2 all: ("announce", 2, *, *)
• Refactored fetchAnnouncements() to ingest v1 + v2 during transition, dedupe overlapping results, and accept viewTagBuckets for targeted v2 queries
• Added dual-layout event parsing (3-topic v1 vs 4-topic v2)
• Extended scanAnnouncements() to accept scheme ID 2 (v2)
• Documented privacy trade-offs in EVENT_FETCHING.md and fetchAnnouncements JSDoc
• Added tests for filter construction, v1/v2 parsing, and mixed ingestion

Set contracts.announcerV2 in deployments once the v2 contract from wraith-protocol/contracts#24 is deployed.

How to Test

1. Install dependencies: npm install
2. Run Stellar tests:

   npm test -- test/chains/stellar/event-filters.test.ts test/chains/stellar/announcements.test.ts test/chains/stellar/scan.test.ts

3. Verify filter construction:

   import { buildV2BucketEventFilter } from '@wraith-protocol/sdk/chains/stellar';
   buildV2BucketEventFilter('C...', 42);
   // topics: ("announce", 2, 42, *)

Breaking Changes

None for existing callers. fetchAnnouncements('stellar') remains valid and continues fetching the v1 stream. v2 ingestion is opt-in via contracts.announcerV2 deployment config.

Related Issues

Closes wraith-protocol/contracts#25

Checklist

• Code builds successfully
• Tests added/updated
• Documentation updated

[truthixify]

Direction is correct, this is the SDK companion to contracts #26's v2 event topic design. The new event-filters.ts and the legacy v1 dual-read approach are what we want.

Same rebase blocker as the other PRs this round. Could you rebase and limit the diff to the v2 topic-filter additions?

git fetch origin
git rebase origin/develop
# during the rebase, keep your event-filters.ts, the scan.test/scan.ts additions, and announcements changes that add bucket-based fetching
# drop any reverting changes to src/chains/stellar/* that you didn't intend to touch (the rest of develop already has JSDoc and range filtering)
git push --force-with-lease

Thanks @wheval.