feat(cketh): move funded deposit addresses to a balance-sweep queue

[gregorydemay]

When the periodic balance scan finds a registered ckERC20 deposit address holding at least a token's minimum, that funded address is moved out of the time-expiring watchlist into a dedicated sweep queue in AutomaticDeposits, keyed per account with one entry per funded token. This hands the deposit off to the future sweeper and stops re-scanning the address. A deposit address is per-account and token-agnostic, so one address can yield several sweep entries (one per funded token) in a single scan. Nothing drains the queue yet.

Highlights:

• Event-sourced. Each detection is recorded the moment funds are found as an AutomaticDepositReceived audit event — one event per scanned account, listing every funded token — durable across an ungraceful trap, replayed on upgrade to rebuild the queue, and surfaced via get_events like every other event, rather than only via a pre-upgrade snapshot.
• Account-keyed queue. The queue is keyed by the user account together with the deposit address derived for it (stored once, since the address is fully determined by the account), and each queued entry names the ERC-20 token contract so it is never conflated with that deposit address.
• Deposit status in deposit_erc20. The response now carries a status: Scanning (armed, still looking) or AwaitingSweep (detected, queued — one entry per funded token, with amount and detection block), so a user can follow the multi-minute flow. A detected address is not re-armed while its funds are queued, preventing duplicate detection/registration. The status variant is extensible for the sweeper's later states (DEFI-2924).
• No new metrics. Balance-scan and sweep observability (queue size, watchlist size, oldest unswept address, per-kind scan error counters, …) is deferred to a dedicated ticket (DEFI-2965).

Deferred: draining/consuming the sweep queue and minting (DEFI-2924); observability metrics (DEFI-2965); the 2-of-3 NoReduction RPC client for latest-block scans (DEFI-2964).

Note: adds an AutomaticDepositReceived variant to the get_events output and reshapes DepositErc20Response (both on the debug/query surface of an unreleased feature), so the Candid change is gated by the CI_OVERRIDE_DIDC_CHECK label.

See the design doc: rs/ethereum/cketh/docs/deposit_from_cex.md.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs:243

• sweep_entries_for_account currently scans the entire sweep queue (self.sweep.iter().filter(...)), making deposit_erc20 O(total_sweep_entries) even though SweepKey is ordered by (account, token). This can become a hot path as the sweep queue grows (especially since nothing drains it yet). Consider using a BTreeMap::range over the contiguous key interval for the requested account so lookup is O(log N + M).

    pub fn sweep_entries_for_account(&self, account: &Account) -> Vec<DetectedSweep> {
        self.sweep
            .iter()
            .filter(|(key, _)| key.account == *account)
            .map(|(key, entry)| DetectedSweep {
                token: key.token,
                address: entry.address,
                scanned_balance: entry.scanned_balance,
                last_scanned_block: entry.last_scanned_block,
            })
            .collect()
    }

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs:241

• sweep_entries_for_account currently iterates the entire sweep BTreeMap and filters by account, making deposit_erc20 O(total_sweep_entries). Since SweepKey is ordered by (account, token), this can be implemented as a BTreeMap::range over just the keys for the requested account to avoid a linear scan as the sweep queue grows.

    pub fn sweep_entries_for_account(&self, account: &Account) -> Vec<DetectedSweep> {
        self.sweep
            .iter()
            .filter(|(key, _)| key.account == *account)
            .map(|(key, entry)| DetectedSweep {
                token: key.token,
                address: entry.address,
                scanned_balance: entry.scanned_balance,
                last_scanned_block: entry.last_scanned_block,
            })
            .collect()

rs/ethereum/cketh/minter/src/state/event.rs:184

• PR description and notes mention a MovedToSweepQueue audit/get_events variant, but the code introduces AutomaticDepositReceived. This mismatch can confuse API consumers and reviewers; either update the PR description/design wording to match the implemented event name or rename the event consistently across the codebase and Candid.

    /// A funded deposit address was found by a balance scan and moved out of the
    /// watchlist into the balance-sweep queue for one `(account, token)`. Recorded
    /// the moment the funds are detected, so the sweep queue is durable even across
    /// an ungraceful trap (unlike the pre-upgrade snapshot).
    #[n(26)]
    AutomaticDepositReceived(#[n(0)] AutomaticDeposit),

rs/ethereum/cketh/minter/tests/ckerc20.rs:341

• Grammar: use "an" before a vowel sound (Automatic...).

            ckerc20.cketh.get_all_events().iter().all(|event| !matches!(
                event.payload,
                EventPayload::AutomaticDepositReceived { .. }
            )),
            "below-minimum balances must not emit a AutomaticDepositReceived event"
        );

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 3067be9.

Security Overview

• 🔎 Scanned files: 18 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/783a9bd4-fb4e-4e10-ab3c-c2fb2ddfb92f?scanId=6f2517e0-67db-4526-8368-4047ebcf80fc&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/ethereum/cketh/minter/BUILD.bazel      Add additional test/dev dependencies ► rs/ethereum/cketh/minter/cketh_minter.did      Introduce DepositStatus, DetectedDeposit, and status fields in DepositErc20Response ► rs/ethereum/cketh/minter/src/balance_scan/mod.rs      Refactor balance scan to use per-account batching with new BalanceScan abstractions ► rs/ethereum/cketh/minter/src/balance_scan/tests.rs      Add tests for BalanceScan attribute mapping and batching behavior ► rs/ethereum/cketh/minter/src/endpoints.rs      Update DepositErc20Response to include DepositStatus and new AutomaticDepositReceived event structure ► rs/ethereum/cketh/minter/src/main.rs      Remove direct DepositRequest usage in deposit flow; rely on new deposit status flow ► rs/ethereum/cketh/minter/src/state/audit.rs      Hook AutomaticDepositReceived into state transition handling ► rs/ethereum/cketh/minter/src/state/audit/tests.rs      Extend tests to cover AutomaticDepositReceived event mapping ► rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs      Add new DepositAccount type and SweepEntry for tracking funded deposits; implement deposit status logic and sweep queue
Refactor	► rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs      Rework data structures to include sweep queue and per-account deposit tracking ► rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs      Change function names and logic to support new status flow and event processing ► rs/ethereum/cketh/minter/src/endpoints.rs      Align API types with new DepositStatus and AutomaticDepositReceived payloads
Bug Fix / Behavior Change	► rs/ethereum/cketh/minter/src/balance_scan/mod.rs (and related balance_scan module bits)      Correct batch construction and decoding parameter usage to align with new BalanceScanResult collection ► rs/ethereum/cketh/minter/src/balance_scan/tests.rs      Adjust tests to reflect new per-account batching and result attribution