iota_config/
node.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{
6    collections::{BTreeMap, BTreeSet},
7    net::{IpAddr, Ipv4Addr, SocketAddr},
8    num::NonZeroUsize,
9    path::{Path, PathBuf},
10    sync::Arc,
11    time::Duration,
12};
13
14use anyhow::Result;
15use consensus_config::Parameters as ConsensusParameters;
16use iota_keys::keypair_file::{read_authority_keypair_from_file, read_keypair_from_file};
17use iota_names::config::IotaNamesConfig;
18use iota_types::{
19    base_types::IotaAddress,
20    committee::EpochId,
21    crypto::{
22        AccountKeyPair, AuthorityKeyPair, AuthorityPublicKeyBytes, IotaKeyPair, KeypairTraits,
23        NetworkKeyPair, get_key_pair_from_rng,
24    },
25    messages_checkpoint::CheckpointSequenceNumber,
26    multiaddr::Multiaddr,
27    supported_protocol_versions::{Chain, SupportedProtocolVersions},
28    traffic_control::{PolicyConfig, RemoteFirewallConfig},
29};
30use once_cell::sync::OnceCell;
31use rand::rngs::OsRng;
32use serde::{Deserialize, Serialize};
33use tracing::info;
34
35use crate::{
36    Config, certificate_deny_config::CertificateDenyConfig, genesis,
37    migration_tx_data::MigrationTxData, object_storage_config::ObjectStoreConfig, p2p::P2pConfig,
38    transaction_deny_config::TransactionDenyConfig, verifier_signing_config::VerifierSigningConfig,
39};
40
41// Default max number of concurrent requests served
42pub const DEFAULT_GRPC_CONCURRENCY_LIMIT: usize = 20000000000;
43
44/// Default gas price of 1000 Nanos
45pub const DEFAULT_VALIDATOR_GAS_PRICE: u64 = iota_types::transaction::DEFAULT_VALIDATOR_GAS_PRICE;
46
47/// Default commission rate of 2%
48pub const DEFAULT_COMMISSION_RATE: u64 = 200;
49
50#[derive(Clone, Debug, Deserialize, Serialize)]
51#[serde(rename_all = "kebab-case")]
52pub struct NodeConfig {
53    /// The public key bytes corresponding to the private key that the validator
54    /// holds to sign transactions.
55    #[serde(default = "default_authority_key_pair")]
56    pub authority_key_pair: AuthorityKeyPairWithPath,
57    /// The public key bytes corresponding to the private key that the validator
58    /// holds to sign consensus blocks.
59    #[serde(default = "default_key_pair")]
60    pub protocol_key_pair: KeyPairWithPath,
61    #[serde(default = "default_key_pair")]
62    pub account_key_pair: KeyPairWithPath,
63    /// The public key bytes corresponding to the private key that the validator
64    /// uses to establish TLS connections.
65    #[serde(default = "default_key_pair")]
66    pub network_key_pair: KeyPairWithPath,
67    pub db_path: PathBuf,
68
69    /// The network address for gRPC communication.
70    ///
71    /// Can be overwritten with args `listen-address` parameters.
72    #[serde(default = "default_grpc_address")]
73    pub network_address: Multiaddr,
74    #[serde(default = "default_json_rpc_address")]
75    pub json_rpc_address: SocketAddr,
76
77    /// Flag to enable the REST API under `/api/v1`
78    /// endpoint on the same interface as `json` `rpc` server.
79    #[serde(default)]
80    pub enable_rest_api: bool,
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub rest: Option<iota_rest_api::Config>,
83
84    /// The address for Prometheus metrics.
85    #[serde(default = "default_metrics_address")]
86    pub metrics_address: SocketAddr,
87
88    /// The address for the admin interface that is
89    /// run in the metrics separate runtime and provides access to
90    /// admin node commands such as logging and tracing options.
91    #[serde(default = "default_admin_interface_address")]
92    pub admin_interface_address: SocketAddr,
93
94    /// Configuration struct for the consensus.
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub consensus_config: Option<ConsensusConfig>,
97
98    /// Flag to enable index processing for a full node.
99    ///
100    /// If set to true, node creates `IndexStore` for transaction
101    /// data including ownership and balance information.
102    #[serde(default = "default_enable_index_processing")]
103    pub enable_index_processing: bool,
104
105    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
106    pub remove_deprecated_tables: bool,
107
108    // only allow websocket connections for jsonrpc traffic
109    #[serde(default)]
110    /// Determines the jsonrpc server type as either:
111    /// - 'websocket' for a websocket based service (deprecated)
112    /// - 'http' for an http based service
113    /// - 'both' for both a websocket and http based service (deprecated)
114    pub jsonrpc_server_type: Option<ServerType>,
115
116    /// Flag to enable gRPC load shedding to manage and
117    /// mitigate overload conditions by shedding excess
118    /// load with `LoadShedLayer` middleware.
119    #[serde(default)]
120    pub grpc_load_shed: Option<bool>,
121
122    #[serde(default = "default_concurrency_limit")]
123    pub grpc_concurrency_limit: Option<usize>,
124
125    /// Configuration struct for P2P.
126    #[serde(default)]
127    pub p2p_config: P2pConfig,
128
129    /// Contains genesis location that might be `InPlace`
130    /// for reading all genesis data to memory or `InFile`,
131    /// and `OnceCell` pointer to a genesis struct.
132    pub genesis: Genesis,
133
134    /// Contains the path where to find the migration blob.
135    pub migration_tx_data_path: Option<PathBuf>,
136
137    /// Configuration for pruning of the authority store, to define when
138    /// an old data is removed from the storage space.
139    #[serde(default = "default_authority_store_pruning_config")]
140    pub authority_store_pruning_config: AuthorityStorePruningConfig,
141
142    /// Size of the broadcast channel used for notifying other systems of end of
143    /// epoch.
144    ///
145    /// If unspecified, this will default to `128`.
146    #[serde(default = "default_end_of_epoch_broadcast_channel_capacity")]
147    pub end_of_epoch_broadcast_channel_capacity: usize,
148
149    /// Configuration for the checkpoint executor for limiting
150    /// the number of checkpoints to execute concurrently,
151    /// and to allow for checkpoint post-processing.
152    #[serde(default)]
153    pub checkpoint_executor_config: CheckpointExecutorConfig,
154
155    #[serde(skip_serializing_if = "Option::is_none")]
156    pub metrics: Option<MetricsConfig>,
157
158    /// In a `iota-node` binary, this is set to
159    /// SupportedProtocolVersions::SYSTEM_DEFAULT in iota-node/src/main.rs.
160    /// It is present in the config so that it can be changed by tests in
161    /// order to test protocol upgrades.
162    #[serde(skip)]
163    pub supported_protocol_versions: Option<SupportedProtocolVersions>,
164
165    /// Configuration to manage database checkpoints,
166    /// including whether to perform checkpoints at the end of an epoch,
167    /// the path for storing checkpoints, and other related settings.
168    #[serde(default)]
169    pub db_checkpoint_config: DBCheckpointConfig,
170
171    /// Configuration for enabling/disabling expensive safety checks.
172    #[serde(default)]
173    pub expensive_safety_check_config: ExpensiveSafetyCheckConfig,
174
175    /// Configuration to specify rules for denying transactions
176    /// based on `objectsIDs`, `addresses`, or enable/disable many
177    /// features such as publishing new packages or using shared objects.
178    #[serde(default)]
179    pub transaction_deny_config: TransactionDenyConfig,
180
181    /// Config used to deny execution for certificate digests
182    /// know for crashing or hanging validator nodes.
183    ///
184    /// Should be used for a fast temporary fixes and
185    /// removed once the issue is fixed.
186    #[serde(default)]
187    pub certificate_deny_config: CertificateDenyConfig,
188
189    /// Used to determine how state debug information is dumped
190    /// when a node forks.
191    #[serde(default)]
192    pub state_debug_dump_config: StateDebugDumpConfig,
193
194    /// Configuration for writing state archive. If `ObjectStorage`
195    /// config is provided, `ArchiveWriter` will be created
196    /// for checkpoints archival.
197    #[serde(default)]
198    pub state_archive_write_config: StateArchiveConfig,
199
200    #[serde(default)]
201    pub state_archive_read_config: Vec<StateArchiveConfig>,
202
203    /// Determines if snapshot should be uploaded to the remote storage.
204    #[serde(default)]
205    pub state_snapshot_write_config: StateSnapshotConfig,
206
207    #[serde(default)]
208    pub indexer_max_subscriptions: Option<usize>,
209
210    #[serde(default = "default_transaction_kv_store_config")]
211    pub transaction_kv_store_read_config: TransactionKeyValueStoreReadConfig,
212
213    // TODO: write config seem to be unused.
214    #[serde(skip_serializing_if = "Option::is_none")]
215    pub transaction_kv_store_write_config: Option<TransactionKeyValueStoreWriteConfig>,
216
217    #[serde(default = "default_jwk_fetch_interval_seconds")]
218    pub jwk_fetch_interval_seconds: u64,
219
220    #[serde(default = "default_zklogin_oauth_providers")]
221    pub zklogin_oauth_providers: BTreeMap<Chain, BTreeSet<String>>,
222
223    /// Configuration for defining thresholds and settings
224    /// for managing system overload conditions in a node.
225    #[serde(default = "default_authority_overload_config")]
226    pub authority_overload_config: AuthorityOverloadConfig,
227
228    /// Specifies the ending epoch for a node for debugging purposes.
229    ///
230    ///  Ignored if set by config, can be configured only by cli arguments.
231    #[serde(skip_serializing_if = "Option::is_none")]
232    pub run_with_range: Option<RunWithRange>,
233
234    // For killswitch use None
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub policy_config: Option<PolicyConfig>,
237
238    #[serde(skip_serializing_if = "Option::is_none")]
239    pub firewall_config: Option<RemoteFirewallConfig>,
240
241    #[serde(default)]
242    pub execution_cache: ExecutionCacheType,
243
244    #[serde(default)]
245    pub execution_cache_config: ExecutionCacheConfig,
246
247    #[serde(default = "bool_true")]
248    pub enable_validator_tx_finalizer: bool,
249
250    #[serde(default)]
251    pub verifier_signing_config: VerifierSigningConfig,
252
253    /// If a value is set, it determines if writes to DB can stall, which can
254    /// halt the whole process. By default, write stall is enabled on
255    /// validators but not on fullnodes.
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub enable_db_write_stall: Option<bool>,
258
259    #[serde(default, skip_serializing_if = "Option::is_none")]
260    pub iota_names_config: Option<IotaNamesConfig>,
261}
262
263#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
264#[serde(rename_all = "kebab-case")]
265pub enum ExecutionCacheType {
266    #[default]
267    WritebackCache,
268    PassthroughCache,
269}
270
271impl From<ExecutionCacheType> for u8 {
272    fn from(cache_type: ExecutionCacheType) -> Self {
273        match cache_type {
274            ExecutionCacheType::WritebackCache => 0,
275            ExecutionCacheType::PassthroughCache => 1,
276        }
277    }
278}
279
280impl From<&u8> for ExecutionCacheType {
281    fn from(cache_type: &u8) -> Self {
282        match cache_type {
283            0 => ExecutionCacheType::WritebackCache,
284            1 => ExecutionCacheType::PassthroughCache,
285            _ => unreachable!("Invalid value for ExecutionCacheType"),
286        }
287    }
288}
289
290/// Type alias for atomic representation of ExecutionCacheType for lock-free
291/// operations
292pub type ExecutionCacheTypeAtomicU8 = std::sync::atomic::AtomicU8;
293
294impl From<ExecutionCacheType> for ExecutionCacheTypeAtomicU8 {
295    fn from(cache_type: ExecutionCacheType) -> Self {
296        ExecutionCacheTypeAtomicU8::new(u8::from(cache_type))
297    }
298}
299
300impl ExecutionCacheType {
301    pub fn cache_type(self) -> Self {
302        if std::env::var("DISABLE_WRITEBACK_CACHE").is_ok() {
303            Self::PassthroughCache
304        } else {
305            self
306        }
307    }
308}
309
310#[derive(Clone, Debug, Default, Deserialize, Serialize)]
311#[serde(rename_all = "kebab-case")]
312pub struct ExecutionCacheConfig {
313    #[serde(default)]
314    pub writeback_cache: WritebackCacheConfig,
315}
316
317#[derive(Clone, Debug, Default, Deserialize, Serialize)]
318#[serde(rename_all = "kebab-case")]
319pub struct WritebackCacheConfig {
320    /// Maximum number of entries in each cache. (There are several
321    /// different caches).
322    #[serde(default, skip_serializing_if = "Option::is_none")]
323    pub max_cache_size: Option<u64>, // defaults to 100000
324
325    #[serde(default, skip_serializing_if = "Option::is_none")]
326    pub package_cache_size: Option<u64>, // defaults to 1000
327
328    #[serde(default, skip_serializing_if = "Option::is_none")]
329    pub object_cache_size: Option<u64>, // defaults to max_cache_size
330    #[serde(default, skip_serializing_if = "Option::is_none")]
331    pub marker_cache_size: Option<u64>, // defaults to object_cache_size
332    #[serde(default, skip_serializing_if = "Option::is_none")]
333    pub object_by_id_cache_size: Option<u64>, // defaults to object_cache_size
334
335    #[serde(default, skip_serializing_if = "Option::is_none")]
336    pub transaction_cache_size: Option<u64>, // defaults to max_cache_size
337    #[serde(default, skip_serializing_if = "Option::is_none")]
338    pub executed_effect_cache_size: Option<u64>, // defaults to transaction_cache_size
339    #[serde(default, skip_serializing_if = "Option::is_none")]
340    pub effect_cache_size: Option<u64>, // defaults to executed_effect_cache_size
341
342    #[serde(default, skip_serializing_if = "Option::is_none")]
343    pub events_cache_size: Option<u64>, // defaults to transaction_cache_size
344
345    #[serde(default, skip_serializing_if = "Option::is_none")]
346    pub transaction_objects_cache_size: Option<u64>, // defaults to 1000
347
348    /// Number of uncommitted transactions at which to pause consensus
349    /// handler.
350    #[serde(default, skip_serializing_if = "Option::is_none")]
351    pub backpressure_threshold: Option<u64>, // defaults to 100_000
352
353    /// Number of uncommitted transactions at which to refuse new
354    /// transaction submissions. Defaults to backpressure_threshold
355    /// if unset.
356    #[serde(default, skip_serializing_if = "Option::is_none")]
357    pub backpressure_threshold_for_rpc: Option<u64>, // defaults to backpressure_threshold
358}
359
360impl WritebackCacheConfig {
361    pub fn max_cache_size(&self) -> u64 {
362        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MAX")
363            .ok()
364            .and_then(|s| s.parse().ok())
365            .or(self.max_cache_size)
366            .unwrap_or(100000)
367    }
368
369    pub fn package_cache_size(&self) -> u64 {
370        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_PACKAGE")
371            .ok()
372            .and_then(|s| s.parse().ok())
373            .or(self.package_cache_size)
374            .unwrap_or(1000)
375    }
376
377    pub fn object_cache_size(&self) -> u64 {
378        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT")
379            .ok()
380            .and_then(|s| s.parse().ok())
381            .or(self.object_cache_size)
382            .unwrap_or_else(|| self.max_cache_size())
383    }
384
385    pub fn marker_cache_size(&self) -> u64 {
386        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MARKER")
387            .ok()
388            .and_then(|s| s.parse().ok())
389            .or(self.marker_cache_size)
390            .unwrap_or_else(|| self.object_cache_size())
391    }
392
393    pub fn object_by_id_cache_size(&self) -> u64 {
394        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT_BY_ID")
395            .ok()
396            .and_then(|s| s.parse().ok())
397            .or(self.object_by_id_cache_size)
398            .unwrap_or_else(|| self.object_cache_size())
399    }
400
401    pub fn transaction_cache_size(&self) -> u64 {
402        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION")
403            .ok()
404            .and_then(|s| s.parse().ok())
405            .or(self.transaction_cache_size)
406            .unwrap_or_else(|| self.max_cache_size())
407    }
408
409    pub fn executed_effect_cache_size(&self) -> u64 {
410        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EXECUTED_EFFECT")
411            .ok()
412            .and_then(|s| s.parse().ok())
413            .or(self.executed_effect_cache_size)
414            .unwrap_or_else(|| self.transaction_cache_size())
415    }
416
417    pub fn effect_cache_size(&self) -> u64 {
418        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EFFECT")
419            .ok()
420            .and_then(|s| s.parse().ok())
421            .or(self.effect_cache_size)
422            .unwrap_or_else(|| self.executed_effect_cache_size())
423    }
424
425    pub fn events_cache_size(&self) -> u64 {
426        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EVENTS")
427            .ok()
428            .and_then(|s| s.parse().ok())
429            .or(self.events_cache_size)
430            .unwrap_or_else(|| self.transaction_cache_size())
431    }
432
433    pub fn transaction_objects_cache_size(&self) -> u64 {
434        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION_OBJECTS")
435            .ok()
436            .and_then(|s| s.parse().ok())
437            .or(self.transaction_objects_cache_size)
438            .unwrap_or(1000)
439    }
440
441    pub fn backpressure_threshold(&self) -> u64 {
442        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD")
443            .ok()
444            .and_then(|s| s.parse().ok())
445            .or(self.backpressure_threshold)
446            .unwrap_or(100_000)
447    }
448
449    pub fn backpressure_threshold_for_rpc(&self) -> u64 {
450        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD_FOR_RPC")
451            .ok()
452            .and_then(|s| s.parse().ok())
453            .or(self.backpressure_threshold_for_rpc)
454            .unwrap_or(self.backpressure_threshold())
455    }
456}
457
458#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
459#[serde(rename_all = "lowercase")]
460pub enum ServerType {
461    WebSocket,
462    Http,
463    Both,
464}
465
466#[derive(Clone, Debug, Deserialize, Serialize)]
467#[serde(rename_all = "kebab-case")]
468pub struct TransactionKeyValueStoreReadConfig {
469    #[serde(default = "default_base_url")]
470    pub base_url: String,
471
472    #[serde(default = "default_cache_size")]
473    pub cache_size: u64,
474}
475
476impl Default for TransactionKeyValueStoreReadConfig {
477    fn default() -> Self {
478        Self {
479            base_url: default_base_url(),
480            cache_size: default_cache_size(),
481        }
482    }
483}
484
485fn default_base_url() -> String {
486    "".to_string()
487}
488
489fn default_cache_size() -> u64 {
490    100_000
491}
492
493fn default_jwk_fetch_interval_seconds() -> u64 {
494    3600
495}
496
497pub fn default_zklogin_oauth_providers() -> BTreeMap<Chain, BTreeSet<String>> {
498    let mut map = BTreeMap::new();
499
500    // providers that are available on devnet only.
501    let experimental_providers = BTreeSet::from([
502        "Google".to_string(),
503        "Facebook".to_string(),
504        "Twitch".to_string(),
505        "Kakao".to_string(),
506        "Apple".to_string(),
507        "Slack".to_string(),
508        "TestIssuer".to_string(),
509        "Microsoft".to_string(),
510        "KarrierOne".to_string(),
511        "Credenza3".to_string(),
512    ]);
513
514    // providers that are available for mainnet and testnet.
515    let providers = BTreeSet::from([
516        "Google".to_string(),
517        "Facebook".to_string(),
518        "Twitch".to_string(),
519        "Apple".to_string(),
520        "KarrierOne".to_string(),
521        "Credenza3".to_string(),
522    ]);
523    map.insert(Chain::Mainnet, providers.clone());
524    map.insert(Chain::Testnet, providers);
525    map.insert(Chain::Unknown, experimental_providers);
526    map
527}
528
529fn default_transaction_kv_store_config() -> TransactionKeyValueStoreReadConfig {
530    TransactionKeyValueStoreReadConfig::default()
531}
532
533fn default_authority_store_pruning_config() -> AuthorityStorePruningConfig {
534    AuthorityStorePruningConfig::default()
535}
536
537pub fn default_enable_index_processing() -> bool {
538    true
539}
540
541fn default_grpc_address() -> Multiaddr {
542    "/ip4/0.0.0.0/tcp/8080".parse().unwrap()
543}
544fn default_authority_key_pair() -> AuthorityKeyPairWithPath {
545    AuthorityKeyPairWithPath::new(get_key_pair_from_rng::<AuthorityKeyPair, _>(&mut OsRng).1)
546}
547
548fn default_key_pair() -> KeyPairWithPath {
549    KeyPairWithPath::new(
550        get_key_pair_from_rng::<AccountKeyPair, _>(&mut OsRng)
551            .1
552            .into(),
553    )
554}
555
556fn default_metrics_address() -> SocketAddr {
557    use std::net::{IpAddr, Ipv4Addr};
558    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9184)
559}
560
561pub fn default_admin_interface_address() -> SocketAddr {
562    SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 1337)
563}
564
565pub fn default_json_rpc_address() -> SocketAddr {
566    use std::net::{IpAddr, Ipv4Addr};
567    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9000)
568}
569
570pub fn default_concurrency_limit() -> Option<usize> {
571    Some(DEFAULT_GRPC_CONCURRENCY_LIMIT)
572}
573
574pub fn default_end_of_epoch_broadcast_channel_capacity() -> usize {
575    128
576}
577
578pub fn bool_true() -> bool {
579    true
580}
581
582fn is_true(value: &bool) -> bool {
583    *value
584}
585
586impl Config for NodeConfig {}
587
588impl NodeConfig {
589    pub fn authority_key_pair(&self) -> &AuthorityKeyPair {
590        self.authority_key_pair.authority_keypair()
591    }
592
593    pub fn protocol_key_pair(&self) -> &NetworkKeyPair {
594        match self.protocol_key_pair.keypair() {
595            IotaKeyPair::Ed25519(kp) => kp,
596            other => {
597                panic!("invalid keypair type: {other:?}, only Ed25519 is allowed for protocol key")
598            }
599        }
600    }
601
602    pub fn network_key_pair(&self) -> &NetworkKeyPair {
603        match self.network_key_pair.keypair() {
604            IotaKeyPair::Ed25519(kp) => kp,
605            other => {
606                panic!("invalid keypair type: {other:?}, only Ed25519 is allowed for network key")
607            }
608        }
609    }
610
611    pub fn authority_public_key(&self) -> AuthorityPublicKeyBytes {
612        self.authority_key_pair().public().into()
613    }
614
615    pub fn db_path(&self) -> PathBuf {
616        self.db_path.join("live")
617    }
618
619    pub fn db_checkpoint_path(&self) -> PathBuf {
620        self.db_path.join("db_checkpoints")
621    }
622
623    pub fn archive_path(&self) -> PathBuf {
624        self.db_path.join("archive")
625    }
626
627    pub fn snapshot_path(&self) -> PathBuf {
628        self.db_path.join("snapshot")
629    }
630
631    pub fn network_address(&self) -> &Multiaddr {
632        &self.network_address
633    }
634
635    pub fn consensus_config(&self) -> Option<&ConsensusConfig> {
636        self.consensus_config.as_ref()
637    }
638
639    pub fn genesis(&self) -> Result<&genesis::Genesis> {
640        self.genesis.genesis()
641    }
642
643    pub fn load_migration_tx_data(&self) -> Result<MigrationTxData> {
644        let Some(location) = &self.migration_tx_data_path else {
645            anyhow::bail!("no file location set");
646        };
647
648        // Load from file
649        let migration_tx_data = MigrationTxData::load(location)?;
650
651        // Validate migration content in order to avoid corrupted or malicious data
652        migration_tx_data.validate_from_genesis(self.genesis.genesis()?)?;
653        Ok(migration_tx_data)
654    }
655
656    pub fn iota_address(&self) -> IotaAddress {
657        (&self.account_key_pair.keypair().public()).into()
658    }
659
660    pub fn archive_reader_config(&self) -> Vec<ArchiveReaderConfig> {
661        self.state_archive_read_config
662            .iter()
663            .flat_map(|config| {
664                config
665                    .object_store_config
666                    .as_ref()
667                    .map(|remote_store_config| ArchiveReaderConfig {
668                        remote_store_config: remote_store_config.clone(),
669                        download_concurrency: NonZeroUsize::new(config.concurrency)
670                            .unwrap_or(NonZeroUsize::new(5).unwrap()),
671                        use_for_pruning_watermark: config.use_for_pruning_watermark,
672                    })
673            })
674            .collect()
675    }
676
677    pub fn jsonrpc_server_type(&self) -> ServerType {
678        self.jsonrpc_server_type.unwrap_or(ServerType::Http)
679    }
680}
681
682#[derive(Debug, Clone, Deserialize, Serialize)]
683pub enum ConsensusProtocol {
684    #[serde(rename = "mysticeti")]
685    Mysticeti,
686    #[serde(rename = "starfish")]
687    Starfish,
688}
689
690#[derive(Debug, Clone, Deserialize, Serialize)]
691#[serde(rename_all = "kebab-case")]
692pub struct ConsensusConfig {
693    // Base consensus DB path for all epochs.
694    pub db_path: PathBuf,
695
696    // The number of epochs for which to retain the consensus DBs. Setting it to 0 will make a
697    // consensus DB getting dropped as soon as system is switched to a new epoch.
698    pub db_retention_epochs: Option<u64>,
699
700    // Pruner will run on every epoch change but it will also check periodically on every
701    // `db_pruner_period_secs` seconds to see if there are any epoch DBs to remove.
702    pub db_pruner_period_secs: Option<u64>,
703
704    /// Maximum number of pending transactions to submit to consensus, including
705    /// those in submission wait.
706    ///
707    /// Default to 20_000 inflight limit, assuming 20_000 txn tps * 1 sec
708    /// consensus latency.
709    pub max_pending_transactions: Option<usize>,
710
711    /// When defined caps the calculated submission position to the
712    /// max_submit_position.
713    ///
714    /// Even if the is elected to submit from a higher
715    /// position than this, it will "reset" to the max_submit_position.
716    pub max_submit_position: Option<usize>,
717
718    /// The submit delay step to consensus defined in milliseconds.
719    ///
720    /// When provided it will override the current back off logic otherwise the
721    /// default backoff logic will be applied based on consensus latency
722    /// estimates.
723    pub submit_delay_step_override_millis: Option<u64>,
724
725    pub parameters: Option<ConsensusParameters>,
726}
727
728impl ConsensusConfig {
729    pub fn db_path(&self) -> &Path {
730        &self.db_path
731    }
732
733    pub fn max_pending_transactions(&self) -> usize {
734        self.max_pending_transactions.unwrap_or(20_000)
735    }
736
737    pub fn submit_delay_step_override(&self) -> Option<Duration> {
738        self.submit_delay_step_override_millis
739            .map(Duration::from_millis)
740    }
741
742    pub fn db_retention_epochs(&self) -> u64 {
743        self.db_retention_epochs.unwrap_or(0)
744    }
745
746    pub fn db_pruner_period(&self) -> Duration {
747        // Default to 1 hour
748        self.db_pruner_period_secs
749            .map(Duration::from_secs)
750            .unwrap_or(Duration::from_secs(3_600))
751    }
752}
753
754#[derive(Clone, Debug, Deserialize, Serialize)]
755#[serde(rename_all = "kebab-case")]
756pub struct CheckpointExecutorConfig {
757    /// Upper bound on the number of checkpoints that can be concurrently
758    /// executed.
759    ///
760    /// If unspecified, this will default to `200`
761    #[serde(default = "default_checkpoint_execution_max_concurrency")]
762    pub checkpoint_execution_max_concurrency: usize,
763
764    /// Number of seconds to wait for effects of a batch of transactions
765    /// before logging a warning. Note that we will continue to retry
766    /// indefinitely.
767    ///
768    /// If unspecified, this will default to `10`.
769    #[serde(default = "default_local_execution_timeout_sec")]
770    pub local_execution_timeout_sec: u64,
771
772    /// Optional directory used for data ingestion pipeline.
773    ///
774    /// When specified, each executed checkpoint will be saved in a local
775    /// directory for post-processing
776    #[serde(default, skip_serializing_if = "Option::is_none")]
777    pub data_ingestion_dir: Option<PathBuf>,
778}
779
780#[derive(Clone, Debug, Default, Deserialize, Serialize)]
781#[serde(rename_all = "kebab-case")]
782pub struct ExpensiveSafetyCheckConfig {
783    /// If enabled, at epoch boundary, we will check that the storage
784    /// fund balance is always identical to the sum of the storage
785    /// rebate of all live objects, and that the total IOTA in the network
786    /// remains the same.
787    #[serde(default)]
788    enable_epoch_iota_conservation_check: bool,
789
790    /// If enabled, we will check that the total IOTA in all input objects of a
791    /// tx (both the Move part and the storage rebate) matches the total IOTA
792    /// in all output objects of the tx + gas fees.
793    #[serde(default)]
794    enable_deep_per_tx_iota_conservation_check: bool,
795
796    /// Disable epoch IOTA conservation check even when we are running in debug
797    /// mode.
798    #[serde(default)]
799    force_disable_epoch_iota_conservation_check: bool,
800
801    /// If enabled, at epoch boundary, we will check that the accumulated
802    /// live object state matches the end of epoch root state digest.
803    #[serde(default)]
804    enable_state_consistency_check: bool,
805
806    /// Disable state consistency check even when we are running in debug mode.
807    #[serde(default)]
808    force_disable_state_consistency_check: bool,
809
810    #[serde(default)]
811    enable_secondary_index_checks: bool,
812    // TODO: Add more expensive checks here
813}
814
815impl ExpensiveSafetyCheckConfig {
816    pub fn new_enable_all() -> Self {
817        Self {
818            enable_epoch_iota_conservation_check: true,
819            enable_deep_per_tx_iota_conservation_check: true,
820            force_disable_epoch_iota_conservation_check: false,
821            enable_state_consistency_check: true,
822            force_disable_state_consistency_check: false,
823            enable_secondary_index_checks: false, // Disable by default for now
824        }
825    }
826
827    pub fn new_disable_all() -> Self {
828        Self {
829            enable_epoch_iota_conservation_check: false,
830            enable_deep_per_tx_iota_conservation_check: false,
831            force_disable_epoch_iota_conservation_check: true,
832            enable_state_consistency_check: false,
833            force_disable_state_consistency_check: true,
834            enable_secondary_index_checks: false,
835        }
836    }
837
838    pub fn force_disable_epoch_iota_conservation_check(&mut self) {
839        self.force_disable_epoch_iota_conservation_check = true;
840    }
841
842    pub fn enable_epoch_iota_conservation_check(&self) -> bool {
843        (self.enable_epoch_iota_conservation_check || cfg!(debug_assertions))
844            && !self.force_disable_epoch_iota_conservation_check
845    }
846
847    pub fn force_disable_state_consistency_check(&mut self) {
848        self.force_disable_state_consistency_check = true;
849    }
850
851    pub fn enable_state_consistency_check(&self) -> bool {
852        (self.enable_state_consistency_check || cfg!(debug_assertions))
853            && !self.force_disable_state_consistency_check
854    }
855
856    pub fn enable_deep_per_tx_iota_conservation_check(&self) -> bool {
857        self.enable_deep_per_tx_iota_conservation_check || cfg!(debug_assertions)
858    }
859
860    pub fn enable_secondary_index_checks(&self) -> bool {
861        self.enable_secondary_index_checks
862    }
863}
864
865fn default_checkpoint_execution_max_concurrency() -> usize {
866    40
867}
868
869fn default_local_execution_timeout_sec() -> u64 {
870    30
871}
872
873impl Default for CheckpointExecutorConfig {
874    fn default() -> Self {
875        Self {
876            checkpoint_execution_max_concurrency: default_checkpoint_execution_max_concurrency(),
877            local_execution_timeout_sec: default_local_execution_timeout_sec(),
878            data_ingestion_dir: None,
879        }
880    }
881}
882
883#[derive(Debug, Clone, Deserialize, Serialize)]
884#[serde(rename_all = "kebab-case")]
885pub struct AuthorityStorePruningConfig {
886    /// number of the latest epoch dbs to retain
887    #[serde(default = "default_num_latest_epoch_dbs_to_retain")]
888    pub num_latest_epoch_dbs_to_retain: usize,
889    /// time interval used by the pruner to determine whether there are any
890    /// epoch DBs to remove
891    #[serde(default = "default_epoch_db_pruning_period_secs")]
892    pub epoch_db_pruning_period_secs: u64,
893    /// number of epochs to keep the latest version of objects for.
894    /// Note that a zero value corresponds to an aggressive pruner.
895    /// This mode is experimental and needs to be used with caution.
896    /// Use `u64::MAX` to disable the pruner for the objects.
897    #[serde(default)]
898    pub num_epochs_to_retain: u64,
899    /// pruner's runtime interval used for aggressive mode
900    #[serde(skip_serializing_if = "Option::is_none")]
901    pub pruning_run_delay_seconds: Option<u64>,
902    /// maximum number of checkpoints in the pruning batch. Can be adjusted to
903    /// increase performance
904    #[serde(default = "default_max_checkpoints_in_batch")]
905    pub max_checkpoints_in_batch: usize,
906    /// maximum number of transaction in the pruning batch
907    #[serde(default = "default_max_transactions_in_batch")]
908    pub max_transactions_in_batch: usize,
909    /// enables periodic background compaction for old SST files whose last
910    /// modified time is older than `periodic_compaction_threshold_days`
911    /// days. That ensures that all sst files eventually go through the
912    /// compaction process
913    #[serde(
914        default = "default_periodic_compaction_threshold_days",
915        skip_serializing_if = "Option::is_none"
916    )]
917    pub periodic_compaction_threshold_days: Option<usize>,
918    /// number of epochs to keep the latest version of transactions and effects
919    /// for
920    #[serde(skip_serializing_if = "Option::is_none")]
921    pub num_epochs_to_retain_for_checkpoints: Option<u64>,
922    #[serde(default = "default_smoothing", skip_serializing_if = "is_true")]
923    pub smooth: bool,
924    /// Enables the compaction filter for pruning the objects table.
925    /// If disabled, a range deletion approach is used instead.
926    /// While it is generally safe to switch between the two modes,
927    /// switching from the compaction filter approach back to range deletion
928    /// may result in some old versions that will never be pruned.
929    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
930    pub enable_compaction_filter: bool,
931}
932
933fn default_num_latest_epoch_dbs_to_retain() -> usize {
934    3
935}
936
937fn default_epoch_db_pruning_period_secs() -> u64 {
938    3600
939}
940
941fn default_max_transactions_in_batch() -> usize {
942    1000
943}
944
945fn default_max_checkpoints_in_batch() -> usize {
946    10
947}
948
949fn default_smoothing() -> bool {
950    cfg!(not(test))
951}
952
953fn default_periodic_compaction_threshold_days() -> Option<usize> {
954    Some(1)
955}
956
957impl Default for AuthorityStorePruningConfig {
958    fn default() -> Self {
959        Self {
960            num_latest_epoch_dbs_to_retain: default_num_latest_epoch_dbs_to_retain(),
961            epoch_db_pruning_period_secs: default_epoch_db_pruning_period_secs(),
962            num_epochs_to_retain: 0,
963            pruning_run_delay_seconds: if cfg!(msim) { Some(2) } else { None },
964            max_checkpoints_in_batch: default_max_checkpoints_in_batch(),
965            max_transactions_in_batch: default_max_transactions_in_batch(),
966            periodic_compaction_threshold_days: None,
967            num_epochs_to_retain_for_checkpoints: if cfg!(msim) { Some(2) } else { None },
968            smooth: true,
969            enable_compaction_filter: cfg!(test) || cfg!(msim),
970        }
971    }
972}
973
974impl AuthorityStorePruningConfig {
975    pub fn set_num_epochs_to_retain(&mut self, num_epochs_to_retain: u64) {
976        self.num_epochs_to_retain = num_epochs_to_retain;
977    }
978
979    pub fn set_num_epochs_to_retain_for_checkpoints(&mut self, num_epochs_to_retain: Option<u64>) {
980        self.num_epochs_to_retain_for_checkpoints = num_epochs_to_retain;
981    }
982
983    pub fn num_epochs_to_retain_for_checkpoints(&self) -> Option<u64> {
984        self.num_epochs_to_retain_for_checkpoints
985            // if n less than 2, coerce to 2 and log
986            .map(|n| {
987                if n < 2 {
988                    info!("num_epochs_to_retain_for_checkpoints must be at least 2, rounding up from {}", n);
989                    2
990                } else {
991                    n
992                }
993            })
994    }
995}
996
997#[derive(Debug, Clone, Deserialize, Serialize)]
998#[serde(rename_all = "kebab-case")]
999pub struct MetricsConfig {
1000    #[serde(skip_serializing_if = "Option::is_none")]
1001    pub push_interval_seconds: Option<u64>,
1002    #[serde(skip_serializing_if = "Option::is_none")]
1003    pub push_url: Option<String>,
1004}
1005
1006#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1007#[serde(rename_all = "kebab-case")]
1008pub struct DBCheckpointConfig {
1009    #[serde(default)]
1010    pub perform_db_checkpoints_at_epoch_end: bool,
1011    #[serde(skip_serializing_if = "Option::is_none")]
1012    pub checkpoint_path: Option<PathBuf>,
1013    #[serde(skip_serializing_if = "Option::is_none")]
1014    pub object_store_config: Option<ObjectStoreConfig>,
1015    #[serde(skip_serializing_if = "Option::is_none")]
1016    pub perform_index_db_checkpoints_at_epoch_end: Option<bool>,
1017    #[serde(skip_serializing_if = "Option::is_none")]
1018    pub prune_and_compact_before_upload: Option<bool>,
1019}
1020
1021#[derive(Debug, Clone)]
1022pub struct ArchiveReaderConfig {
1023    pub remote_store_config: ObjectStoreConfig,
1024    pub download_concurrency: NonZeroUsize,
1025    pub use_for_pruning_watermark: bool,
1026}
1027
1028#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1029#[serde(rename_all = "kebab-case")]
1030pub struct StateArchiveConfig {
1031    #[serde(skip_serializing_if = "Option::is_none")]
1032    pub object_store_config: Option<ObjectStoreConfig>,
1033    pub concurrency: usize,
1034    pub use_for_pruning_watermark: bool,
1035}
1036
1037#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1038#[serde(rename_all = "kebab-case")]
1039pub struct StateSnapshotConfig {
1040    #[serde(skip_serializing_if = "Option::is_none")]
1041    pub object_store_config: Option<ObjectStoreConfig>,
1042    pub concurrency: usize,
1043}
1044
1045#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1046#[serde(rename_all = "kebab-case")]
1047pub struct TransactionKeyValueStoreWriteConfig {
1048    pub aws_access_key_id: String,
1049    pub aws_secret_access_key: String,
1050    pub aws_region: String,
1051    pub table_name: String,
1052    pub bucket_name: String,
1053    pub concurrency: usize,
1054}
1055
1056/// Configuration for the threshold(s) at which we consider the system
1057/// to be overloaded. When one of the threshold is passed, the node may
1058/// stop processing new transactions and/or certificates until the congestion
1059/// resolves.
1060#[derive(Clone, Debug, Deserialize, Serialize)]
1061#[serde(rename_all = "kebab-case")]
1062pub struct AuthorityOverloadConfig {
1063    #[serde(default = "default_max_txn_age_in_queue")]
1064    pub max_txn_age_in_queue: Duration,
1065
1066    // The interval of checking overload signal.
1067    #[serde(default = "default_overload_monitor_interval")]
1068    pub overload_monitor_interval: Duration,
1069
1070    // The execution queueing latency when entering load shedding mode.
1071    #[serde(default = "default_execution_queue_latency_soft_limit")]
1072    pub execution_queue_latency_soft_limit: Duration,
1073
1074    // The execution queueing latency when entering aggressive load shedding mode.
1075    #[serde(default = "default_execution_queue_latency_hard_limit")]
1076    pub execution_queue_latency_hard_limit: Duration,
1077
1078    // The maximum percentage of transactions to shed in load shedding mode.
1079    #[serde(default = "default_max_load_shedding_percentage")]
1080    pub max_load_shedding_percentage: u32,
1081
1082    // When in aggressive load shedding mode, the minimum percentage of
1083    // transactions to shed.
1084    #[serde(default = "default_min_load_shedding_percentage_above_hard_limit")]
1085    pub min_load_shedding_percentage_above_hard_limit: u32,
1086
1087    // If transaction ready rate is below this rate, we consider the validator
1088    // is well under used, and will not enter load shedding mode.
1089    #[serde(default = "default_safe_transaction_ready_rate")]
1090    pub safe_transaction_ready_rate: u32,
1091
1092    // When set to true, transaction signing may be rejected when the validator
1093    // is overloaded.
1094    #[serde(default = "default_check_system_overload_at_signing")]
1095    pub check_system_overload_at_signing: bool,
1096
1097    // When set to true, transaction execution may be rejected when the validator
1098    // is overloaded.
1099    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1100    pub check_system_overload_at_execution: bool,
1101
1102    // Reject a transaction if transaction manager queue length is above this threshold.
1103    // 100_000 = 10k TPS * 5s resident time in transaction manager (pending + executing) * 2.
1104    #[serde(default = "default_max_transaction_manager_queue_length")]
1105    pub max_transaction_manager_queue_length: usize,
1106
1107    // Reject a transaction if the number of pending transactions depending on the object
1108    // is above the threshold.
1109    #[serde(default = "default_max_transaction_manager_per_object_queue_length")]
1110    pub max_transaction_manager_per_object_queue_length: usize,
1111}
1112
1113fn default_max_txn_age_in_queue() -> Duration {
1114    Duration::from_millis(500)
1115}
1116
1117fn default_overload_monitor_interval() -> Duration {
1118    Duration::from_secs(10)
1119}
1120
1121fn default_execution_queue_latency_soft_limit() -> Duration {
1122    Duration::from_secs(1)
1123}
1124
1125fn default_execution_queue_latency_hard_limit() -> Duration {
1126    Duration::from_secs(10)
1127}
1128
1129fn default_max_load_shedding_percentage() -> u32 {
1130    95
1131}
1132
1133fn default_min_load_shedding_percentage_above_hard_limit() -> u32 {
1134    50
1135}
1136
1137fn default_safe_transaction_ready_rate() -> u32 {
1138    100
1139}
1140
1141fn default_check_system_overload_at_signing() -> bool {
1142    true
1143}
1144
1145fn default_max_transaction_manager_queue_length() -> usize {
1146    100_000
1147}
1148
1149fn default_max_transaction_manager_per_object_queue_length() -> usize {
1150    20
1151}
1152
1153impl Default for AuthorityOverloadConfig {
1154    fn default() -> Self {
1155        Self {
1156            max_txn_age_in_queue: default_max_txn_age_in_queue(),
1157            overload_monitor_interval: default_overload_monitor_interval(),
1158            execution_queue_latency_soft_limit: default_execution_queue_latency_soft_limit(),
1159            execution_queue_latency_hard_limit: default_execution_queue_latency_hard_limit(),
1160            max_load_shedding_percentage: default_max_load_shedding_percentage(),
1161            min_load_shedding_percentage_above_hard_limit:
1162                default_min_load_shedding_percentage_above_hard_limit(),
1163            safe_transaction_ready_rate: default_safe_transaction_ready_rate(),
1164            check_system_overload_at_signing: true,
1165            check_system_overload_at_execution: false,
1166            max_transaction_manager_queue_length: default_max_transaction_manager_queue_length(),
1167            max_transaction_manager_per_object_queue_length:
1168                default_max_transaction_manager_per_object_queue_length(),
1169        }
1170    }
1171}
1172
1173fn default_authority_overload_config() -> AuthorityOverloadConfig {
1174    AuthorityOverloadConfig::default()
1175}
1176
1177#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1178pub struct Genesis {
1179    #[serde(flatten)]
1180    location: Option<GenesisLocation>,
1181
1182    #[serde(skip)]
1183    genesis: once_cell::sync::OnceCell<genesis::Genesis>,
1184}
1185
1186impl Genesis {
1187    pub fn new(genesis: genesis::Genesis) -> Self {
1188        Self {
1189            location: Some(GenesisLocation::InPlace {
1190                genesis: Box::new(genesis),
1191            }),
1192            genesis: Default::default(),
1193        }
1194    }
1195
1196    pub fn new_from_file<P: Into<PathBuf>>(path: P) -> Self {
1197        Self {
1198            location: Some(GenesisLocation::File {
1199                genesis_file_location: path.into(),
1200            }),
1201            genesis: Default::default(),
1202        }
1203    }
1204
1205    pub fn new_empty() -> Self {
1206        Self {
1207            location: None,
1208            genesis: Default::default(),
1209        }
1210    }
1211
1212    pub fn genesis(&self) -> Result<&genesis::Genesis> {
1213        match &self.location {
1214            Some(GenesisLocation::InPlace { genesis }) => Ok(genesis),
1215            Some(GenesisLocation::File {
1216                genesis_file_location,
1217            }) => self
1218                .genesis
1219                .get_or_try_init(|| genesis::Genesis::load(genesis_file_location)),
1220            None => anyhow::bail!("no genesis location set"),
1221        }
1222    }
1223}
1224
1225#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1226#[serde(untagged)]
1227enum GenesisLocation {
1228    InPlace {
1229        genesis: Box<genesis::Genesis>,
1230    },
1231    File {
1232        #[serde(rename = "genesis-file-location")]
1233        genesis_file_location: PathBuf,
1234    },
1235}
1236
1237/// Wrapper struct for IotaKeyPair that can be deserialized from a file path.
1238/// Used by network, worker, and account keypair.
1239#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
1240pub struct KeyPairWithPath {
1241    #[serde(flatten)]
1242    location: KeyPairLocation,
1243
1244    #[serde(skip)]
1245    keypair: OnceCell<Arc<IotaKeyPair>>,
1246}
1247
1248#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1249#[serde(untagged)]
1250enum KeyPairLocation {
1251    InPlace {
1252        #[serde(with = "bech32_formatted_keypair")]
1253        value: Arc<IotaKeyPair>,
1254    },
1255    File {
1256        path: PathBuf,
1257    },
1258}
1259
1260impl KeyPairWithPath {
1261    pub fn new(kp: IotaKeyPair) -> Self {
1262        let cell: OnceCell<Arc<IotaKeyPair>> = OnceCell::new();
1263        let arc_kp = Arc::new(kp);
1264        // OK to unwrap panic because authority should not start without all keypairs
1265        // loaded.
1266        cell.set(arc_kp.clone()).expect("failed to set keypair");
1267        Self {
1268            location: KeyPairLocation::InPlace { value: arc_kp },
1269            keypair: cell,
1270        }
1271    }
1272
1273    pub fn new_from_path(path: PathBuf) -> Self {
1274        let cell: OnceCell<Arc<IotaKeyPair>> = OnceCell::new();
1275        // OK to unwrap panic because authority should not start without all keypairs
1276        // loaded.
1277        cell.set(Arc::new(read_keypair_from_file(&path).unwrap_or_else(
1278            |e| panic!("invalid keypair file at path {:?}: {e}", &path),
1279        )))
1280        .expect("failed to set keypair");
1281        Self {
1282            location: KeyPairLocation::File { path },
1283            keypair: cell,
1284        }
1285    }
1286
1287    pub fn keypair(&self) -> &IotaKeyPair {
1288        self.keypair
1289            .get_or_init(|| match &self.location {
1290                KeyPairLocation::InPlace { value } => value.clone(),
1291                KeyPairLocation::File { path } => {
1292                    // OK to unwrap panic because authority should not start without all keypairs
1293                    // loaded.
1294                    Arc::new(
1295                        read_keypair_from_file(path).unwrap_or_else(|e| {
1296                            panic!("invalid keypair file at path {path:?}: {e}")
1297                        }),
1298                    )
1299                }
1300            })
1301            .as_ref()
1302    }
1303}
1304
1305/// Wrapper struct for AuthorityKeyPair that can be deserialized from a file
1306/// path.
1307#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
1308pub struct AuthorityKeyPairWithPath {
1309    #[serde(flatten)]
1310    location: AuthorityKeyPairLocation,
1311
1312    #[serde(skip)]
1313    keypair: OnceCell<Arc<AuthorityKeyPair>>,
1314}
1315
1316#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1317#[serde(untagged)]
1318enum AuthorityKeyPairLocation {
1319    InPlace { value: Arc<AuthorityKeyPair> },
1320    File { path: PathBuf },
1321}
1322
1323impl AuthorityKeyPairWithPath {
1324    pub fn new(kp: AuthorityKeyPair) -> Self {
1325        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
1326        let arc_kp = Arc::new(kp);
1327        // OK to unwrap panic because authority should not start without all keypairs
1328        // loaded.
1329        cell.set(arc_kp.clone())
1330            .expect("failed to set authority keypair");
1331        Self {
1332            location: AuthorityKeyPairLocation::InPlace { value: arc_kp },
1333            keypair: cell,
1334        }
1335    }
1336
1337    pub fn new_from_path(path: PathBuf) -> Self {
1338        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
1339        // OK to unwrap panic because authority should not start without all keypairs
1340        // loaded.
1341        cell.set(Arc::new(
1342            read_authority_keypair_from_file(&path)
1343                .unwrap_or_else(|_| panic!("invalid authority keypair file at path {:?}", &path)),
1344        ))
1345        .expect("failed to set authority keypair");
1346        Self {
1347            location: AuthorityKeyPairLocation::File { path },
1348            keypair: cell,
1349        }
1350    }
1351
1352    pub fn authority_keypair(&self) -> &AuthorityKeyPair {
1353        self.keypair
1354            .get_or_init(|| match &self.location {
1355                AuthorityKeyPairLocation::InPlace { value } => value.clone(),
1356                AuthorityKeyPairLocation::File { path } => {
1357                    // OK to unwrap panic because authority should not start without all keypairs
1358                    // loaded.
1359                    Arc::new(
1360                        read_authority_keypair_from_file(path).unwrap_or_else(|_| {
1361                            panic!("invalid authority keypair file {:?}", &path)
1362                        }),
1363                    )
1364                }
1365            })
1366            .as_ref()
1367    }
1368}
1369
1370/// Configurations which determine how we dump state debug info.
1371/// Debug info is dumped when a node forks.
1372#[derive(Clone, Debug, Deserialize, Serialize, Default)]
1373#[serde(rename_all = "kebab-case")]
1374pub struct StateDebugDumpConfig {
1375    #[serde(skip_serializing_if = "Option::is_none")]
1376    pub dump_file_directory: Option<PathBuf>,
1377}
1378
1379#[cfg(test)]
1380mod tests {
1381    use std::path::PathBuf;
1382
1383    use fastcrypto::traits::KeyPair;
1384    use iota_keys::keypair_file::{write_authority_keypair_to_file, write_keypair_to_file};
1385    use iota_types::crypto::{
1386        AuthorityKeyPair, IotaKeyPair, NetworkKeyPair, get_key_pair_from_rng,
1387    };
1388    use rand::{SeedableRng, rngs::StdRng};
1389
1390    use super::Genesis;
1391    use crate::NodeConfig;
1392
1393    #[test]
1394    fn serialize_genesis_from_file() {
1395        let g = Genesis::new_from_file("path/to/file");
1396
1397        let s = serde_yaml::to_string(&g).unwrap();
1398        assert_eq!("---\ngenesis-file-location: path/to/file\n", s);
1399        let loaded_genesis: Genesis = serde_yaml::from_str(&s).unwrap();
1400        assert_eq!(g, loaded_genesis);
1401    }
1402
1403    #[test]
1404    fn fullnode_template() {
1405        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
1406
1407        let _template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
1408    }
1409
1410    #[test]
1411    fn load_key_pairs_to_node_config() {
1412        let authority_key_pair: AuthorityKeyPair =
1413            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
1414        let protocol_key_pair: NetworkKeyPair =
1415            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
1416        let network_key_pair: NetworkKeyPair =
1417            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
1418
1419        write_authority_keypair_to_file(&authority_key_pair, PathBuf::from("authority.key"))
1420            .unwrap();
1421        write_keypair_to_file(
1422            &IotaKeyPair::Ed25519(protocol_key_pair.copy()),
1423            PathBuf::from("protocol.key"),
1424        )
1425        .unwrap();
1426        write_keypair_to_file(
1427            &IotaKeyPair::Ed25519(network_key_pair.copy()),
1428            PathBuf::from("network.key"),
1429        )
1430        .unwrap();
1431
1432        const TEMPLATE: &str = include_str!("../data/fullnode-template-with-path.yaml");
1433        let template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
1434        assert_eq!(
1435            template.authority_key_pair().public(),
1436            authority_key_pair.public()
1437        );
1438        assert_eq!(
1439            template.network_key_pair().public(),
1440            network_key_pair.public()
1441        );
1442        assert_eq!(
1443            template.protocol_key_pair().public(),
1444            protocol_key_pair.public()
1445        );
1446    }
1447}
1448
1449// RunWithRange is used to specify the ending epoch/checkpoint to process.
1450// this is intended for use with disaster recovery debugging and verification
1451// workflows, never in normal operations
1452#[derive(Clone, Copy, PartialEq, Debug, Serialize, Deserialize)]
1453pub enum RunWithRange {
1454    Epoch(EpochId),
1455    Checkpoint(CheckpointSequenceNumber),
1456}
1457
1458impl RunWithRange {
1459    // is epoch_id > RunWithRange::Epoch
1460    pub fn is_epoch_gt(&self, epoch_id: EpochId) -> bool {
1461        matches!(self, RunWithRange::Epoch(e) if epoch_id > *e)
1462    }
1463
1464    pub fn matches_checkpoint(&self, seq_num: CheckpointSequenceNumber) -> bool {
1465        matches!(self, RunWithRange::Checkpoint(seq) if *seq == seq_num)
1466    }
1467
1468    pub fn into_checkpoint_bound(self) -> Option<CheckpointSequenceNumber> {
1469        match self {
1470            RunWithRange::Epoch(_) => None,
1471            RunWithRange::Checkpoint(seq) => Some(seq),
1472        }
1473    }
1474}
1475
1476/// A serde helper module used with #[serde(with = "...")] to change the
1477/// de/serialization format of an `IotaKeyPair` to Bech32 when written to or
1478/// read from a node config.
1479mod bech32_formatted_keypair {
1480    use std::ops::Deref;
1481
1482    use iota_types::crypto::{EncodeDecodeBase64, IotaKeyPair};
1483    use serde::{Deserialize, Deserializer, Serializer};
1484
1485    pub fn serialize<S, T>(kp: &T, serializer: S) -> Result<S::Ok, S::Error>
1486    where
1487        S: Serializer,
1488        T: Deref<Target = IotaKeyPair>,
1489    {
1490        use serde::ser::Error;
1491
1492        // Serialize the keypair to a Bech32 string
1493        let s = kp.encode().map_err(Error::custom)?;
1494
1495        serializer.serialize_str(&s)
1496    }
1497
1498    pub fn deserialize<'de, D, T>(deserializer: D) -> Result<T, D::Error>
1499    where
1500        D: Deserializer<'de>,
1501        T: From<IotaKeyPair>,
1502    {
1503        use serde::de::Error;
1504
1505        let s = String::deserialize(deserializer)?;
1506
1507        // Try to deserialize the keypair from a Bech32 formatted string
1508        IotaKeyPair::decode(&s)
1509            .or_else(|_| {
1510                // For backwards compatibility try Base64 if Bech32 failed
1511                IotaKeyPair::decode_base64(&s)
1512            })
1513            .map(Into::into)
1514            .map_err(Error::custom)
1515    }
1516}