feat(minter): record the origin of a queued deposit

docs/src/development/design.md

@@ -171,7 +171,7 @@ Entries leave the watchlist when a scan queues a deposit, when a `deposit_sol` c
 
 **Detection.** A tick collects the due entries, reads the balances of their deposit addresses with `getMultipleAccounts` at the `finalized` commitment level, up to 100 addresses per call and at most `MAX_CONCURRENT_RPC_CALLS` calls concurrently, so that one tick covers the full watchlist, and treats a missing account as a zero balance. Deposit addresses are plain system accounts without data, so the request asks for no account data and the response is about 150 bytes per address; the cycles attached to a call are sized by the number of addresses it carries, while its response size is left to the default estimate of the SOL RPC canister, as for every other call (see [Section 3.3.2](#332-cksol-minter-fees)). The call uses the typed `getMultipleAccounts` endpoint of the SOL RPC canister, so the automatic flow requires a version of that canister which offers it. A call that fails counts as a scan of its entries, which advance to their next slot as after a balance below the minimum, so that a persistent failure of the SOL RPC canister costs the ckSOL minter no more than the schedule and costs the user the scans lost to the failure.
 
-An address whose balance is at or above the minimum deposit amount in force at that moment is queued exactly as `deposit_sol` queues it: the sweepable amount is the balance minus the rent exemption threshold, the deposit gets the next deposit id, and the `QueuedDeposit` event is recorded, carrying in addition the automatic deposit fee in force at that moment. The recorded fee is the one deducted when the deposit is credited, so a fee change by upgrade after detection does not affect it: a deposit that an upgrade finds queued, swept or finalized is credited afterwards with the fee restored from its `QueuedDeposit`, and a deposit already credited has its mint amount recorded in `CreditedSweep`, as for any sweep; the constraint of [Section 3.3.4](#334-parameter-constraints) is checked against the current parameters at every init and upgrade, so a deposit detected under them always mints a positive amount. The trust model is that of the manual flow: the balance is read at `finalized` with the 3-out-of-4 provider consensus and becomes the planned sweep amount, and a wrong balance cannot cause an over-mint, since ckSOL is minted only after the sweep has been finalized and settled against the finalized transaction. This differs from the ckETH minter, where the scanned balance is only a trigger. An address whose balance is below the minimum, including one that holds only the rent exemption threshold left by a previous sweep, advances to its next scan.
+An address whose balance is at or above the minimum deposit amount in force at that moment is queued exactly as `deposit_sol` queues it: the sweepable amount is the balance minus the rent exemption threshold, the deposit gets the next deposit id, and the `QueuedDeposit` event is recorded, carrying in addition the automatic deposit fee in force at that moment and the origin of the deposit, automatic rather than manual. The origin is recorded on its own rather than inferred from the presence of a fee, so that what depends on the flow, such as the re-arm of a dropped sweep below, stays right should a fee ever be charged for manual deposits. The recorded fee is the one deducted when the deposit is credited, so a fee change by upgrade after detection does not affect it: a deposit that an upgrade finds queued, swept or finalized is credited afterwards with the fee restored from its `QueuedDeposit`, and a deposit already credited has its mint amount recorded in `CreditedSweep`, as for any sweep; the constraint of [Section 3.3.4](#334-parameter-constraints) is checked against the current parameters at every init and upgrade, so a deposit detected under them always mints a positive amount. The trust model is that of the manual flow: the balance is read at `finalized` with the 3-out-of-4 provider consensus and becomes the planned sweep amount, and a wrong balance cannot cause an over-mint, since ckSOL is minted only after the sweep has been finalized and settled against the finalized transaction. This differs from the ckETH minter, where the scanned balance is only a trigger. An address whose balance is below the minimum, including one that holds only the rent exemption threshold left by a previous sweep, advances to its next scan.
 
 **Concurrency.** Scan ticks never overlap: the scan runs under the same single-round guard as the sweep and finalization timers, so a tick that fires while the previous one is still waiting for its calls returns immediately, and the bound of `MAX_CONCURRENT_RPC_CALLS` in-flight calls holds. The scan and `deposit_sol`, however, may read the balance of the same address at the same time, since both span an inter-canister call, and neither path may assert on the other. Before its call, the scan skips the accounts for which a `deposit_sol` call is in progress; after the call, it checks each entry again and skips it silently if it is no longer watched under the same registration, if its window has passed in the meantime, or if the account has a deposit in flight; the window end thus holds even for a read that started just before it, at the price of discarding that one read. Symmetrically, `deposit_sol` records the id of the latest deposit of the account before its `getBalance` call and compares it after: if it changed, a scan queued a deposit in the meantime, so the call returns that id, whatever state the deposit has reached since, and charges only the RPC call. Comparing the id rather than checking whether a deposit is in flight also covers the theoretical case of the scan's deposit being minted or dropped before the callback runs, which would otherwise free the account for a second deposit from a stale balance. An account registered while a tick is running is scanned at the next tick. Since the watchlist is heap state, an upgrade in the middle of a tick loses nothing but that tick: the snapshot taken before the upgrade carries the watchlist, and the scan is redone afterwards.
 
@@ -181,7 +181,7 @@ An address whose balance is at or above the minimum deposit amount in force at t
 
 The event log is not a vector: a registration records nothing, so an adversary cannot grow the log for free, and the only events the automatic flow adds to the ones a detected deposit shares with a manual one (the submission, settlement, mint and possible failure or expiry of its sweep) are the `QueuedDeposit` of the detected deposit, which requires at least the minimum deposit amount on chain, and the watchlist snapshot taken once per upgrade, whose size is bounded by the capacity, see [Section 3.5](#35-events). A full watchlist blocks honest registrations, and the manual flow remains available in that case; since filling it is free, the number of live registrations is exposed as a metric so that an alert can fire before the capacity is reached.
 
-**Compatibility.** The automatic flow is added to a ckSOL minter that is deployed on mainnet, so it only extends the interface and the state: one new endpoint; a new optional `automatic_deposit_fee` field in the init and upgrade arguments and in `get_minter_info`, together with the collected fees; an optional field of the `QueuedDeposit` event carrying the fee of an automatic deposit, absent for manual deposits; a new snapshot event recorded by a new `pre_upgrade` hook; and a new timer. The types of `deposit_sol` and `deposit_sol_status` and the stable memory layout are unchanged, and an event log written before the upgrade replays unchanged.
+**Compatibility.** The automatic flow is added to a ckSOL minter that is deployed on mainnet, so it only extends the interface and the state: one new endpoint; a new optional `automatic_deposit_fee` field in the init and upgrade arguments and in `get_minter_info`, together with the collected fees; two fields of the `QueuedDeposit` event, an optional one carrying the fee of the deposit, absent if none is charged, and one carrying its origin, which events recorded before the automatic flow lack and which then reads as manual, since all of them were queued by `deposit_sol`; a new snapshot event recorded by a new `pre_upgrade` hook; and a new timer. The types of `deposit_sol` and `deposit_sol_status` and the stable memory layout are unchanged, and an event log written before the upgrade replays unchanged.
 
 #### 3.1.2. Manual Flow
 

integration_tests/tests/snapshot.rs

@@ -3,7 +3,7 @@ use cksol_int_tests::CkSolMinter;
 use cksol_types::MinterInfo;
 use cksol_types_internal::{
     UpgradeArgs,
-    event::{Event, EventType},
+    event::{DepositOrigin, Event, EventType},
 };
 use pocket_ic::PocketIcBuilder;
 
@@ -44,11 +44,25 @@ async fn should_load_staging_snapshot_and_upgrade_to_current_wasm() {
         }
     );
     let (replayed_events, new_events) = state_after.events.split_at(state_before.events.len());
-    assert_eq!(replayed_events, state_before.events);
+    let expected_events: Vec<_> = state_before
+        .events
+        .into_iter()
+        .map(with_recorded_origin)
+        .collect();
+    assert_eq!(replayed_events, expected_events);
     assert_matches!(
         new_events,
         [Event { payload: EventType::Upgrade(args), .. }] if *args == upgrade_args
     );
 
     env.drop().await;
 }
+
+/// The event as reported by the current wasm: a `QueuedDeposit` recorded without an origin
+/// predates the automatic flow, so it reports the deposit as queued by `deposit_sol`.
+fn with_recorded_origin(mut event: Event) -> Event {
+    if let EventType::QueuedDeposit { origin, .. } = &mut event.payload {
+        origin.get_or_insert(DepositOrigin::Manual);
+    }
+    event
+}

integration_tests/tests/tests.rs

@@ -16,7 +16,7 @@ use cksol_types::{
 };
 use cksol_types_internal::{
     UpgradeArgs,
-    event::{EventType, TransactionPurpose},
+    event::{DepositOrigin, EventType, TransactionPurpose},
     log::Priority,
 };
 use icrc_ledger_types::icrc1::account::{Account, Subaccount};
@@ -870,6 +870,7 @@ mod deposit_sol_tests {
                         address: deposit_address.clone(),
                         balance: BALANCE_ABOVE_MINIMUM,
                         deposit_fee: None,
+                        origin: Some(DepositOrigin::Manual),
                     }]
             );
         });
