feat(cketh): give the sweeper address its own transaction pipeline

[gregorydemay]

Why

The minter's dedicated sweeper address needs to send Ethereum transactions, and it must not share the main address' nonce sequence: a sweep stuck behind a fee-starved transaction would head-of-line-block every user withdrawal.

What

A second instance of the transaction pipeline, for the sweeper address, on a nonce sequence of its own. A sweep burns no ckETH, so it is keyed by a plain counter rather than a ledger burn index, and is never reimbursed; it pays gas from the sweeper's prepaid balance, so it has no transaction fee it can fail to cover. Five audit events record the pipeline's transitions, with reconstruction, Candid mirrors and .did.

The sweeper's start nonce can be set from both lifecycle arguments. It is optional on install where the main address' equivalent is required, because install arguments are replayed from the event log and a required field would be missing from every event already written.

Scope

The pipeline only. No timer drives it and nothing enqueues a sweep, so the new state stays empty: the sending task is DEFI-2926 in #11237, and EIP-7702 first-time delegation is #11250, stacked above. The sweep-queue source and prepaid-gas gating are still to come.

Sweeper funding — burning ckETH from the minter's fee subaccount to prepay that gas — is a separate stack (DEFI-2933) that meets this one only in the withdrawal pipeline, where its request variant has already landed. Hence the audit events here are numbered from n28, above the funding event master now owns.

Candid compatibility

CI_OVERRIDE_DIDC_CHECK is set. The check flags the five cases this PR adds to the Event payload variant, since a variant returned to callers may not grow under Candid subtyping. It is the additive shape every new audit event has taken: existing cases keep their names and fields, and callers matching exhaustively on the old set see the new ones only for sweeper activity, which nothing enqueues yet. The new optional nonce field on the two argument types is compatible on its own.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

This PR prepares ckETH minter support for Ethereum transactions sent from the dedicated sweeper address by introducing a second, independent transaction “send lane” with its own nonce sequence, ensuring sweeps cannot head-of-line block withdrawals from the main minter address.

Changes:

• Generalizes the existing EthTransactions state machine into a reusable TransactionLane<R> and keeps main-lane behavior via a type alias.
• Introduces SweepId/SweepRequest, a dedicated State::sweeper_transactions lane, and a new timer-driven process_sweeper_transactions pipeline that signs with derivation path [3].
• Extends audit/event plumbing (events n27..n31) and Candid surface area (DID + endpoint payload mirrors) for sweeper-lane observability and replay.

Reviewed changes

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

Show a summary per file

File	Description
rs/ethereum/cketh/minter/tests/dump_stable_memory.rs	Extends stable-memory dump test mapping to cover new sweeper-lane audit event payloads.
rs/ethereum/cketh/minter/src/withdraw.rs	Refactors RPC helpers to be sender-agnostic (reused by both lanes) and threads sender into count/finalization.
rs/ethereum/cketh/minter/src/sweep.rs	Adds the sweeper transaction processing task (create/sign/send/resubmit/finalize) for the sweeper lane.
rs/ethereum/cketh/minter/src/state/transactions/tests.rs	Updates expectations for generalized lane terminology and adds dedicated sweep-lane unit tests.
rs/ethereum/cketh/minter/src/state/transactions/mod.rs	Introduces TransactionLane<R>, adds SweepId/SweepRequest, and centralizes lane-generic mechanics + main-lane-only reimbursement/status logic.
rs/ethereum/cketh/minter/src/state/tests.rs	Updates state fixtures/equivalence tests to include new sweeper-lane state and upgrade arg field.
rs/ethereum/cketh/minter/src/state/event.rs	Adds new EventType variants for sweep request lifecycle and sweeper transaction lifecycle.
rs/ethereum/cketh/minter/src/state/audit/tests.rs	Extends audit replay test mapping for sweeper-lane events.
rs/ethereum/cketh/minter/src/state/audit.rs	Extends state-transition application logic to replay sweeper-lane events into state.
rs/ethereum/cketh/minter/src/state.rs	Adds sweeper_transactions + next_sweep_id to state and supports overriding the sweeper nonce via upgrade args.
rs/ethereum/cketh/minter/src/main.rs	Schedules the sweeper-lane timer task and exposes sweeper-lane events via get_events.
rs/ethereum/cketh/minter/src/lifecycle/upgrade.rs	Adds next_sweeper_transaction_nonce upgrade argument.
rs/ethereum/cketh/minter/src/lifecycle/init.rs	Initializes the sweeper lane at nonce 0 and initializes next_sweep_id.
rs/ethereum/cketh/minter/src/lib.rs	Exposes the new sweep module.
rs/ethereum/cketh/minter/src/endpoints.rs	Extends public event payload variants with sweeper-lane events.
rs/ethereum/cketh/minter/src/deposit_address/mod.rs	Makes sweeper_derivation_path available to the new sweeper-lane signing code.
rs/ethereum/cketh/minter/cketh_minter.did	Updates DID to include new upgrade arg and sweeper-lane event variants.

