fedimint_wallet_common/
lib.rs

1#![deny(clippy::pedantic)]
2#![allow(clippy::missing_errors_doc)]
3#![allow(clippy::missing_panics_doc)]
4#![allow(clippy::module_name_repetitions)]
5#![allow(clippy::must_use_candidate)]
6#![allow(clippy::needless_lifetimes)]
7#![allow(clippy::return_self_not_must_use)]
8
9use std::hash::Hasher;
10
11use bitcoin::address::NetworkUnchecked;
12use bitcoin::psbt::raw::ProprietaryKey;
13use bitcoin::{Address, Amount, BlockHash, TxOut, Txid, secp256k1};
14use config::WalletClientConfig;
15use fedimint_core::core::{Decoder, ModuleInstanceId, ModuleKind};
16use fedimint_core::encoding::btc::NetworkLegacyEncodingWrapper;
17use fedimint_core::encoding::{Decodable, Encodable};
18use fedimint_core::module::{CommonModuleInit, ModuleCommon, ModuleConsensusVersion};
19use fedimint_core::{Feerate, extensible_associated_module_type, plugin_types_trait_impl_common};
20use impl_tools::autoimpl;
21use miniscript::Descriptor;
22use serde::{Deserialize, Serialize};
23use thiserror::Error;
24use tracing::error;
25
26use crate::keys::CompressedPublicKey;
27use crate::txoproof::{PegInProof, PegInProofError};
28
29pub mod config;
30pub mod endpoint_constants;
31pub mod envs;
32pub mod keys;
33pub mod tweakable;
34pub mod txoproof;
35
36pub const KIND: ModuleKind = ModuleKind::from_static_str("wallet");
37pub const MODULE_CONSENSUS_VERSION: ModuleConsensusVersion = ModuleConsensusVersion::new(2, 2);
38
39/// Module consensus version that introduced support for processing Bitcoin
40/// transactions that exceed the `ALEPH_BFT_UNIT_BYTE_LIMIT`.
41pub const SAFE_DEPOSIT_MODULE_CONSENSUS_VERSION: ModuleConsensusVersion =
42    ModuleConsensusVersion::new(2, 2);
43
44/// To further mitigate the risk of a peg-out transaction getting stuck in the
45/// mempool, we multiply the feerate estimate returned from the backend by this
46/// value.
47pub const FEERATE_MULTIPLIER_DEFAULT: f64 = 2.0;
48
49pub type PartialSig = Vec<u8>;
50
51pub type PegInDescriptor = Descriptor<CompressedPublicKey>;
52
53#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Encodable, Decodable)]
54pub enum WalletConsensusItem {
55    BlockCount(u32), /* FIXME: use block hash instead, but needs more complicated
56                      * * verification logic */
57    Feerate(Feerate),
58    PegOutSignature(PegOutSignatureItem),
59    ModuleConsensusVersion(ModuleConsensusVersion),
60    #[encodable_default]
61    Default {
62        variant: u64,
63        bytes: Vec<u8>,
64    },
65}
66
67impl std::fmt::Display for WalletConsensusItem {
68    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
69        match self {
70            WalletConsensusItem::BlockCount(count) => {
71                write!(f, "Wallet Block Count {count}")
72            }
73            WalletConsensusItem::Feerate(feerate) => {
74                write!(
75                    f,
76                    "Wallet Feerate with sats per kvb {}",
77                    feerate.sats_per_kvb
78                )
79            }
80            WalletConsensusItem::PegOutSignature(sig) => {
81                write!(f, "Wallet PegOut signature for Bitcoin TxId {}", sig.txid)
82            }
83            WalletConsensusItem::ModuleConsensusVersion(version) => {
84                write!(
85                    f,
86                    "Wallet Consensus Version {}.{}",
87                    version.major, version.minor
88                )
89            }
90            WalletConsensusItem::Default { variant, .. } => {
91                write!(f, "Unknown Wallet CI variant={variant}")
92            }
93        }
94    }
95}
96
97#[derive(Clone, Debug, Serialize, Deserialize, Encodable, Decodable)]
98pub struct PegOutSignatureItem {
99    pub txid: Txid,
100    pub signature: Vec<secp256k1::ecdsa::Signature>,
101}
102
103#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize, Encodable, Decodable)]
104pub struct SpendableUTXO {
105    #[serde(with = "::fedimint_core::encoding::as_hex")]
106    pub tweak: [u8; 33],
107    #[serde(with = "bitcoin::amount::serde::as_sat")]
108    pub amount: bitcoin::Amount,
109}
110
111/// A transaction output, either unspent or consumed
112#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
113pub struct TxOutputSummary {
114    pub outpoint: bitcoin::OutPoint,
115    #[serde(with = "bitcoin::amount::serde::as_sat")]
116    pub amount: bitcoin::Amount,
117}
118
119/// Summary of the coins within the wallet.
120///
121/// Coins within the wallet go from spendable, to consumed in a transaction that
122/// does not have threshold signatures (unsigned), to threshold signed and
123/// unconfirmed on-chain (unconfirmed).
124///
125/// This summary provides the most granular view possible of coins in the
126/// wallet.
127#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
128pub struct WalletSummary {
129    /// All UTXOs available as inputs for transactions
130    pub spendable_utxos: Vec<TxOutputSummary>,
131    /// Transaction outputs consumed in peg-out transactions that have not
132    /// reached threshold signatures
133    pub unsigned_peg_out_txos: Vec<TxOutputSummary>,
134    /// Change UTXOs created from peg-out transactions that have not reached
135    /// threshold signatures
136    pub unsigned_change_utxos: Vec<TxOutputSummary>,
137    /// Transaction outputs consumed in peg-out transactions that have reached
138    /// threshold signatures waiting for finality delay confirmations
139    pub unconfirmed_peg_out_txos: Vec<TxOutputSummary>,
140    /// Change UTXOs created from peg-out transactions that have reached
141    /// threshold signatures waiting for finality delay confirmations
142    pub unconfirmed_change_utxos: Vec<TxOutputSummary>,
143}
144
145impl WalletSummary {
146    fn sum<'a>(txos: impl Iterator<Item = &'a TxOutputSummary>) -> Amount {
147        txos.fold(Amount::ZERO, |acc, txo| txo.amount + acc)
148    }
149
150    /// Total amount of all spendable UTXOs
151    pub fn total_spendable_balance(&self) -> Amount {
152        WalletSummary::sum(self.spendable_utxos.iter())
153    }
154
155    /// Total amount of all transaction outputs from peg-out transactions that
156    /// have not reached threshold signatures
157    pub fn total_unsigned_peg_out_balance(&self) -> Amount {
158        WalletSummary::sum(self.unsigned_peg_out_txos.iter())
159    }
160
161    /// Total amount of all change UTXOs from peg-out transactions that have not
162    /// reached threshold signatures
163    pub fn total_unsigned_change_balance(&self) -> Amount {
164        WalletSummary::sum(self.unsigned_change_utxos.iter())
165    }
166
167    /// Total amount of all transaction outputs from peg-out transactions that
168    /// have reached threshold signatures waiting for finality delay
169    /// confirmations
170    pub fn total_unconfirmed_peg_out_balance(&self) -> Amount {
171        WalletSummary::sum(self.unconfirmed_peg_out_txos.iter())
172    }
173
174    /// Total amount of all change UTXOs from peg-out transactions that have
175    /// reached threshold signatures waiting for finality delay confirmations
176    pub fn total_unconfirmed_change_balance(&self) -> Amount {
177        WalletSummary::sum(self.unconfirmed_change_utxos.iter())
178    }
179
180    /// Total amount of all transaction outputs from peg-out transactions that
181    /// are either waiting for threshold signatures or confirmations. This is
182    /// the total in-flight amount leaving the wallet.
183    pub fn total_pending_peg_out_balance(&self) -> Amount {
184        self.total_unsigned_peg_out_balance() + self.total_unconfirmed_peg_out_balance()
185    }
186
187    /// Total amount of all change UTXOs from peg-out transactions that are
188    /// either waiting for threshold signatures or confirmations. This is the
189    /// total in-flight amount that will become spendable by the wallet.
190    pub fn total_pending_change_balance(&self) -> Amount {
191        self.total_unsigned_change_balance() + self.total_unconfirmed_change_balance()
192    }
193
194    /// Total amount of immediately spendable UTXOs and pending change UTXOs.
195    /// This is the spendable balance once all transactions confirm.
196    pub fn total_owned_balance(&self) -> Amount {
197        self.total_spendable_balance() + self.total_pending_change_balance()
198    }
199
200    /// All transaction outputs from peg-out transactions that are either
201    /// waiting for threshold signatures or confirmations. These are all the
202    /// in-flight coins leaving the wallet.
203    pub fn pending_peg_out_txos(&self) -> Vec<TxOutputSummary> {
204        self.unsigned_peg_out_txos
205            .clone()
206            .into_iter()
207            .chain(self.unconfirmed_peg_out_txos.clone())
208            .collect()
209    }
210
211    /// All change UTXOs from peg-out transactions that are either waiting for
212    /// threshold signatures or confirmations. These are all the in-flight coins
213    /// that will become spendable by the wallet.
214    pub fn pending_change_utxos(&self) -> Vec<TxOutputSummary> {
215        self.unsigned_change_utxos
216            .clone()
217            .into_iter()
218            .chain(self.unconfirmed_change_utxos.clone())
219            .collect()
220    }
221}
222
223/// Recovery data for slice-based client recovery
224#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
225pub enum RecoveryItem {
226    /// A peg-in input was claimed
227    Input {
228        /// The Bitcoin outpoint that was claimed
229        outpoint: bitcoin::OutPoint,
230        /// The `script_pubkey` of the peg-in address (tweaked descriptor)
231        script: bitcoin::ScriptBuf,
232    },
233}
234
235#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
236pub struct PegOutFees {
237    pub fee_rate: Feerate,
238    pub total_weight: u64,
239}
240
241impl PegOutFees {
242    pub fn new(sats_per_kvb: u64, total_weight: u64) -> Self {
243        PegOutFees {
244            fee_rate: Feerate { sats_per_kvb },
245            total_weight,
246        }
247    }
248
249    pub fn amount(&self) -> Amount {
250        self.fee_rate.calculate_fee(self.total_weight)
251    }
252}
253
254#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
255pub struct PegOut {
256    pub recipient: Address<NetworkUnchecked>,
257    #[serde(with = "bitcoin::amount::serde::as_sat")]
258    pub amount: bitcoin::Amount,
259    pub fees: PegOutFees,
260}
261
262extensible_associated_module_type!(
263    WalletOutputOutcome,
264    WalletOutputOutcomeV0,
265    UnknownWalletOutputOutcomeVariantError
266);
267
268impl WalletOutputOutcome {
269    pub fn new_v0(txid: bitcoin::Txid) -> WalletOutputOutcome {
270        WalletOutputOutcome::V0(WalletOutputOutcomeV0(txid))
271    }
272}
273
274/// Contains the Bitcoin transaction id of the transaction created by the
275/// withdraw request
276#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
277pub struct WalletOutputOutcomeV0(pub bitcoin::Txid);
278
279impl std::fmt::Display for WalletOutputOutcomeV0 {
280    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
281        write!(f, "Wallet PegOut Bitcoin TxId {}", self.0)
282    }
283}
284
285#[derive(Debug)]
286pub struct WalletCommonInit;
287
288impl CommonModuleInit for WalletCommonInit {
289    const CONSENSUS_VERSION: ModuleConsensusVersion = MODULE_CONSENSUS_VERSION;
290    const KIND: ModuleKind = KIND;
291
292    type ClientConfig = WalletClientConfig;
293
294    fn decoder() -> Decoder {
295        WalletModuleTypes::decoder()
296    }
297}
298
299#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
300pub enum WalletInput {
301    V0(WalletInputV0),
302    V1(WalletInputV1),
303    #[encodable_default]
304    Default {
305        variant: u64,
306        bytes: Vec<u8>,
307    },
308}
309
310impl WalletInput {
311    pub fn maybe_v0_ref(&self) -> Option<&WalletInputV0> {
312        match self {
313            WalletInput::V0(v0) => Some(v0),
314            _ => None,
315        }
316    }
317}
318
319#[derive(
320    Debug,
321    thiserror::Error,
322    Clone,
323    Eq,
324    PartialEq,
325    Hash,
326    serde::Deserialize,
327    serde::Serialize,
328    fedimint_core::encoding::Encodable,
329    fedimint_core::encoding::Decodable,
330)]
331#[error("Unknown {} variant {variant}", stringify!($name))]
332pub struct UnknownWalletInputVariantError {
333    pub variant: u64,
334}
335
336impl std::fmt::Display for WalletInput {
337    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
338        match &self {
339            WalletInput::V0(inner) => std::fmt::Display::fmt(&inner, f),
340            WalletInput::V1(inner) => std::fmt::Display::fmt(&inner, f),
341            WalletInput::Default { variant, .. } => {
342                write!(f, "Unknown variant (variant={variant})")
343            }
344        }
345    }
346}
347
348impl WalletInput {
349    pub fn new_v0(peg_in_proof: PegInProof) -> WalletInput {
350        WalletInput::V0(WalletInputV0(Box::new(peg_in_proof)))
351    }
352
353    pub fn new_v1(peg_in_proof: &PegInProof) -> WalletInput {
354        WalletInput::V1(WalletInputV1 {
355            outpoint: peg_in_proof.outpoint(),
356            tweak_key: peg_in_proof.tweak_key(),
357            tx_out: peg_in_proof.tx_output(),
358        })
359    }
360}
361
362#[autoimpl(Deref, DerefMut using self.0)]
363#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
364pub struct WalletInputV0(pub Box<PegInProof>);
365
366#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
367pub struct WalletInputV1 {
368    pub outpoint: bitcoin::OutPoint,
369    pub tweak_key: secp256k1::PublicKey,
370    pub tx_out: TxOut,
371}
372
373impl std::fmt::Display for WalletInputV0 {
374    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
375        write!(
376            f,
377            "Wallet PegIn with Bitcoin TxId {}",
378            self.0.outpoint().txid
379        )
380    }
381}
382
383impl std::fmt::Display for WalletInputV1 {
384    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
385        write!(f, "Wallet PegIn V1 with TxId {}", self.outpoint.txid)
386    }
387}
388
389extensible_associated_module_type!(
390    WalletOutput,
391    WalletOutputV0,
392    UnknownWalletOutputVariantError
393);
394
395impl WalletOutput {
396    pub fn new_v0_peg_out(
397        recipient: Address,
398        amount: bitcoin::Amount,
399        fees: PegOutFees,
400    ) -> WalletOutput {
401        WalletOutput::V0(WalletOutputV0::PegOut(PegOut {
402            recipient: recipient.into_unchecked(),
403            amount,
404            fees,
405        }))
406    }
407    pub fn new_v0_rbf(fees: PegOutFees, txid: Txid) -> WalletOutput {
408        WalletOutput::V0(WalletOutputV0::Rbf(Rbf { fees, txid }))
409    }
410}
411
412#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
413pub enum WalletOutputV0 {
414    PegOut(PegOut),
415    Rbf(Rbf),
416}
417
418/// Allows a user to bump the fees of a `PendingTransaction`
419#[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Encodable, Decodable)]
420pub struct Rbf {
421    /// Fees expressed as an increase over existing peg-out fees
422    pub fees: PegOutFees,
423    /// Bitcoin tx id to bump the fees for
424    pub txid: Txid,
425}
426
427impl WalletOutputV0 {
428    pub fn amount(&self) -> Amount {
429        match self {
430            WalletOutputV0::PegOut(pegout) => pegout.amount + pegout.fees.amount(),
431            WalletOutputV0::Rbf(rbf) => rbf.fees.amount(),
432        }
433    }
434}
435
436impl std::fmt::Display for WalletOutputV0 {
437    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
438        match self {
439            WalletOutputV0::PegOut(pegout) => {
440                write!(
441                    f,
442                    "Wallet PegOut {} to {}",
443                    pegout.amount,
444                    pegout.recipient.clone().assume_checked()
445                )
446            }
447            WalletOutputV0::Rbf(rbf) => write!(f, "Wallet RBF {:?} to {}", rbf.fees, rbf.txid),
448        }
449    }
450}
451
452pub struct WalletModuleTypes;
453
454pub fn proprietary_tweak_key() -> ProprietaryKey {
455    ProprietaryKey {
456        prefix: b"fedimint".to_vec(),
457        subtype: 0x00,
458        key: vec![],
459    }
460}
461
462impl std::hash::Hash for PegOutSignatureItem {
463    fn hash<H: Hasher>(&self, state: &mut H) {
464        self.txid.hash(state);
465        for sig in &self.signature {
466            sig.serialize_der().hash(state);
467        }
468    }
469}
470
471impl PartialEq for PegOutSignatureItem {
472    fn eq(&self, other: &PegOutSignatureItem) -> bool {
473        self.txid == other.txid && self.signature == other.signature
474    }
475}
476
477impl Eq for PegOutSignatureItem {}
478
479plugin_types_trait_impl_common!(
480    KIND,
481    WalletModuleTypes,
482    WalletClientConfig,
483    WalletInput,
484    WalletOutput,
485    WalletOutputOutcome,
486    WalletConsensusItem,
487    WalletInputError,
488    WalletOutputError
489);
490
491#[derive(Debug, Error, Encodable, Decodable, Hash, Clone, Eq, PartialEq)]
492pub enum WalletInputError {
493    #[error("Unknown block hash in peg-in proof: {0}")]
494    UnknownPegInProofBlock(BlockHash),
495    #[error("Invalid peg-in proof: {0}")]
496    PegInProofError(#[from] PegInProofError),
497    #[error("The peg-in was already claimed")]
498    PegInAlreadyClaimed,
499    #[error("The wallet input version is not supported by this federation")]
500    UnknownInputVariant(#[from] UnknownWalletInputVariantError),
501    #[error("Unknown UTXO")]
502    UnknownUTXO,
503    #[error("Wrong output script")]
504    WrongOutputScript,
505    #[error("Wrong tx out")]
506    WrongTxOut,
507}
508
509#[derive(Debug, Error, Encodable, Decodable, Hash, Clone, Eq, PartialEq)]
510pub enum WalletOutputError {
511    #[error("Connected bitcoind is on wrong network, expected {0}, got {1}")]
512    WrongNetwork(NetworkLegacyEncodingWrapper, NetworkLegacyEncodingWrapper),
513    #[error("Peg-out fee rate {0:?} is set below consensus {1:?}")]
514    PegOutFeeBelowConsensus(Feerate, Feerate),
515    #[error("Not enough SpendableUTXO")]
516    NotEnoughSpendableUTXO,
517    #[error("Peg out amount was under the dust limit")]
518    PegOutUnderDustLimit,
519    #[error("RBF transaction id not found")]
520    RbfTransactionIdNotFound,
521    #[error("Peg-out fee weight {0} doesn't match actual weight {1}")]
522    TxWeightIncorrect(u64, u64),
523    #[error("Peg-out fee rate is below min relay fee")]
524    BelowMinRelayFee,
525    #[error("The wallet output version is not supported by this federation")]
526    UnknownOutputVariant(#[from] UnknownWalletOutputVariantError),
527}
528
529// For backwards-compatibility with old clients, we use an UnknownOutputVariant
530// error when a client attempts a deprecated RBF withdrawal.
531// see: https://github.com/fedimint/fedimint/issues/5453
532pub const DEPRECATED_RBF_ERROR: WalletOutputError =
533    WalletOutputError::UnknownOutputVariant(UnknownWalletOutputVariantError { variant: 1 });
534
535#[derive(Debug, Error)]
536pub enum ProcessPegOutSigError {
537    #[error("No unsigned transaction with id {0} exists")]
538    UnknownTransaction(Txid),
539    #[error("Expected {0} signatures, got {1}")]
540    WrongSignatureCount(usize, usize),
541    #[error("Bad Sighash")]
542    SighashError,
543    #[error("Malformed signature: {0}")]
544    MalformedSignature(secp256k1::Error),
545    #[error("Invalid signature")]
546    InvalidSignature,
547    #[error("Duplicate signature")]
548    DuplicateSignature,
549    #[error("Missing change tweak")]
550    MissingOrMalformedChangeTweak,
551    #[error("Error finalizing PSBT {0:?}")]
552    ErrorFinalizingPsbt(Vec<miniscript::psbt::Error>),
553}
fedimint_wallet_common/lib.rs

fedimint_wallet_common/
lib.rs
