feat(relayer): persist eth scan progress

[sadiq1971]

Problem

The relayer only persisted its Ethereum scan offset as a side effect of processing a deposit. Ranges with no deposits advanced the in-memory scan position but never wrote to chain_state, so on restart the poller resumed from the last block that happened to contain a deposit — re-scanning potentially large empty ranges (or, if eth_start_block was bumped manually to compensate, risking skipped blocks).

Fix

The poller now emits a scan-progress checkpoint after every fully scanned slice — including slices with no deposits — and the DB offset is persisted from it in real time.

• After each successful eth_getLogs slice, WatchDepositEvents calls the existing handler with a DepositEvent{Checkpoint: true} carrying the last scanned block. Progress advances only through the last successful slice; a failing slice and everything after it is retried next tick.
• The Ethereum source turns a checkpoint event into a lightweight Checkpoint relayer.Event that rides the same ordered channel behind that slice's deposits.
• The processor persists the offset for a checkpoint and does no transfer work; persistOffset dedupes against the last saved offset.

Carrying the signal on the existing handler (rather than a new onProgress callback) keeps the EthereumBridgeClient interface — and its generated mock — unchanged, so the diff stays contained.

Nothing missed / nothing double-processed

• The checkpoint for block N is consumed in order, after every deposit ≤ N — the processor loop is single-threaded — so the offset never advances past an unprocessed deposit.
• Each deposit is durably recorded via CreateTransfer (idempotent, ON CONFLICT DO NOTHING) before submission is attempted. A failed submit stays pending and is retried by the reconcile loop, independent of scan progress — so advancing the scan offset past it can't drop it.
• On restart the offset is a block that was fully scanned; the poller resumes at offset+1, and any re-seen deposit is deduped by CreateTransfer.

Tests

• TestProcessor_Start_CheckpointPersistsOffsetWithoutProcessing — a checkpoint event persists the offset and runs no transfer processing.
• TestEthereumSource_StreamEvents_EmitsScanCheckpoint — a checkpoint DepositEvent from the handler becomes a checkpoint relayer.Event carrying the scanned block.
• Existing deposit-mapping / engine tests unchanged (interface signature preserved).

[gemini-code-assist]

Code Review

This pull request introduces a checkpointing mechanism to track and persist scan progress during Ethereum deposit event polling. It updates WatchDepositEvents to accept an onProgress callback, which emits in-order checkpoint events that the processor handles by persisting the offset without triggering transfer processing. A critical logic error was identified in pkg/ethereum/client.go where currentBlock is updated before onProgress successfully executes. If onProgress fails, the poller would skip re-scanning the failed block range on the next tick. It is recommended to only update the block tracking state after onProgress successfully completes.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 75.00000% with 5 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@b20e2dc). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
pkg/ethereum/client.go	0.00%	3 Missing ⚠️
pkg/relayer/engine/source.go	85.71%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #344   +/-   ##
=======================================
  Coverage        ?   31.75%           
=======================================
  Files           ?      154           
  Lines           ?    11987           
  Branches        ?        0           
=======================================
  Hits            ?     3806           
  Misses          ?     7888           
  Partials        ?      293           

Flag	Coverage Δ
unittests	31.75% <75.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/relayer/engine/processor.go	80.35% <100.00%> (ø)
pkg/relayer/engine/source.go	95.55% <85.71%> (ø)
pkg/ethereum/client.go	6.13% <0.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dhyaniarun1993]

Yea, I encountered this bug while testing prompt token integration. Thanks for looking into this.