@@ -951,6 +952,7 @@ mod deposit_sol_tests {
                         address: deposit_address.clone(),
                         balance: BALANCE_ABOVE_MINIMUM,
                         deposit_fee: None,
+                        origin: Some(DepositOrigin::Manual),
                     }]
             );
         });
@@ -1325,6 +1327,7 @@ mod automatic_deposit_sol_tests {
                         address: DEFAULT_CALLER_DEPOSIT_ADDRESS.parse().unwrap(),
                         balance: BALANCE_ABOVE_MINIMUM,
                         deposit_fee: Some(Setup::DEFAULT_AUTOMATIC_DEPOSIT_FEE),
+                        origin: Some(DepositOrigin::Automatic),
                     }]
             );
         });

libs/types-internal/src/event.rs

@@ -76,9 +76,11 @@ pub enum EventType {
         address: Address,
         /// The balance of the deposit address when the deposit was queued.
         balance: Lamport,
-        /// The fee in lamports deducted from the minted amount; absent for a deposit queued via
-        /// `deposit_sol`.
+        /// The fee in lamports deducted from the minted amount; absent if none is charged.
         deposit_fee: Option<Lamport>,
+        /// The flow that queued the deposit; absent in events recorded before the automatic
+        /// flow, whose deposits were all queued via `deposit_sol`.
+        origin: Option<DepositOrigin>,
     },
     /// The minter read the amount that the finalized sweep transaction moved to its
     /// main account and enqueued a pending mint for each deposit of that sweep.