---

💡 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 18 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (3)

rs/ethereum/cketh/minter/src/state/audit.rs:112

• next_sweep_id is updated unconditionally from the accepted request’s id. If events are ever replayed out-of-order or a malformed event is recorded, this can move next_sweep_id backwards and allow duplicate SweepIds to be minted later. Safer to monotonically advance it (take the max of the current value and request.id + 1).

        EventType::AcceptedSweepRequest(request) => {
            state.next_sweep_id = SweepId(request.id.0.saturating_add(1));
            state
                .sweeper_transactions
                .record_withdrawal_request(request.clone());
        }

rs/ethereum/cketh/minter/src/withdraw.rs:499

• fetch_finalized_receipts is documented to return None when the batch should be retried later, but it currently assert_eq!s that every expected id has a receipt. If the RPC temporarily returns Ok(None) for all hashes of some finalized id (RPC lag / pruning / transient issues), this will trap the canister instead of retrying.

    let actual_finalized_ids: BTreeSet<Id> = receipts.keys().copied().collect();
    assert_eq!(
        expected_finalized_ids, actual_finalized_ids,
        "ERROR: unexpected transaction receipts for some ids"
    );
    Some(receipts)

rs/ethereum/cketh/minter/src/state/transactions/mod.rs:300

• The failure log says the sweep funds “stay at the deposit address”, but sweep transactions are sent from the dedicated sweeper address (so on failure funds remain at the sweeper address). This message is misleading for operators/debugging.

        log!(
            INFO,
            "[record_finalized_transaction]: sweep {} to {} FAILED (tx {}); sweeps are never \
             reimbursed, the funds stay at the deposit address for a later sweep",
            self.id,
            self.destination,
            receipt.transaction_hash,
        );

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (2)

rs/ethereum/cketh/minter/src/state/transactions/mod.rs:482

• The LaneRequest doc comment says the trait also covers reimbursement behavior, but the trait itself doesn’t define any reimbursement-related API; reimbursement is handled elsewhere (e.g., on EthTransactions / WithdrawalRequest). This is misleading now that SweepRequest also implements LaneRequest.

/// A request that can flow through a [`TransactionLane`]: it carries an identity used as the
/// lane's alternate map key, knows the EIP-1559 transaction it turns into, and (for lanes whose
/// failed transactions are paid back) how to reimburse a failure.
///
/// Implemented by [`WithdrawalRequest`] — the minter **main address** lane (`Id = LedgerBurnIndex`)

rs/ethereum/cketh/minter/src/state/transactions/mod.rs:247

• max_transaction_fee is only used by resubmission_strategy; to_transaction doesn’t consult it when setting max_fee_per_gas, so describing it as a general “ceiling on the transaction fee” is inaccurate. Either enforce the cap in to_transaction or adjust the field documentation to match the current behavior.

    /// Ceiling on the transaction fee, used as the resubmission fee cap.

[Copilot]

Pull request overview

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

Suppressed comments (2)

rs/ethereum/cketh/minter/src/state/tests.rs:689

• arb_upgrade_arg always sets next_sweeper_transaction_nonce to None, so proptests that generate EventType::Upgrade never exercise (de)serialization and upgrade handling for the new field.

