fedimint_core/
core.rs

1//! Fedimint Core API (common) module interface
2//!
3//! Fedimint supports externally implemented modules.
4//!
5//! This (Rust) module defines common interoperability types
6//! and functionality that is used on both client and sever side.
7use core::fmt;
8use std::any::{Any, TypeId};
9use std::borrow::Cow;
10use std::collections::BTreeMap;
11use std::fmt::{Debug, Display, Formatter};
12use std::io::Read;
13use std::str::FromStr;
14use std::sync::Arc;
15
16use anyhow::anyhow;
17use bitcoin::hashes::{Hash, sha256};
18use fedimint_core::encoding::{Decodable, DecodeError, DynEncodable, Encodable};
19use fedimint_core::module::registry::ModuleDecoderRegistry;
20use rand::RngCore;
21use serde::{Deserialize, Deserializer, Serialize};
22
23use crate::module::registry::ModuleRegistry;
24use crate::{
25    erased_eq_no_instance_id, module_plugin_dyn_newtype_clone_passthrough,
26    module_plugin_dyn_newtype_define, module_plugin_dyn_newtype_display_passthrough,
27    module_plugin_dyn_newtype_encode_decode, module_plugin_dyn_newtype_eq_passthrough,
28    module_plugin_static_trait_define, module_plugin_static_trait_define_config,
29};
30
31pub mod backup;
32
33/// Unique identifier for one semantic, correlatable operation.
34///
35/// The concept of *operations* is used to avoid losing privacy while being as
36/// efficient as possible with regards to network requests.
37///
38/// For Fedimint transactions to be private users need to communicate with the
39/// federation using an anonymous communication network. If each API request was
40/// done in a way that it cannot be correlated to any other API request we would
41/// achieve privacy, but would reduce efficiency. E.g. on Tor we would need to
42/// open a new circuit for every request and open a new web socket connection.
43///
44/// Fortunately we do not need to do that to maintain privacy. Many API requests
45/// and transactions can be correlated by the federation anyway, in these cases
46/// it does not make any difference to re-use the same network connection. All
47/// requests, transactions, state machines that are connected from the
48/// federation's point of view anyway are grouped together as one *operation*.
49///
50/// # Choice of Operation ID
51///
52/// In cases where an operation is created by a new transaction that's being
53/// submitted the transaction's ID can be used as operation ID. If there is no
54/// transaction related to it, it should be generated randomly. Since it is a
55/// 256bit value collisions are impossible for all intents and purposes.
56#[derive(Clone, Copy, PartialEq, Eq, Hash, Encodable, Decodable, PartialOrd, Ord)]
57pub struct OperationId(pub [u8; 32]);
58
59#[cfg(feature = "uniffi")]
60uniffi::custom_type!(OperationId, String, {
61    lower: |obj| obj.fmt_full().to_string(),
62    try_lift: |s| OperationId::from_str(&s).map_err(|e| anyhow::anyhow!("Failed to parse OperationId from hex: {e}")),
63    }
64);
65
66pub struct OperationIdFullFmt<'a>(&'a OperationId);
67pub struct OperationIdShortFmt<'a>(&'a OperationId);
68
69impl OperationId {
70    /// Generate random [`OperationId`]
71    pub fn new_random() -> Self {
72        let mut rng = rand::thread_rng();
73        let mut bytes = [0u8; 32];
74        rng.fill_bytes(&mut bytes);
75        Self(bytes)
76    }
77
78    pub fn from_encodable<E: Encodable>(encodable: &E) -> Self {
79        Self(encodable.consensus_hash::<sha256::Hash>().to_byte_array())
80    }
81
82    pub fn fmt_short(&'_ self) -> OperationIdShortFmt<'_> {
83        OperationIdShortFmt(self)
84    }
85    pub fn fmt_full(&'_ self) -> OperationIdFullFmt<'_> {
86        OperationIdFullFmt(self)
87    }
88}
89
90impl Display for OperationIdShortFmt<'_> {
91    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
92        fedimint_core::format_hex(&self.0.0[0..4], f)?;
93        f.write_str("_")?;
94        fedimint_core::format_hex(&self.0.0[28..], f)?;
95        Ok(())
96    }
97}
98
99impl Display for OperationIdFullFmt<'_> {
100    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
101        fedimint_core::format_hex(&self.0.0, f)
102    }
103}
104
105impl Debug for OperationId {
106    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
107        write!(f, "OperationId({})", self.fmt_short())
108    }
109}
110
111impl FromStr for OperationId {
112    type Err = hex::FromHexError;
113
114    fn from_str(s: &str) -> Result<Self, Self::Err> {
115        let bytes: [u8; 32] = hex::FromHex::from_hex(s)?;
116        Ok(Self(bytes))
117    }
118}
119
120impl Serialize for OperationId {
121    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
122        if serializer.is_human_readable() {
123            serializer.serialize_str(&self.fmt_full().to_string())
124        } else {
125            serializer.serialize_bytes(&self.0)
126        }
127    }
128}
129
130impl<'de> Deserialize<'de> for OperationId {
131    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
132    where
133        D: Deserializer<'de>,
134    {
135        if deserializer.is_human_readable() {
136            let s = String::deserialize(deserializer)?;
137            let operation_id = Self::from_str(&s)
138                .map_err(|e| serde::de::Error::custom(format!("invalid operation id: {e}")))?;
139            Ok(operation_id)
140        } else {
141            let bytes: [u8; 32] = <[u8; 32]>::deserialize(deserializer)?;
142            Ok(Self(bytes))
143        }
144    }
145}
146
147/// Module instance ID
148///
149/// This value uniquely identifies a single instance of a module in a
150/// federation.
151///
152/// In case a single [`ModuleKind`] is instantiated twice (rare, but possible),
153/// each instance will have a different id.
154///
155/// Note: We have used this type differently before, assuming each `u16`
156/// uniquly identifies a type of module in question. This function will move
157/// to a `ModuleKind` type which only identifies type of a module (mint vs
158/// wallet vs ln, etc)
159// TODO: turn in a newtype
160pub type ModuleInstanceId = u16;
161
162/// Special IDs we use for global dkg
163pub const MODULE_INSTANCE_ID_GLOBAL: u16 = u16::MAX;
164
165/// A type of a module
166///
167/// This is a short string that identifies type of a module.
168/// Authors of 3rd party modules are free to come up with a string,
169/// long enough to avoid conflicts with similar modules.
170#[derive(PartialEq, Eq, Clone, PartialOrd, Ord, Serialize, Deserialize, Encodable, Decodable)]
171pub struct ModuleKind(Cow<'static, str>);
172
173#[cfg(feature = "uniffi")]
174uniffi::custom_type!(ModuleKind, String);
175
176impl ModuleKind {
177    pub fn clone_from_str(s: &str) -> Self {
178        Self(Cow::from(s.to_owned()))
179    }
180
181    pub const fn from_static_str(s: &'static str) -> Self {
182        Self(Cow::Borrowed(s))
183    }
184
185    pub fn as_str(&self) -> &str {
186        &self.0
187    }
188}
189
190impl From<ModuleKind> for String {
191    fn from(module_kind: ModuleKind) -> Self {
192        module_kind.0.into_owned()
193    }
194}
195
196impl From<String> for ModuleKind {
197    fn from(value: String) -> Self {
198        Self(Cow::Owned(value))
199    }
200}
201
202impl fmt::Display for ModuleKind {
203    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
204        std::fmt::Display::fmt(&self.0, f)
205    }
206}
207
208impl fmt::Debug for ModuleKind {
209    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
210        std::fmt::Display::fmt(&self.0, f)
211    }
212}
213
214impl From<&'static str> for ModuleKind {
215    fn from(val: &'static str) -> Self {
216        Self::from_static_str(val)
217    }
218}
219
220/// A type used by when decoding dyn-types, when the module is missing
221///
222/// This allows parsing and handling of dyn-types of modules which
223/// are not available.
224#[derive(Debug, Hash, PartialEq, Eq, Clone)]
225pub struct DynUnknown(pub Vec<u8>);
226
227impl fmt::Display for DynUnknown {
228    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
229        f.write_str(&self.0.consensus_encode_to_hex())
230    }
231}
232
233// Note: confusingly, while `DynUnknown` carries a `Vec`
234// it is actually not responsible for writing out the length of the data,
235// as the higher level (`module_plugin_dyn_newtype_encode_decode`) is doing
236// it, based on how many bytes are written here. That's why `DynUnknown` does
237// not implement `Decodable` directly, and `Vec` here has len only
238// for the purpose of knowing how many bytes to carry.
239impl Encodable for DynUnknown {
240    fn consensus_encode<W: std::io::Write>(&self, w: &mut W) -> Result<(), std::io::Error> {
241        w.write_all(&self.0[..])?;
242        Ok(())
243    }
244}
245
246/// A type that has a `Dyn*`, type erased version of itself
247pub trait IntoDynInstance {
248    /// The type erased version of the type implementing this trait
249    type DynType: 'static;
250
251    /// Convert `self` into its type-erased equivalent
252    fn into_dyn(self, instance_id: ModuleInstanceId) -> Self::DynType;
253}
254
255type DecodeFn = Box<
256    dyn for<'a> Fn(
257            Box<dyn Read + 'a>,
258            ModuleInstanceId,
259            &ModuleDecoderRegistry,
260        ) -> Result<Box<dyn Any>, DecodeError>
261        + Send
262        + Sync,
263>;
264
265#[derive(Default)]
266pub struct DecoderBuilder {
267    decode_fns: BTreeMap<TypeId, DecodeFn>,
268    transparent: bool,
269}
270
271impl DecoderBuilder {
272    pub fn build(self) -> Decoder {
273        Decoder {
274            decode_fns: Arc::new(self.decode_fns),
275        }
276    }
277
278    /// Attach decoder for a specific `Type`/`DynType` pair where `DynType =
279    /// <Type as IntoDynInstance>::DynType`.
280    ///
281    /// This allows calling `decode::<DynType>` on this decoder, returning a
282    /// `DynType` object which contains a `Type` object internally.
283    ///
284    /// **Caution**: One `Decoder` object should only contain decoders that
285    /// belong to the same [*module kind*](fedimint_core::core::ModuleKind).
286    ///
287    /// # Panics
288    /// * If multiple `Types` with the same `DynType` are added
289    pub fn with_decodable_type<Type>(&mut self)
290    where
291        Type: IntoDynInstance + Decodable,
292    {
293        let is_transparent_decoder = self.transparent;
294        // TODO: enforce that all decoders are for the same module kind (+fix docs
295        // after)
296        let decode_fn: DecodeFn = Box::new(
297            move |mut reader, instance, decoders: &ModuleDecoderRegistry| {
298                // TODO: Ideally `DynTypes` decoding couldn't ever be nested, so we could just
299                // pass empty `decoders`. But the client context uses nested `DynTypes` in
300                // `DynState`, so we special-case it with a flag.
301                let decoders = if is_transparent_decoder {
302                    decoders
303                } else {
304                    &ModuleRegistry::default()
305                };
306                let typed_val =
307                    Type::consensus_decode_partial(&mut reader, decoders).map_err(|err| {
308                        err.context(format!("while decoding Dyn type module_id={instance}"))
309                    })?;
310                let dyn_val = typed_val.into_dyn(instance);
311                let any_val: Box<dyn Any> = Box::new(dyn_val);
312                Ok(any_val)
313            },
314        );
315        if self
316            .decode_fns
317            .insert(TypeId::of::<Type::DynType>(), decode_fn)
318            .is_some()
319        {
320            panic!("Tried to add multiple decoders for the same DynType");
321        }
322    }
323}
324
325/// Consensus encoding decoder for module-specific types
326#[derive(Clone, Default)]
327pub struct Decoder {
328    decode_fns: Arc<BTreeMap<TypeId, DecodeFn>>,
329}
330
331impl Decoder {
332    /// Creates a `DecoderBuilder` to which decoders for single types can be
333    /// attached to build a `Decoder`.
334    pub fn builder() -> DecoderBuilder {
335        DecoderBuilder::default()
336    }
337
338    /// System Dyn-type, don't use.
339    #[doc(hidden)]
340    pub fn builder_system() -> DecoderBuilder {
341        DecoderBuilder {
342            transparent: true,
343            ..DecoderBuilder::default()
344        }
345    }
346
347    /// Decodes a specific `DynType` from the `reader` byte stream.
348    ///
349    /// # Panics
350    /// * If no decoder is registered for the `DynType`
351    pub fn decode_complete<DynType: Any>(
352        &self,
353        reader: &mut dyn Read,
354        total_len: u64,
355        module_id: ModuleInstanceId,
356        decoders: &ModuleDecoderRegistry,
357    ) -> Result<DynType, DecodeError> {
358        let mut reader = reader.take(total_len);
359
360        let val = self.decode_partial(&mut reader, module_id, decoders)?;
361        let left = reader.limit();
362
363        if left != 0 {
364            return Err(fedimint_core::encoding::DecodeError::custom(format!(
365                "Dyn type did not consume all bytes during decoding; module_id={module_id}; \
366                 expected={total_len}; left={left}; type={}",
367                std::any::type_name::<DynType>(),
368            )));
369        }
370
371        Ok(val)
372    }
373
374    /// Like [`Self::decode_complete`] but does not verify that all bytes were
375    /// consumed
376    pub fn decode_partial<DynType: Any>(
377        &self,
378        reader: &mut dyn Read,
379        module_id: ModuleInstanceId,
380        decoders: &ModuleDecoderRegistry,
381    ) -> Result<DynType, DecodeError> {
382        let decode_fn = self
383            .decode_fns
384            .get(&TypeId::of::<DynType>())
385            .ok_or_else(|| {
386                anyhow!(
387                    "Type unknown to decoder: {}, (registered decoders={})",
388                    std::any::type_name::<DynType>(),
389                    self.decode_fns.len()
390                )
391            })
392            .expect("Types being decoded must be registered");
393        Ok(*decode_fn(Box::new(reader), module_id, decoders)?
394            .downcast::<DynType>()
395            .expect("Decode fn returned wrong type, can't happen due to with_decodable_type"))
396    }
397}
398
399impl Debug for Decoder {
400    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
401        write!(f, "Decoder(registered_types = {})", self.decode_fns.len())
402    }
403}
404
405pub trait IClientConfig: Debug + Display + DynEncodable {
406    fn as_any(&self) -> &(dyn Any + Send + Sync);
407    fn module_kind(&self) -> Option<ModuleKind>;
408    fn clone(&self, instance_id: ModuleInstanceId) -> DynClientConfig;
409    fn dyn_hash(&self) -> u64;
410    fn erased_eq_no_instance_id(&self, other: &DynClientConfig) -> bool;
411    fn to_json(&self) -> Option<serde_json::Value>;
412}
413
414module_plugin_static_trait_define_config! {
415    DynClientConfig, ClientConfig, IClientConfig,
416    { },
417    {
418        erased_eq_no_instance_id!(DynClientConfig);
419
420        fn to_json(&self) -> Option<serde_json::Value> {
421            Some(serde_json::to_value(self.to_owned()).expect("serialization can't fail"))
422        }
423    },
424    {
425        erased_eq_no_instance_id!(DynClientConfig);
426
427        fn to_json(&self) -> Option<serde_json::Value> {
428            None
429        }
430    }
431}
432
433module_plugin_dyn_newtype_define! {
434    /// An owned, immutable input to a [`Transaction`](fedimint_core::transaction::Transaction)
435    pub DynClientConfig(Box<IClientConfig>)
436}
437module_plugin_dyn_newtype_encode_decode!(DynClientConfig);
438
439module_plugin_dyn_newtype_clone_passthrough!(DynClientConfig);
440
441module_plugin_dyn_newtype_eq_passthrough!(DynClientConfig);
442
443module_plugin_dyn_newtype_display_passthrough!(DynClientConfig);
444
445/// Something that can be an [`DynInput`] in a
446/// [`Transaction`](fedimint_core::transaction::Transaction)
447///
448/// General purpose code should use [`DynInput`] instead
449pub trait IInput: Debug + Display + DynEncodable {
450    fn as_any(&self) -> &(dyn Any + Send + Sync);
451    fn module_kind(&self) -> Option<ModuleKind>;
452    fn clone(&self, instance_id: ModuleInstanceId) -> DynInput;
453    fn dyn_hash(&self) -> u64;
454    fn erased_eq_no_instance_id(&self, other: &DynInput) -> bool;
455}
456
457module_plugin_static_trait_define! {
458    DynInput, Input, IInput,
459    { },
460    {
461        erased_eq_no_instance_id!(DynInput);
462    }
463}
464
465module_plugin_dyn_newtype_define! {
466    /// An owned, immutable input to a [`Transaction`](fedimint_core::transaction::Transaction)
467    pub DynInput(Box<IInput>)
468}
469module_plugin_dyn_newtype_encode_decode!(DynInput);
470
471module_plugin_dyn_newtype_clone_passthrough!(DynInput);
472
473module_plugin_dyn_newtype_eq_passthrough!(DynInput);
474
475module_plugin_dyn_newtype_display_passthrough!(DynInput);
476
477/// Something that can be an [`DynOutput`] in a
478/// [`Transaction`](fedimint_core::transaction::Transaction)
479///
480/// General purpose code should use [`DynOutput`] instead
481pub trait IOutput: Debug + Display + DynEncodable {
482    fn as_any(&self) -> &(dyn Any + Send + Sync);
483    fn module_kind(&self) -> Option<ModuleKind>;
484    fn clone(&self, instance_id: ModuleInstanceId) -> DynOutput;
485    fn dyn_hash(&self) -> u64;
486    fn erased_eq_no_instance_id(&self, other: &DynOutput) -> bool;
487}
488
489module_plugin_dyn_newtype_define! {
490    /// An owned, immutable output of a [`Transaction`](fedimint_core::transaction::Transaction)
491    pub DynOutput(Box<IOutput>)
492}
493module_plugin_static_trait_define! {
494    DynOutput, Output, IOutput,
495    { },
496    {
497        erased_eq_no_instance_id!(DynOutput);
498    }
499}
500module_plugin_dyn_newtype_encode_decode!(DynOutput);
501
502module_plugin_dyn_newtype_clone_passthrough!(DynOutput);
503
504module_plugin_dyn_newtype_eq_passthrough!(DynOutput);
505
506module_plugin_dyn_newtype_display_passthrough!(DynOutput);
507
508pub enum FinalizationError {
509    SomethingWentWrong,
510}
511
512pub trait IOutputOutcome: Debug + Display + DynEncodable {
513    fn as_any(&self) -> &(dyn Any + Send + Sync);
514    fn module_kind(&self) -> Option<ModuleKind>;
515    fn clone(&self, module_instance_id: ModuleInstanceId) -> DynOutputOutcome;
516    fn dyn_hash(&self) -> u64;
517    fn erased_eq_no_instance_id(&self, other: &DynOutputOutcome) -> bool;
518}
519
520module_plugin_dyn_newtype_define! {
521    /// An owned, immutable output of a [`Transaction`](fedimint_core::transaction::Transaction) before it was finalized
522    pub DynOutputOutcome(Box<IOutputOutcome>)
523}
524module_plugin_static_trait_define! {
525    DynOutputOutcome, OutputOutcome, IOutputOutcome,
526    { },
527    {
528        erased_eq_no_instance_id!(DynOutputOutcome);
529    }
530}
531module_plugin_dyn_newtype_encode_decode!(DynOutputOutcome);
532module_plugin_dyn_newtype_clone_passthrough!(DynOutputOutcome);
533module_plugin_dyn_newtype_eq_passthrough!(DynOutputOutcome);
534module_plugin_dyn_newtype_display_passthrough!(DynOutputOutcome);
535
536pub trait IModuleConsensusItem: Debug + Display + DynEncodable {
537    fn as_any(&self) -> &(dyn Any + Send + Sync);
538    fn module_kind(&self) -> Option<ModuleKind>;
539    fn clone(&self, module_instance_id: ModuleInstanceId) -> DynModuleConsensusItem;
540    fn dyn_hash(&self) -> u64;
541
542    fn erased_eq_no_instance_id(&self, other: &DynModuleConsensusItem) -> bool;
543}
544
545module_plugin_dyn_newtype_define! {
546    /// An owned, immutable output of a [`Transaction`](fedimint_core::transaction::Transaction) before it was finalized
547    pub DynModuleConsensusItem(Box<IModuleConsensusItem>)
548}
549module_plugin_static_trait_define! {
550    DynModuleConsensusItem, ModuleConsensusItem, IModuleConsensusItem,
551    { },
552    {
553        erased_eq_no_instance_id!(DynModuleConsensusItem);
554    }
555}
556module_plugin_dyn_newtype_encode_decode!(DynModuleConsensusItem);
557
558module_plugin_dyn_newtype_clone_passthrough!(DynModuleConsensusItem);
559
560module_plugin_dyn_newtype_eq_passthrough!(DynModuleConsensusItem);
561
562module_plugin_dyn_newtype_display_passthrough!(DynModuleConsensusItem);
563
564pub trait IOutputError: Debug + Display + DynEncodable {
565    fn as_any(&self) -> &(dyn Any + Send + Sync);
566    fn module_kind(&self) -> Option<ModuleKind>;
567    fn clone(&self, module_instance_id: ModuleInstanceId) -> DynOutputError;
568    fn dyn_hash(&self) -> u64;
569
570    fn erased_eq_no_instance_id(&self, other: &DynOutputError) -> bool;
571}
572
573module_plugin_dyn_newtype_define! {
574    pub DynOutputError(Box<IOutputError>)
575}
576module_plugin_static_trait_define! {
577    DynOutputError, OutputError, IOutputError,
578    { },
579    {
580        erased_eq_no_instance_id!(DynOutputError);
581    }
582}
583module_plugin_dyn_newtype_encode_decode!(DynOutputError);
584
585module_plugin_dyn_newtype_clone_passthrough!(DynOutputError);
586
587module_plugin_dyn_newtype_eq_passthrough!(DynOutputError);
588
589module_plugin_dyn_newtype_display_passthrough!(DynOutputError);
590
591pub trait IInputError: Debug + Display + DynEncodable {
592    fn as_any(&self) -> &(dyn Any + Send + Sync);
593    fn module_kind(&self) -> Option<ModuleKind>;
594    fn clone(&self, module_instance_id: ModuleInstanceId) -> DynInputError;
595    fn dyn_hash(&self) -> u64;
596
597    fn erased_eq_no_instance_id(&self, other: &DynInputError) -> bool;
598}
599
600module_plugin_dyn_newtype_define! {
601    pub DynInputError(Box<IInputError>)
602}
603module_plugin_static_trait_define! {
604    DynInputError, InputError, IInputError,
605    { },
606    {
607        erased_eq_no_instance_id!(DynInputError);
608    }
609}
610module_plugin_dyn_newtype_encode_decode!(DynInputError);
611
612module_plugin_dyn_newtype_clone_passthrough!(DynInputError);
613
614module_plugin_dyn_newtype_eq_passthrough!(DynInputError);
615
616module_plugin_dyn_newtype_display_passthrough!(DynInputError);
fedimint_core/core.rs

fedimint_core/
core.rs
