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 fn admin_auth(&self) -> Result<ApiAuth, MetaAdminError> {
61 self.admin_auth
62 .clone()
63 .ok_or(MetaAdminError::AdminAuthMissing)
64 }
65
66 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 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 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 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#[derive(Debug, Error)]
144#[non_exhaustive]
145pub enum MetaAdminError {
146 #[error("Admin auth not set")]
149 AdminAuthMissing,
150
151 #[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#[derive(Debug, Clone)]
187pub struct MetaClientContext {
188 pub meta_decoder: Decoder,
189}
190
191impl 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#[derive(Debug, Error)]
261enum RpcError {
262 #[error(transparent)]
264 Json(#[from] serde_json::Error),
265
266 #[error(transparent)]
268 Federation(#[from] FederationError),
269
270 #[error("deserializing consensus value as json")]
272 ConsensusValueJson(#[source] serde_json::Error),
273
274 #[error("Unknown method: {method}")]
276 UnknownMethod { method: String },
277}
278
279#[derive(Debug, Clone)]
280pub struct MetaClientInit;
281
282impl 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#[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#[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 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#[derive(Debug)]
382enum MetaModuleSource {
383 Consensus(MetaConsensusValue),
385 Legacy,
388 KeepStored(FederationError),
392}
393
394type 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 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;