feat(cketh): per-(deposit address, ERC-20) deposit granularity

[gregorydemay]

Why

Automatic ERC-20 deposit detection was keyed at the granularity of a deposit address: one deposit_erc20 call armed an address, and the balance scan read every armed address against every supported ERC-20 in gas-capped batches. That per-address unit is the source of most of the machinery (keeping an address's per-token calls in one batch, advancing a whole address, dropping all of an address's tokens the moment any one funds) and a status wart (AwaitingSweep lumping every token together).

This PR makes the natural finer unit — (deposit address, ERC-20 token) — the unit of registration, scanning, status, and sweeping, which is also the standard CEX deposit UX: pick the token, the network is always Ethereum, then show the (shared) deposit address.

Nothing here is live yet

The automatic-deposit feature as a whole — deposit_erc20 and the balance scan behind it — has never shipped to mainnet. No deployed minter exposes the endpoint, so no production event log contains any of its events and no client calls it.

That is what makes the rest of this PR cheap, and it is worth keeping in mind while reviewing:

• The Candid changes are marked breaking, but they break no deployed caller.
• Event payloads are reshaped and their fields renamed in place, with no versioning or migration, because there is no recorded history to stay compatible with.
• Where an encoding is preserved (the newtype and field renames below leave the CBOR bytes untouched), that is for the sake of the replayable mainnet/Sepolia event-log tests, not for production data.

What

• deposit_erc20 takes an explicit erc20_contract_address, required to be a minter-supported ckERC20. The deposit address stays shared across a caller's tokens.
• Registration / watchlist / scan schedule / sweep queue are keyed by (account, token); funding one token no longer removes its siblings. Per-account cap of 5 concurrently armed tokens.
• The balance scan reads only the registered (address, token) pairs — the cartesian batching (split-assert, whole-address advance) is gone; each pair is one balanceOf call.
• AwaitingSweep now carries a single detected deposit; the automatic-deposit events carry one entry per token.
• The deposit_from_cex.md spec is updated to match.

Review follow-ups

• Every Candid field naming an ERC-20 contract is now erc20_contract_address rather than token, matching the existing deposit_erc20 argument and the minted-token event. The internal event payloads follow suit, so the two layers no longer disagree.
• deposit_erc20's failure handling now matches withdraw_erc20: an unparseable contract address traps, and an unsupported token returns the list of tokens the minter does support instead of an empty error.
• A deposit address derived by the minter and an ERC-20 contract address were both plain Ethereum addresses, so every place the deposit flow handled both was a silent-swap hazard that still compiled — including the balance-scan call where transposing them would have queried the wrong account and quietly read zero. The derived address now has its own type, which makes those transpositions compile errors.
• The (account, token) pair and the scan bookkeeping stored against it were named the wrong way round; they now say what they are, mirroring WithdrawalRequest on the withdrawal side.

Rebased onto master now that #10946 has merged. Tracks DEFI-2976.

[Copilot]

Pull request overview

This PR changes ckERC20 automatic deposit registration and processing from per-deposit-address to per (deposit address, ERC-20 token) granularity, aligning scanning, status reporting, audit events, and docs with the new per-token deposit UX while keeping a shared derived address per account.

Changes:

• deposit_erc20 now requires an explicit erc20_contract_address and validates it is a minter-supported ckERC20.
• Automatic deposit watchlist/scanning/sweep-queue are keyed by (account, token); AwaitingSweep and related events carry a single detected deposit per token.
• Tests, Candid, and the deposit_from_cex.md spec are updated to reflect the new per-pair behavior and event shapes.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
rs/ethereum/cketh/test_utils/src/live_scan.rs	Updates test helper APIs to register/await scans per (caller, token) and pass erc20_contract_address.
rs/ethereum/cketh/test_utils/src/ckerc20.rs	Extends test deposit flow helper to include erc20_contract_address in DepositErc20Arg.
rs/ethereum/cketh/minter/tests/dump_stable_memory.rs	Updates event mapping to new per-token registration and per-pair AutomaticDepositReceived payload.
rs/ethereum/cketh/minter/tests/deposit_from_cex.rs	Adjusts integration test expectations for per-token AwaitingSweep and per-token registration.
rs/ethereum/cketh/minter/tests/ckerc20.rs	Updates minter endpoint tests for new arg shape and per-pair scan/sweep semantics.
rs/ethereum/cketh/minter/src/state/tests.rs	Updates state equivalence test setup to arm deposits per (account, token).
rs/ethereum/cketh/minter/src/state/event.rs	Reshapes audit event payloads for per-pair deposits (adds token, removes per-event deposits list).
rs/ethereum/cketh/minter/src/state/automatic_deposits/tests.rs	Refactors unit tests to cover per-pair watchlist/sweep behavior and per-account token caps.
rs/ethereum/cketh/minter/src/state/automatic_deposits/mod.rs	Implements per-pair watchlist keys, per-account token cap, scan targeting, and per-pair sweep queue.
rs/ethereum/cketh/minter/src/state/audit/tests.rs	Updates audit test parsing/mapping for new event and registration shapes.
rs/ethereum/cketh/minter/src/state.rs	Adds is_supported_ckerc20 and threads token through deposit registration.
rs/ethereum/cketh/minter/src/main.rs	Validates erc20_contract_address, checks support, and registers/reports status per (account, token).
rs/ethereum/cketh/minter/src/endpoints.rs	Updates Candid types for new deposit arg, per-token AwaitingSweep, and new error variants.
rs/ethereum/cketh/minter/src/balance_scan/tests.rs	Refactors scan tests to per-pair calls/chunking and updated watchlist interactions.
rs/ethereum/cketh/minter/src/balance_scan/mod.rs	Refactors balance scan to scan only registered (address, token) pairs and emit per-pair events.
rs/ethereum/cketh/minter/cketh_minter.did	Updates DID to new DepositErc20Arg, DepositStatus, and event payload shapes.
rs/ethereum/cketh/docs/deposit_from_cex.md	Updates spec narrative and diagrams for per-pair registration/scanning/status/sweep behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

rs/ethereum/cketh/minter/src/endpoints.rs:261

• The documentation for DepositStatus still refers to a “deposit address”, but the API is now keyed per (deposit address, ERC-20 token) pair (including scan count / last scanned block). Updating these doc comments will make the Candid/Rust API clearer for consumers.

/// The stage a ckERC20 deposit address is at. Extensible with `Sweeping`/`Swept`
/// once sweeping lands (DEFI-2924).
#[derive(CandidType, Deserialize, Clone, Debug, Eq, PartialEq)]
pub enum DepositStatus {
    /// Armed and being scanned; no deposit at or above the minimum detected yet.
    Scanning {
        /// Timestamp in nanoseconds since the Unix epoch until which a deposit
        /// sent to the address is guaranteed to be noticed by the minter.
        valid_until: u64,
        /// The latest Ethereum block at which the address' balance was scanned,
        /// or `None` if it has not been scanned yet.
        last_scanned_block: Option<Nat>,
        /// How many times the address' balance has been scanned so far.
        scan_count: u64,

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 9dab822.

Security Overview

• 🔎 Scanned files: 24 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/783a9bd4-fb4e-4e10-ab3c-c2fb2ddfb92f?scanId=f98b63b7-c36c-411d-9e6a-98df1057f575&codeScanTypes=PrScan&tab=issues

Detected Code Changes

The diff is too large to display a summary of code changes.

[mbjorkqvist]

Thanks @gregorydemay, just a few minor comments!