feat(cketh): detect deposits above minimum

[gregorydemay]

A background task periodically reads the on-chain ERC-20 balance of the armed deposit addresses that are due for a scan and flags the ones at or above a per-token minimum as deposit candidates (reported via metrics). A balance is only a cheap scheduling hint — it triggers work but never credits; filter 2 (DEFI-2924) re-verifies against finalized logs before any mint. Nothing runs downstream yet.

Highlights:

• Deployless batcher instead of Multicall3. Balances are read with a single create-style eth_call (to omitted) that runs a small program returning them as a compact flat array — ~5× less response overhead and a trivial decode, with no deployed contract. The shipped bytecode is pinned by a byte-for-byte assembly golden and its behaviour verified on a local anvil node (balances across tokens/holders; fail-loud on a bad token), in addition to end-to-end validation against Ethereum mainnet across all four providers the minter uses and through the deployed EVM-RPC canister.
• Driven by the schedule. Scans only the addresses due per feat(cketh): balance-scan scheduling layer #10881's block-based backoff, pins the call to the refreshed latest block height, and advances each address' schedule after a successful scan.
• Per-token minimums worth ~0.005 ETH each, covering every token the mainnet and Sepolia minters support (a hard-coded rate snapshot; DEFI-2961 tracks refreshing them daily from the exchange-rate canister).
• Discoverable progress. deposit_erc20 now returns each address' last_scanned_block and scan_count, and an end-to-end test exercises register → scan → observe.

Deferred: filter 2, blocklist/dedup and crediting (DEFI-2924); exposing the minimum to users (DEFI-2962).

PR stack

• feat(cketh): balance-scan scheduling layer #10881 — scan-scheduling layer — base master
• feat(cketh): detect deposits above minimum #10873 (this PR) — balance scan filter 1 (deployless-batcher balances) — stacked on feat(cketh): balance-scan scheduling layer #10881

#10878 (the earlier wall-clock scan-schedule) was closed as superseded by #10881.

[Copilot]

Pull request overview

Adds the first “filter 1” consumer of the ckERC20 deposit-address watchlist by introducing a periodic background balance scan that batches ERC-20 balanceOf checks via Multicall3 aggregate3, then exposes last-run scan stats via metrics.

Changes:

• Introduces balance_scan module: builds (account, token) call sets from live deposit addresses + supported tokens, runs chunked Multicall3 eth_call, and records scan stats in state.
• Adds a small hand-rolled Multicall3 ABI encoder/decoder (with unit tests focused on bounds/overflow safety).
• Wires the scan into canister timers and exposes scan gauges in the HTTP metrics endpoint; adds a live_addresses iterator on the automatic deposits watchlist.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
rs/ethereum/cketh/minter/src/state/tests.rs	Updates state test construction for the new last_balance_scan field.
rs/ethereum/cketh/minter/src/state/automatic_deposits/tests.rs	Adds unit test coverage for yielding only live (non-expired) deposit addresses.
rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs	Adds live_addresses() iterator for filtering watchlist entries by expiry.
rs/ethereum/cketh/minter/src/state.rs	Adds last_balance_scan to state and a new TaskType::BalanceScan.
rs/ethereum/cketh/minter/src/main.rs	Schedules balance scan timers and exports last scan stats as metrics gauges.
rs/ethereum/cketh/minter/src/lifecycle/init.rs	Initializes last_balance_scan to None on init.
rs/ethereum/cketh/minter/src/lib.rs	Exposes balance_scan module and adds BALANCE_SCAN_INTERVAL constant.
rs/ethereum/cketh/minter/src/balance_scan/tests.rs	Adds unit tests for candidate counting and call-building behavior.
rs/ethereum/cketh/minter/src/balance_scan/multicall3/tests.rs	Adds golden-vector and adversarial decoding tests for Multicall3 ABI handling.
rs/ethereum/cketh/minter/src/balance_scan/multicall3.rs	Implements Multicall3 aggregate3 + ERC-20 balanceOf ABI encoder/decoder.
rs/ethereum/cketh/minter/src/balance_scan/mod.rs	Implements the periodic scan task, chunking logic, stats tracking, and RPC call arguments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 7db8031.

Security Overview

