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.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 2d3a6be.

Security Overview

• 🔎 Scanned files: 19 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/783a9bd4-fb4e-4e10-ab3c-c2fb2ddfb92f?scanId=20a7c97a-defe-4b30-b803-2486aa558ea9&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/ethereum/cketh/minter/did b/rs/ethereum/cketh/minter/cketh_minter.did     Add next_sweeper_transaction_nonce field in InitArg and UpgradeArg; add AcceptedSweepRequest, CreatedSweeperTransaction, SignedSweeperTransaction, ReplacedSweeperTransaction, FinalizedSweeperTransaction events
Enhancement	► rs/ethereum/cketh/minter/src/dashboard/tests.rs     Initialize next_sweeper_transaction_nonce to None in init
Enhancement	► rs/ethereum/cketh/minter/src/endpoints.rs     Extend events with AcceptedSweepRequest, CreatedSweeperTransaction, SignedSweeperTransaction, ReplacedSweeperTransaction, FinalizedSweeperTransaction
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/init.rs     Parse and initialize next_sweeper_transaction_nonce; create sweeper_transactions pipeline; add next_sweep_id initialization
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/tests.rs     Tests for sweeper nonce initialization and independence from main nonce
Enhancement	► rs/ethereum/cketh/minter/src/lifecycle/upgrade.rs     Add next_sweeper_transaction_nonce to UpgradeArg with CBOR option
Enhancement	► rs/ethereum/cketh/minter/src/main.rs     Handle new sweeper-related events in get_events
Enhancement	► rs/ethereum/cketh/minter/src/state.rs     Add sweeper_transactions field and next_sweep_id; include next_sweeper_transaction_nonce in upgrade/state transitions
Enhancement	► rs/ethereum/cketh/minter/src/state/audit.rs     Handle new sweeper-related EventType transitions (AcceptedSweepRequest, CreatedSweeperTransaction, SignedSweeperTransaction, ReplacedSweeperTransaction, FinalizedSweeperTransaction)
Enhancement	► rs/ethereum/cketh/minter/src/state/audit/tests.rs     Update tests to include sweeper-related events and types
Enhancement	► rs/ethereum/cketh/minter/src/state/event.rs     Add SweepId and SweepRequest to EventType imports
Enhancement	► rs/ethereum/cketh/minter/src/state/tests.rs     Update test fixtures to include next_sweeper_transaction_nonce and sweeper-related state
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/mod.rs     Introduce SweepId and SweepRequest; define SweeperTransactionPipeline; add SweepRequest handling in PipelineRequest; add CreateSweepTransactionError
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/request.rs     Implement PipelineRequest for SweepRequest; add validation and creation logic for sweeper transactions
Enhancement	► rs/ethereum/cketh/minter/src/state/transactions/tests.rs     Add sweep_lane tests for sweep transaction lifecycle and error conditions
Enhancement	► rs/ethereum/cketh/minter/dump/test fixtures and mappings updates in tests dumps

[mbjorkqvist]

Thanks @gregorydemay!