feat(cketh): task skeleton to create sweeper requests (#11347)

## Why

- The sweep queue that the balance scan fills has nothing turning its
deposits into sweeps, and the signing that will do so needs a canister —
which is what makes it untestable today.

## What

- An async `CanisterRuntime` trait extending `TimeProvider` with tECDSA
signing as its first capability, plus the implementation backed by the
system API and a mock for tests.
- A skeleton `create_pending_sweeper_requests`, its task type, and the
timer that runs it.
- The skeleton does nothing yet, and a unit test pins that down: a
deposit sits in the sweep queue, the runtime carries no expectation, and
the whole state comes back unchanged. Each later commit then shows up as
a diff against a passing test.

[DEFI-2926]: https://dfinity.atlassian.net/browse/DEFI-2926

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: gregorydemay

Cargo.lock

@@ -30,6 +30,7 @@ filegroup(
         crate_name = "ic_cketh_minter",
         proc_macro_deps = [
             # Keep sorted.
+            "@crate_index//:async-trait",
             "@crate_index//:strum_macros",
         ],
         version = "0.1.0",

rs/ethereum/cketh/minter/BUILD.bazel

@@ -16,6 +16,7 @@ path = "bin/principal_to_hex.rs"
 
 [dependencies]
 askama = { workspace = true }
+async-trait = { workspace = true }
 canbench-rs = { workspace = true, optional = true }
 candid = { workspace = true }
 ethnum = { workspace = true }

rs/ethereum/cketh/minter/Cargo.toml

@@ -13,6 +13,7 @@ mod tests;
 use crate::deposit_address::{DepositAddressSchema, deposit_derivation_path};
 use crate::eth_logs::encode_principal;
 use crate::eth_rpc::Hash;
+use crate::runtime::CanisterRuntime;
 use crate::tx::{TransactionSignature, sign_digest};
 use ic_ethereum_types::Address;
 use icrc_ledger_types::icrc1::account::Account;
@@ -96,12 +97,14 @@ impl AttestationRequest {
 ///
 /// # Errors
 /// * a description of why the threshold-ECDSA signature could not be produced.
-pub async fn sign_attestation(
+pub async fn sign_attestation<R: CanisterRuntime>(
     request: &AttestationRequest,
+    runtime: &R,
 ) -> Result<TransactionSignature, String> {
     sign_digest(
         &request.digest(),
         &deposit_derivation_path(DepositAddressSchema::CkErc20, &request.account),
+        runtime,
     )
     .await
 }

rs/ethereum/cketh/minter/src/attestation/mod.rs

@@ -19,6 +19,7 @@ pub mod management;
 pub mod map;
 pub mod memo;
 pub mod numeric;
+pub mod runtime;
 pub mod state;
 pub mod storage;
 pub mod sweep;
@@ -44,6 +45,10 @@ pub const REFRESH_LATEST_BLOCK_HEIGHT_INTERVAL: Duration = Duration::from_secs(3
 pub const BALANCE_SCAN_INTERVAL: Duration = Duration::from_secs(30);
 pub const SWEEPER_FUNDING_INTERVAL: Duration = Duration::from_secs(24 * 60 * 60);
 pub const PROCESS_ETH_RETRIEVE_TRANSACTIONS_INTERVAL: Duration = Duration::from_secs(6 * 60);
+/// How often the minter turns detected deposits into sweeper requests. Far shorter than the
+/// intervals that send transactions: the mint follows the sweep, so this interval is part of a
+/// user's crediting latency, and creating a request is cheap — it signs, but sends nothing.
+pub const SWEEP_ENQUEUE_INTERVAL: Duration = Duration::from_secs(60);
 pub const PROCESS_REIMBURSEMENT: Duration = Duration::from_secs(3 * 60);
 pub const PROCESS_ETH_RETRIEVE_TRANSACTIONS_RETRY_INTERVAL: Duration = Duration::from_secs(3 * 60);
 pub const PROCESS_SWEEPER_TRANSACTIONS_INTERVAL: Duration = Duration::from_secs(6 * 60);

rs/ethereum/cketh/minter/src/lib.rs

@@ -29,6 +29,7 @@ use ic_cketh_minter::lifecycle::MinterArg;
 use ic_cketh_minter::logs::INFO;
 use ic_cketh_minter::memo::{self, BurnMemo};
 use ic_cketh_minter::numeric::{Erc20Value, LedgerBurnIndex, Wei};
+use ic_cketh_minter::runtime::IC_CANISTER_RUNTIME;
 use ic_cketh_minter::state::audit::{Event, EventType, process_event};
 use ic_cketh_minter::state::automatic_deposits::DepositRequest;
 use ic_cketh_minter::state::eth_logs_scraping::{LogScrapingId, LogScrapingInfo};
@@ -39,7 +40,7 @@ use ic_cketh_minter::state::transactions::{
 use ic_cketh_minter::state::{
     STATE, State, lazy_call_ecdsa_public_key, mutate_state, read_state, transactions,
 };
-use ic_cketh_minter::sweep::process_sweeper_transactions;
+use ic_cketh_minter::sweep::{create_pending_sweeper_requests, process_sweeper_transactions};
 use ic_cketh_minter::sweeper::fund_sweeper_address;
 use ic_cketh_minter::time::IC_TIME_PROVIDER;
 use ic_cketh_minter::timed_sized_map::Timestamp;
@@ -51,7 +52,7 @@ use ic_cketh_minter::withdraw::{
 use ic_cketh_minter::{
     BALANCE_SCAN_INTERVAL, PROCESS_ETH_RETRIEVE_TRANSACTIONS_INTERVAL, PROCESS_REIMBURSEMENT,
     PROCESS_SWEEPER_TRANSACTIONS_INTERVAL, REFRESH_LATEST_BLOCK_HEIGHT_INTERVAL,
-    SCRAPING_ETH_LOGS_INTERVAL, SWEEPER_FUNDING_INTERVAL, state, storage,
+    SCRAPING_ETH_LOGS_INTERVAL, SWEEP_ENQUEUE_INTERVAL, SWEEPER_FUNDING_INTERVAL, state, storage,
 };
 use ic_cketh_minter::{endpoints, erc20};
 use ic_ethereum_types::Address;
@@ -84,7 +85,7 @@ fn validate_ckerc20_active() {
 fn setup_timers() {
     ic_cdk_timers::set_timer(Duration::from_secs(0), async {
         // Initialize the minter's public key to make the address known.
-        let _ = lazy_call_ecdsa_public_key().await;
+        let _ = lazy_call_ecdsa_public_key(&IC_CANISTER_RUNTIME).await;
         // Sequenced after the key rather than scheduled on a delay: the sweeper address cannot be
         // derived without it, and a delay only guesses at when it will be cached. Running here also
         // keeps the two off separate tasks, since two concurrent `ecdsa_public_key` calls trap.
@@ -106,10 +107,13 @@ fn setup_timers() {
         refresh_latest_block_height().await;
     });
     ic_cdk_timers::set_timer_interval(PROCESS_ETH_RETRIEVE_TRANSACTIONS_INTERVAL, async || {
-        process_retrieve_eth_requests(IC_TIME_PROVIDER).await;
+        process_retrieve_eth_requests(IC_CANISTER_RUNTIME).await;
+    });
+    ic_cdk_timers::set_timer_interval(SWEEP_ENQUEUE_INTERVAL, async || {
+        create_pending_sweeper_requests(&IC_CANISTER_RUNTIME).await;
     });
     ic_cdk_timers::set_timer_interval(PROCESS_SWEEPER_TRANSACTIONS_INTERVAL, async || {
-        process_sweeper_transactions(IC_TIME_PROVIDER).await;
+        process_sweeper_transactions(IC_CANISTER_RUNTIME).await;
     });
     ic_cdk_timers::set_timer_interval(PROCESS_REIMBURSEMENT, async || {
         process_reimbursement(&IC_TIME_PROVIDER).await;
@@ -193,7 +197,9 @@ fn post_upgrade(minter_arg: Option<MinterArg>) {
 
 #[update]
 async fn minter_address() -> String {
-    state::minter_address().await.to_string()
+    state::minter_address(&IC_CANISTER_RUNTIME)
+        .await
+        .to_string()
 }
 
 #[update]
@@ -240,7 +246,7 @@ async fn deposit_erc20(arg: DepositErc20Arg) -> Result<DepositErc20Response, Dep
 
     // Not armed yet: register. Ensure the minter's ECDSA public key has been fetched and cached in
     // the state so that the (synchronous) registration below can derive the address.
-    state::lazy_call_ecdsa_public_key_with_chain_code().await;
+    state::lazy_call_ecdsa_public_key_with_chain_code(&IC_CANISTER_RUNTIME).await;
     let now = Timestamp::from_nanos(ic_cdk::api::time());
     // Re-check the status after the await: a concurrent balance scan may have detected a deposit and
     // moved this pair into the sweep queue while we waited for the ECDSA key (only possible right

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

@@ -1,4 +1,4 @@
-use ic_cdk::call::{CallFailed, RejectCode};
+use ic_cdk::call::{CallFailed, Error as CdkCallError, RejectCode};
 use ic_cdk_management_canister::SignCallError;
 use ic_management_canister_types_private::DerivationPath;
 use std::fmt;
@@ -79,6 +79,17 @@ impl Reason {
         }
     }
 
+    fn from_cdk_call_error(error: CdkCallError) -> Self {
+        match error {
+            CdkCallError::CandidDecodeFailed(e) => {
+                Self::InternalError(format!("candid decode failed: {e}"))
+            }
+            CdkCallError::CallRejected(rejected) => Self::from_call_failed(rejected.into()),
+            CdkCallError::InsufficientLiquidCycleBalance(e) => Self::from_call_failed(e.into()),
+            CdkCallError::CallPerformFailed(e) => Self::from_call_failed(e.into()),
+        }
+    }
+
     fn from_call_failed(failed: CallFailed) -> Self {
         match failed {
             CallFailed::CallRejected(rejected) => {
@@ -104,6 +115,28 @@ impl Reason {
     }
 }
 
+/// Fetches the canister's tECDSA public key and chain code from the management canister.
+pub async fn ecdsa_public_key(
+    key_name: String,
+    derivation_path: DerivationPath,
+) -> Result<ic_cdk_management_canister::EcdsaPublicKeyResult, CallError> {
+    use ic_cdk_management_canister::{EcdsaCurve, EcdsaKeyId, EcdsaPublicKeyArgs};
+
+    ic_cdk_management_canister::ecdsa_public_key(&EcdsaPublicKeyArgs {
+        canister_id: None,
+        derivation_path: derivation_path.into_inner(),
+        key_id: EcdsaKeyId {
+            curve: EcdsaCurve::Secp256k1,
+            name: key_name,
+        },
+    })
+    .await
+    .map_err(|error| CallError {
+        method: "ecdsa_public_key".to_string(),
+        reason: Reason::from_cdk_call_error(error),
+    })
+}
+
 /// Signs a message hash using the tECDSA API.
 pub async fn sign_with_ecdsa(
     key_name: String,

rs/ethereum/cketh/minter/src/management/mod.rs

@@ -0,0 +1,68 @@
+use crate::management::CallError;
+use crate::time::{IC_TIME_PROVIDER, TimeProvider};
+use async_trait::async_trait;
+use ic_cdk_management_canister::EcdsaPublicKeyResult;
+use ic_management_canister_types_private::DerivationPath;
+use serde_bytes::ByteBuf;
+
+/// The canister capabilities the minter needs from its environment.
+///
+/// Abstracting them away lets the logic that drives them be exercised without a canister.
+#[async_trait]
+pub trait CanisterRuntime: TimeProvider {
+    /// Signs a message hash with the tECDSA key `key_name` derived along `derivation_path`.
+    async fn sign_with_ecdsa(
+        &self,
+        key_name: String,
+        derivation_path: Vec<Vec<u8>>,
+        message_hash: [u8; 32],
+    ) -> Result<[u8; 64], CallError>;
+
+    /// The tECDSA public key `key_name` derived along `derivation_path`, with its chain code.
+    async fn ecdsa_public_key(
+        &self,
+        key_name: String,
+        derivation_path: Vec<Vec<u8>>,
+    ) -> Result<EcdsaPublicKeyResult, CallError>;
+}
+
+/// The [`CanisterRuntime`] used in production, backed by the Internet Computer system API.
+pub const IC_CANISTER_RUNTIME: IcCanisterRuntime = IcCanisterRuntime;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct IcCanisterRuntime;
+
+impl TimeProvider for IcCanisterRuntime {
+    fn time(&self) -> u64 {
+        IC_TIME_PROVIDER.time()
+    }
+}
+
+#[async_trait]
+impl CanisterRuntime for IcCanisterRuntime {
+    async fn sign_with_ecdsa(
+        &self,
+        key_name: String,
+        derivation_path: Vec<Vec<u8>>,
+        message_hash: [u8; 32],
+    ) -> Result<[u8; 64], CallError> {
+        crate::management::sign_with_ecdsa(
+            key_name,
+            DerivationPath::new(derivation_path.into_iter().map(ByteBuf::from).collect()),
+            message_hash,
+        )
+        .await
+    }
+
+    async fn ecdsa_public_key(
+        &self,
+        key_name: String,
+        derivation_path: Vec<Vec<u8>>,
+    ) -> Result<EcdsaPublicKeyResult, CallError> {
+        crate::management::ecdsa_public_key(
+            key_name,
+            DerivationPath::new(derivation_path.into_iter().map(ByteBuf::from).collect()),
+        )
+        .await
+    }
+}

rs/ethereum/cketh/minter/src/runtime/mod.rs

@@ -12,6 +12,7 @@ use crate::map::DedupMultiKeyMap;
 use crate::numeric::{
     BlockNumber, Erc20Value, LedgerBurnIndex, LedgerMintIndex, TransactionNonce, Wei,
 };
+use crate::runtime::CanisterRuntime;
 use crate::state::automatic_deposits::{AutomaticDeposits, ScanProgress};
 use crate::state::eth_logs_scraping::{LogScrapingId, LogScrapings};
 use crate::state::sweeper_funding::{SweeperFundingAccounting, SweeperFundingConfig};
@@ -799,11 +800,9 @@ where
     })
 }
 
-pub async fn lazy_call_ecdsa_public_key_with_chain_code() -> (PublicKey, [u8; 32]) {
-    use ic_cdk_management_canister::{
-        EcdsaCurve, EcdsaKeyId, EcdsaPublicKeyArgs, ecdsa_public_key,
-    };
-
+pub async fn lazy_call_ecdsa_public_key_with_chain_code<R: CanisterRuntime>(
+    runtime: &R,
+) -> (PublicKey, [u8; 32]) {
     fn to_public_key_and_chain_code(response: &EcdsaPublicKeyResult) -> (PublicKey, [u8; 32]) {
         let public_key = PublicKey::deserialize_sec1(&response.public_key).unwrap_or_else(|e| {
             ic_cdk::trap(format!("failed to decode minter's public key: {e:?}"))
@@ -823,29 +822,26 @@ pub async fn lazy_call_ecdsa_public_key_with_chain_code() -> (PublicKey, [u8; 32
     }
     let key_name = read_state(|s| s.ecdsa_key_name.clone());
     log!(DEBUG, "Fetching the ECDSA public key {key_name}");
-    let response = ecdsa_public_key(&EcdsaPublicKeyArgs {
-        canister_id: None,
-        derivation_path: crate::MAIN_DERIVATION_PATH
-            .into_iter()
-            .map(|x| x.to_vec())
-            .collect(),
-        key_id: EcdsaKeyId {
-            curve: EcdsaCurve::Secp256k1,
-            name: key_name,
-        },
-    })
-    .await
-    .unwrap_or_else(|err| ic_cdk::trap(format!("failed to get minter's public key: {err}")));
+    let response = runtime
+        .ecdsa_public_key(
+            key_name,
+            crate::MAIN_DERIVATION_PATH
+                .into_iter()
+                .map(|x| x.to_vec())
+                .collect(),
+        )
+        .await
+        .unwrap_or_else(|err| ic_cdk::trap(format!("failed to get minter's public key: {err}")));
     mutate_state(|s| s.ecdsa_public_key = Some(response.clone()));
     to_public_key_and_chain_code(&response)
 }
 
-pub async fn lazy_call_ecdsa_public_key() -> PublicKey {
-    lazy_call_ecdsa_public_key_with_chain_code().await.0
+pub async fn lazy_call_ecdsa_public_key<R: CanisterRuntime>(runtime: &R) -> PublicKey {
+    lazy_call_ecdsa_public_key_with_chain_code(runtime).await.0
 }
 
-pub async fn minter_address() -> Address {
-    ecdsa_public_key_to_address(&lazy_call_ecdsa_public_key().await)
+pub async fn minter_address<R: CanisterRuntime>(runtime: &R) -> Address {
+    ecdsa_public_key_to_address(&lazy_call_ecdsa_public_key(runtime).await)
 }
 
 #[derive(Clone, Eq, PartialEq, Debug)]
@@ -986,4 +982,5 @@ pub enum TaskType {
     BalanceScan,
     SweeperFunding,
     SweeperSend,
+    SweeperEnqueue,
 }