Stellar `fetchAnnouncements` time-range filtering

[truthixify]

Labels: Stellar Wave, stellar, feature, drips, help-wanted
Tier: M (2–4 days)
Type: feature

Context

fetchAnnouncements('stellar') today returns announcements across a probed ledger range starting max - 5000 if no cursor is provided. There's no way to say "only give me announcements from the last hour" or "everything since I last scanned." Every consumer ends up paginating from scratch.

Spectre's background scanner re-fetches the same window every 5 minutes. The Soroban RPC is expensive. We need incremental scan support.

Scope

Extend fetchAnnouncements (and fetchAnnouncementsStream from #09 if it lands) to accept:

type FetchOpts = {
  fromLedger?: number      // earliest ledger to include (inclusive)
  toLedger?: number        // latest ledger (exclusive); defaults to latest
  fromTimestamp?: Date     // convenience: convert to ledger using Horizon
  toTimestamp?: Date
  cursor?: string          // resume from a previous run
}

Behavior:

• cursor takes precedence over fromLedger if both supplied.
• fromTimestamp and fromLedger are mutually exclusive; error if both set.
• Returned result includes a nextCursor field consumers can pass to the next call.
• If the Soroban RPC's retention window has elapsed past fromLedger, throw a typed error RetentionExceededError with the actual oldest available ledger.

Acceptance criteria

• Implementation in sdk/src/chains/stellar/announcements.ts.
• Tests covering: explicit range, cursor resume, timestamp conversion, retention-exceeded error.
• Spectre follow-up issue filed for using the cursor approach in the background scanner (this is the big win — eliminating duplicate fetches).
• Docs updated with a "incremental scanning" example.

Why this matters

This single change cuts Spectre's Stellar RPC usage by ~50×. Five-minute scans of the last five minutes only, not the last five hours.

Resources

• Soroban RPC getEvents cursor: https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents
• Horizon ledger lookup: https://developers.stellar.org/docs/data/horizon/api-reference/resources/ledgers

[israelolrunfemi]

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

I've been writing scalable software for about 5+yrs now I'll appreciate if you can approve me to work on this issue

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

[JohnOluB]

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

I’ll start by extending fetchAnnouncements in sdk/src/chains/stellar/announcements.ts to support ledger and timestamp based incremental scans with cursor aware pagination. I’ll also implement typed retention window errors, timestamp to ledger conversion via Horizon, and nextCursor support to avoid redundant RPC scans.

I have experience building efficient blockchain event indexing systems and will ensure the implementation is well tested, documented, and optimized for Spectre’s background scanning workflow.

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

[TheDEV111]

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

Hi I have prior understanding of your codebase and would like to take up this issue

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

[drips-wave]

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

🧑‍💻 @JohnOluB: 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 🌊

[truthixify]

Resolved by #16 (merged into develop).