Skip to main content

fedimint_meta_client/
lib.rs

1#![deny(clippy::pedantic)]
2#![allow(clippy::missing_errors_doc)]
3#![allow(clippy::module_name_repetitions)]
4
5pub mod api;
6#[cfg(feature = "cli")]
7pub mod cli;
8pub mod db;
9pub mod states;
10
11use std::collections::BTreeMap;
12use std::time::Duration;
13
14use api::MetaFederationApi;
15use common::{KIND, MetaConsensusValue, MetaKey, MetaValue};
16use db::DbKeyPrefix;
17use fedimint_api_client::api::{DynGlobalApi, DynModuleApi, FederationError};
18use fedimint_client_module::db::ClientModuleMigrationFn;
19use fedimint_client_module::error::{ClientModuleError, MetaFetchError};
20use fedimint_client_module::meta::{
21    FetchKind, LegacyMetaSource, MetaFieldKey, MetaFieldValue, MetaSource, MetaValues,
22};
23use fedimint_client_module::module::init::{ClientModuleInit, ClientModuleInitArgs};
24use fedimint_client_module::module::recovery::NoModuleBackup;
25use fedimint_client_module::module::{ClientModule, IClientModule};
26use fedimint_client_module::sm::Context;
27use fedimint_core::config::{ClientConfig, META_FEDERATION_NAME_KEY};
28use fedimint_core::core::{Decoder, ModuleKind};
29use fedimint_core::db::{DatabaseTransaction, DatabaseVersion};
30use fedimint_core::module::{
31    Amounts, ApiAuth, ApiVersion, ModuleCommon, ModuleInit, MultiApiVersion,
32};
33use fedimint_core::util::backoff_util::FibonacciBackoff;
34use fedimint_core::util::{BoxStream, backoff_util, retry};
35use fedimint_core::{PeerId, apply, async_trait_maybe_send};
36use fedimint_logging::LOG_CLIENT_MODULE_META;
37pub use fedimint_meta_common as common;
38use fedimint_meta_common::{DEFAULT_META_KEY, MetaCommonInit, MetaModuleTypes};
39use futures::{TryStreamExt as _, stream};
40use serde::Deserialize;
41use serde_json::json;
42use states::MetaStateMachine;
43use strum::IntoEnumIterator;
44use thiserror::Error;
45use tracing::{debug, warn};
46
47#[derive(Debug)]
48pub struct MetaClientModule {
49    module_api: DynModuleApi,
50    admin_auth: Option<ApiAuth>,
51}
52
53impl MetaClientModule {
54    /// The admin credentials this client was built with.
55    ///
56    /// # Errors
57    ///
58    /// Fails with [`MetaAdminError::AdminAuthMissing`] if the client was built
59    /// without them.
60    fn admin_auth(&self) -> Result<ApiAuth, MetaAdminError> {
61        self.admin_auth
62            .clone()
63            .ok_or(MetaAdminError::AdminAuthMissing)
64    }
65
66    /// Submit a meta consensus value
67    ///
68    /// When *threshold* amount of peers submits the exact same value it
69    /// becomes a new consensus value.
70    ///
71    /// To "cancel" previous vote, peer can submit a value equal to the current
72    /// consensus value.
73    ///
74    /// # Errors
75    ///
76    /// Fails with [`MetaAdminError::AdminAuthMissing`] if this client holds no
77    /// admin credentials, and with [`MetaAdminError::Federation`] if the
78    /// guardians could not be asked to record the vote.
79    pub async fn submit(&self, key: MetaKey, value: MetaValue) -> Result<(), MetaAdminError> {
80        self.module_api
81            .submit(key, value, self.admin_auth()?)
82            .await?;
83
84        Ok(())
85    }
86
87    /// Get the current meta consensus value along with it's revision
88    ///
89    /// See [`Self::get_consensus_value_rev`] to use when checking for updates.
90    ///
91    /// # Errors
92    ///
93    /// Fails with a [`FederationError`] if the federation could not be asked
94    /// for the value.
95    pub async fn get_consensus_value(
96        &self,
97        key: MetaKey,
98    ) -> Result<Option<MetaConsensusValue>, FederationError> {
99        self.module_api.get_consensus(key).await
100    }
101
102    /// Get the current meta consensus value revision
103    ///
104    /// Each time a meta consensus value changes, the revision increases,
105    /// so checking just the revision can save a lot of bandwidth in periodic
106    /// checks.
107    ///
108    /// # Errors
109    ///
110    /// Fails with a [`FederationError`] if the federation could not be asked
111    /// for the revision.
112    pub async fn get_consensus_value_rev(
113        &self,
114        key: MetaKey,
115    ) -> Result<Option<u64>, FederationError> {
116        self.module_api.get_consensus_rev(key).await
117    }
118
119    /// Get current submissions to change the meta consensus value.
120    ///
121    /// Upon changing the consensus
122    ///
123    /// # Errors
124    ///
125    /// Fails with [`MetaAdminError::AdminAuthMissing`] if this client holds no
126    /// admin credentials, and with [`MetaAdminError::Federation`] if the
127    /// guardians could not be asked for their submissions.
128    pub async fn get_submissions(
129        &self,
130        key: MetaKey,
131    ) -> Result<BTreeMap<PeerId, MetaValue>, MetaAdminError> {
132        Ok(self
133            .module_api
134            .get_submissions(key, self.admin_auth()?)
135            .await?)
136    }
137}
138
139/// A failure of one of the meta client's guardian-only operations.
140///
141/// These endpoints can fail before any request leaves the client, when it
142/// holds no admin credentials, as well as while talking to the federation.
143#[derive(Debug, Error)]
144#[non_exhaustive]
145pub enum MetaAdminError {
146    /// This client was not built with admin credentials, so it cannot call a
147    /// guardian-only endpoint.
148    #[error("Admin auth not set")]
149    AdminAuthMissing,
150
151    /// The federation rejected the request, or could not be reached.
152    #[error("The federation request failed")]
153    Federation(#[source] Box<FederationError>),
154}
155
156impl From<FederationError> for MetaAdminError {
157    fn from(source: FederationError) -> Self {
158        Self::Federation(Box::new(source))
159    }
160}
161
162#[derive(Debug, Deserialize)]
163struct GetConsensusValueRequest {
164    key: MetaKey,
165}
166
167fn format_rpc_consensus_value_response(
168    maybe_consensus_value: Option<MetaConsensusValue>,
169) -> Result<serde_json::Value, RpcError> {
170    Ok(match maybe_consensus_value {
171        Some(MetaConsensusValue { revision, value }) => {
172            let value = value
173                .to_json_lossy()
174                .map_err(RpcError::ConsensusValueJson)?;
175
176            json!({
177                "revision": revision,
178                "value": value,
179            })
180        }
181        None => serde_json::Value::Null,
182    })
183}
184
185/// Data needed by the state machine
186#[derive(Debug, Clone)]
187pub struct MetaClientContext {
188    pub meta_decoder: Decoder,
189}
190
191// TODO: Boiler-plate
192impl Context for MetaClientContext {
193    const KIND: Option<ModuleKind> = Some(KIND);
194}
195
196#[apply(async_trait_maybe_send!)]
197impl ClientModule for MetaClientModule {
198    type Init = MetaClientInit;
199    type Common = MetaModuleTypes;
200    type Backup = NoModuleBackup;
201    type ModuleStateMachineContext = MetaClientContext;
202    type States = MetaStateMachine;
203
204    fn context(&self) -> Self::ModuleStateMachineContext {
205        MetaClientContext {
206            meta_decoder: self.decoder(),
207        }
208    }
209
210    fn input_fee(
211        &self,
212        _amount: &Amounts,
213        _input: &<Self::Common as ModuleCommon>::Input,
214    ) -> Option<Amounts> {
215        unreachable!()
216    }
217
218    fn output_fee(
219        &self,
220        _amount: &Amounts,
221        _output: &<Self::Common as ModuleCommon>::Output,
222    ) -> Option<Amounts> {
223        unreachable!()
224    }
225
226    async fn handle_rpc(
227        &self,
228        method: String,
229        request: serde_json::Value,
230    ) -> BoxStream<'_, Result<serde_json::Value, ClientModuleError>> {
231        Box::pin(
232            stream::once(async move {
233                match method.as_str() {
234                    "get_consensus_value" => {
235                        let req: GetConsensusValueRequest = serde_json::from_value(request)?;
236                        let maybe_consensus_value = self.get_consensus_value(req.key).await?;
237                        format_rpc_consensus_value_response(maybe_consensus_value)
238                    }
239                    _ => Err(RpcError::UnknownMethod {
240                        method: method.clone(),
241                    }),
242                }
243            })
244            .map_err(ClientModuleError::other),
245        )
246    }
247
248    #[cfg(feature = "cli")]
249    async fn handle_cli_command(
250        &self,
251        args: &[std::ffi::OsString],
252    ) -> Result<serde_json::Value, ClientModuleError> {
253        cli::handle_cli_command(self, args)
254            .await
255            .map_err(ClientModuleError::other)
256    }
257}
258
259/// A failure of a meta module RPC request.
260#[derive(Debug, Error)]
261enum RpcError {
262    /// The request's parameters do not fit the method.
263    #[error(transparent)]
264    Json(#[from] serde_json::Error),
265
266    /// The federation did not serve the request.
267    #[error(transparent)]
268    Federation(#[from] FederationError),
269
270    /// The consensus value is not valid JSON.
271    #[error("deserializing consensus value as json")]
272    ConsensusValueJson(#[source] serde_json::Error),
273
274    /// The request names a method the module does not have.
275    #[error("Unknown method: {method}")]
276    UnknownMethod { method: String },
277}
278
279#[derive(Debug, Clone)]
280pub struct MetaClientInit;
281
282// TODO: Boilerplate-code
283impl ModuleInit for MetaClientInit {
284    type Common = MetaCommonInit;
285
286    async fn dump_database(
287        &self,
288        _dbtx: &mut DatabaseTransaction<'_>,
289        prefix_names: Vec<String>,
290    ) -> Box<dyn Iterator<Item = (String, Box<dyn erased_serde::Serialize + Send>)> + '_> {
291        let items: BTreeMap<String, Box<dyn erased_serde::Serialize + Send>> = BTreeMap::new();
292        let filtered_prefixes = DbKeyPrefix::iter().filter(|f| {
293            prefix_names.is_empty() || prefix_names.contains(&f.to_string().to_lowercase())
294        });
295
296        #[allow(clippy::never_loop)]
297        for table in filtered_prefixes {
298            match table {}
299        }
300
301        Box::new(items.into_iter())
302    }
303}
304
305/// Generates the client module
306#[apply(async_trait_maybe_send!)]
307impl ClientModuleInit for MetaClientInit {
308    type Module = MetaClientModule;
309
310    fn supported_api_versions(&self) -> MultiApiVersion {
311        MultiApiVersion::try_from_iter([ApiVersion { major: 0, minor: 0 }])
312            .expect("no version conflicts")
313    }
314
315    async fn init(
316        &self,
317        args: &ClientModuleInitArgs<Self>,
318    ) -> Result<Self::Module, ClientModuleError> {
319        Ok(MetaClientModule {
320            module_api: args.module_api().clone(),
321            admin_auth: args.admin_auth().cloned(),
322        })
323    }
324
325    fn get_database_migrations(&self) -> BTreeMap<DatabaseVersion, ClientModuleMigrationFn> {
326        BTreeMap::new()
327    }
328}
329
330/// Meta source fetching meta values from the meta module if available or the
331/// legacy meta source otherwise.
332#[derive(Clone, Debug, Default)]
333pub struct MetaModuleMetaSourceWithFallback<S = LegacyMetaSource> {
334    legacy: S,
335}
336
337impl<S> MetaModuleMetaSourceWithFallback<S> {
338    pub fn new(legacy: S) -> Self {
339        Self { legacy }
340    }
341}
342
343#[apply(async_trait_maybe_send!)]
344impl<S: MetaSource> MetaSource for MetaModuleMetaSourceWithFallback<S> {
345    async fn wait_for_update(&self) {
346        fedimint_core::runtime::sleep(Duration::from_mins(10)).await;
347    }
348
349    async fn fetch(
350        &self,
351        client_config: &ClientConfig,
352        api: &DynGlobalApi,
353        fetch_kind: fedimint_client_module::meta::FetchKind,
354        last_revision: Option<u64>,
355    ) -> Result<fedimint_client_module::meta::MetaValues, MetaFetchError> {
356        let backoff = match fetch_kind {
357            // need to be fast the first time.
358            FetchKind::Initial => backoff_util::aggressive_backoff(),
359            FetchKind::Background => backoff_util::background_backoff(),
360        };
361
362        match meta_module_source(
363            get_meta_module_value(client_config, api, backoff).await,
364            last_revision,
365        ) {
366            MetaModuleSource::Consensus(meta) => Ok(MetaValues {
367                values: parse_meta_values(meta.value.as_slice())?,
368                revision: meta.revision,
369            }),
370            MetaModuleSource::Legacy => {
371                self.legacy
372                    .fetch(client_config, api, fetch_kind, last_revision)
373                    .await
374            }
375            MetaModuleSource::KeepStored(error) => Err(MetaFetchError::Custom(Box::new(error))),
376        }
377    }
378}
379
380/// Where [`MetaModuleMetaSourceWithFallback`] takes the meta values from.
381#[derive(Debug)]
382enum MetaModuleSource {
383    /// The meta module's consensus value.
384    Consensus(MetaConsensusValue),
385    /// The legacy source: the federation has no meta module or no value in
386    /// it, or the module could not be reached and nothing is stored yet.
387    Legacy,
388    /// The module could not be reached. Keep the stored values: the legacy
389    /// values would replace the federation's current meta with stale config
390    /// values until the next successful fetch.
391    KeepStored(FederationError),
392}
393
394/// `None` when the federation has no meta module.
395type MetaModuleValue = Option<Result<Option<MetaConsensusValue>, FederationError>>;
396
397fn meta_module_source(value: MetaModuleValue, last_revision: Option<u64>) -> MetaModuleSource {
398    match value {
399        Some(Ok(Some(consensus))) => MetaModuleSource::Consensus(consensus),
400        Some(Err(error)) if last_revision.is_some() => MetaModuleSource::KeepStored(error),
401        None | Some(Ok(None) | Err(_)) => MetaModuleSource::Legacy,
402    }
403}
404
405fn parse_meta_values(
406    value: &[u8],
407) -> Result<BTreeMap<MetaFieldKey, MetaFieldValue>, serde_json::Error> {
408    let json: serde_json::Value = serde_json::from_slice(value)?;
409    let mut values: BTreeMap<MetaFieldKey, MetaFieldValue> = serde_json::from_value(json.clone())?;
410    // Other metadata fields retain the legacy JSON-string unwrapping behavior,
411    // but a federation name is a literal string, even if it looks like JSON.
412    if let Some(name) = json.get(META_FEDERATION_NAME_KEY) {
413        values.insert(
414            MetaFieldKey(META_FEDERATION_NAME_KEY.to_owned()),
415            MetaFieldValue(name.clone()),
416        );
417    }
418    Ok(values)
419}
420
421async fn get_meta_module_value(
422    client_config: &ClientConfig,
423    api: &DynGlobalApi,
424    backoff: FibonacciBackoff,
425) -> MetaModuleValue {
426    let (instance_id, _) = client_config.get_first_module_by_kind_cfg(KIND).ok()?;
427    let meta_api = api.with_module(instance_id);
428    let consensus = retry("fetch_meta_values", backoff, || async {
429        meta_api.get_consensus(DEFAULT_META_KEY).await
430    })
431    .await
432    .inspect_err(|e| {
433        warn!(target: LOG_CLIENT_MODULE_META, "Failed to fetch meta module consensus value: {}", e);
434    });
435    if let Ok(None) = consensus {
436        debug!(target: LOG_CLIENT_MODULE_META, "Meta module returned no consensus value");
437    }
438    Some(consensus)
439}
440
441#[cfg(test)]
442mod tests;