feat(ingest): EVM ingest worker — ERC-20 Transfer log scanning

[Emmyt24]

Depends on: #218, #220, #223. Blocks: #222.

Description

octo-ingest polls Horizon /payments oldest-first from a saved
paging_token, attributes each payment by muxed id or memo id, and records it idempotently, with
dedup on the Horizon TOID. EVM deposit detection is structurally different:

• No per-account payments feed. You scan eth_getLogs for ERC-20 Transfer events whose
  to topic matches one of your deposit addresses.
• The cursor is a block number, not an opaque token.
• Native ETH transfers emit no logs at all — they are only visible by inspecting block
  transactions or debug_traceBlock. Decide and document whether native ETH deposits are in scope
  (recommendation: out of scope for v1, ERC-20 stablecoins only, stated explicitly in the docs
  rather than silently unsupported).
• Non-standard ERC-20s exist: fee-on-transfer tokens where the amount received ≠ the amount in the
  event, and rebasing tokens. The registry (feat(store): ERC-20 token registry #223) is the defence; this worker must trust the
  registry, not the token.

Build the EVM ingest worker to the same reliability bar as the Stellar one.

Requirements and context

• Reuse the existing supervisor and backoff design. wallets_due_for_poll
  (crates/store/src/lib.rs) already implements activity-based poll
  tiers (active/idle/dormant); do not build a parallel scheduler.
• Crash safety: the cursor advances only after a record is durably processed, matching the
  guarantee documented in crates/ingest/src/lib.rs. A crash mid-batch
  must resume without missing or double-processing.
• Adaptive range bisection: on RangeTooLarge from feat(evm-rpc): Resilient JSON-RPC client for EVM chains #218, halve the block range and retry. A fixed
  range will fail on some providers and waste requests on others.
• This issue does not credit deposits. It detects and records them as unconfirmed. Crediting
  is gated by feat(ingest): Confirmation depth and reorg handling for EVM deposits #222. Merging feat(ingest): EVM ingest worker — ERC-20 Transfer log scanning #221 without feat(ingest): Confirmation depth and reorg handling for EVM deposits #222 must not create spendable balances — enforce that in code,
  not by convention.
• Preserve the quarantine behaviour: a transfer to a known address for an unregistered token is
  recorded without attribution rather than guessed or dropped.
• Security: verify the log's address field is the registered token contract. Anyone can
  deploy a contract emitting a fake Transfer event with any topics; attributing on topics alone
  lets an attacker mint balances for free. This is the single most important check in this issue.

Suggested execution

Branch: feat/evm-ingest-worker

Implement changes

• Add crates/ingest/src/evm.rs with an EvmIngestor mirroring Ingestor's shape and returning
  the same Processed { Recorded, Duplicate, Skipped } enum.
• Implement log scanning: eth_getLogs filtered by registered token addresses and the
  Transfer(address,address,uint256) topic0, with the to topic matched against deposit addresses.
• Decode Transfer correctly: from/to are indexed (topics 1 and 2, left-padded to 32 bytes)
  and value is in data. Parse value as U256 via feat(store): Arbitrary-precision amounts — replace i64 stroops with NUMERIC(78,0) #215's Amount.
• Persist a block-number cursor per (wallet, chain), reusing the ingest_cursor table with the
  chain-scoped columns from feat(store): Multi-chain database schema migration #214, and keep mark_polled's "looked at" vs "saw activity" distinction.
• Dedup on (chain_id, tx_hash, log_index) via the index from feat(store): Multi-chain database schema migration #214.

Test and commit

• Anvil integration tests (chore(testing): Anvil-based EVM integration test harness #219): a real ERC-20 transfer to a deposit address is detected, attributed,
  and recorded with the exact amount at 6 and 18 decimals.
• Adversarial test — the critical one: deploy a hostile contract that emits a
  Transfer event with a deposit address in the to topic and a huge value, and assert it is
  not credited because the emitting contract is not a registered token. Model on
  crates/ingest/tests/adversarial_replay_tests.rs.
• Replay/idempotency test: processing the same log range twice records nothing new.
• Crash-resume test: kill mid-batch, restart, assert exactly-once processing. Mirror
  resume_replay_tests.rs.
• Range-bisection test: a mock RPC returning RangeTooLarge causes bisection, not a stall.
• Test that a transfer of an unregistered token to a known address is quarantined, not credited.
• Update docs/ingest-integration.md.

Example commit message

feat(ingest): EVM deposit detection via ERC-20 Transfer logs

Scans eth_getLogs for registered token contracts with a block-number
cursor, advancing only after durable processing so a crash resumes
exactly-once — the same guarantee the Horizon path gives.

Logs are matched on the emitting contract address, not topics alone:
any contract can emit a Transfer event with arbitrary topics, so
topic-only attribution would let an attacker mint balances.

Deposits are recorded unconfirmed; crediting is gated on #222.

Refs #221

Guidelines

Large issue — split into stacked PRs (cursor/scanning, then decoding/attribution) if that helps
review. Do not merge a version that credits balances before #222 lands.

---

[bobo-24]

Hi! I’m a full-stack developer with a strong blockchain background, and I’m confident I can resolve this issue quickly and effectively. I’ll deliver a clean, reliable solution with immediate attention to detail, ensuring it’s completed as soon as possible. Please assign it to me—I’m ready to get started right away.

[DEV-DESIGN6]

Hello Octo Protocol team,

I’d like to work on #221 — EVM deposit detection / ingest worker.

I’ve reviewed the issue and understand that this is not simply an eth_getLogs implementation. The worker needs to maintain the same reliability and crash-safety guarantees as the existing Stellar ingestion path while adapting to EVM-specific behaviour such as block-based cursors, ERC-20 event decoding, adaptive RPC ranges, and token-contract verification.

My implementation approach would be:

• Add crates/ingest/src/evm.rs with an EvmIngestor following the existing Ingestor structure and Processed semantics.
• Scan eth_getLogs using registered token contracts and the ERC-20 Transfer(address,address,uint256) topic, matching the indexed to address against registered deposit addresses.
• Decode indexed from/to topics correctly and parse the value using the existing Amount/U256 implementation.
• Persist a block-number cursor per (wallet, chain) and advance it only after durable processing, preserving crash-resume and idempotency guarantees.
• Reuse the existing supervisor, polling tiers, backoff, and mark_polled behaviour rather than introducing another scheduler.
• Implement adaptive range bisection when providers return RangeTooLarge.
• Preserve quarantine behaviour for transfers involving unregistered tokens.
• Treat deposits as unconfirmed and ensure this worker cannot create spendable balances before feat(ingest): Confirmation depth and reorg handling for EVM deposits #222.

The security requirement is particularly important to me. I will explicitly verify that the log's address is the registered token contract before attributing a deposit. I understand that checking only Transfer topics is unsafe because any contract can emit a fabricated event with arbitrary topics and values.

For testing, I would cover:

1. Real ERC-20 deposits through Anvil at both 6 and 18 decimals.
2. An adversarial contract emitting a fake Transfer event to a deposit address.
3. Replay/idempotency of the same log range.
4. Crash and resume during a batch.
5. RangeTooLarge adaptive bisection.
6. Quarantine of unregistered-token transfers.
7. Correct cursor and polling-state behaviour.

I would also update docs/ingest-integration.md and explicitly document the v1 scope around native ETH deposits. I agree with the issue's recommendation to keep native ETH deposits out of v1 and support ERC-20 stablecoins first.

I’m comfortable working within the existing Rust architecture and would keep the implementation focused on the issue's scope and existing patterns rather than introducing unnecessary abstractions.

I’d be happy to take this up on branch:

feat/evm-ingest-worker

Thanks for considering my application.