feat(wallet): EVM deposit sweep engine

[Emmyt24]

Depends on: #220, #225, #226. Blocks: nothing (terminal).

Description

Because EVM deposits land at N distinct per-customer addresses (#220) rather than in one muxed base
account, funds must be consolidated into a treasury address. This has no Stellar analogue at
all — the muxed model exists precisely so that sweeping is unnecessary
(docs/deposit-model.md).

Sweeping is genuinely hard and this issue holds real customer funds:

• A deposit address holds ERC-20 tokens but no native ETH, so it cannot pay gas for its own
  transfer. The sweeper must send gas first, then sweep — a two-transaction dance where a crash
  between the two must be recoverable.
• Gas cost can exceed the deposit value. Sweeping a $2 deposit for $4 of gas destroys value.
• Sweeps must be idempotent. A double-sweep wastes gas; a lost sweep record strands funds.
• The sweeper must hold spending keys for every deposit address, which is the largest departure
  from Octo's non-custodial posture in the entire epic (AD-4).

Requirements and context

• Only sweep confirmed deposits (per feat(ingest): Confirmation depth and reorg handling for EVM deposits #222). Sweeping an unconfirmed deposit that then reorgs
  means paying gas to move money that never existed.
• Economic gating is required, not optional: do not sweep when
  estimated_gas_cost > sweep_value × threshold. Accumulate and batch instead. Make the threshold
  configurable per chain — it is completely different on L1 versus Base.
• Every sweep must be idempotent and crash-recoverable. Persist intent before broadcasting, and
  reconcile on restart. Reuse the idempotency-key pattern from
  Store::create_withdrawal.
• Reuse feat(api): Nonce management, gas pricing, and EVM transaction lifecycle #226's nonce management. Do not build a second nonce allocator.
• Security — state these plainly in the threat model:
  • The sweeper's key material can move all unswept customer funds. Bound the exposure: what is the
    maximum unswept balance at any time, and what is the blast radius of a sweeper compromise?
  • Non-hardened derivation (feat(store): EVM per-customer deposit addresses via HD derivation #220) means a leaked deposit key plus a leaked xpub compromises all
    siblings — so the sweeper's key store and the xpub must not share a compromise boundary.
  • Gas-funding transfers to deposit addresses are visible on-chain and fingerprint Octo's entire
    deposit address set to any observer. Note this as an accepted privacy trade-off, or mitigate.
  • Keys must be sealed with octo-crypto at rest and only opened
    inside the signing boundary, zeroized after.

Suggested execution

Branch: feat/evm-sweep-engine

Implement changes

• Migration 00NN_sweeps.sql: a sweeps table recording source address, token, amount, gas-funding
  tx hash, sweep tx hash, state machine (pending → gas_funded → submitted → confirmed /
  failed), and an idempotency key.
• Implement the sweep worker: select eligible confirmed deposits, apply the economic gate, fund gas,
  build and sign the ERC-20 transfer to treasury, submit via feat(api): EVM signed-transaction relay with policy validation #225/feat(api): Nonce management, gas pricing, and EVM transaction lifecycle #226, and track to confirmation.
• Implement crash recovery: on startup, reconcile every non-terminal sweep against on-chain state
  before initiating anything new.
• Add operational metrics and alerts: unswept balance per chain, sweeps blocked by the economic
  gate, sweeps stuck in a non-terminal state.
• Evaluate and document whether a CREATE2 forwarder design (if chosen in feat(store): EVM per-customer deposit addresses via HD derivation #220) removes the
  gas-funding step.

Test and commit

• Anvil tests (chore(testing): Anvil-based EVM integration test harness #219): fund a deposit address with a mock ERC-20, run the sweeper, assert the treasury
  balance increases by exactly the deposit amount and the sweep row reaches confirmed.
• Crash-recovery test: kill the process between gas funding and sweep, restart, assert exactly
  one sweep occurs and no gas is double-sent.
• Economic-gating test: a dust deposit whose gas exceeds its value is not swept.
• Idempotency test: running the sweeper twice concurrently over the same deposit produces one sweep.
• Test that an unconfirmed deposit is never swept.
• A failure-path test: the sweep transaction reverts, and the sweep row lands in failed with the
  funds still safely at the deposit address.
• Update docs/threat-model.md with the full sweeper key-exposure analysis.

Example commit message

feat(wallet): EVM deposit sweep engine

Per-customer EOAs (#220) mean funds must be consolidated into a treasury,
which the Stellar muxed model never required.

Sweeps are gas-funded then executed as a two-step, persisted-intent
state machine that reconciles against on-chain state on restart, so a
crash between funding and sweeping cannot double-send or strand funds.
Dust below the configurable gas-to-value threshold accumulates instead
of being swept at a loss.

Only confirmed deposits are swept — sweeping a reorg-able deposit
spends gas moving money that never existed.

Refs #224

Guidelines

Security-critical, holds customer funds. Two maintainer reviewers, and a written threat-model
section is part of the deliverable, not a follow-up.

---

[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.

[guptakumarranjeet150]

Hi maintainers,

I can tackle feat(wallet): EVM deposit sweep engine. Proposed implementation roadmap:

• Analysis: Inspect current behavior and edge cases in Octo-Protocol-org/Octo-Protocol
• Implementation: Deliver a clean, modular solution for feat(wallet): EVM deposit sweep engine strictly following Octo-Protocol-org/Octo-Protocol conventions.
• Testing: Cover changes with automated tests ensuring CI passes smoothly.
• PR: Atomic commit with clean git hygiene and passing CI

Happy to pick this up today—please assign to me!

[ranjeet150]

Hello @maintainers,

I would love to take this on. My planned approach:

• Deliver a clean, modular solution for feat(wallet): EVM deposit sweep engine strictly following Octo-Protocol-org/Octo-Protocol conventions.
• Cover changes with automated tests ensuring CI passes smoothly.

Ready to deliver a clean, tested PR within 12–24 hours. Please assign!