@@ -155,6 +157,15 @@ pub struct CreditedDeposit {
     pub amount_to_mint: Lamport,
 }
 
+/// The flow that queued a deposit.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, CandidType, Deserialize)]
+pub enum DepositOrigin {
+    /// Queued by a user via `deposit_sol`.
+    Manual,
+    /// Queued by a balance scan of the automatic flow.
+    Automatic,
+}
+
 /// The key that produced one signature of a submitted Solana transaction.
 #[derive(Clone, Debug, PartialEq, CandidType, Deserialize)]
 pub enum Signer {

minter/cksol_minter.did

@@ -418,6 +418,17 @@ type VersionedTransactionMessage = variant {
     Legacy : blob;
 };
 
+// The flow that queued a deposit.
+//
+// *WARNING*: This type is used exclusively by the debug `get_events` endpoint.
+// Backwards-compatibility is not guaranteed.
+type DepositOrigin = variant {
+    // Queued by a user via `deposit_sol`.
+    Manual;
+    // Queued by a balance scan of the automatic flow.
+    Automatic;
+};
+
 // The key that produced one signature of a submitted Solana transaction.
 //
 // *WARNING*: This type is used exclusively by the debug `get_events` endpoint.
@@ -508,9 +519,12 @@ type EventType = variant {
         address: Address;
         // The balance of the deposit address when the deposit was queued.
         balance: Lamport;
-        // The fee in lamports deducted from the minted amount; absent for a deposit
-        // queued via `deposit_sol`.
+        // The fee in lamports deducted from the minted amount; absent if none is
+        // charged.
         deposit_fee: opt Lamport;
+        // The flow that queued the deposit; absent in events recorded before the
+        // automatic flow, whose deposits were all queued via `deposit_sol`.
+        origin: opt DepositOrigin;
     };
     // The minter read the amount that the finalized sweep transaction moved to
     // its main account and enqueued a pending mint for each deposit of that sweep.

minter/src/canbench.rs

@@ -7,7 +7,7 @@ use crate::{
     runtime::IcCanisterRuntime,
     sol_transfer::build_batch_withdrawal_message,
     state::{
-        DepositBalance, QueuedDeposit, SchnorrPublicKey, Sweep,
+        DepositBalance, DepositOrigin, QueuedDeposit, SchnorrPublicKey, Sweep,
         audit::{process_event, replay_events},
         event::{
             CreditedDeposit, EventType, Signer, TransactionPurpose, VersionedMessage,
@@ -109,6 +109,7 @@ fn queue_and_sweep(deposit_id: u64, account_index: usize, amount: u64, sig: Sign
         address: deposit_address(account_index),
         balance: DepositBalance::new(amount + RENT_EXEMPTION_THRESHOLD)
             .expect("BUG: the balance covers the rent exemption threshold"),
+        origin: DepositOrigin::Manual,
         deposit_fee: None,
     };
     record(EventType::QueuedDeposit {
@@ -117,6 +118,7 @@ fn queue_and_sweep(deposit_id: u64, account_index: usize, amount: u64, sig: Sign
         address: deposit.address,
         balance: deposit.balance,
         deposit_fee: None,
+        origin: DepositOrigin::Manual,
     });
     let sweep = Sweep::plan([(deposit_id, deposit)], minter_address(&master_key()));
     record(EventType::SubmittedTransaction {

minter/src/deposit/automatic/scan/mod.rs

@@ -5,8 +5,8 @@ use crate::{
     rpc::{GetMultipleAccountsError, get_balances},
     runtime::CanisterRuntime,
     state::{
-        DepositBalance, MAX_WATCHED_ADDRESSES, QueuedDeposit, State, TaskType, WatchedAddress,
-        mutate_state, read_state,
+        DepositBalance, DepositOrigin, MAX_WATCHED_ADDRESSES, QueuedDeposit, State, TaskType,
+        WatchedAddress, mutate_state, read_state,
     },
     storage::{ScanOutcome, record_deposit_address_scans},
     utils::timed_sized_map::Timestamp,
@@ -153,6 +153,7 @@ fn apply_balance_read<R: CanisterRuntime>(
                 account: watched.account,
                 address: watched.address,
                 balance,
+                origin: DepositOrigin::Automatic,
                 deposit_fee: Some(automatic_deposit_fee),
             },
         );

minter/src/deposit/automatic/scan/tests.rs

@@ -6,7 +6,7 @@ use crate::{
         Scan, apply_balance_read, record_failed_read, scan_watched_addresses,
     },
     guard::deposit_sol_guard,
-    state::{TaskType, WatchedAddress, event::EventType, mutate_state, read_state},
+    state::{DepositOrigin, TaskType, WatchedAddress, event::EventType, mutate_state, read_state},
     storage::{ScanOutcome, deposit_address_scan_count},
     test_fixtures::{
         AUTOMATIC_DEPOSIT_FEE, EventsAssert, MINIMUM_DEPOSIT_AMOUNT, MINUTE_NANOS, REGISTERED_AT,
@@ -85,6 +85,7 @@ async fn should_queue_a_deposit_reaching_the_minimum_with_the_fee_in_force() {
             address: expected.address,
             balance: expected.balance,
             deposit_fee: Some(AUTOMATIC_DEPOSIT_FEE),
+            origin: DepositOrigin::Automatic,
         })
         .assert_no_more_events();
     read_state(|s| {

minter/src/deposit/sweep/mod.rs

@@ -6,7 +6,7 @@ use crate::{
     rpc::get_balance,
     runtime::CanisterRuntime,
     state::{
-        DepositBalance, InFlightDeposit, QueuedDeposit, State, audit::process_event,
+        DepositBalance, DepositOrigin, InFlightDeposit, QueuedDeposit, State, audit::process_event,
         event::EventType, mutate_state, read_state,
     },
     utils::assert_valid_deposit_owner,
@@ -90,6 +90,7 @@ pub async fn deposit_sol<R: CanisterRuntime>(
                 account,
                 address: deposit_address,
                 balance,
+                origin: DepositOrigin::Manual,
                 deposit_fee: None,
             },
         )
@@ -119,6 +120,7 @@ pub(crate) fn queue_deposit<R: CanisterRuntime>(
             address: deposit.address,
             balance: deposit.balance,
             deposit_fee: deposit.deposit_fee,
+            origin: deposit.origin,
         },
         runtime,
     );

minter/src/deposit/sweep/tests.rs

@@ -2,7 +2,7 @@ use crate::{
     constants::{GET_BALANCE_CYCLES, RENT_EXEMPTION_THRESHOLD},
     deposit::sweep::{deposit_sol, deposit_status},
     guard::deposit_sol_guard,
-    state::{event::EventType, read_state},
+    state::{DepositOrigin, event::EventType, read_state},
     storage::with_event_iter,
     test_fixtures::{
         AUTOMATIC_DEPOSIT_FEE, DEPOSIT_SOL_FEE, DEPOSIT_SOL_REQUIRED_CYCLES, EventsAssert,
@@ -247,6 +247,7 @@ async fn assert_yields_to_the_deposit_queued_by_a_scan_during_the_read(
             address: scanned.address,
             balance: queued_deposit_of(DEPOSITOR_ACCOUNT, scanned.sweepable_amount).balance,
             deposit_fee: Some(AUTOMATIC_DEPOSIT_FEE),
+            origin: DepositOrigin::Automatic,
         })
         .assert_no_more_events();
     assert_eq!(
@@ -345,6 +346,7 @@ fn queued_deposit_event(deposit_id: u64, account: Account, sweepable_amount: Lam
         address: deposit.address,
         balance: deposit.balance,
         deposit_fee: None,
+        origin: DepositOrigin::Manual,
     }
 }
 

minter/src/state/audit.rs

@@ -100,13 +100,15 @@ fn apply_state_transition(state: &mut State, payload: &EventType, timestamp: u64
             address,
             balance,
             deposit_fee,
+            origin,
         } => {
             state.process_queued_deposit(
                 *deposit_id,
                 QueuedDeposit {
                     account: *account,
                     address: *address,
                     balance: *balance,
+                    origin: *origin,
                     deposit_fee: *deposit_fee,
                 },
                 timestamp,