Feat/indexer polling and event filter enhancements

[Osuochasam]

Before touching anything, I went through each module the tickets pointed at, since they were pretty light on specifics — mostly "here's the goal, here's a validation check," no detail on the actual design. Wanted to make sure I wasn't inventing behavior the code didn't already support, especially since ticket 1 touches duplicate-prevention logic, which is the kind of thing you really don't want to get subtly wrong in something handling escrow.

Ticket 1 (dynamic polling backoff): First thing I checked was whether changing poll frequency could break the actual duplicate-prevention guarantee, and it can't — every poll picks up from the last committed ledger pointer, and the UNIQUE constraint plus the atomic pointer advance mean timing has no bearing on correctness either way. Wrote that reasoning into the commit message so it's not just in my head. Once that was settled, added idle backoff: multiplies the wait by 1.5x up to a 120s ceiling, and snaps straight back to the 15s base as soon as a new ledger closes. Tested it going both directions — backing off and recovering — since the original ask only really covered the backoff half.

Ticket 2 (index optimization): Went looking for the actual query duplicate-prevention runs before assuming an index was even needed, and it turns out SQLite already auto-generates an index for the UNIQUE constraint (sqlite_autoindex_events_1), and it's already the right shape for this lookup. Ran EXPLAIN QUERY PLAN to confirm — it's doing a covering index search already. So there was nothing to add here; adding a redundant index would've just been busywork the ticket itself cautioned against. What I did do was pull the check out into a named isDuplicateEvent() function, since right now it's implicit and hard to point EXPLAIN at directly — this makes the "is the index actually used" question something you can test going forward instead of just trusting it.

Ticket 3 (custom ledger range imports): There's no backfill mechanism anywhere in this repo currently — checked thoroughly, nothing to build on top of. Built fetchHistoricalEvents(start, end) from scratch with pagination past the 100-event page limit, and made a deliberate call to reject bad ranges outright rather than silently clamp them the way pagination elsewhere in the codebase does — importing the wrong ledger range isn't like landing on the wrong page, it's importing the wrong data, so it should fail loud. Also kept the insert path for historical events completely separate from the live poller's pointer, so a backfill run can never accidentally rewind or skip the live indexer.

Ticket 4 (debug logging): Before adding any logging, checked what's actually in the payloads this module handles — turns out dataJson can carry wallet addresses and amounts, so the logs only ever record byte sizes, never the payload itself. Wrote a test that plants realistic-looking addresses in a payload and asserts they never show up in the log output, so this isn't just a promise, it's checked. There wasn't an existing log-throttling pattern, so added a simple time-based one on top of the existing log-level gate (confirmed separately that debug() is already off by default in production).

A few judgment calls I made and flagged rather than guessed silently on:

Ticket 1: treating "idle" as "no new ledger closed" — a failed poll counts as idle too, not just a quiet one.
Ticket 3: rejecting bad ranges instead of clamping them, breaking from how pagination handles bad input elsewhere — noted why in the commit.
Ticket 4: measured "poll speed" as the full fetch-plus-insert cycle, not just the RPC round trip, since that's the number that'd actually explain a slow poll.

Closes #292
Closes #286
Closes #279
Closes #281

[drips-wave]

@Osuochasam 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