Blockchain: Event listener (external on-chain mints only — Circle tx covered by webhooks)

[manoahLinks]

Status

UPDATED 2026-04-24. Circle-originated transactions (mint / checkIn / withdraw / createTicket) are now confirmed via Circle webhooks (#65) — no RPC polling needed for those. This listener is scoped to external on-chain activity only: direct mints initiated outside HostIT (e.g. a user calling `mintTicket` straight from a wallet extension).

Summary

RPC-based event log listener that indexes Diamond events not triggered by HostIT's backend. Keeps the DB in sync with the canonical on-chain state even when transactions bypass our API.

Scope

• Ethers.js `provider.on(filter, handler)` against Base RPC (primary) and Lisk RPC (legacy, until Diamond fully migrated).
• Events to watch:
  • `TicketMinted` — external mint detection
  • `TicketBalanceWithdrawn` — external withdraw detection (unlikely but possible)
  • `HostItBalanceWithdrawn` — platform withdrawal (reconciliation)
  • `CheckedIn` — external check-in (direct admin call)
• For each event:
  • Look up existing `BlockchainTransaction` by tx hash
  • If already tracked (Circle-originated): no-op
  • If new: create domain record + mark `source=EXTERNAL`
• Persistent cursor per chain to survive restarts (store last processed block).
• Reorg handling: re-scan last N blocks on every run.

Explicitly out of scope

• ❌ Watching Circle-originated transactions — those are confirmed via Webhooks: Circle webhook handler (/webhooks/circle) #65
• ❌ Polling tx receipts for pending writes — Circle SCP handles that
• ❌ WebSocket provider (use JsonRpcProvider with cursor instead — more reliable)

Acceptance criteria

• External mint → ticket row appears in DB with `source=EXTERNAL`
• Cursor persists across restarts
• Reorg replay doesn't duplicate rows
• Both Base + Lisk indexed until legacy Diamond retired

Depends on

• Blockchain: Service setup (ethers.js read client + Circle treasury for writes) #33 (ethers read service)
• Smart contracts: Deploy Diamond to Base Sepolia + Base mainnet #66 (Diamond on Base)