feat(wallet): add offline ecash receiving with DLEQ verification (NUT-12)

Author: GEET3001

crates/cashu/src/nuts/nut07.rs

@@ -37,6 +37,8 @@ pub enum State {
     Reserved,
     /// Pending spent (i.e., spent but not yet swapped by receiver)
     PendingSpent,
+    /// Pending receive (i.e. offline received but not yet swapped)
+    PendingReceive,
 }
 
 impl fmt::Display for State {
@@ -47,6 +49,7 @@ impl fmt::Display for State {
             Self::Pending => "PENDING",
             Self::Reserved => "RESERVED",
             Self::PendingSpent => "PENDING_SPENT",
+            Self::PendingReceive => "PENDING_RECEIVE",
         };
 
         write!(f, "{s}")
@@ -63,6 +66,7 @@ impl FromStr for State {
             "PENDING" => Ok(Self::Pending),
             "RESERVED" => Ok(Self::Reserved),
             "PENDING_SPENT" => Ok(Self::PendingSpent),
+            "PENDING_RECEIVE" => Ok(Self::PendingReceive),
             _ => Err(Error::UnknownState),
         }
     }

crates/cdk-cli/src/main.rs

@@ -96,6 +96,8 @@ enum Commands {
     Transfer(sub_commands::transfer::TransferSubCommand),
     /// Reclaim pending proofs that are no longer pending
     CheckPending,
+    /// Finalize pending receives by contacting the mint and swapping
+    FinalizeReceives(sub_commands::finalize_receives::FinalizeReceivesSubCommand),
     /// Check incoming payments for stored payment requests.
     CheckRequests,
     /// View mint info
@@ -298,6 +300,10 @@ async fn main() -> Result<()> {
         Commands::CheckPending => {
             sub_commands::check_pending::check_pending(&wallet_repository).await
         }
+        Commands::FinalizeReceives(sub_command_args) => {
+            sub_commands::finalize_receives::finalize_receives(&wallet_repository, sub_command_args)
+                .await
+        }
         Commands::CheckRequests => {
             sub_commands::check_requests::check_requests(&wallet_repository).await
         }

crates/cdk-cli/src/sub_commands/finalize_receives.rs

@@ -0,0 +1,48 @@
+use anyhow::Result;
+use cdk::wallet::WalletRepository;
+
+#[derive(clap::Args, Clone)]
+pub struct FinalizeReceivesSubCommand {
+    /// Specify the mint url
+    #[arg(short, long)]
+    pub mint_url: Option<String>,
+}
+
+pub async fn finalize_receives(
+    wallet_repository: &WalletRepository,
+    sub_command_args: &FinalizeReceivesSubCommand,
+) -> Result<()> {
+    let wallets = wallet_repository.get_wallets().await;
+
+    let mut found_mint = false;
+    for wallet in wallets.iter() {
+        if let Some(mint_url) = &sub_command_args.mint_url {
+            if wallet.mint_url.to_string() != *mint_url {
+                continue;
+            }
+        }
+        found_mint = true;
+
+        match wallet.finalize_pending_receives().await {
+            Ok(amount) => {
+                println!(
+                    "Finalized pending receives for {}: {} {}",
+                    wallet.mint_url, amount, wallet.unit
+                );
+            }
+            Err(e) => {
+                println!("Error finalizing receives for {}: {}", wallet.mint_url, e);
+            }
+        }
+    }
+
+    if !found_mint {
+        if let Some(mint_url) = &sub_command_args.mint_url {
+            println!("No wallet found for mint: {}", mint_url);
+        } else {
+            println!("No wallets found.");
+        }
+    }
+
+    Ok(())
+}

crates/cdk-cli/src/sub_commands/mod.rs

@@ -7,6 +7,7 @@ pub mod check_requests;
 pub mod create_request;
 pub mod decode_request;
 pub mod decode_token;
+pub mod finalize_receives;
 pub mod generate_public_key;
 pub mod get_public_keys;
 pub mod list_mint_proofs;

crates/cdk-cli/src/sub_commands/receive.rs

@@ -37,6 +37,9 @@ pub struct ReceiveSubCommand {
     /// Allow receiving from untrusted mints (mints not already in the wallet)
     #[arg(long, default_value = "false")]
     allow_untrusted: bool,
+    /// Only accept the token offline and place it into PendingReceive state
+    #[arg(long, default_value = "false")]
+    offline: bool,
 }
 
 pub async fn receive(
@@ -72,6 +75,7 @@ pub async fn receive(
                 &signing_keys,
                 &sub_command_args.preimage,
                 sub_command_args.allow_untrusted,
+                sub_command_args.offline,
                 unit,
             )
             .await?
@@ -114,6 +118,7 @@ pub async fn receive(
                     &signing_keys,
                     &sub_command_args.preimage,
                     sub_command_args.allow_untrusted,
+                    sub_command_args.offline,
                     unit,
                 )
                 .await
@@ -142,6 +147,7 @@ async fn receive_token(
     signing_keys: &[SecretKey],
     preimage: &[String],
     allow_untrusted: bool,
+    offline: bool,
     unit: &CurrencyUnit,
 ) -> Result<Amount> {
     let token: Token = Token::from_str(token_str)?;
@@ -162,15 +168,24 @@ async fn receive_token(
     // Get or create wallet for the token's mint
     let wallet = get_or_create_wallet(wallet_repository, &mint_url, unit).await?;
 
-    // Create receive options
-    let receive_options = ReceiveOptions {
-        p2pk_signing_keys: signing_keys.to_vec(),
-        preimages: preimage.to_vec(),
-        ..Default::default()
-    };
-
-    let received = wallet.receive(token_str, receive_options).await?;
-    Ok(received)
+    if offline {
+        let options = cdk_common::wallet::OfflineReceiveOptions {
+            minimum_locktime: None,
+            require_locked: false,
+        };
+        let received = wallet.receive_offline(token_str, options).await?;
+        Ok(received)
+    } else {
+        // Create receive options
+        let receive_options = ReceiveOptions {
+            p2pk_signing_keys: signing_keys.to_vec(),
+            preimages: preimage.to_vec(),
+            ..Default::default()
+        };
+
+        let received = wallet.receive(token_str, receive_options).await?;
+        Ok(received)
+    }
 }
 
 /// Receive tokens sent to nostr pubkey via dm

crates/cdk-common/src/database/mint/test/proofs.rs

@@ -582,7 +582,8 @@ where
             | State::Reserved
             | State::Pending
             | State::Spent
-            | State::PendingSpent => {}
+            | State::PendingSpent
+            | State::PendingReceive => {}
         }
     }
     // It's OK if state is None for some implementations

crates/cdk-common/src/wallet/mod.rs

@@ -486,6 +486,22 @@ impl fmt::Debug for ReceiveOptions {
     }
 }
 
+/// Offline Receive options
+///
+/// DLEQ proof verification is always performed for offline receives
+/// since it is the only way to verify token authenticity without
+/// contacting the mint.
+///
+/// The wallet is already bound to a specific mint URL, so mint
+/// filtering is handled automatically.
+#[derive(Debug, Clone, Default)]
+pub struct OfflineReceiveOptions {
+    /// Optional minimum locktime required for the token
+    pub minimum_locktime: Option<u64>,
+    /// Require the token to be P2PK locked
+    pub require_locked: bool,
+}
+
 /// Send Kind
 #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default, Serialize, Deserialize)]
 pub enum SendKind {
@@ -855,6 +871,12 @@ pub trait Wallet: Send + Sync {
     /// Total pending balance of the wallet
     async fn total_pending_balance(&self) -> Result<Self::Amount, Self::Error>;
 
+    /// Total pending-receive balance of the wallet
+    ///
+    /// Proofs in this state have been DLEQ-verified offline but not yet
+    /// swapped with the mint. Call `finalize_pending_receives` to settle them.
+    async fn total_pending_receive_balance(&self) -> Result<Self::Amount, Self::Error>;
+
     /// Total reserved balance of the wallet
     async fn total_reserved_balance(&self) -> Result<Self::Amount, Self::Error>;
 
@@ -967,6 +989,16 @@ pub trait Wallet: Send + Sync {
         token: Option<String>,
     ) -> Result<Self::Amount, Self::Error>;
 
+    /// Receive an encoded token offline without contacting the mint
+    async fn receive_offline(
+        &self,
+        encoded_token: &str,
+        options: OfflineReceiveOptions,
+    ) -> Result<Self::Amount, Self::Error>;
+
+    /// Finalize pending offline receives by attempting to swap them
+    async fn finalize_pending_receives(&self) -> Result<Self::Amount, Self::Error>;
+
     /// Prepare a send transaction
     async fn prepare_send(
         &self,

crates/cdk-common/src/wallet/saga/mod.rs

@@ -84,6 +84,7 @@ impl WalletSagaState {
             WalletSagaState::Receive(s) => match s {
                 ReceiveSagaState::ProofsPending => "proofs_pending",
                 ReceiveSagaState::SwapRequested => "swap_requested",
+                ReceiveSagaState::OfflinePendingReceive => "offline_pending_receive",
             },
             WalletSagaState::Swap(s) => match s {
                 SwapSagaState::ProofsReserved => "proofs_reserved",

crates/cdk-common/src/wallet/saga/receive.rs

@@ -13,13 +13,19 @@ pub enum ReceiveSagaState {
     ProofsPending,
     /// Swap request sent to mint, awaiting signatures for new proofs
     SwapRequested,
+    /// Proofs accepted offline (DLEQ-verified), stored as PendingReceive awaiting
+    /// `finalize_pending_receives`. This saga holds the original token string so
+    /// the memo and proof grouping survive until the wallet comes back online.
+    /// Recovery must NOT compensate this state — `finalize_pending_receives` owns it.
+    OfflinePendingReceive,
 }
 
 impl std::fmt::Display for ReceiveSagaState {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             ReceiveSagaState::ProofsPending => write!(f, "proofs_pending"),
             ReceiveSagaState::SwapRequested => write!(f, "swap_requested"),
+            ReceiveSagaState::OfflinePendingReceive => write!(f, "offline_pending_receive"),
         }
     }
 }
@@ -30,6 +36,7 @@ impl std::str::FromStr for ReceiveSagaState {
         match s {
             "proofs_pending" => Ok(ReceiveSagaState::ProofsPending),
             "swap_requested" => Ok(ReceiveSagaState::SwapRequested),
+            "offline_pending_receive" => Ok(ReceiveSagaState::OfflinePendingReceive),
             _ => Err(Error::InvalidOperationState),
         }
     }

crates/cdk-ffi/src/types/proof.rs

@@ -17,6 +17,8 @@ pub enum ProofState {
     Spent,
     Reserved,
     PendingSpent,
+    /// Proofs received offline, verified via DLEQ, awaiting final swap
+    PendingReceive,
 }
 
 impl From<CdkState> for ProofState {
@@ -27,6 +29,7 @@ impl From<CdkState> for ProofState {
             CdkState::Spent => ProofState::Spent,
             CdkState::Reserved => ProofState::Reserved,
             CdkState::PendingSpent => ProofState::PendingSpent,
+            CdkState::PendingReceive => ProofState::PendingReceive,
         }
     }
 }
@@ -39,6 +42,7 @@ impl From<ProofState> for CdkState {
             ProofState::Spent => CdkState::Spent,
             ProofState::Reserved => CdkState::Reserved,
             ProofState::PendingSpent => CdkState::PendingSpent,
+            ProofState::PendingReceive => CdkState::PendingReceive,
         }
     }
 }