cdk_common/
wallet.rs

1//! Wallet Types
2
3use std::collections::HashMap;
4use std::fmt;
5use std::str::FromStr;
6
7use bitcoin::hashes::{sha256, Hash, HashEngine};
8use cashu::util::hex;
9use cashu::{nut00, PaymentMethod, Proofs, PublicKey};
10use serde::{Deserialize, Serialize};
11
12use crate::mint_url::MintUrl;
13use crate::nuts::{CurrencyUnit, MeltQuoteState, MintQuoteState, SecretKey};
14use crate::{Amount, Error};
15
16/// Wallet Key
17#[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
18pub struct WalletKey {
19    /// Mint Url
20    pub mint_url: MintUrl,
21    /// Currency Unit
22    pub unit: CurrencyUnit,
23}
24
25impl fmt::Display for WalletKey {
26    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
27        write!(f, "mint_url: {}, unit: {}", self.mint_url, self.unit,)
28    }
29}
30
31impl WalletKey {
32    /// Create new [`WalletKey`]
33    pub fn new(mint_url: MintUrl, unit: CurrencyUnit) -> Self {
34        Self { mint_url, unit }
35    }
36}
37
38/// Mint Quote Info
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct MintQuote {
41    /// Quote id
42    pub id: String,
43    /// Mint Url
44    pub mint_url: MintUrl,
45    /// Payment method
46    #[serde(default)]
47    pub payment_method: PaymentMethod,
48    /// Amount of quote
49    pub amount: Option<Amount>,
50    /// Unit of quote
51    pub unit: CurrencyUnit,
52    /// Quote payment request e.g. bolt11
53    pub request: String,
54    /// Quote state
55    pub state: MintQuoteState,
56    /// Expiration time of quote
57    pub expiry: u64,
58    /// Secretkey for signing mint quotes [NUT-20]
59    pub secret_key: Option<SecretKey>,
60    /// Amount minted
61    #[serde(default)]
62    pub amount_issued: Amount,
63    /// Amount paid to the mint for the quote
64    #[serde(default)]
65    pub amount_paid: Amount,
66}
67
68/// Melt Quote Info
69#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
70pub struct MeltQuote {
71    /// Quote id
72    pub id: String,
73    /// Quote unit
74    pub unit: CurrencyUnit,
75    /// Quote amount
76    pub amount: Amount,
77    /// Quote Payment request e.g. bolt11
78    pub request: String,
79    /// Quote fee reserve
80    pub fee_reserve: Amount,
81    /// Quote state
82    pub state: MeltQuoteState,
83    /// Expiration time of quote
84    pub expiry: u64,
85    /// Payment preimage
86    pub payment_preimage: Option<String>,
87    /// Payment method
88    #[serde(default)]
89    pub payment_method: PaymentMethod,
90}
91
92impl MintQuote {
93    /// Create a new MintQuote
94    #[allow(clippy::too_many_arguments)]
95    pub fn new(
96        id: String,
97        mint_url: MintUrl,
98        payment_method: PaymentMethod,
99        amount: Option<Amount>,
100        unit: CurrencyUnit,
101        request: String,
102        expiry: u64,
103        secret_key: Option<SecretKey>,
104    ) -> Self {
105        Self {
106            id,
107            mint_url,
108            payment_method,
109            amount,
110            unit,
111            request,
112            state: MintQuoteState::Unpaid,
113            expiry,
114            secret_key,
115            amount_issued: Amount::ZERO,
116            amount_paid: Amount::ZERO,
117        }
118    }
119
120    /// Calculate the total amount including any fees
121    pub fn total_amount(&self) -> Amount {
122        self.amount_paid
123    }
124
125    /// Check if the quote has expired
126    pub fn is_expired(&self, current_time: u64) -> bool {
127        current_time > self.expiry
128    }
129
130    /// Amount that can be minted
131    pub fn amount_mintable(&self) -> Amount {
132        if self.amount_issued > self.amount_paid {
133            return Amount::ZERO;
134        }
135
136        let difference = self.amount_paid - self.amount_issued;
137
138        if difference == Amount::ZERO && self.state != MintQuoteState::Issued {
139            if let Some(amount) = self.amount {
140                return amount;
141            }
142        }
143
144        difference
145    }
146}
147
148/// Send Kind
149#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Default, Serialize, Deserialize)]
150pub enum SendKind {
151    #[default]
152    /// Allow online swap before send if wallet does not have exact amount
153    OnlineExact,
154    /// Prefer offline send if difference is less then tolerance
155    OnlineTolerance(Amount),
156    /// Wallet cannot do an online swap and selected proof must be exactly send amount
157    OfflineExact,
158    /// Wallet must remain offline but can over pay if below tolerance
159    OfflineTolerance(Amount),
160}
161
162impl SendKind {
163    /// Check if send kind is online
164    pub fn is_online(&self) -> bool {
165        matches!(self, Self::OnlineExact | Self::OnlineTolerance(_))
166    }
167
168    /// Check if send kind is offline
169    pub fn is_offline(&self) -> bool {
170        matches!(self, Self::OfflineExact | Self::OfflineTolerance(_))
171    }
172
173    /// Check if send kind is exact
174    pub fn is_exact(&self) -> bool {
175        matches!(self, Self::OnlineExact | Self::OfflineExact)
176    }
177
178    /// Check if send kind has tolerance
179    pub fn has_tolerance(&self) -> bool {
180        matches!(self, Self::OnlineTolerance(_) | Self::OfflineTolerance(_))
181    }
182}
183
184/// Wallet Transaction
185#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
186pub struct Transaction {
187    /// Mint Url
188    pub mint_url: MintUrl,
189    /// Transaction direction
190    pub direction: TransactionDirection,
191    /// Amount
192    pub amount: Amount,
193    /// Fee
194    pub fee: Amount,
195    /// Currency Unit
196    pub unit: CurrencyUnit,
197    /// Proof Ys
198    pub ys: Vec<PublicKey>,
199    /// Unix timestamp
200    pub timestamp: u64,
201    /// Memo
202    pub memo: Option<String>,
203    /// User-defined metadata
204    pub metadata: HashMap<String, String>,
205    /// Quote ID if this is a mint or melt transaction
206    pub quote_id: Option<String>,
207}
208
209impl Transaction {
210    /// Transaction ID
211    pub fn id(&self) -> TransactionId {
212        TransactionId::new(self.ys.clone())
213    }
214
215    /// Check if transaction matches conditions
216    pub fn matches_conditions(
217        &self,
218        mint_url: &Option<MintUrl>,
219        direction: &Option<TransactionDirection>,
220        unit: &Option<CurrencyUnit>,
221    ) -> bool {
222        if let Some(mint_url) = mint_url {
223            if &self.mint_url != mint_url {
224                return false;
225            }
226        }
227        if let Some(direction) = direction {
228            if &self.direction != direction {
229                return false;
230            }
231        }
232        if let Some(unit) = unit {
233            if &self.unit != unit {
234                return false;
235            }
236        }
237        true
238    }
239}
240
241impl PartialOrd for Transaction {
242    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
243        Some(self.cmp(other))
244    }
245}
246
247impl Ord for Transaction {
248    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
249        self.timestamp
250            .cmp(&other.timestamp)
251            .reverse()
252            .then_with(|| self.id().cmp(&other.id()))
253    }
254}
255
256/// Transaction Direction
257#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
258pub enum TransactionDirection {
259    /// Incoming transaction (i.e., receive or mint)
260    Incoming,
261    /// Outgoing transaction (i.e., send or melt)
262    Outgoing,
263}
264
265impl std::fmt::Display for TransactionDirection {
266    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
267        match self {
268            TransactionDirection::Incoming => write!(f, "Incoming"),
269            TransactionDirection::Outgoing => write!(f, "Outgoing"),
270        }
271    }
272}
273
274impl FromStr for TransactionDirection {
275    type Err = Error;
276
277    fn from_str(value: &str) -> Result<Self, Self::Err> {
278        match value {
279            "Incoming" => Ok(Self::Incoming),
280            "Outgoing" => Ok(Self::Outgoing),
281            _ => Err(Error::InvalidTransactionDirection),
282        }
283    }
284}
285
286/// Transaction ID
287#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
288#[serde(transparent)]
289pub struct TransactionId([u8; 32]);
290
291impl TransactionId {
292    /// Create new [`TransactionId`]
293    pub fn new(ys: Vec<PublicKey>) -> Self {
294        let mut ys = ys;
295        ys.sort();
296        let mut hasher = sha256::Hash::engine();
297        for y in ys {
298            hasher.input(&y.to_bytes());
299        }
300        let hash = sha256::Hash::from_engine(hasher);
301        Self(hash.to_byte_array())
302    }
303
304    /// From proofs
305    pub fn from_proofs(proofs: Proofs) -> Result<Self, nut00::Error> {
306        let ys = proofs
307            .iter()
308            .map(|proof| proof.y())
309            .collect::<Result<Vec<PublicKey>, nut00::Error>>()?;
310        Ok(Self::new(ys))
311    }
312
313    /// From bytes
314    pub fn from_bytes(bytes: [u8; 32]) -> Self {
315        Self(bytes)
316    }
317
318    /// From hex string
319    pub fn from_hex(value: &str) -> Result<Self, Error> {
320        let bytes = hex::decode(value)?;
321        if bytes.len() != 32 {
322            return Err(Error::InvalidTransactionId);
323        }
324        let mut array = [0u8; 32];
325        array.copy_from_slice(&bytes);
326        Ok(Self(array))
327    }
328
329    /// From slice
330    pub fn from_slice(slice: &[u8]) -> Result<Self, Error> {
331        if slice.len() != 32 {
332            return Err(Error::InvalidTransactionId);
333        }
334        let mut array = [0u8; 32];
335        array.copy_from_slice(slice);
336        Ok(Self(array))
337    }
338
339    /// Get inner value
340    pub fn as_bytes(&self) -> &[u8; 32] {
341        &self.0
342    }
343
344    /// Get inner value as slice
345    pub fn as_slice(&self) -> &[u8] {
346        &self.0
347    }
348}
349
350impl std::fmt::Display for TransactionId {
351    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
352        write!(f, "{}", hex::encode(self.0))
353    }
354}
355
356impl FromStr for TransactionId {
357    type Err = Error;
358
359    fn from_str(value: &str) -> Result<Self, Self::Err> {
360        Self::from_hex(value)
361    }
362}
363
364impl TryFrom<Proofs> for TransactionId {
365    type Error = nut00::Error;
366
367    fn try_from(proofs: Proofs) -> Result<Self, Self::Error> {
368        Self::from_proofs(proofs)
369    }
370}
371
372#[cfg(test)]
373mod tests {
374    use super::*;
375
376    #[test]
377    fn test_transaction_id_from_hex() {
378        let hex_str = "a1b2c3d4e5f60718293a0b1c2d3e4f506172839a0b1c2d3e4f506172839a0b1c";
379        let transaction_id = TransactionId::from_hex(hex_str).unwrap();
380        assert_eq!(transaction_id.to_string(), hex_str);
381    }
382
383    #[test]
384    fn test_transaction_id_from_hex_empty_string() {
385        let hex_str = "";
386        let res = TransactionId::from_hex(hex_str);
387        assert!(matches!(res, Err(Error::InvalidTransactionId)));
388    }
389
390    #[test]
391    fn test_transaction_id_from_hex_longer_string() {
392        let hex_str = "a1b2c3d4e5f60718293a0b1c2d3e4f506172839a0b1c2d3e4f506172839a0b1ca1b2";
393        let res = TransactionId::from_hex(hex_str);
394        assert!(matches!(res, Err(Error::InvalidTransactionId)));
395    }
396}
cdk_common/wallet.rs

cdk_common/
wallet.rs
