feat(minter): automatic deposit flow

Cargo.toml

@@ -76,6 +76,7 @@ solana-transaction-status-client-types = "3.1.8"
 tar = "0.4.44"
 tempfile = "3.26.0"
 thiserror = "2.0.18"
+time = "0.3.47"
 tokio = "1.49.0"
 
 [profile.release]

docs/src/development/deployment.md

@@ -138,6 +138,22 @@ The fees and minimum amounts follow [Section 3.3 of the design](design.md#33-fee
 | `nonce_accounts`              | empty                 | Replace with the addresses created in [Create nonce accounts](#create-nonce-accounts).          |
 | `automatic_deposit_fee`       | unset                 | Keeps the automatic flow disabled; to be set to 0.002 SOL (2,000,000) once it is complete.      |
 
+### Enable the automatic deposit flow
+
+Enable the automatic deposit flow on a running minter in two upgrades. The first installs the version with the flow and leaves `automatic_deposit_fee` unset, so the flow stays disabled: `watch_deposit_address` returns `TemporarilyUnavailable` and the scan timer reads no balance. No automatic deposit is queued and no watchlist snapshot is recorded, so this upgrade can still be rolled back to the previous version. Once the minter runs as expected, a second upgrade sets the fee and enables the flow:
+
+```candid
+(
+  variant {
+    Upgrade = record {
+      automatic_deposit_fee = opt (2_000_000 : nat64);
+    }
+  },
+)
+```
+
+From then on, a faulty version has to be fixed forward instead of rolled back, as described in [Section 3.5 of the design](design.md#35-events).
+
 ## Ledger
 
 Initialization arguments:

docs/src/development/design.md

@@ -157,7 +157,7 @@ stateDiagram-v2
     Quarantined: Quarantined, until a minter upgrade resolves the deposit
 ```
 
-The status is `Watching`, with the end of the window, the number of scans so far, the time of the last scan and the time the next scan is *due*, which is not a promise of when it runs: a scan lands on the next tick at or after that time, so the time lies in the past until then, and a client reads a next scan time in the past as a scan still pending, as long as the account is on the watchlist, and `Detected`, with the *deposit id* that identifies a sweep of the account for its whole life, as defined in [Section 3.1.2](#312-manual-flow), once a deposit is in flight for the account. As in the ckETH minter, there is no separate status endpoint: calling `watch_deposit_address` again is how a client follows a registration. Registering an account that is already watched is idempotent and returns the stored registration without extending its window; an account with a deposit in flight is not registered, since the sweep flow already owns its address, and the call returns `Detected`; and an account whose latest deposit is minted or dropped is registered anew, so that the next deposit to the same address needs nothing but another call. The id of the latest deposit is returned in every case, so that a client coming back hours after a detection can follow the deposit with `deposit_sol_status`. An account whose automatically detected deposit was dropped is reported as `Watching` again when the re-arm described below has put it back on the watchlist.
+The status is `Watching`, with the end of the window, the number of scans so far, the time of the last scan and the time the next scan is *due*, which is not a promise of when it runs: a scan lands on the next tick at or after that time, so the time lies in the past until then, and a client reads a next scan time in the past as a scan still pending, as long as the account is on the watchlist, and `Detected`, with the *deposit id* that identifies a sweep of the account for its whole life, as defined in [Section 3.1.2](#312-manual-flow), once a deposit is in flight for the account. As in the ckETH minter, there is no separate status endpoint: calling `watch_deposit_address` again is how a client follows a registration. Registering an account that is already watched is idempotent and returns the stored registration without extending its window; an account with a deposit in flight is not registered, since the sweep flow already owns its address, and the call returns `Detected`; and an account whose latest deposit is minted or dropped is registered anew, so that the next deposit to the same address needs nothing but another call. The id of the latest deposit of the account, if any, is returned in every reply except `TemporarilyUnavailable`, so that a client coming back hours after a detection can follow the deposit with `deposit_sol_status`. An account whose automatically detected deposit was dropped is reported as `Watching` again when the re-arm described below has put it back on the watchlist.
 
 The call does not contact the SOL RPC canister and requires no cycles. It is rejected when the latest deposit of the account is quarantined (`Quarantined`, as for `deposit_sol`), when the call would create a new registration while the watchlist is full of live entries (`TooManyWatchedAddresses`, with the id of the latest deposit of the account, if any; an account already watched or with a deposit in flight needs no slot and gets its status), and with `TemporarilyUnavailable` when the minter's public key is not yet known or when the automatic deposit fee has not been configured. A `deposit_sol` call in progress for the same account does not prevent the registration: if that call queues a deposit, the registration is removed again, and otherwise it stays, which is what the caller wanted in either case. A registration is not recorded in the event log, see [Section 3.5](#35-events).
 
@@ -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; 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.
+**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, which `get_minter_info` always reports, zero until a sweep collects some; 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
 
@@ -655,7 +655,7 @@ The ckSOL minter exposes the following endpoints:
 4. `watch_deposit_address(opt subaccount)`: Registers the deposit address of the caller's account for the automatic flow of [Section 3.1.1](#311-automatic-flow), for free, or reports on an existing registration. Returns the deposit address, the current minimum deposit amount and automatic deposit fee as quotes, the status of the account (`Watching` with the end of the window, the number of scans, the time of the last scan and the time the next scan is due, which may lie in the past until the tick that runs it, or `Detected` with the id of the deposit in flight) and the id of the latest deposit queued for the account, if any. Otherwise, an error is returned: `Quarantined` with the id of the quarantined deposit, `TooManyWatchedAddresses` with the id of the latest deposit queued for the account, if any, or `TemporarilyUnavailable`. The owner is always the caller.
 5. `withdraw_sol(opt subaccount, amount, address)`: Burns the given amount of ckSOL from the user's account and transfers the same amount minus a fee in SOL to the given user address. Returns the block index of the burn operation on the ckSOL ledger in case of success. Otherwise, an error is returned.
 6. `withdraw_sol_status(block_index)`: Returns the withdrawal status (`NotFound`, `Pending`, `TxSent`, `TxFinalized`) for the withdrawal identified by the given block index.
-7. `get_minter_info`: Returns information about the ckSOL minter, specifically the various fees, including the automatic deposit fee once configured, the minimum deposit and withdrawal amounts, the current balance of the ckSOL minter, the automatic deposit fees it has collected, its main address, and the addresses of its durable nonce accounts.
+7. `get_minter_info`: Returns information about the ckSOL minter, specifically the various fees, including the automatic deposit fee once configured, the minimum deposit and withdrawal amounts, the current balance of the ckSOL minter, the automatic deposit fees it has collected (always reported, zero until a sweep collects some), its main address, and the addresses of its durable nonce accounts.
 8. `get_events(start, length)`: Returns a page of the event log, at most 2000 events per call. This is a debug endpoint; backwards compatibility is not guaranteed for it.
 
 The authoritative interface is the Candid file [`minter/cksol_minter.did`](https://github.com/dfinity/cksol/blob/main/minter/cksol_minter.did).

docs/src/usage/cli.md

@@ -41,9 +41,27 @@ A successful response returns the deposit id, which you can use to track the dep
 (variant { Ok = 42 : nat64 })
 ```
 
+## Register your deposit address for automatic deposits
+
+Instead of calling `deposit_sol` after each transfer, call `watch_deposit_address` to have the minter watch your deposit address for about 24 hours and queue the deposit itself once the balance reaches the minimum deposit amount. The call is free and needs no cycles, so no proxy canister is required; the automatic deposit fee reported by `get_minter_info` (`automatic_deposit_fee` field) is deducted from the minted amount instead. The owner is always your calling identity, so pass only the `subaccount` used when calling `get_deposit_address`:
+
+```sh
+icp canister call -e prod cksol_minter watch_deposit_address '(record { subaccount = null })'
+```
+
+A successful response returns the deposit address, the minimum deposit amount, the automatic deposit fee, the status of the registration and the id of the latest deposit of your account, if any:
+
+```
+(variant { Ok = record { status = variant { Watching = record { valid_until = ...; scan_count = 0; last_scanned_at = null; next_scan_at = opt ... } }; ... } })
+```
+
+Call `watch_deposit_address` again to follow the registration: the status becomes `Detected` with the deposit id once the minter has queued the deposit, which you can then track with `deposit_sol_status`. Calling it again after the deposit is minted registers the address anew.
+
+The last scan runs about half an hour before the window ends (`valid_until`), so a transfer finalized after it is only detected once you register again, which is free and possible as soon as the window has closed.
+
 ## Check a deposit status
 
-After calling `deposit_sol`, track the deposit using the deposit id returned in the response. The status moves through `Queued` → `Swept` → `Finalized` → `Minted` as the minter sweeps the deposit address and mints ckSOL:
+After calling `deposit_sol`, or once `watch_deposit_address` reports a deposit as `Detected`, track the deposit using its deposit id. The status moves through `Queued` → `Swept` → `Finalized` → `Minted` as the minter sweeps the deposit address and mints ckSOL:
 
 ```sh
 icp canister call -e prod cksol_minter deposit_sol_status '(42 : nat64)' --query

docs/src/usage/how-it-works.md

@@ -42,6 +42,18 @@ sequenceDiagram
     Minter-->>User: Minted { block_index, minted_amount }
 ```
 
+### Automatic deposits
+
+If you cannot call the minter after the transfer, for example because the SOL comes straight from an exchange, register your deposit address with `watch_deposit_address` instead of calling `deposit_sol`:
+
+1. **Register the deposit address.** Call `watch_deposit_address` on the minter with the same optional subaccount as in step 1; the owner is always your principal. The call is free, requires no cycles and returns the deposit address, the current minimum deposit amount and automatic deposit fee, and the status of the registration, which is `Watching` for about 24 hours with the time of the next scan.
+
+2. **Send SOL.** Transfer SOL to the deposit address within that window, as in step 2. The last scan runs about half an hour before the window ends, so a transfer finalized after it is only detected once you register again, which you can do for free as soon as the window has closed.
+
+3. **Let the minter detect the deposit.** The minter reads the balance of every registered deposit address on a schedule, frequently right after the registration and then hourly. Once the balance reaches the minimum deposit amount, the minter queues the deposit as if `deposit_sol` had been called, and the sweep and mint of step 4 follow; the automatic deposit fee in force at detection is deducted from the minted amount instead of cycles.
+
+4. **Track the deposit.** Call `watch_deposit_address` again: once the deposit is detected, the status is `Detected` with the deposit id, which you can follow with `deposit_sol_status` as in step 5. The id of the latest deposit of your account, if any, is returned in every reply except `TemporarilyUnavailable`. Once the deposit is minted, calling `watch_deposit_address` registers the address anew, so that the next deposit to the same address only needs another call. If the sweep fails or expires instead, `deposit_sol_status` reports `Dropped` and the minter puts the address back on the watchlist for a fresh window, if it has room, so that the funds are detected again under a new deposit id, which `watch_deposit_address` reports as above, without calling `deposit_sol`.
+
 ## Withdrawal: ckSOL → SOL
 
 1. **Approve the minter.** Grant the minter an [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) allowance on your ckSOL ledger account.

integration_tests/src/lib.rs

@@ -4,8 +4,8 @@ use canlog::{Log, LogEntry};
 use cksol_types::{
     Address, DepositSolArgs, DepositSolError, DepositSolId, DepositSolStatus,
     GetDepositAddressArgs, MinterInfo, WatchDepositAddressArgs, WatchDepositAddressError,
-    WatchDepositAddressOk, WithdrawSolArgs, WithdrawSolError, WithdrawSolOk, WithdrawSolStatus,
-    WithdrawSolStatusArgs,
+    WatchDepositAddressOk, WatchDepositAddressStatus, WithdrawSolArgs, WithdrawSolError,
+    WithdrawSolOk, WithdrawSolStatus, WithdrawSolStatusArgs,
 };
 use cksol_types_internal::{
     MinterArg,
@@ -603,6 +603,32 @@ impl<'a> CkSolMinter<'a> {
         .await
     }
 
+    /// Polls `watch_deposit_address` on a live instance until the scan tick the caller fired
+    /// has detected a deposit on the address of the caller's account and returns the id of
+    /// that deposit. The poll never advances time, since that would also fire the sweep
+    /// timer on whatever is queued by then.
+    ///
+    /// # Panics
+    ///
+    /// Panics if no deposit is detected within the timeout.
+    pub async fn wait_for_deposit_detected(&self, subaccount: Option<Subaccount>) -> DepositSolId {
+        const MAX_POLLS: usize = 45;
+        const POLL_INTERVAL: Duration = Duration::from_secs(1);
+        for _ in 0..MAX_POLLS {
+            let registration = self
+                .watch_deposit_address(subaccount)
+                .await
+                .expect("watch_deposit_address should succeed");
+            if let WatchDepositAddressStatus::Detected { deposit_id } = registration.status {
+                return deposit_id;
+            }
+            tokio::time::sleep(POLL_INTERVAL).await;
+        }
+        panic!(
+            "No deposit was detected on the deposit address of subaccount {subaccount:?} within timeout"
+        );
+    }
+
     pub async fn withdraw_sol(
         &self,
         args: WithdrawSolArgs,