• 🔎 Scanned files: 20 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/783a9bd4-fb4e-4e10-ab3c-c2fb2ddfb92f?scanId=242add5d-3211-4d28-8ab9-411f8ad4bada&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/ethereum/cketh/minter/src/balance_scan/batcher/mod.rs     Implement deployless balance-batcher, encoding/decoding, and related helpers
Enhancement	► rs/ethereum/cketh/minter/src/balance_scan/batcher/tests.rs     Tests for batcher functionality and encoding/decoding
Enhancement	► rs/ethereum/cketh/minter/src/balance_scan/mod.rs     Introduce balance_scan module and orchestration for batch balance reads
Enhancement	► rs/ethereum/cketh/minter/BUILD.bazel     Add test scaffolding and new test cases for deposit_from_cex functionality
Enhancement	► rs/ethereum/cketh/minter/minter.did     Extend DepositErc20Response with last_scanned_block and scan_count fields
Enhancement	► rs/ethereum/cketh/minter/src/balance_scan/tests.rs     (Additional test implementations for balance_scan)

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (4)

rs/ethereum/cketh/minter/tests/deposit_from_cex.rs:417

• wait_until_ready also performs blocking HTTP requests without a timeout. A stuck connection can make the readiness loop hang longer than the intended 30s deadline.

        let ready = reqwest::blocking::Client::new()
            .post(url)
            .json(&serde_json::json!({"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}))
            .send()
            .map(|r| r.status().is_success())

rs/ethereum/cketh/minter/src/main.rs:1041

• The metric help text still refers to "multicall" chunks, but the balance scan now uses the deployless batcher (create-style eth_call). This makes the exported metric documentation misleading for operators.

                    w.encode_gauge(
                        "cketh_minter_balance_scan_failed_chunks",
                        stats.chunks_failed as f64,
                        "Number of multicall chunks that failed in the last balance scan.",
                    )?;

rs/ethereum/cketh/minter/src/balance_scan/mod.rs:208

• min_deposit uses unwrap_or(Erc20Value::MAX) to represent an unsupported token, but count_candidates uses >=, so an unsupported token can still be counted as a candidate if its balance happens to equal Erc20Value::MAX. This contradicts the function doc (“absent … never counts”).

/// Minimum balance for `token` to count as a scan candidate; a token absent from
/// [`MIN_DEPOSITS`] never counts.
fn min_deposit(token: &Address) -> Erc20Value {
    MIN_DEPOSITS
        .iter()

rs/ethereum/cketh/minter/tests/deposit_from_cex.rs:325

• rpc_result uses reqwest::blocking::Client::new() with no request timeout. If the local node stops responding mid-test, this can hang the test indefinitely rather than failing fast.

This issue also appears on line 413 of the same file.

    fn rpc_result(&self, method: &str, params: Value) -> Result<Value, String> {
        let body: Value = reqwest::blocking::Client::new()
            .post(&self.url)
            .json(
                &serde_json::json!({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}),

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (4)

rs/ethereum/cketh/minter/tests/deposit_from_cex.rs:418

• wait_until_ready also performs blocking HTTP requests without a timeout, so a network hang can block the readiness loop longer than intended. Use a client with a per-request timeout here as well.

        let ready = reqwest::blocking::Client::new()
            .post(url)
            .json(&serde_json::json!({"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}))
            .send()
            .map(|r| r.status().is_success())

rs/ethereum/cketh/minter/src/balance_scan/mod.rs:94

• watchlist_len counts all entries in the underlying TimedSizedMap, including expired-but-not-yet-evicted entries. The log message currently reads as if all watchlist_len entries are "ready to be scanned", which can be misleading when most/all entries are expired.

        log!(
            DEBUG,
            "[balance_scan] SKIPPING: 0/{watchlist_len} user addresses ready to be scanned"
        );

rs/ethereum/cketh/minter/src/balance_scan/mod.rs:211

• min_deposit claims that a token absent from MIN_DEPOSITS never counts, but the current implementation returns Erc20Value::MAX and count_candidates uses >=. That means an unsupported/unknown token would be counted as a candidate if it ever reports a u256::MAX balance (e.g., a misbehaving ERC-20), contradicting the function contract.

fn count_candidates(calls: &[BalanceOfCall], balances: &[Erc20Value]) -> usize {
    calls
        .iter()
        .zip(balances)
        .filter(|(call, balance)| **balance >= min_deposit(&call.token))
        .count()

rs/ethereum/cketh/minter/tests/deposit_from_cex.rs:320

• These reqwest::blocking calls use the default client configuration, which has no request timeout. If anvil stalls or the connection hangs, this test can block indefinitely and stall CI. Set an explicit timeout on the HTTP client (even a few seconds is enough for local anvil).

        let body: Value = reqwest::blocking::Client::new()
            .post(&self.url)
            .json(
                &serde_json::json!({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}),
            )