prop_compose! {
    fn arb_upgrade_arg()(
        contract_address in proptest::option::of(arb_address()),
        ethereum_block_height in proptest::option::of(arb_block_tag()),
        minimum_withdrawal_amount in proptest::option::of(arb_nat()),
        next_transaction_nonce in proptest::option::of(arb_nat()),
        ledger_suite_orchestrator_id in proptest::option::of(arb_principal()),
        erc20_helper_contract_address in proptest::option::of(arb_address()),
        last_erc20_scraped_block_number in proptest::option::of(arb_nat()),
        evm_rpc_id in proptest::option::of(arb_principal()),
        deposit_with_subaccount_helper_contract_address in proptest::option::of(arb_address()),
        last_deposit_with_subaccount_scraped_block_number in proptest::option::of(arb_nat()),
        sweeper_contract_address in proptest::option::of(arb_address()),
    ) -> UpgradeArg {
        UpgradeArg {
            next_sweeper_transaction_nonce: None,
            ethereum_contract_address: contract_address.map(|addr| addr.to_string()),
            ethereum_block_height,
            minimum_withdrawal_amount,
            next_transaction_nonce,
            ledger_suite_orchestrator_id,
            erc20_helper_contract_address: erc20_helper_contract_address.map(|addr| addr.to_string()),
            last_erc20_scraped_block_number,
            evm_rpc_id,
            deposit_with_subaccount_helper_contract_address: deposit_with_subaccount_helper_contract_address.map(|addr| addr.to_string()),
            last_deposit_with_subaccount_scraped_block_number,
            ethereum_sweeper_contract_address: sweeper_contract_address.map(|addr| addr.to_string()),
        }

rs/ethereum/cketh/minter/src/state/transactions/request.rs:225

• SweepRequest::assert_created_transaction validates destination and amount, but not the request calldata. For sweeps the data field can be semantically critical (e.g. ERC-20 sweep calls), so a mismatched CreatedSweeperTransaction event could slip through replay without being detected.

    fn assert_created_transaction(&self, transaction: &Eip1559TransactionRequest) {
        assert_eq!(
            self.destination, transaction.destination,
            "BUG: request and transaction destination mismatch"
        );
        assert_eq!(
            transaction.amount, self.amount,
            "BUG: sweep transaction amount should equal the request amount"
        );
    }

[Copilot]

Pull request overview

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

Suppressed comments (2)

rs/ethereum/cketh/minter/src/state/audit/tests.rs:251

• map_signed_sweep_transaction reconstructs signed sweeper transactions as SweepTransaction::Eip1559(..) unconditionally, so the audit replay test harness cannot represent SignedSweeperTransaction events for EIP-7702 (type 0x04) delegating sweeps. This will break replay once sweeper sending is enabled and such events are emitted.

        fn map_signed_sweep_transaction(raw_transaction: &str) -> SignedSweepTransaction {
            let (transaction, signature) = decode_signed_transaction(raw_transaction);
            SignedSweepTransaction::from((SweepTransaction::Eip1559(transaction), signature))
        }

rs/ethereum/cketh/minter/tests/dump_stable_memory.rs:194

• map_signed_sweep_transaction always reconstructs a SignedSweepTransaction as SweepTransaction::Eip1559(..). That makes this stable-memory dump tool unable to reconstruct SignedSweeperTransaction events for delegating sweeps (type 0x04 / EIP-7702), even though the sweeper lane supports signing EIP-7702 transactions.

fn map_signed_sweep_transaction(raw_transaction: &str) -> SignedSweepTransaction {
    let (transaction, signature) = decode_signed_transaction(raw_transaction);
    SignedSweepTransaction::from((SweepTransaction::Eip1559(transaction), signature))
}

[Copilot]

Pull request overview

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

Suppressed comments (2)

rs/ethereum/cketh/minter/src/state/transactions/request.rs:249

• SweepRequest::create_transaction computes max_fee_per_gas/max_priority_fee_per_gas purely from gas_fee_estimate.to_price(gas_limit) and does not enforce self.max_transaction_fee as a ceiling. Since resubmission_strategy() uses max_transaction_fee as the fee cap, the initial transaction can be created (and potentially sent) with a max fee that already exceeds that cap, making the ceiling ineffective. Consider deriving max_fee_per_gas from self.max_transaction_fee.into_wei_per_gas(gas_limit) (and capping max_priority_fee_per_gas accordingly), or otherwise ensuring the initial fee cannot exceed max_transaction_fee.

        Ok(Eip1559TransactionRequest {
            chain_id: ethereum_network.chain_id(),
            nonce,
            max_priority_fee_per_gas: transaction_price.max_priority_fee_per_gas,
            max_fee_per_gas: transaction_price.max_fee_per_gas,

rs/ethereum/cketh/minter/src/state/tests.rs:679

• arb_upgrade_arg hardcodes next_sweeper_transaction_nonce: None, so the property-based event/replay tests never exercise upgrading the sweeper lane nonce (including its validation and its independence from the main lane). Since this field is now part of UpgradeArg and State::upgrade applies it, it should be generated (e.g. proptest::option::of(arb_nat())) and threaded into the returned UpgradeArg to get coverage for the new behavior.

    ) -> UpgradeArg {
        UpgradeArg {
            next_sweeper_transaction_nonce: None,
            ethereum_contract_address: contract_address.map(|addr| addr.to_string()),
            ethereum_block_height,

[Copilot]

Pull request overview

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

Suppressed comments (1)

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

• In EventType, existing struct-like variants consistently number their fields starting at #[n(0)] (e.g. CreatedTransaction uses its first field at n(0)), but the new sweeper variants start at #[n(1)]/#[n(2)]. minicbor allows sparse tags, but this inconsistency makes the encoding scheme harder to audit/maintain. Consider renumbering these new variants to start at n(0)/n(1) for consistency (and apply the same change to SignedSweeperTransaction, ReplacedSweeperTransaction, and FinalizedSweeperTransaction below).

        #[n(1)]
        sweep_id: SweepId,
        #[n(2)]
        transaction: Eip1559TransactionRequest,
    },

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 30c178a.

Security Overview

• 🔎 Scanned files: 19 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/783a9bd4-fb4e-4e10-ab3c-c2fb2ddfb92f?scanId=6313ab33-2f13-4303-875a-226f8661c963&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/ethereum/cketh/minter/did
Enhancement	► rs/ethereum/cketh/minter/src/dashboard/tests.rs     Add next_sweeper_transaction_nonce initialization
Enhancement	► rs/ethereum/cketh/minter/src/endpoints.rs     Add AcceptedSweepRequest and related sweep events to events enum
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/init.rs     Initialize next_sweeper_transaction_nonce and wire into state
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/tests.rs     Tests for sweeper nonce behavior and independence from main nonce
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/upgrade.rs     UpgradeArg includes next_sweeper_transaction_nonce
Enhancement	► rs/ethereum/cketh/minter/src/main.rs     Handle new sweep-related events in get_events
Enhancement	► rs/ethereum/cketh/minter/src/state.rs     Add sweeper_transactions pipeline and next_sweep_id to State
Enhancement	► rs/ethereum/cketh/minter/src/state/audit.rs     Audit/state transition support for sweep events
Enhancement	► rs/ethereum/cketh/minter/src/state/event.rs     Define SweepId and SweepRequest event types integration
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/mod.rs     Introduce SweepId, SweepRequest, SweeperTransactionPipeline aliases
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/request.rs     Implement PipelineRequest for SweepRequest
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/tests.rs     Sweep lane tests and coverage for sweeper pipeline
Enhancement	► rs/ethereum/cketh/minter/src/test_fixtures.rs     Include next_sweeper_transaction_nonce in test fixtures
Enhancement	► rs/tests/cross_chain/ic_xc_cketh_test.rs     Add next_sweeper_transaction_nonce to minter init args
Enhancement	► rs/ethereum/cketh/minter/tests/dump_stable_memory.rs     Support new sweep-related event payload mappings in test dump