From 246a4d248f8ad0c7347e78d7ff805a5430831b7b Mon Sep 17 00:00:00 2001 From: Louis Pahlavi Date: Fri, 24 Apr 2026 10:51:43 +0200 Subject: [PATCH 1/3] docs: add automatic deposit flow stub to README Adds a WIP stub for the automatic deposit flow, including a how-it-works section with a sequence diagram and a CLI snippet. Both are annotated with a warning that the feature is not yet available on mainnet. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5e37b8f6..f1944f03 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ Each ckSOL is backed by exactly 1 SOL held by the ckSOL minter canister. ckSOL c ## Table of Contents - [How It Works](#how-it-works) - - [Deposit: SOL → ckSOL](#deposit-sol--cksol) + - [Deposit: SOL → ckSOL (Manual)](#deposit-sol--cksol-manual) + - [Deposit: SOL → ckSOL (Automatic)](#deposit-sol--cksol-automatic) - [Withdrawal: ckSOL → SOL](#withdrawal-cksol--sol) - [Architecture](#architecture) - [Deployment](#deployment) @@ -41,7 +42,7 @@ The ckSOL token itself is implemented as an [ICRC-1/ICRC-2](https://github.com/d The minter controls one or more Solana addresses derived from a [threshold Schnorr over Ed25519](https://internetcomputer.org/docs/references/ic-interface-spec#ic-sign-with-schnorr) public key and a per-account derivation path. No private key ever exists in plaintext — Solana transactions are signed via the IC management canister's `sign_with_schnorr` API (`SchnorrAlgorithm::Ed25519`). -### Deposit: SOL → ckSOL +### Deposit: SOL → ckSOL (Manual) 1. **Get a deposit address.** Call `get_deposit_address` on the minter with your ICP principal (and an optional subaccount). The minter returns a Solana address derived specifically for your account. @@ -74,6 +75,42 @@ sequenceDiagram Minter-->>User: Minted { block_index, minted_amount } ``` +### Deposit: SOL → ckSOL (Automatic) + +> [!WARNING] +> The automatic deposit flow is a work in progress and not yet available on mainnet. + +The automatic deposit flow removes the need to call `process_deposit` manually. Instead, you register your account once and the minter monitors your deposit address and mints ckSOL automatically when SOL arrives. + +1. **Get a deposit address.** Call `get_deposit_address` as in the manual flow to obtain your personal Solana deposit address. + +2. **Register for monitoring.** Call `update_balance` on the minter with an optional subaccount. This registers your account (caller + subaccount) for automated deposit monitoring. + +3. **Send SOL.** Transfer SOL to your deposit address from any Solana wallet. + +4. **Automatic minting.** The minter periodically polls for new transactions on all monitored deposit addresses. When a valid deposit is found, it verifies the transaction and mints the corresponding ckSOL (minus the automated deposit fee) to your ICRC-1 account — no further action required on your part. + +```mermaid +sequenceDiagram + actor User + participant Minter as ckSOL Minter + participant Ledger as ckSOL Ledger + participant Solana + + User->>Minter: get_deposit_address(subaccount) + Minter-->>User: deposit_address + + User->>Minter: update_balance(subaccount) + Note over Minter: account registered for monitoring + + User->>Solana: transfer SOL to deposit_address + + Note over Minter,Solana: (minter polls automatically) + Minter->>Solana: poll for new transactions + Minter->>Ledger: mint with icrc1_transfer(to=user, amount - automated_deposit_fee) + Ledger-->>Minter: block_index +``` + ### 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. @@ -169,6 +206,18 @@ icp canister call -e prod cksol_minter get_deposit_address \ '(record { owner = null; subaccount = null })' --query ``` +### Register for automatic deposit monitoring + +> [!WARNING] +> The automatic deposit flow is a work in progress and not yet available on mainnet. + +Register your account (the calling principal and an optional subaccount) so the minter automatically monitors your deposit address and mints ckSOL when SOL arrives: + +```sh +icp canister call -e prod cksol_minter update_balance \ + '(record { subaccount = null })' +``` + ### Notify the minter of a deposit After sending SOL to your deposit address, call `process_deposit` with the Solana transaction signature to trigger minting. Pass the same `owner`/`subaccount` used when calling `get_deposit_address` — when `owner` is `null`, it defaults to your calling identity's principal. Replace `` with the base-58 encoded transaction signature. From b0a2e1ffd545840f9465732a8613c1f0ce2a48b2 Mon Sep 17 00:00:00 2001 From: Louis Pahlavi Date: Fri, 24 Apr 2026 10:55:12 +0200 Subject: [PATCH 2/3] docs: update repository structure to reflect actual minter src layout Expand the minter/src tree to show all modules, split deposit/ into manual/ and automatic/ (WIP), and add guard/, ledger/, rpc/, signer/, and sol_transfer/ which were missing from the previous listing. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f1944f03..d8837e8a 100644 --- a/README.md +++ b/README.md @@ -270,13 +270,19 @@ icp canister call -e prod cksol_minter withdrawal_status \ │ │ ├── address/ # Deposit address derivation │ │ ├── consolidate/ # Deposit consolidation logic │ │ ├── dashboard/ # HTTP dashboard -│ │ ├── lifecycle.rs # Canister init/upgrade and event log -│ │ ├── metrics.rs # Prometheus metrics +│ │ ├── deposit/ +│ │ │ ├── manual/ # Manual deposit processing +│ │ │ └── automatic/ # Automatic deposit processing (WIP) +│ │ ├── guard/ # Concurrency guards +│ │ ├── ledger/ # ckSOL ledger client │ │ ├── monitor/ # Transaction monitoring +│ │ ├── rpc/ # Solana RPC client +│ │ ├── signer/ # Threshold Schnorr signing +│ │ ├── sol_transfer/ # Solana transaction construction │ │ ├── state/ # Minter state and event sourcing -│ │ ├── deposit/manual/ # Manual deposit processing │ │ ├── withdraw/ # Withdrawal processing -│ │ └── ... +│ │ ├── lifecycle.rs # Canister init/upgrade +│ │ └── metrics.rs # Prometheus metrics │ └── cksol_minter.did # Candid interface ├── libs/ │ ├── types/ # Public ckSOL types (cksol-types crate) From 31c14ba127c33021979cc531ad2117279dde643a Mon Sep 17 00:00:00 2001 From: Louis Pahlavi Date: Fri, 24 Apr 2026 10:56:25 +0200 Subject: [PATCH 3/3] docs: revert repo structure to original style, only expand deposit/ Keep the existing abbreviated listing with ... intact. Only replace the flat deposit/manual/ entry with a proper deposit/ subtree showing manual/ and automatic/ (WIP). Co-Authored-By: Claude Sonnet 4.6 --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d8837e8a..c0fdb040 100644 --- a/README.md +++ b/README.md @@ -273,16 +273,12 @@ icp canister call -e prod cksol_minter withdrawal_status \ │ │ ├── deposit/ │ │ │ ├── manual/ # Manual deposit processing │ │ │ └── automatic/ # Automatic deposit processing (WIP) -│ │ ├── guard/ # Concurrency guards -│ │ ├── ledger/ # ckSOL ledger client +│ │ ├── lifecycle.rs # Canister init/upgrade and event log +│ │ ├── metrics.rs # Prometheus metrics │ │ ├── monitor/ # Transaction monitoring -│ │ ├── rpc/ # Solana RPC client -│ │ ├── signer/ # Threshold Schnorr signing -│ │ ├── sol_transfer/ # Solana transaction construction │ │ ├── state/ # Minter state and event sourcing │ │ ├── withdraw/ # Withdrawal processing -│ │ ├── lifecycle.rs # Canister init/upgrade -│ │ └── metrics.rs # Prometheus metrics +│ │ └── ... │ └── cksol_minter.did # Candid interface ├── libs/ │ ├── types/ # Public ckSOL types (cksol-types crate)