Skip to main content

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    net::{IpAddr, Ipv4Addr, SocketAddr},
7    num::{NonZeroU32, NonZeroUsize},
8    path::{Path, PathBuf},
9    sync::Arc,
10    time::Duration,
11};
12
13use anyhow::Result;
14use iota_keys::keypair_file::{read_authority_keypair_from_file, read_keypair_from_file};
15use iota_metrics::MetricGroups;
16use iota_multiaddr::Multiaddr;
17use iota_names::config::IotaNamesConfig;
18use iota_sdk_crypto::simple::SimpleKeypair;
19use iota_sdk_types::Address;
20use iota_types::{
21    committee::EpochId,
22    crypto::{
23        AccountPrivateKey, AuthorityKeyPair, AuthorityPublicKeyBytes, KeypairTraits,
24        NetworkPrivateKey, get_key_pair_from_rng,
25    },
26    messages_checkpoint::CheckpointSequenceNumber,
27    supported_protocol_versions::{Chain, SupportedProtocolVersions},
28    traffic_control::PolicyConfig,
29};
30use once_cell::sync::OnceCell;
31use rand::{rand_core::UnwrapErr, rngs::SysRng};
32use serde::{Deserialize, Serialize};
33use starfish_config::Parameters as StarfishParameters;
34
35use crate::{
36    Config, certificate_deny_config::CertificateDenyConfig, genesis,
37    migration_tx_data::MigrationTxData, object_storage_config::ObjectStoreConfig, p2p::P2pConfig,
38    setting::Setting, transaction_deny_config::TransactionDenyConfig,
39    verifier_signing_config::VerifierSigningConfig,
40};
41
42/// Default gas price of 1000 Nanos
43pub const DEFAULT_VALIDATOR_GAS_PRICE: u64 = iota_types::transaction::DEFAULT_VALIDATOR_GAS_PRICE;
44
45/// Default commission rate of 2%
46pub const DEFAULT_COMMISSION_RATE: u64 = 200;
47
48/// Default budget in MiB for the in-memory full-checkpoint-contents cache.
49pub const DEFAULT_FULL_CHECKPOINT_CONTENTS_CACHE_SIZE_MB: usize = 1024;
50
51#[derive(Clone, Debug, Deserialize, Serialize)]
52#[serde(rename_all = "kebab-case")]
53pub struct NodeConfig {
54    /// The public key bytes corresponding to the private key that the validator
55    /// holds to sign transactions.
56    #[serde(default = "default_authority_key_pair")]
57    pub authority_key_pair: AuthorityKeyPairWithPath,
58    /// The public key bytes corresponding to the private key that the validator
59    /// holds to sign consensus blocks.
60    #[serde(default = "default_key_pair")]
61    pub protocol_key_pair: KeyPairWithPath,
62    #[serde(default = "default_key_pair")]
63    pub account_key_pair: KeyPairWithPath,
64    /// The public key bytes corresponding to the private key that the validator
65    /// uses to establish TLS connections.
66    #[serde(default = "default_key_pair")]
67    pub network_key_pair: KeyPairWithPath,
68    pub db_path: PathBuf,
69
70    /// The network address for gRPC communication.
71    ///
72    /// Can be overwritten with args `listen-address` parameters.
73    #[serde(default = "default_grpc_address")]
74    pub network_address: Multiaddr,
75    #[serde(default = "default_json_rpc_address")]
76    pub json_rpc_address: SocketAddr,
77
78    /// The address for Prometheus metrics.
79    #[serde(default = "default_metrics_address")]
80    pub metrics_address: SocketAddr,
81
82    /// The address for the admin interface that is
83    /// run in the metrics separate runtime and provides access to
84    /// admin node commands such as logging and tracing options.
85    #[serde(default = "default_admin_interface_address")]
86    pub admin_interface_address: SocketAddr,
87
88    /// Configuration struct for the consensus.
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub consensus_config: Option<ConsensusConfig>,
91
92    /// Flag to enable the JSON-RPC API. Default: `true`. When `false` a full
93    /// node serves only the `/health` endpoint on `json_rpc_address`.
94    #[serde(default = "default_enable_jsonrpc_api")]
95    pub enable_jsonrpc_api: bool,
96
97    /// Flag to enable gRPC load shedding: requests over a service's
98    /// concurrency limit are rejected immediately with `RESOURCE_EXHAUSTED`
99    /// instead of waiting for a slot.
100    #[serde(default)]
101    pub grpc_load_shed: Option<bool>,
102
103    /// Maximum number of in-flight requests per CPU core, applied to each
104    /// service of the validator gRPC server separately (`Validator`,
105    /// `ValidatorV2`, `ValidatorPeer`), so a flood of client transaction
106    /// submissions cannot crowd validator-peer RPCs out of admission slots.
107    /// The per-service limit is this value times the CPU cores of the machine
108    /// at server startup.
109    ///
110    /// A request is in flight from admission until its response has been
111    /// sent, so a `SubmitTx` or `GetTxStatus` stream counts while it streams;
112    /// a `GetTxStatus` stream waits up to 30 s for its transactions. A
113    /// response not fully sent 60 s after its headers gives up its slot and
114    /// ends with `DEADLINE_EXCEEDED`, whether or not the client is still
115    /// reading. A request over the limit waits for a slot, or is rejected if
116    /// `grpc_load_shed` is set.
117    ///
118    /// A lower value must leave room for every `GetTxStatus` stream open at
119    /// peak.
120    ///
121    /// Zero is rejected at config load: it would block every request rather
122    /// than disable the limit.
123    #[serde(default = "default_grpc_concurrency_limit_per_core")]
124    pub grpc_concurrency_limit_per_core: NonZeroUsize,
125
126    /// Configuration struct for P2P.
127    #[serde(default)]
128    pub p2p_config: P2pConfig,
129
130    /// Contains genesis location that might be `InPlace`
131    /// for reading all genesis data to memory or `InFile`,
132    /// and `OnceCell` pointer to a genesis struct.
133    pub genesis: Genesis,
134
135    /// Contains the path where to find the migration blob.
136    pub migration_tx_data_path: Option<PathBuf>,
137
138    /// Configuration for pruning of the authority store, to define when
139    /// an old data is removed from the storage space.
140    #[serde(default = "default_authority_store_pruning_config")]
141    pub authority_store_pruning_config: AuthorityStorePruningConfig,
142
143    /// Size of the broadcast channel used for notifying other systems of end of
144    /// epoch.
145    ///
146    /// If unspecified, this will default to `128`.
147    #[serde(default = "default_end_of_epoch_broadcast_channel_capacity")]
148    pub end_of_epoch_broadcast_channel_capacity: usize,
149
150    /// Configuration for the checkpoint executor for limiting
151    /// the number of checkpoints to execute concurrently,
152    /// and to allow for checkpoint post-processing.
153    #[serde(default)]
154    pub checkpoint_executor_config: CheckpointExecutorConfig,
155
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub metrics: Option<MetricsConfig>,
158
159    /// In a `iota-node` binary, this is set to
160    /// SupportedProtocolVersions::SYSTEM_DEFAULT in iota-node/src/main.rs.
161    /// It is present in the config so that it can be changed by tests in
162    /// order to test protocol upgrades.
163    #[serde(skip)]
164    pub supported_protocol_versions: Option<SupportedProtocolVersions>,
165
166    /// Configuration for enabling/disabling expensive safety checks.
167    #[serde(default)]
168    pub expensive_safety_check_config: ExpensiveSafetyCheckConfig,
169
170    /// Configuration to specify rules for denying transactions
171    /// based on `objectsIDs`, `addresses`, or enable/disable many
172    /// features such as publishing new packages or using shared objects.
173    #[serde(default)]
174    pub transaction_deny_config: TransactionDenyConfig,
175
176    /// Config used to deny execution for certificate digests
177    /// know for crashing or hanging validator nodes.
178    ///
179    /// Should be used for a fast temporary fixes and
180    /// removed once the issue is fixed.
181    #[serde(default)]
182    pub certificate_deny_config: CertificateDenyConfig,
183
184    /// Used to determine how state debug information is dumped
185    /// when a node forks.
186    #[serde(default)]
187    pub state_debug_dump_config: StateDebugDumpConfig,
188
189    #[serde(default)]
190    pub checkpoint_archive_config: Option<CheckpointArchiveConfig>,
191
192    /// Determines if snapshot should be uploaded to the remote storage.
193    #[serde(default)]
194    pub state_snapshot_write_config: StateSnapshotConfig,
195
196    #[serde(default = "default_transaction_kv_store_config")]
197    pub transaction_kv_store_read_config: TransactionKeyValueStoreReadConfig,
198
199    // TODO: write config seem to be unused.
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub transaction_kv_store_write_config: Option<TransactionKeyValueStoreWriteConfig>,
202
203    /// Configuration for defining thresholds and settings
204    /// for managing system overload conditions in a node.
205    #[serde(default = "default_authority_overload_config")]
206    pub authority_overload_config: AuthorityOverloadConfig,
207
208    /// Specifies the ending epoch for a node for debugging purposes.
209    ///
210    ///  Ignored if set by config, can be configured only by cli arguments.
211    #[serde(skip_serializing_if = "Option::is_none")]
212    pub run_with_range: Option<RunWithRange>,
213
214    /// Traffic control policy. For killswitch use None.
215    ///
216    /// With the key absent the default denial-of-service protection policy
217    /// applies, an explicit `null` turns traffic control off, and a value
218    /// configures it.
219    #[serde(
220        skip_serializing_if = "is_default_traffic_controller_policy_config",
221        default = "default_traffic_controller_policy_config"
222    )]
223    pub policy_config: Option<PolicyConfig>,
224
225    #[serde(default)]
226    pub execution_cache_config: ExecutionCacheConfig,
227
228    /// Memory budget in MiB for the in-memory cache of full checkpoint
229    /// contents, which serves the checkpoint executor's bulk transaction
230    /// loads and checkpoint-contents requests from state-sync peers. When
231    /// the budget is exceeded, the oldest checkpoints are evicted first.
232    /// Set to 0 to disable the cache; consumers then fall back to
233    /// reconstructing contents from the transaction and effects stores.
234    ///
235    /// The budget is accounted in serialized (BCS) bytes; the resident
236    /// memory of a full cache is somewhat higher than the configured value
237    /// due to in-memory representation overhead.
238    #[serde(default = "default_full_checkpoint_contents_cache_size_mb")]
239    pub full_checkpoint_contents_cache_size_mb: usize,
240
241    #[serde(default = "bool_true")]
242    pub enable_validator_tx_finalizer: bool,
243
244    /// Enables the pre-consensus soft-locking mechanism used by the
245    /// certificate-less (pcool) transaction flow (default: enabled).
246    ///
247    /// When disabled, post-consensus validation alone resolves owned-object
248    /// conflicts. Has no effect unless the pcool flow is enabled.
249    #[serde(default = "bool_true")]
250    pub enable_soft_locking: bool,
251
252    #[serde(default)]
253    pub verifier_signing_config: VerifierSigningConfig,
254
255    /// How many threads read the inputs of a consensus commit's transactions
256    /// at once in post-consensus validation, the consensus handler's own
257    /// thread included. One reads them one after another. By default a
258    /// third of the cores, at least one and at most sixteen. Has no effect
259    /// unless the pcool flow is enabled.
260    #[serde(default, skip_serializing_if = "Option::is_none")]
261    pub post_consensus_validation_readers: Option<NonZeroUsize>,
262
263    /// If a value is set, it determines if writes to DB can stall, which can
264    /// halt the whole process. By default, write stall is enabled on
265    /// validators but not on fullnodes.
266    #[serde(skip_serializing_if = "Option::is_none")]
267    pub enable_db_write_stall: Option<bool>,
268
269    #[serde(default, skip_serializing_if = "Option::is_none")]
270    pub iota_names_config: Option<IotaNamesConfig>,
271
272    /// Flag to enable the gRPC API.
273    #[serde(default)]
274    pub enable_grpc_api: bool,
275    /// Configuration of the gRPC API, read when `enable_grpc_api` is set.
276    ///
277    /// With the key absent the default configuration applies, an explicit
278    /// `null` leaves the API unconfigured — a node with `enable-grpc-api` set
279    /// then fails to start — and a value configures it.
280    #[serde(
281        default = "default_grpc_api_config",
282        skip_serializing_if = "is_default_grpc_api_config"
283    )]
284    pub grpc_api_config: Option<GrpcApiConfig>,
285
286    /// Allow overriding the chain for testing purposes. For instance, it allows
287    /// you to create a test network that believes it is mainnet or testnet.
288    /// Attempting to override this value on production networks will result
289    /// in an error.
290    #[serde(skip_serializing_if = "Option::is_none")]
291    pub chain_override_for_testing: Option<Chain>,
292
293    /// Configuration for the validator client monitor that tracks
294    /// client-observed performance metrics for validators.
295    #[serde(default, skip_serializing_if = "Option::is_none")]
296    pub validator_client_monitor_config:
297        Option<crate::validator_client_monitor_config::ValidatorClientMonitorConfig>,
298
299    /// Limits of the validator's gRPC listener on `network_address`.
300    #[serde(default, skip_serializing_if = "ListenerLimitsConfig::is_unset")]
301    pub validator_grpc_listener_limits: ListenerLimitsConfig,
302
303    /// Limits of the JSON-RPC listener on `json_rpc_address`.
304    #[serde(default, skip_serializing_if = "ListenerLimitsConfig::is_unset")]
305    pub json_rpc_listener_limits: ListenerLimitsConfig,
306
307    /// Limits of the gRPC API listener on `grpc_api_config.address`.
308    #[serde(default, skip_serializing_if = "ListenerLimitsConfig::is_unset")]
309    pub grpc_api_listener_limits: ListenerLimitsConfig,
310}
311
312/// Limits a listener places on the clients that connect to it.
313///
314/// Each field names a setting of `iota_http::Config`, which documents what the
315/// listener does with it. A field left out takes the listener's default, and a
316/// field written as `null` turns that limit off.
317#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
318#[serde(rename_all = "kebab-case")]
319pub struct ListenerLimitsConfig {
320    /// How long an accepted connection may take to complete its TLS handshake.
321    /// Can be turned off only together with `max-pending-connections`.
322    #[serde(default, skip_serializing_if = "Setting::is_unset")]
323    pub handshake_timeout: Setting<Duration>,
324
325    /// How many accepted connections may be in their TLS handshake at the
326    /// same time.
327    #[serde(default, skip_serializing_if = "Setting::is_unset")]
328    pub max_pending_connections: Setting<NonZeroUsize>,
329
330    /// How many connections the listener may hold at once.
331    #[serde(default, skip_serializing_if = "Setting::is_unset")]
332    pub max_connections: Setting<NonZeroUsize>,
333
334    /// How many connections one client address may hold at once.
335    #[serde(default, skip_serializing_if = "Setting::is_unset")]
336    pub max_connections_per_client_ip: Setting<NonZeroUsize>,
337
338    /// How many leading bits of an IPv6 address identify one client.
339    /// Must be between 32 and 128.
340    #[serde(default, skip_serializing_if = "Option::is_none")]
341    pub ipv6_prefix_len: Option<u8>,
342
343    /// How long a connection may serve no request before the listener closes
344    /// it.
345    #[serde(default, skip_serializing_if = "Setting::is_unset")]
346    pub max_connection_idle: Setting<Duration>,
347
348    /// How many HTTP/2 streams one connection may have open at once.
349    #[serde(default, skip_serializing_if = "Setting::is_unset")]
350    pub max_concurrent_streams: Setting<NonZeroU32>,
351
352    /// How often the listener pings an HTTP/2 connection to find out whether
353    /// its peer is still there.
354    #[serde(default, skip_serializing_if = "Setting::is_unset")]
355    pub http2_keepalive_interval: Setting<Duration>,
356
357    /// How long an HTTP/1 connection may take to send a complete request
358    /// header block.
359    #[serde(default, skip_serializing_if = "Setting::is_unset")]
360    pub http1_header_read_timeout: Setting<Duration>,
361}
362
363impl ListenerLimitsConfig {
364    /// Whether every field was left out. Meant for `skip_serializing_if`.
365    pub fn is_unset(&self) -> bool {
366        *self == Self::default()
367    }
368
369    /// Rejects the limits the listener would refuse to start with. `key` is
370    /// the section's key in `NodeConfig`, used in the error.
371    fn validate(&self, key: &str) -> Result<()> {
372        for (name, duration) in [
373            ("handshake-timeout", self.handshake_timeout),
374            ("max-connection-idle", self.max_connection_idle),
375            ("http2-keepalive-interval", self.http2_keepalive_interval),
376            ("http1-header-read-timeout", self.http1_header_read_timeout),
377        ] {
378            if duration == Setting::Value(Duration::ZERO) {
379                anyhow::bail!(
380                    "`{key}.{name}` is 0; set it greater than zero, or to `null` to turn it off"
381                );
382            }
383        }
384        // Every listener defaults both settings to on, so an absent
385        // `max-pending-connections` is on too.
386        if self.handshake_timeout == Setting::Disabled
387            && self.max_pending_connections != Setting::Disabled
388        {
389            anyhow::bail!(
390                "`{key}.handshake-timeout` is `null`, but `max-pending-connections` is on, and \
391                 only the handshake timeout frees its slots; set a handshake timeout, or set \
392                 `max-pending-connections` to `null` too"
393            );
394        }
395        if let Some(len) = self
396            .ipv6_prefix_len
397            .filter(|len| !(MIN_IPV6_PREFIX_LEN..=128).contains(len))
398        {
399            anyhow::bail!(
400                "`{key}.ipv6-prefix-len` is {len}; set it between {MIN_IPV6_PREFIX_LEN} and 128"
401            );
402        }
403        Ok(())
404    }
405}
406
407/// The shortest IPv6 prefix length a listener accepts.
408const MIN_IPV6_PREFIX_LEN: u8 = 32;
409
410#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)]
411#[serde(rename_all = "kebab-case")]
412pub struct TlsConfig {
413    /// File path to a PEM formatted TLS certificate chain
414    cert: String,
415    /// File path to a PEM formatted TLS private key
416    key: String,
417}
418
419impl TlsConfig {
420    pub fn cert(&self) -> &str {
421        &self.cert
422    }
423
424    pub fn key(&self) -> &str {
425        &self.key
426    }
427}
428
429/// Configuration for the gRPC API service
430#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
431#[serde(rename_all = "kebab-case")]
432pub struct GrpcApiConfig {
433    /// The address to bind the gRPC server to
434    #[serde(default = "default_grpc_api_address")]
435    pub address: SocketAddr,
436
437    /// TLS configuration for the gRPC server.
438    ///
439    /// If not provided, the gRPC server will use plain TCP without TLS.
440    #[serde(skip_serializing_if = "Option::is_none")]
441    pub tls: Option<TlsConfig>,
442
443    /// Maximum message size for gRPC responses (in bytes)
444    #[serde(default = "default_grpc_api_max_message_size_bytes")]
445    pub max_message_size_bytes: u32,
446
447    /// Buffer size for broadcast channels used for streaming
448    #[serde(default = "default_grpc_api_broadcast_buffer_size")]
449    pub broadcast_buffer_size: u32,
450
451    /// Maximum number of concurrent subscribers to checkpoint streaming RPCs.
452    /// Once the cap is reached, additional subscribe requests are rejected
453    /// with `Unavailable` to protect the server from being overwhelmed by
454    /// unbounded streaming clients. Values below 1 are clamped to 1 at
455    /// server startup.
456    #[serde(default = "default_grpc_api_max_concurrent_stream_subscribers")]
457    pub max_concurrent_stream_subscribers: u32,
458
459    /// Maximum size for Move values when rendering to JSON
460    /// in bytes.
461    #[serde(default = "default_grpc_api_max_json_move_value_size")]
462    pub max_json_move_value_size: usize,
463
464    /// Maximum number of transactions allowed in a single ExecuteTransactions
465    /// batch request.
466    #[serde(default = "default_grpc_api_max_execute_transaction_batch_size")]
467    pub max_execute_transaction_batch_size: u32,
468
469    /// Maximum number of transactions allowed in a single SimulateTransactions
470    /// batch request.
471    #[serde(default = "default_grpc_api_max_simulate_transaction_batch_size")]
472    pub max_simulate_transaction_batch_size: u32,
473
474    /// Maximum number of objects allowed in a single GetObjects batch request.
475    #[serde(default = "default_grpc_api_max_get_objects_batch_size")]
476    pub max_get_objects_batch_size: u32,
477
478    /// Maximum number of transactions allowed in a single GetTransactions batch
479    /// request.
480    #[serde(default = "default_grpc_api_max_get_transactions_batch_size")]
481    pub max_get_transactions_batch_size: u32,
482
483    /// Maximum number of view function calls allowed in a single
484    /// ViewFunctionCalls batch request.
485    #[serde(default = "default_grpc_api_max_view_function_call_batch_size")]
486    pub max_view_function_call_batch_size: u32,
487
488    /// Maximum allowed timeout in milliseconds for waiting for checkpoint
489    /// inclusion in ExecuteTransactions requests. Client-specified timeouts
490    /// are clamped to this value.
491    #[serde(default = "default_grpc_api_max_checkpoint_inclusion_timeout_ms")]
492    pub max_checkpoint_inclusion_timeout_ms: u64,
493}
494
495fn default_grpc_api_address() -> SocketAddr {
496    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 50051)
497}
498
499fn default_grpc_api_broadcast_buffer_size() -> u32 {
500    100
501}
502
503fn default_grpc_api_max_concurrent_stream_subscribers() -> u32 {
504    1024
505}
506
507fn default_grpc_api_max_message_size_bytes() -> u32 {
508    128 * 1024 * 1024 // 128MB
509}
510
511fn default_grpc_api_max_json_move_value_size() -> usize {
512    1024 * 1024 // 1 MB
513}
514
515fn default_grpc_api_max_execute_transaction_batch_size() -> u32 {
516    20
517}
518
519fn default_grpc_api_max_simulate_transaction_batch_size() -> u32 {
520    20
521}
522
523fn default_grpc_api_max_get_objects_batch_size() -> u32 {
524    1000
525}
526
527fn default_grpc_api_max_get_transactions_batch_size() -> u32 {
528    1000
529}
530
531fn default_grpc_api_max_view_function_call_batch_size() -> u32 {
532    20
533}
534
535fn default_grpc_api_max_checkpoint_inclusion_timeout_ms() -> u64 {
536    60_000 // 60 seconds
537}
538
539impl Default for GrpcApiConfig {
540    fn default() -> Self {
541        Self {
542            address: default_grpc_api_address(),
543            tls: None,
544            max_message_size_bytes: default_grpc_api_max_message_size_bytes(),
545            broadcast_buffer_size: default_grpc_api_broadcast_buffer_size(),
546            max_concurrent_stream_subscribers: default_grpc_api_max_concurrent_stream_subscribers(),
547            max_json_move_value_size: default_grpc_api_max_json_move_value_size(),
548            max_execute_transaction_batch_size: default_grpc_api_max_execute_transaction_batch_size(
549            ),
550            max_simulate_transaction_batch_size:
551                default_grpc_api_max_simulate_transaction_batch_size(),
552            max_get_objects_batch_size: default_grpc_api_max_get_objects_batch_size(),
553            max_get_transactions_batch_size: default_grpc_api_max_get_transactions_batch_size(),
554            max_view_function_call_batch_size: default_grpc_api_max_view_function_call_batch_size(),
555            max_checkpoint_inclusion_timeout_ms:
556                default_grpc_api_max_checkpoint_inclusion_timeout_ms(),
557        }
558    }
559}
560
561impl GrpcApiConfig {
562    // The default maximum uncompressed size in bytes for a message, based on
563    // tonic's default.
564    const GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE: u32 = 4 * 1024 * 1024; // 4MB
565    const GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES: u32 =
566        Self::GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE;
567
568    pub fn tls_config(&self) -> Option<&TlsConfig> {
569        self.tls.as_ref()
570    }
571
572    pub fn max_message_size_bytes(&self) -> u32 {
573        // Ensure max message size is at least the minimum allowed
574        self.max_message_size_bytes
575            .max(Self::GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES)
576    }
577
578    /// Calculate the maximum size for a message that can be
579    /// sent to a client, taking into account the client's max message size
580    /// preference.
581    pub fn max_message_size_client_bytes(&self, client_max_message_size_bytes: Option<u32>) -> u32 {
582        client_max_message_size_bytes
583            // if the client did not specify a max message size, use the tonic default receive
584            // message size
585            .unwrap_or(Self::GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE)
586            // clamp the value between the tonic default and the service max message size
587            .clamp(
588                Self::GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES,
589                self.max_message_size_bytes(),
590            )
591    }
592}
593
594#[derive(Clone, Debug, Default, Deserialize, Serialize)]
595#[serde(rename_all = "kebab-case")]
596pub struct ExecutionCacheConfig {
597    #[serde(default)]
598    pub writeback_cache: WritebackCacheConfig,
599}
600
601#[derive(Clone, Debug, Default, Deserialize, Serialize)]
602#[serde(rename_all = "kebab-case")]
603pub struct WritebackCacheConfig {
604    /// Maximum number of entries in each cache. (There are several
605    /// different caches).
606    #[serde(default, skip_serializing_if = "Option::is_none")]
607    pub max_cache_size: Option<u64>, // defaults to 100000
608
609    #[serde(default, skip_serializing_if = "Option::is_none")]
610    pub package_cache_size: Option<u64>, // defaults to 1000
611
612    #[serde(default, skip_serializing_if = "Option::is_none")]
613    pub object_cache_size: Option<u64>, // defaults to max_cache_size
614    #[serde(default, skip_serializing_if = "Option::is_none")]
615    pub marker_cache_size: Option<u64>, // defaults to object_cache_size
616    #[serde(default, skip_serializing_if = "Option::is_none")]
617    pub object_by_id_cache_size: Option<u64>, // defaults to object_cache_size
618
619    #[serde(default, skip_serializing_if = "Option::is_none")]
620    pub transaction_cache_size: Option<u64>, // defaults to max_cache_size
621    #[serde(default, skip_serializing_if = "Option::is_none")]
622    pub executed_effect_cache_size: Option<u64>, // defaults to transaction_cache_size
623    #[serde(default, skip_serializing_if = "Option::is_none")]
624    pub effect_cache_size: Option<u64>, // defaults to executed_effect_cache_size
625
626    #[serde(default, skip_serializing_if = "Option::is_none")]
627    pub events_cache_size: Option<u64>, // defaults to transaction_cache_size
628
629    #[serde(default, skip_serializing_if = "Option::is_none")]
630    pub transaction_objects_cache_size: Option<u64>, // defaults to 1000
631
632    /// Number of uncommitted transactions at which to pause consensus
633    /// handler.
634    #[serde(default, skip_serializing_if = "Option::is_none")]
635    pub backpressure_threshold: Option<u64>, // defaults to 100_000
636
637    /// Number of uncommitted transactions at which to refuse new
638    /// transaction submissions. Defaults to backpressure_threshold
639    /// if unset.
640    #[serde(default, skip_serializing_if = "Option::is_none")]
641    pub backpressure_threshold_for_rpc: Option<u64>, // defaults to backpressure_threshold
642
643    /// Percentage of `backpressure_threshold` at which graduated load shedding
644    /// based on writeback-cache pending transaction count begins. The
645    /// locally-calculated shedding percentage increases linearly from 0% at
646    /// `backpressure_threshold * backpressure_soft_limit_pct / 100` up to
647    /// 100% at the `backpressure_threshold` if the cache size continues to
648    /// increase. The calculated shedding percentage is broadcast to other
649    /// validators for a coordinated response. Defaults to 50.
650    #[serde(default, skip_serializing_if = "Option::is_none")]
651    pub backpressure_soft_limit_pct: Option<u32>,
652}
653
654impl WritebackCacheConfig {
655    pub fn max_cache_size(&self) -> u64 {
656        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MAX")
657            .ok()
658            .and_then(|s| s.parse().ok())
659            .or(self.max_cache_size)
660            .unwrap_or(100000)
661    }
662
663    pub fn package_cache_size(&self) -> u64 {
664        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_PACKAGE")
665            .ok()
666            .and_then(|s| s.parse().ok())
667            .or(self.package_cache_size)
668            .unwrap_or(1000)
669    }
670
671    pub fn object_cache_size(&self) -> u64 {
672        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT")
673            .ok()
674            .and_then(|s| s.parse().ok())
675            .or(self.object_cache_size)
676            .unwrap_or_else(|| self.max_cache_size())
677    }
678
679    pub fn marker_cache_size(&self) -> u64 {
680        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MARKER")
681            .ok()
682            .and_then(|s| s.parse().ok())
683            .or(self.marker_cache_size)
684            .unwrap_or_else(|| self.object_cache_size())
685    }
686
687    pub fn object_by_id_cache_size(&self) -> u64 {
688        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT_BY_ID")
689            .ok()
690            .and_then(|s| s.parse().ok())
691            .or(self.object_by_id_cache_size)
692            .unwrap_or_else(|| self.object_cache_size())
693    }
694
695    pub fn transaction_cache_size(&self) -> u64 {
696        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION")
697            .ok()
698            .and_then(|s| s.parse().ok())
699            .or(self.transaction_cache_size)
700            .unwrap_or_else(|| self.max_cache_size())
701    }
702
703    pub fn executed_effect_cache_size(&self) -> u64 {
704        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EXECUTED_EFFECT")
705            .ok()
706            .and_then(|s| s.parse().ok())
707            .or(self.executed_effect_cache_size)
708            .unwrap_or_else(|| self.transaction_cache_size())
709    }
710
711    pub fn effect_cache_size(&self) -> u64 {
712        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EFFECT")
713            .ok()
714            .and_then(|s| s.parse().ok())
715            .or(self.effect_cache_size)
716            .unwrap_or_else(|| self.executed_effect_cache_size())
717    }
718
719    pub fn events_cache_size(&self) -> u64 {
720        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EVENTS")
721            .ok()
722            .and_then(|s| s.parse().ok())
723            .or(self.events_cache_size)
724            .unwrap_or_else(|| self.transaction_cache_size())
725    }
726
727    pub fn transaction_objects_cache_size(&self) -> u64 {
728        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION_OBJECTS")
729            .ok()
730            .and_then(|s| s.parse().ok())
731            .or(self.transaction_objects_cache_size)
732            .unwrap_or(1000)
733    }
734
735    pub fn backpressure_threshold(&self) -> u64 {
736        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD")
737            .ok()
738            .and_then(|s| s.parse().ok())
739            .or(self.backpressure_threshold)
740            .unwrap_or(100_000)
741    }
742
743    pub fn backpressure_threshold_for_rpc(&self) -> u64 {
744        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD_FOR_RPC")
745            .ok()
746            .and_then(|s| s.parse().ok())
747            .or(self.backpressure_threshold_for_rpc)
748            .unwrap_or(self.backpressure_threshold())
749    }
750
751    pub fn backpressure_soft_limit_pct(&self) -> u32 {
752        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_SOFT_LIMIT_PCT")
753            .ok()
754            .and_then(|s| s.parse().ok())
755            .or(self.backpressure_soft_limit_pct)
756            .unwrap_or(50)
757            .min(100)
758    }
759}
760
761#[derive(Clone, Debug, Deserialize, Serialize)]
762#[serde(rename_all = "kebab-case")]
763pub struct TransactionKeyValueStoreReadConfig {
764    #[serde(default = "default_base_url")]
765    pub base_url: String,
766
767    #[serde(default = "default_cache_size")]
768    pub cache_size: u64,
769}
770
771impl Default for TransactionKeyValueStoreReadConfig {
772    fn default() -> Self {
773        Self {
774            base_url: default_base_url(),
775            cache_size: default_cache_size(),
776        }
777    }
778}
779
780fn default_base_url() -> String {
781    "".to_string()
782}
783
784fn default_cache_size() -> u64 {
785    100_000
786}
787
788fn default_transaction_kv_store_config() -> TransactionKeyValueStoreReadConfig {
789    TransactionKeyValueStoreReadConfig::default()
790}
791
792fn default_authority_store_pruning_config() -> AuthorityStorePruningConfig {
793    AuthorityStorePruningConfig::default()
794}
795
796pub fn default_enable_jsonrpc_api() -> bool {
797    true
798}
799
800fn default_grpc_address() -> Multiaddr {
801    "/ip4/0.0.0.0/tcp/8080".parse().unwrap()
802}
803fn default_authority_key_pair() -> AuthorityKeyPairWithPath {
804    AuthorityKeyPairWithPath::new(
805        get_key_pair_from_rng::<AuthorityKeyPair, _>(&mut UnwrapErr(SysRng)).1,
806    )
807}
808
809fn default_key_pair() -> KeyPairWithPath {
810    KeyPairWithPath::new(AccountPrivateKey::random().into())
811}
812
813fn default_metrics_address() -> SocketAddr {
814    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9184)
815}
816
817pub fn default_admin_interface_address() -> SocketAddr {
818    SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 1337)
819}
820
821pub fn default_json_rpc_address() -> SocketAddr {
822    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9000)
823}
824
825pub fn default_grpc_api_config() -> Option<GrpcApiConfig> {
826    Some(GrpcApiConfig::default())
827}
828
829fn is_default_grpc_api_config(grpc_api_config: &Option<GrpcApiConfig>) -> bool {
830    serializes_like(grpc_api_config, &default_grpc_api_config())
831}
832
833/// Returns whether `value` and `default` serialize to the same YAML.
834///
835/// Meant for `skip_serializing_if` predicates, which cannot report an error: a
836/// value that fails to serialize is reported as unlike the default, so the
837/// field is kept and the failure surfaces when serializing the field itself.
838fn serializes_like<T: Serialize>(value: &T, default: &T) -> bool {
839    match (serde_yaml::to_string(value), serde_yaml::to_string(default)) {
840        (Ok(value), Ok(default)) => value == default,
841        _ => false,
842    }
843}
844
845pub fn default_grpc_concurrency_limit_per_core() -> NonZeroUsize {
846    NonZeroUsize::new(1000).unwrap()
847}
848
849pub fn default_end_of_epoch_broadcast_channel_capacity() -> usize {
850    128
851}
852
853pub fn default_full_checkpoint_contents_cache_size_mb() -> usize {
854    DEFAULT_FULL_CHECKPOINT_CONTENTS_CACHE_SIZE_MB
855}
856
857pub fn bool_true() -> bool {
858    true
859}
860
861impl Config for NodeConfig {}
862
863impl NodeConfig {
864    pub fn authority_key_pair(&self) -> &AuthorityKeyPair {
865        self.authority_key_pair.authority_keypair()
866    }
867
868    pub fn protocol_private_key(&self) -> NetworkPrivateKey {
869        self.protocol_key_pair.network_private_key()
870    }
871
872    pub fn network_private_key(&self) -> NetworkPrivateKey {
873        self.network_key_pair.network_private_key()
874    }
875
876    pub fn authority_public_key(&self) -> AuthorityPublicKeyBytes {
877        self.authority_key_pair().public().into()
878    }
879
880    pub fn db_path(&self) -> PathBuf {
881        self.db_path.join("live")
882    }
883
884    pub fn snapshot_path(&self) -> PathBuf {
885        self.db_path.join("snapshot")
886    }
887
888    pub fn network_address(&self) -> &Multiaddr {
889        &self.network_address
890    }
891
892    pub fn consensus_config(&self) -> Option<&ConsensusConfig> {
893        self.consensus_config.as_ref()
894    }
895
896    /// Whether this node builds the RPC indexes: only a fullnode with the
897    /// JSON-RPC or gRPC API enabled does.
898    pub fn maintains_rpc_indexes(&self) -> bool {
899        self.consensus_config().is_none() && (self.enable_jsonrpc_api || self.enable_grpc_api)
900    }
901
902    pub fn genesis(&self) -> Result<&genesis::Genesis> {
903        self.genesis.genesis()
904    }
905
906    pub fn load_migration_tx_data(&self) -> Result<MigrationTxData> {
907        let Some(location) = &self.migration_tx_data_path else {
908            anyhow::bail!("no file location set");
909        };
910
911        // Load from file
912        let migration_tx_data = MigrationTxData::load(location)?;
913
914        // Validate migration content in order to avoid corrupted or malicious data
915        migration_tx_data.validate_from_genesis(self.genesis.genesis()?)?;
916        Ok(migration_tx_data)
917    }
918
919    pub fn iota_address(&self) -> Address {
920        self.account_key_pair
921            .keypair()
922            .public_key()
923            .derive_address()
924    }
925
926    pub fn checkpoint_archive_config(&self) -> Option<&CheckpointArchiveConfig> {
927        self.checkpoint_archive_config.as_ref()
928    }
929
930    /// A config selects the validator role exactly when it has a consensus
931    /// config.
932    pub fn is_validator(&self) -> bool {
933        self.consensus_config.is_some()
934    }
935
936    /// Validate the node config. The checks reject a config a node could
937    /// not start with. They also reject the known cases where a node would
938    /// start and ignore part of the config.
939    pub fn validate(&self) -> Result<()> {
940        // The settings a validator must not carry: it never starts the gRPC
941        // server, and snapshot publication is a fullnode role.
942        if self.is_validator() {
943            if self.enable_grpc_api {
944                anyhow::bail!(
945                    "`enable-grpc-api` is set, but validators do not expose the gRPC API; turn \
946                     it off, or move the API to a fullnode"
947                );
948            }
949            if self
950                .state_snapshot_write_config
951                .object_store_config
952                .is_some()
953            {
954                anyhow::bail!(
955                    "`state-snapshot-write-config.object-store-config` is set, but snapshot \
956                     upload is only supported on fullnodes; remove the setting or move the \
957                     upload to a fullnode"
958                );
959            }
960        }
961        // In a file, an absent key deserializes to the default config, and a
962        // config built in code carries it too. `None` here therefore means an
963        // explicit `null`.
964        if self.enable_grpc_api && self.grpc_api_config.is_none() {
965            anyhow::bail!(
966                "`enable-grpc-api` is set but `grpc-api-config` is `null`; give it a value, \
967                 remove the key to take the default config, or turn off `enable-grpc-api`"
968            );
969        }
970        // The uploader builds the store at startup, which needs a backend.
971        if self
972            .state_snapshot_write_config
973            .object_store_config
974            .as_ref()
975            .is_some_and(|store| store.object_store.is_none())
976        {
977            anyhow::bail!(
978                "`state-snapshot-write-config.object-store-config` has no `object-store`; \
979                 snapshot upload needs a storage backend"
980            );
981        }
982        // Right after an epoch boundary, peers still sync the end of the
983        // previous epoch, and a validator still decides whether a transaction
984        // re-proposed from it was already executed, from its checkpoints.
985        if self
986            .authority_store_pruning_config
987            .num_epochs_to_retain_for_checkpoints()
988            == Some(0)
989        {
990            anyhow::bail!(
991                "`num-epochs-to-retain-for-checkpoints` is 0, but the previous epoch's \
992                 checkpoints are still needed after an epoch boundary; set it to 1 or more"
993            );
994        }
995        // Checked on every node: a fullnode starts the validator listener
996        // only when it joins the committee, at an epoch change.
997        for (key, limits) in [
998            (
999                "validator-grpc-listener-limits",
1000                &self.validator_grpc_listener_limits,
1001            ),
1002            ("json-rpc-listener-limits", &self.json_rpc_listener_limits),
1003            ("grpc-api-listener-limits", &self.grpc_api_listener_limits),
1004        ] {
1005            limits.validate(key)?;
1006        }
1007        Ok(())
1008    }
1009}
1010
1011#[derive(Debug, Clone, Deserialize, Serialize)]
1012#[serde(rename_all = "kebab-case")]
1013pub struct ConsensusConfig {
1014    /// Base consensus DB path for all epochs.
1015    pub db_path: PathBuf,
1016
1017    /// The number of epochs for which to retain the consensus DBs.
1018    /// Setting it to 0 will make a consensus DB getting dropped
1019    /// as soon as system is switched to a new epoch.
1020    pub db_retention_epochs: Option<u64>,
1021
1022    /// Pruner will run on every epoch change but it will also check
1023    /// periodically on every `db_pruner_period_secs` seconds to see
1024    /// if there are any epoch DBs to remove.
1025    pub db_pruner_period_secs: Option<u64>,
1026
1027    /// Hard limit on the number of pending transactions to submit to
1028    /// consensus, including those in submission wait and, in the
1029    /// certificate-less (P-COOL) mode, user transactions the validator is
1030    /// still checking. Used as the upper
1031    /// bound for graduated pre-consensus load shedding
1032    /// (`graduated_load_shedding_soft_limit_pct`) in the certificate-less
1033    /// (P-COOL) mode, and as the threshold for the binary
1034    /// cutoff in `ConsensusAdapter::check_consensus_overload()` in both
1035    /// certificate-less and certificate-based flows.
1036    ///
1037    /// Default to 20_000 inflight limit, assuming 20_000 txn tps * 1 sec
1038    /// consensus latency. In the P-COOL mode, a user transaction counts from
1039    /// admission, so that second also includes the checks there and, with
1040    /// attestation, the dry run and the wait for it.
1041    pub max_pending_transactions: Option<usize>,
1042
1043    /// When defined caps the calculated submission position to the
1044    /// max_submit_position.
1045    ///
1046    /// Even if the is elected to submit from a higher
1047    /// position than this, it will "reset" to the max_submit_position.
1048    pub max_submit_position: Option<usize>,
1049
1050    /// The submit delay step to consensus defined in milliseconds.
1051    ///
1052    /// When provided it will override the current back off logic otherwise the
1053    /// default backoff logic will be applied based on consensus latency
1054    /// estimates.
1055    pub submit_delay_step_override_millis: Option<u64>,
1056
1057    /// Parameters for Starfish consensus
1058    #[serde(skip_serializing_if = "Option::is_none", alias = "starfish_parameters")]
1059    pub parameters: Option<StarfishParameters>,
1060
1061    /// Percentage of `max_pending_transactions` (hard limit) defining the soft
1062    /// limit at which graduated pre-consensus load shedding begins. When
1063    /// in-flight transactions are at or below the soft limit, no shedding
1064    /// occurs; above it, the shedding rate scales linearly from 0% to 100% at
1065    /// `max_pending_transactions`. Used in the certificate-less (P-COOL) mode.
1066    #[serde(skip_serializing_if = "Option::is_none")]
1067    pub graduated_load_shedding_soft_limit_pct: Option<u32>,
1068}
1069
1070impl ConsensusConfig {
1071    pub fn db_path(&self) -> &Path {
1072        &self.db_path
1073    }
1074
1075    /// Returns the hard limit on the number of pending transactions to submit
1076    /// to consensus, including those in submission wait and, in the
1077    /// certificate-less (P-COOL) mode, user transactions the validator is
1078    /// still checking. Defaults to 20_000 inflight limit, assuming 20_000 txn
1079    /// tps * 1 sec consensus latency. In the P-COOL mode, a user transaction
1080    /// counts from admission, so that second also includes the checks there
1081    /// and, with attestation, the dry run and the wait for it.
1082    pub fn max_pending_transactions(&self) -> usize {
1083        self.max_pending_transactions.unwrap_or(20_000)
1084    }
1085
1086    /// Returns the percentage of `max_pending_transactions` (hard limit)
1087    /// defining the soft limit at which graduated pre-consensus load
1088    /// shedding begins. Defaults to 50%. Used in the certificate-less
1089    /// (P-COOL) mode.
1090    pub fn graduated_load_shedding_soft_limit_pct(&self) -> u32 {
1091        self.graduated_load_shedding_soft_limit_pct
1092            .unwrap_or(50)
1093            .min(100)
1094    }
1095
1096    pub fn submit_delay_step_override(&self) -> Option<Duration> {
1097        self.submit_delay_step_override_millis
1098            .map(Duration::from_millis)
1099    }
1100
1101    pub fn db_retention_epochs(&self) -> u64 {
1102        self.db_retention_epochs.unwrap_or(0)
1103    }
1104
1105    pub fn db_pruner_period(&self) -> Duration {
1106        // Default to 1 hour
1107        self.db_pruner_period_secs
1108            .map(Duration::from_secs)
1109            .unwrap_or(Duration::from_secs(3_600))
1110    }
1111}
1112
1113#[derive(Clone, Debug, Deserialize, Serialize)]
1114#[serde(rename_all = "kebab-case")]
1115pub struct CheckpointExecutorConfig {
1116    /// Upper bound on the number of checkpoints that can be concurrently
1117    /// executed.
1118    ///
1119    /// If unspecified, this will default to `200`
1120    #[serde(default = "default_checkpoint_execution_max_concurrency")]
1121    pub checkpoint_execution_max_concurrency: usize,
1122
1123    /// Number of seconds to wait for effects of a batch of transactions
1124    /// before logging a warning. Note that we will continue to retry
1125    /// indefinitely.
1126    ///
1127    /// If unspecified, this will default to `10`.
1128    #[serde(default = "default_local_execution_timeout_sec")]
1129    pub local_execution_timeout_sec: u64,
1130
1131    /// Optional directory used for data ingestion pipeline.
1132    ///
1133    /// When specified, each executed checkpoint will be saved in a local
1134    /// directory for post-processing
1135    #[serde(default, skip_serializing_if = "Option::is_none")]
1136    pub data_ingestion_dir: Option<PathBuf>,
1137}
1138
1139#[derive(Clone, Debug, Default, Deserialize, Serialize)]
1140#[serde(rename_all = "kebab-case")]
1141pub struct ExpensiveSafetyCheckConfig {
1142    /// If enabled, at epoch boundary, we will check that the storage
1143    /// fund balance is always identical to the sum of the storage
1144    /// rebate of all live objects, and that the total IOTA in the network
1145    /// remains the same.
1146    #[serde(default)]
1147    enable_epoch_iota_conservation_check: bool,
1148
1149    /// If enabled, we will check that the total IOTA in all input objects of a
1150    /// tx (both the Move part and the storage rebate) matches the total IOTA
1151    /// in all output objects of the tx + gas fees.
1152    #[serde(default)]
1153    enable_deep_per_tx_iota_conservation_check: bool,
1154
1155    /// Disable epoch IOTA conservation check even when we are running in debug
1156    /// mode.
1157    #[serde(default)]
1158    force_disable_epoch_iota_conservation_check: bool,
1159
1160    /// If enabled, at epoch boundary, we will check that the accumulated
1161    /// live object state matches the end of epoch root state digest.
1162    #[serde(default)]
1163    enable_state_consistency_check: bool,
1164
1165    /// Disable state consistency check even when we are running in debug mode.
1166    #[serde(default)]
1167    force_disable_state_consistency_check: bool,
1168}
1169
1170impl ExpensiveSafetyCheckConfig {
1171    pub fn new_enable_all() -> Self {
1172        Self {
1173            enable_epoch_iota_conservation_check: true,
1174            enable_deep_per_tx_iota_conservation_check: true,
1175            force_disable_epoch_iota_conservation_check: false,
1176            enable_state_consistency_check: true,
1177            force_disable_state_consistency_check: false,
1178        }
1179    }
1180
1181    pub fn new_disable_all() -> Self {
1182        Self {
1183            enable_epoch_iota_conservation_check: false,
1184            enable_deep_per_tx_iota_conservation_check: false,
1185            force_disable_epoch_iota_conservation_check: true,
1186            enable_state_consistency_check: false,
1187            force_disable_state_consistency_check: true,
1188        }
1189    }
1190
1191    pub fn force_disable_epoch_iota_conservation_check(&mut self) {
1192        self.force_disable_epoch_iota_conservation_check = true;
1193    }
1194
1195    pub fn enable_epoch_iota_conservation_check(&self) -> bool {
1196        (self.enable_epoch_iota_conservation_check || cfg!(debug_assertions))
1197            && !self.force_disable_epoch_iota_conservation_check
1198    }
1199
1200    pub fn force_disable_state_consistency_check(&mut self) {
1201        self.force_disable_state_consistency_check = true;
1202    }
1203
1204    pub fn enable_state_consistency_check(&self) -> bool {
1205        (self.enable_state_consistency_check || cfg!(debug_assertions))
1206            && !self.force_disable_state_consistency_check
1207    }
1208
1209    pub fn enable_deep_per_tx_iota_conservation_check(&self) -> bool {
1210        self.enable_deep_per_tx_iota_conservation_check || cfg!(debug_assertions)
1211    }
1212}
1213
1214fn default_checkpoint_execution_max_concurrency() -> usize {
1215    4
1216}
1217
1218fn default_local_execution_timeout_sec() -> u64 {
1219    30
1220}
1221
1222impl Default for CheckpointExecutorConfig {
1223    fn default() -> Self {
1224        Self {
1225            checkpoint_execution_max_concurrency: default_checkpoint_execution_max_concurrency(),
1226            local_execution_timeout_sec: default_local_execution_timeout_sec(),
1227            data_ingestion_dir: None,
1228        }
1229    }
1230}
1231
1232#[derive(Debug, Clone, Deserialize, Serialize)]
1233#[serde(rename_all = "kebab-case")]
1234pub struct AuthorityStorePruningConfig {
1235    /// number of the latest epoch dbs to retain
1236    #[serde(default = "default_num_latest_epoch_dbs_to_retain")]
1237    pub num_latest_epoch_dbs_to_retain: usize,
1238    /// Number of historic epochs of object versions to keep, on top of the
1239    /// epoch the node is in. Read through [`Self::num_epochs_to_retain`].
1240    ///   0        — keep the epoch the node is in only (default).
1241    ///   N        — keep the epoch the node is in plus the N epochs before it.
1242    ///   u64::MAX — keep every epoch's bucket; object pruning is off.
1243    #[serde(default)]
1244    pub num_epochs_to_retain: u64,
1245    /// enables periodic background compaction for old SST files whose last
1246    /// modified time is older than `periodic_compaction_threshold_days`
1247    /// days. That ensures that all sst files eventually go through the
1248    /// compaction process
1249    ///
1250    /// With the key absent files older than a day are compacted, an explicit
1251    /// `null` turns periodic compaction off, and a value sets the threshold in
1252    /// days.
1253    #[serde(
1254        default = "default_periodic_compaction_threshold_days",
1255        skip_serializing_if = "is_default_periodic_compaction_threshold_days"
1256    )]
1257    pub periodic_compaction_threshold_days: Option<usize>,
1258    /// Number of historic epochs of transactions, effects, events, and
1259    /// checkpoint data to keep, on top of the epoch the node is in. Controls
1260    /// transaction pruning. Read through
1261    /// [`Self::num_epochs_to_retain_for_checkpoints`].
1262    ///   0        — refused by [`NodeConfig::validate`].
1263    ///   N        — keep the epoch the node is in plus the N epochs before it.
1264    ///   u64::MAX — keep every epoch's bucket; transaction pruning is off.
1265    ///   None     — [`DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS`].
1266    #[serde(skip_serializing_if = "Option::is_none")]
1267    pub num_epochs_to_retain_for_checkpoints: Option<u64>,
1268    /// Number of historic epochs of RPC index history (the transaction and
1269    /// event lookups behind `iotax_queryTransactionBlocks` and
1270    /// `iotax_queryEvents`) to keep, on top of the epoch the node is in. Index tables for live
1271    /// objects are not affected. Read through [`Self::num_epochs_to_retain_for_indexes`].
1272    ///   0        — keep the epoch the node is in only.
1273    ///   N        — keep the epoch the node is in plus the N epochs before it.
1274    ///   u64::MAX — keep every epoch's bucket; index pruning is off.
1275    ///   None     — follow `num_epochs_to_retain_for_checkpoints`.
1276    ///
1277    /// Must not exceed `num_epochs_to_retain_for_checkpoints`; the node
1278    /// refuses to start otherwise.
1279    #[serde(skip_serializing_if = "Option::is_none")]
1280    pub num_epochs_to_retain_for_indexes: Option<u64>,
1281}
1282
1283/// The historic epochs of transactions, effects, events and checkpoint data
1284/// kept when `num-epochs-to-retain-for-checkpoints` is not set: about a month
1285/// at the networks' one-day epochs.
1286pub const DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS: u64 = 30;
1287
1288fn default_num_latest_epoch_dbs_to_retain() -> usize {
1289    3
1290}
1291
1292fn default_periodic_compaction_threshold_days() -> Option<usize> {
1293    Some(1)
1294}
1295
1296fn is_default_periodic_compaction_threshold_days(days: &Option<usize>) -> bool {
1297    *days == default_periodic_compaction_threshold_days()
1298}
1299
1300impl Default for AuthorityStorePruningConfig {
1301    fn default() -> Self {
1302        Self {
1303            num_latest_epoch_dbs_to_retain: default_num_latest_epoch_dbs_to_retain(),
1304            num_epochs_to_retain: 0,
1305            periodic_compaction_threshold_days: default_periodic_compaction_threshold_days(),
1306            num_epochs_to_retain_for_checkpoints: if cfg!(msim) { Some(2) } else { None },
1307            num_epochs_to_retain_for_indexes: None,
1308        }
1309    }
1310}
1311
1312impl AuthorityStorePruningConfig {
1313    pub fn set_num_epochs_to_retain(&mut self, num_epochs_to_retain: u64) {
1314        self.num_epochs_to_retain = num_epochs_to_retain;
1315    }
1316
1317    pub fn set_num_epochs_to_retain_for_checkpoints(&mut self, num_epochs_to_retain: Option<u64>) {
1318        self.num_epochs_to_retain_for_checkpoints = num_epochs_to_retain;
1319    }
1320
1321    /// Historic epochs of object versions to keep on top of the epoch the
1322    /// node is in, `None` when object pruning is off.
1323    pub fn num_epochs_to_retain(&self) -> Option<u64> {
1324        (self.num_epochs_to_retain != u64::MAX).then_some(self.num_epochs_to_retain)
1325    }
1326
1327    /// Historic epochs of transactions, effects, events and checkpoint data
1328    /// to keep on top of the epoch the node is in, `None` when transaction
1329    /// pruning is off. Unset is
1330    /// [`DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS`].
1331    pub fn num_epochs_to_retain_for_checkpoints(&self) -> Option<u64> {
1332        match self.num_epochs_to_retain_for_checkpoints {
1333            Some(u64::MAX) => None,
1334            Some(n) => Some(n),
1335            None => Some(DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS),
1336        }
1337    }
1338
1339    /// Historic epochs of RPC index history to keep on top of the epoch the
1340    /// node is in, `None` when index pruning is off. Unset follows the
1341    /// transaction retention.
1342    pub fn num_epochs_to_retain_for_indexes(&self) -> Option<u64> {
1343        match self.num_epochs_to_retain_for_indexes {
1344            Some(n) if n == u64::MAX => None,
1345            Some(n) => Some(n),
1346            None => self.num_epochs_to_retain_for_checkpoints(),
1347        }
1348    }
1349
1350    /// Fails if the index retention exceeds the transaction retention, which
1351    /// would let `iotax_queryTransactionBlocks` return digests the node has
1352    /// already pruned.
1353    pub fn check_index_retention_within_ledger(&self) -> Result<()> {
1354        let Some(ledger) = self.num_epochs_to_retain_for_checkpoints() else {
1355            // An unbounded ledger outlives every index retention.
1356            return Ok(());
1357        };
1358        let index = self.num_epochs_to_retain_for_indexes();
1359        if index.is_none_or(|index| index > ledger) {
1360            let index = index.map_or("unlimited".to_owned(), |index| index.to_string());
1361            anyhow::bail!(
1362                "num-epochs-to-retain-for-indexes ({index}) must not exceed \
1363                 num-epochs-to-retain-for-checkpoints ({ledger}): a longer index retention \
1364                 lets iotax_queryTransactionBlocks return a transaction digest whose ledger \
1365                 data has already been pruned. Lower num-epochs-to-retain-for-indexes or \
1366                 raise num-epochs-to-retain-for-checkpoints."
1367            );
1368        }
1369        Ok(())
1370    }
1371}
1372
1373#[derive(Debug, Clone, Deserialize, Serialize)]
1374#[serde(rename_all = "kebab-case")]
1375pub struct MetricsConfig {
1376    #[serde(skip_serializing_if = "Option::is_none")]
1377    pub push_interval_seconds: Option<u64>,
1378    #[serde(skip_serializing_if = "Option::is_none")]
1379    pub push_url: Option<String>,
1380    #[serde(skip_serializing_if = "Option::is_none")]
1381    pub groups: Option<MetricGroups>,
1382}
1383
1384fn default_checkpoint_archive_download_concurrency() -> NonZeroUsize {
1385    NonZeroUsize::new(10).unwrap()
1386}
1387
1388fn default_checkpoint_archive_verify_concurrency() -> NonZeroUsize {
1389    std::thread::available_parallelism().unwrap_or(NonZeroUsize::new(4).unwrap())
1390}
1391
1392/// Configuration for backfilling checkpoint contents from the
1393/// checkpoint archive when peers no longer serve the required range.
1394#[derive(Debug, Clone, Deserialize, Serialize)]
1395#[serde(rename_all = "kebab-case")]
1396pub struct CheckpointArchiveConfig {
1397    /// URL of the checkpoint archive to backfill from.
1398    pub url: String,
1399    /// Non-zero number of checkpoints to download in parallel.
1400    #[serde(default = "default_checkpoint_archive_download_concurrency")]
1401    pub download_concurrency: NonZeroUsize,
1402    /// Non-zero number of downloaded checkpoints to verify in parallel.
1403    /// Defaults to the number of CPU cores.
1404    #[serde(default = "default_checkpoint_archive_verify_concurrency")]
1405    pub verify_concurrency: NonZeroUsize,
1406}
1407
1408/// Configuration for the per-epoch state-snapshot publisher.
1409///
1410/// **Operator note (V2 snapshot publishing).** A node configured to publish
1411/// V2 snapshots must have a perpetual store containing no pre-V2
1412/// (`StoreObjectV1`) rows. This means a snapshot-publishing node must have
1413/// either synced from genesis under V2 or been restored from a V2 snapshot.
1414/// There is no on-disk backfill: a fresh sync is the only supported path.
1415#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1416#[serde(rename_all = "kebab-case")]
1417pub struct StateSnapshotConfig {
1418    #[serde(skip_serializing_if = "Option::is_none")]
1419    pub object_store_config: Option<ObjectStoreConfig>,
1420    pub concurrency: usize,
1421}
1422
1423#[derive(Default, Debug, Clone, Deserialize, Serialize)]
1424#[serde(rename_all = "kebab-case")]
1425pub struct TransactionKeyValueStoreWriteConfig {
1426    pub aws_access_key_id: String,
1427    pub aws_secret_access_key: String,
1428    pub aws_region: String,
1429    pub table_name: String,
1430    pub bucket_name: String,
1431    pub concurrency: usize,
1432}
1433
1434/// Configuration for the threshold(s) at which we consider the system
1435/// to be overloaded. When one of the threshold is passed, the node may
1436/// stop processing new transactions and/or certificates until the congestion
1437/// resolves.
1438#[derive(Clone, Debug, Deserialize, Serialize)]
1439#[serde(rename_all = "kebab-case")]
1440pub struct AuthorityOverloadConfig {
1441    /// Maximum time a transaction can wait in the transaction manager execution
1442    /// queue before it triggers an overload detection on the object it depends
1443    /// on.
1444    #[serde(default = "default_max_txn_age_in_queue")]
1445    pub max_txn_age_in_queue: Duration,
1446
1447    /// The interval of checking overload signal.
1448    #[serde(default = "default_overload_monitor_interval")]
1449    pub overload_monitor_interval: Duration,
1450
1451    /// The execution queueing latency when entering load shedding mode.
1452    #[serde(default = "default_execution_queue_latency_soft_limit")]
1453    pub execution_queue_latency_soft_limit: Duration,
1454
1455    /// The execution queueing latency when entering aggressive load shedding
1456    /// mode.
1457    #[serde(default = "default_execution_queue_latency_hard_limit")]
1458    pub execution_queue_latency_hard_limit: Duration,
1459
1460    /// The maximum percentage of transactions to shed in load shedding mode.
1461    #[serde(default = "default_max_load_shedding_percentage")]
1462    pub max_load_shedding_percentage: u32,
1463
1464    /// When in aggressive load shedding mode, the minimum percentage of
1465    /// transactions to shed.
1466    #[serde(default = "default_min_load_shedding_percentage_above_hard_limit")]
1467    pub min_load_shedding_percentage_above_hard_limit: u32,
1468
1469    /// If transaction ready rate is below this rate, we consider the validator
1470    /// is well under used, and will not enter load shedding mode.
1471    #[serde(default = "default_safe_transaction_ready_rate")]
1472    pub safe_transaction_ready_rate: u32,
1473
1474    /// When set to true, transaction signing may be rejected when the validator
1475    /// is overloaded.
1476    #[serde(default = "default_check_system_overload_at_signing")]
1477    pub check_system_overload_at_signing: bool,
1478
1479    /// When set to true, transaction execution may be rejected when the
1480    /// validator is overloaded.
1481    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1482    pub check_system_overload_at_execution: bool,
1483
1484    /// Reject a transaction if transaction manager queue length is above this
1485    /// threshold. 100_000 = 10k TPS * 5s resident time in transaction
1486    /// manager (pending + executing) * 2.
1487    #[serde(default = "default_max_transaction_manager_queue_length")]
1488    pub max_transaction_manager_queue_length: usize,
1489
1490    /// Reject a transaction if the number of pending transactions depending on
1491    /// the object is above the threshold.
1492    #[serde(default = "default_max_transaction_manager_per_object_queue_length")]
1493    pub max_transaction_manager_per_object_queue_length: usize,
1494
1495    /// Percentage of `max_transaction_manager_queue_length` at which graduated
1496    /// load shedding begins in the certificate-less (P-COOL) mode. Read
1497    /// via the same-named accessor, which clamps the value to <=100.
1498    #[serde(default = "default_max_transaction_manager_queue_length_soft_limit_pct")]
1499    pub max_transaction_manager_queue_length_soft_limit_pct: u32,
1500
1501    /// Maximum number of attestation dry runs the validator runs at once.
1502    /// Unset means a quarter of the available cores, at least one.
1503    #[serde(default, skip_serializing_if = "Option::is_none")]
1504    pub max_concurrent_attestations: Option<NonZeroUsize>,
1505
1506    /// Maximum number of submissions that wait for a free attestation dry run,
1507    /// a bound on the memory they hold. A submission that finds every dry run
1508    /// taken and this many waiting is rejected with
1509    /// [`IotaError::ValidatorOverloadedRetryAfter`]. Unset means 1,024.
1510    ///
1511    /// [`IotaError::ValidatorOverloadedRetryAfter`]: iota_types::error::IotaError::ValidatorOverloadedRetryAfter
1512    #[serde(default, skip_serializing_if = "Option::is_none")]
1513    pub max_queued_attestations: Option<usize>,
1514
1515    /// Maximum time a submission waits for a free attestation dry run. A
1516    /// submission that has waited this long, or whose expected wait is longer
1517    /// when it arrives, is rejected with
1518    /// [`IotaError::ValidatorOverloadedRetryAfter`], which asks the client to
1519    /// retry after the first whole second past this wait. Unset means 500 ms.
1520    ///
1521    /// [`IotaError::ValidatorOverloadedRetryAfter`]: iota_types::error::IotaError::ValidatorOverloadedRetryAfter
1522    #[serde(default, skip_serializing_if = "Option::is_none")]
1523    pub max_attestation_wait: Option<Duration>,
1524}
1525
1526impl AuthorityOverloadConfig {
1527    /// Returns the soft-limit percentage, clamped to <=100 to guard against
1528    /// out-of-range operator-supplied values.
1529    pub fn max_transaction_manager_queue_length_soft_limit_pct(&self) -> u32 {
1530        self.max_transaction_manager_queue_length_soft_limit_pct
1531            .min(100)
1532    }
1533}
1534
1535fn default_max_txn_age_in_queue() -> Duration {
1536    Duration::from_millis(500)
1537}
1538
1539fn default_overload_monitor_interval() -> Duration {
1540    Duration::from_secs(10)
1541}
1542
1543fn default_execution_queue_latency_soft_limit() -> Duration {
1544    Duration::from_secs(1)
1545}
1546
1547fn default_execution_queue_latency_hard_limit() -> Duration {
1548    Duration::from_secs(10)
1549}
1550
1551fn default_max_load_shedding_percentage() -> u32 {
1552    95
1553}
1554
1555fn default_min_load_shedding_percentage_above_hard_limit() -> u32 {
1556    50
1557}
1558
1559fn default_safe_transaction_ready_rate() -> u32 {
1560    100
1561}
1562
1563fn default_check_system_overload_at_signing() -> bool {
1564    true
1565}
1566
1567fn default_max_transaction_manager_queue_length() -> usize {
1568    100_000
1569}
1570
1571fn default_max_transaction_manager_queue_length_soft_limit_pct() -> u32 {
1572    50
1573}
1574
1575fn default_max_transaction_manager_per_object_queue_length() -> usize {
1576    20
1577}
1578
1579impl Default for AuthorityOverloadConfig {
1580    fn default() -> Self {
1581        Self {
1582            max_txn_age_in_queue: default_max_txn_age_in_queue(),
1583            overload_monitor_interval: default_overload_monitor_interval(),
1584            execution_queue_latency_soft_limit: default_execution_queue_latency_soft_limit(),
1585            execution_queue_latency_hard_limit: default_execution_queue_latency_hard_limit(),
1586            max_load_shedding_percentage: default_max_load_shedding_percentage(),
1587            min_load_shedding_percentage_above_hard_limit:
1588                default_min_load_shedding_percentage_above_hard_limit(),
1589            safe_transaction_ready_rate: default_safe_transaction_ready_rate(),
1590            check_system_overload_at_signing: true,
1591            check_system_overload_at_execution: false,
1592            max_transaction_manager_queue_length: default_max_transaction_manager_queue_length(),
1593            max_transaction_manager_queue_length_soft_limit_pct:
1594                default_max_transaction_manager_queue_length_soft_limit_pct(),
1595            max_transaction_manager_per_object_queue_length:
1596                default_max_transaction_manager_per_object_queue_length(),
1597            max_concurrent_attestations: None,
1598            max_queued_attestations: None,
1599            max_attestation_wait: None,
1600        }
1601    }
1602}
1603
1604fn default_authority_overload_config() -> AuthorityOverloadConfig {
1605    AuthorityOverloadConfig::default()
1606}
1607
1608fn default_traffic_controller_policy_config() -> Option<PolicyConfig> {
1609    Some(PolicyConfig::default_dos_protection_policy())
1610}
1611
1612fn is_default_traffic_controller_policy_config(policy_config: &Option<PolicyConfig>) -> bool {
1613    serializes_like(policy_config, &default_traffic_controller_policy_config())
1614}
1615
1616#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1617pub struct Genesis {
1618    #[serde(flatten)]
1619    location: Option<GenesisLocation>,
1620
1621    #[serde(skip)]
1622    genesis: once_cell::sync::OnceCell<genesis::Genesis>,
1623}
1624
1625impl Genesis {
1626    pub fn new(genesis: genesis::Genesis) -> Self {
1627        Self {
1628            location: Some(GenesisLocation::InPlace {
1629                genesis: Box::new(genesis),
1630            }),
1631            genesis: Default::default(),
1632        }
1633    }
1634
1635    pub fn new_from_file<P: Into<PathBuf>>(path: P) -> Self {
1636        Self {
1637            location: Some(GenesisLocation::File {
1638                genesis_file_location: path.into(),
1639            }),
1640            genesis: Default::default(),
1641        }
1642    }
1643
1644    pub fn new_empty() -> Self {
1645        Self {
1646            location: None,
1647            genesis: Default::default(),
1648        }
1649    }
1650
1651    pub fn genesis(&self) -> Result<&genesis::Genesis> {
1652        match &self.location {
1653            Some(GenesisLocation::InPlace { genesis }) => Ok(genesis),
1654            Some(GenesisLocation::File {
1655                genesis_file_location,
1656            }) => self
1657                .genesis
1658                .get_or_try_init(|| genesis::Genesis::load(genesis_file_location)),
1659            None => anyhow::bail!("no genesis location set"),
1660        }
1661    }
1662}
1663
1664#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1665#[serde(untagged)]
1666enum GenesisLocation {
1667    InPlace {
1668        genesis: Box<genesis::Genesis>,
1669    },
1670    File {
1671        #[serde(rename = "genesis-file-location")]
1672        genesis_file_location: PathBuf,
1673    },
1674}
1675
1676/// Wrapper struct for SimpleKeypair that can be deserialized from a file path.
1677/// Used by network, worker, and account keypair.
1678#[derive(Clone, Debug, Deserialize, Serialize)]
1679pub struct KeyPairWithPath {
1680    #[serde(flatten)]
1681    location: KeyPairLocation,
1682
1683    #[serde(skip)]
1684    keypair: OnceCell<Arc<SimpleKeypair>>,
1685}
1686
1687impl PartialEq for KeyPairWithPath {
1688    fn eq(&self, other: &Self) -> bool {
1689        self.location == other.location
1690    }
1691}
1692
1693impl Eq for KeyPairWithPath {}
1694
1695#[derive(Debug, Clone, Deserialize, Serialize)]
1696#[serde(untagged)]
1697enum KeyPairLocation {
1698    InPlace {
1699        #[serde(with = "bech32_formatted_keypair")]
1700        value: Arc<SimpleKeypair>,
1701    },
1702    File {
1703        path: PathBuf,
1704    },
1705}
1706
1707impl PartialEq for KeyPairLocation {
1708    fn eq(&self, other: &Self) -> bool {
1709        match (self, other) {
1710            (Self::InPlace { value: a }, Self::InPlace { value: b }) => {
1711                a.to_bytes() == b.to_bytes()
1712            }
1713            (Self::File { path: a }, Self::File { path: b }) => a == b,
1714            _ => false,
1715        }
1716    }
1717}
1718
1719impl Eq for KeyPairLocation {}
1720
1721impl KeyPairWithPath {
1722    pub fn new(kp: SimpleKeypair) -> Self {
1723        let cell: OnceCell<Arc<SimpleKeypair>> = OnceCell::new();
1724        let arc_kp = Arc::new(kp);
1725        // OK to unwrap panic because authority should not start without all keypairs
1726        // loaded.
1727        cell.set(arc_kp.clone()).expect("failed to set keypair");
1728        Self {
1729            location: KeyPairLocation::InPlace { value: arc_kp },
1730            keypair: cell,
1731        }
1732    }
1733
1734    pub fn new_from_path(path: PathBuf) -> Self {
1735        let cell: OnceCell<Arc<SimpleKeypair>> = OnceCell::new();
1736        // OK to unwrap panic because authority should not start without all keypairs
1737        // loaded.
1738        cell.set(Arc::new(read_keypair_from_file(&path).unwrap_or_else(
1739            |e| panic!("invalid keypair file at path {path:?}: {e}"),
1740        )))
1741        .expect("failed to set keypair");
1742        Self {
1743            location: KeyPairLocation::File { path },
1744            keypair: cell,
1745        }
1746    }
1747
1748    pub fn keypair(&self) -> &SimpleKeypair {
1749        self.keypair
1750            .get_or_init(|| match &self.location {
1751                KeyPairLocation::InPlace { value } => value.clone(),
1752                KeyPairLocation::File { path } => {
1753                    // OK to unwrap panic because authority should not start without all keypairs
1754                    // loaded.
1755                    Arc::new(
1756                        read_keypair_from_file(path).unwrap_or_else(|e| {
1757                            panic!("invalid keypair file at path {path:?}: {e}")
1758                        }),
1759                    )
1760                }
1761            })
1762            .as_ref()
1763    }
1764
1765    /// The stored keypair as an ed25519 network private key, for the network
1766    /// stacks that consume that type directly. Panics if the stored keypair
1767    /// is not ed25519.
1768    pub fn network_private_key(&self) -> NetworkPrivateKey {
1769        self.keypair()
1770            .as_opt_ed25519()
1771            .cloned()
1772            .expect("only Ed25519 network keys are allowed")
1773    }
1774}
1775
1776/// Wrapper struct for AuthorityKeyPair that can be deserialized from a file
1777/// path.
1778#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
1779pub struct AuthorityKeyPairWithPath {
1780    #[serde(flatten)]
1781    location: AuthorityKeyPairLocation,
1782
1783    #[serde(skip)]
1784    keypair: OnceCell<Arc<AuthorityKeyPair>>,
1785}
1786
1787#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
1788#[serde(untagged)]
1789enum AuthorityKeyPairLocation {
1790    InPlace { value: Arc<AuthorityKeyPair> },
1791    File { path: PathBuf },
1792}
1793
1794impl AuthorityKeyPairWithPath {
1795    pub fn new(kp: AuthorityKeyPair) -> Self {
1796        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
1797        let arc_kp = Arc::new(kp);
1798        // OK to unwrap panic because authority should not start without all keypairs
1799        // loaded.
1800        cell.set(arc_kp.clone())
1801            .expect("failed to set authority keypair");
1802        Self {
1803            location: AuthorityKeyPairLocation::InPlace { value: arc_kp },
1804            keypair: cell,
1805        }
1806    }
1807
1808    pub fn new_from_path(path: PathBuf) -> Self {
1809        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
1810        // OK to unwrap panic because authority should not start without all keypairs
1811        // loaded.
1812        cell.set(Arc::new(
1813            read_authority_keypair_from_file(&path)
1814                .unwrap_or_else(|_| panic!("invalid authority keypair file at path {path:?}")),
1815        ))
1816        .expect("failed to set authority keypair");
1817        Self {
1818            location: AuthorityKeyPairLocation::File { path },
1819            keypair: cell,
1820        }
1821    }
1822
1823    pub fn authority_keypair(&self) -> &AuthorityKeyPair {
1824        self.keypair
1825            .get_or_init(|| match &self.location {
1826                AuthorityKeyPairLocation::InPlace { value } => value.clone(),
1827                AuthorityKeyPairLocation::File { path } => {
1828                    // OK to unwrap panic because authority should not start without all keypairs
1829                    // loaded.
1830                    Arc::new(
1831                        read_authority_keypair_from_file(path)
1832                            .unwrap_or_else(|_| panic!("invalid authority keypair file {path:?}")),
1833                    )
1834                }
1835            })
1836            .as_ref()
1837    }
1838}
1839
1840/// Configurations which determine how we dump state debug info.
1841/// Debug info is dumped when a node forks.
1842#[derive(Clone, Debug, Deserialize, Serialize, Default)]
1843#[serde(rename_all = "kebab-case")]
1844pub struct StateDebugDumpConfig {
1845    #[serde(skip_serializing_if = "Option::is_none")]
1846    pub dump_file_directory: Option<PathBuf>,
1847}
1848
1849#[cfg(test)]
1850mod tests {
1851    use std::{
1852        num::{NonZeroU32, NonZeroUsize},
1853        path::PathBuf,
1854        time::Duration,
1855    };
1856
1857    use fastcrypto::traits::KeyPair;
1858    use iota_keys::keypair_file::{write_authority_keypair_to_file, write_keypair_to_file};
1859    use iota_sdk_crypto::simple::SimpleKeypair;
1860    use iota_types::{
1861        crypto::{AuthorityKeyPair, NetworkPrivateKey, get_key_pair_from_rng},
1862        traffic_control::PolicyConfig,
1863    };
1864    use rand::{SeedableRng, rngs::StdRng};
1865    use serde::Serialize;
1866    use serde_yaml::Value;
1867
1868    use super::{
1869        AuthorityStorePruningConfig, DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS, Genesis,
1870        GrpcApiConfig, ListenerLimitsConfig, ObjectStoreConfig, default_grpc_api_config,
1871        default_periodic_compaction_threshold_days, default_traffic_controller_policy_config,
1872    };
1873    use crate::{
1874        ConsensusConfig, NodeConfig, object_storage_config::ObjectStoreType, setting::Setting,
1875    };
1876
1877    const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
1878
1879    const POLICY_CONFIG: &[&str] = &["policy-config"];
1880    const GRPC_API_CONFIG: &[&str] = &["grpc-api-config"];
1881    const COMPACTION_THRESHOLD: &[&str] = &[
1882        "authority-store-pruning-config",
1883        "periodic-compaction-threshold-days",
1884    ];
1885
1886    fn template_config() -> NodeConfig {
1887        serde_yaml::from_str(TEMPLATE).unwrap()
1888    }
1889
1890    fn consensus_config() -> super::ConsensusConfig {
1891        serde_yaml::from_str("db-path: /opt/iota/consensus-db").unwrap()
1892    }
1893
1894    fn object_store_config() -> ObjectStoreConfig {
1895        ObjectStoreConfig {
1896            object_store: Some(ObjectStoreType::File),
1897            directory: Some(PathBuf::from("/opt/iota/snapshots")),
1898            ..Default::default()
1899        }
1900    }
1901
1902    fn round_trip(config: &NodeConfig) -> NodeConfig {
1903        serde_yaml::from_str(&serde_yaml::to_string(config).unwrap()).unwrap()
1904    }
1905
1906    fn as_yaml<T: Serialize>(value: &T) -> String {
1907        serde_yaml::to_string(value).unwrap()
1908    }
1909
1910    /// Reads `path` out of a serialized value, returning `None` when the last
1911    /// key is absent.
1912    fn written_at(value: &Value, path: &[&str]) -> Option<Value> {
1913        let (last, parents) = path.split_last().unwrap();
1914        let mut current = value;
1915        for name in parents {
1916            current = current
1917                .as_mapping()
1918                .unwrap()
1919                .get(&Value::String((*name).to_owned()))
1920                .unwrap();
1921        }
1922        current
1923            .as_mapping()
1924            .unwrap()
1925            .get(&Value::String((*last).to_owned()))
1926            .cloned()
1927    }
1928
1929    #[test]
1930    fn a_retention_below_two_is_no_longer_rounded_up() {
1931        let config = AuthorityStorePruningConfig {
1932            num_epochs_to_retain_for_checkpoints: Some(1),
1933            ..Default::default()
1934        };
1935        assert_eq!(config.num_epochs_to_retain_for_checkpoints(), Some(1));
1936    }
1937
1938    #[test]
1939    fn index_retention_within_ledger_retention_is_accepted() {
1940        let config = AuthorityStorePruningConfig {
1941            num_epochs_to_retain_for_checkpoints: Some(2),
1942            num_epochs_to_retain_for_indexes: Some(2),
1943            ..Default::default()
1944        };
1945        assert!(config.check_index_retention_within_ledger().is_ok());
1946    }
1947
1948    #[test]
1949    fn index_retention_beyond_ledger_retention_is_refused() {
1950        let config = AuthorityStorePruningConfig {
1951            num_epochs_to_retain_for_checkpoints: Some(2),
1952            num_epochs_to_retain_for_indexes: Some(3),
1953            ..Default::default()
1954        };
1955        let err = config
1956            .check_index_retention_within_ledger()
1957            .unwrap_err()
1958            .to_string();
1959        assert!(err.contains("num-epochs-to-retain-for-indexes"), "{err}");
1960        assert!(
1961            err.contains("num-epochs-to-retain-for-checkpoints"),
1962            "{err}"
1963        );
1964        assert!(err.contains('3'), "{err}");
1965        assert!(err.contains('2'), "{err}");
1966    }
1967
1968    #[test]
1969    fn the_narrowest_ledger_retention_refuses_a_longer_index_retention() {
1970        let config = AuthorityStorePruningConfig {
1971            num_epochs_to_retain_for_checkpoints: Some(1),
1972            num_epochs_to_retain_for_indexes: Some(2),
1973            ..Default::default()
1974        };
1975        assert!(config.check_index_retention_within_ledger().is_err());
1976    }
1977
1978    #[test]
1979    fn equal_narrowest_retentions_are_accepted() {
1980        let config = AuthorityStorePruningConfig {
1981            num_epochs_to_retain_for_checkpoints: Some(1),
1982            num_epochs_to_retain_for_indexes: Some(1),
1983            ..Default::default()
1984        };
1985        assert!(config.check_index_retention_within_ledger().is_ok());
1986    }
1987
1988    #[test]
1989    fn unbounded_ledger_retention_accepts_any_index_retention() {
1990        let config = AuthorityStorePruningConfig {
1991            num_epochs_to_retain_for_checkpoints: Some(u64::MAX),
1992            num_epochs_to_retain_for_indexes: Some(1000),
1993            ..Default::default()
1994        };
1995        assert!(config.check_index_retention_within_ledger().is_ok());
1996    }
1997
1998    #[test]
1999    fn unset_ledger_retention_keeps_the_default_and_the_index_follows_it() {
2000        let config = AuthorityStorePruningConfig {
2001            num_epochs_to_retain_for_checkpoints: None,
2002            num_epochs_to_retain_for_indexes: None,
2003            ..Default::default()
2004        };
2005        assert_eq!(
2006            config.num_epochs_to_retain_for_checkpoints(),
2007            Some(DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS)
2008        );
2009        assert_eq!(
2010            config.num_epochs_to_retain_for_indexes(),
2011            Some(DEFAULT_NUM_EPOCHS_TO_RETAIN_FOR_CHECKPOINTS)
2012        );
2013        assert!(config.check_index_retention_within_ledger().is_ok());
2014    }
2015
2016    #[test]
2017    fn unset_index_retention_follows_the_ledger() {
2018        let config = AuthorityStorePruningConfig {
2019            num_epochs_to_retain_for_checkpoints: Some(3),
2020            num_epochs_to_retain_for_indexes: None,
2021            ..Default::default()
2022        };
2023        assert_eq!(config.num_epochs_to_retain_for_indexes(), Some(3));
2024        assert!(config.check_index_retention_within_ledger().is_ok());
2025    }
2026
2027    #[test]
2028    fn index_pruning_turned_off_against_a_bounded_ledger_is_refused() {
2029        // `u64::MAX` is index pruning off, which outlives any bounded ledger.
2030        let config = AuthorityStorePruningConfig {
2031            num_epochs_to_retain_for_checkpoints: Some(2),
2032            num_epochs_to_retain_for_indexes: Some(u64::MAX),
2033            ..Default::default()
2034        };
2035        let err = config
2036            .check_index_retention_within_ledger()
2037            .unwrap_err()
2038            .to_string();
2039        assert!(err.contains("unlimited"), "{err}");
2040    }
2041
2042    #[test]
2043    fn max_retention_means_pruning_is_off_for_every_knob() {
2044        let config = AuthorityStorePruningConfig {
2045            num_epochs_to_retain: u64::MAX,
2046            num_epochs_to_retain_for_checkpoints: Some(u64::MAX),
2047            num_epochs_to_retain_for_indexes: Some(u64::MAX),
2048            ..Default::default()
2049        };
2050        assert_eq!(config.num_epochs_to_retain(), None);
2051        assert_eq!(config.num_epochs_to_retain_for_checkpoints(), None);
2052        assert_eq!(config.num_epochs_to_retain_for_indexes(), None);
2053    }
2054
2055    #[test]
2056    fn a_fullnode_serving_an_api_builds_the_indexes() {
2057        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
2058
2059        let config: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2060        assert!(config.maintains_rpc_indexes());
2061    }
2062
2063    #[test]
2064    fn a_fullnode_with_both_apis_off_builds_no_indexes() {
2065        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
2066
2067        let mut config: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2068        config.enable_jsonrpc_api = false;
2069        config.enable_grpc_api = false;
2070        assert!(!config.maintains_rpc_indexes());
2071    }
2072
2073    #[test]
2074    fn a_validator_builds_no_indexes_even_with_an_api_enabled() {
2075        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
2076
2077        let mut config: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2078        config.enable_jsonrpc_api = true;
2079        config.consensus_config = Some(ConsensusConfig {
2080            db_path: PathBuf::from("/tmp/consensus"),
2081            db_retention_epochs: None,
2082            db_pruner_period_secs: None,
2083            max_pending_transactions: None,
2084            max_submit_position: None,
2085            submit_delay_step_override_millis: None,
2086            parameters: None,
2087            graduated_load_shedding_soft_limit_pct: None,
2088        });
2089        assert!(!config.maintains_rpc_indexes());
2090    }
2091
2092    #[test]
2093    fn serialize_genesis_from_file() {
2094        let g = Genesis::new_from_file("path/to/file");
2095
2096        let s = serde_yaml::to_string(&g).unwrap();
2097        assert_eq!("---\ngenesis-file-location: path/to/file\n", s);
2098        let loaded_genesis: Genesis = serde_yaml::from_str(&s).unwrap();
2099        assert_eq!(g, loaded_genesis);
2100    }
2101
2102    #[test]
2103    fn fullnode_template() {
2104        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
2105
2106        let _template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2107    }
2108
2109    #[test]
2110    fn validate_requires_a_grpc_config_when_the_api_is_enabled() {
2111        // An absent key gives the default config, so only an explicit `null`
2112        // reaches this rule.
2113        let mut config = template_config();
2114        config.grpc_api_config = None;
2115        config.validate().unwrap();
2116
2117        config.enable_grpc_api = true;
2118        let err = config.validate().unwrap_err().to_string();
2119        assert!(err.contains("`grpc-api-config` is `null`"), "{err}");
2120
2121        config.grpc_api_config = Some(GrpcApiConfig::default());
2122        config.validate().unwrap();
2123
2124        // Validators do not expose the gRPC API, so the config check does
2125        // not apply to them and the API itself is rejected instead.
2126        config.grpc_api_config = None;
2127        config.consensus_config = Some(consensus_config());
2128        let err = config.validate().unwrap_err().to_string();
2129        assert!(err.contains("validators do not expose"), "{err}");
2130    }
2131
2132    #[test]
2133    fn validate_rejects_the_grpc_api_on_a_validator() {
2134        let mut config = template_config();
2135        config.consensus_config = Some(consensus_config());
2136        config.validate().unwrap();
2137
2138        config.enable_grpc_api = true;
2139        let err = config.validate().unwrap_err().to_string();
2140        assert!(err.contains("validators do not expose"), "{err}");
2141
2142        // The same config is valid for a fullnode.
2143        config.consensus_config = None;
2144        config.validate().unwrap();
2145    }
2146
2147    #[test]
2148    fn validate_rejects_snapshot_upload_on_a_validator() {
2149        let mut config = template_config();
2150        config.state_snapshot_write_config.object_store_config = Some(object_store_config());
2151        config.validate().unwrap();
2152
2153        config.consensus_config = Some(consensus_config());
2154        let err = config.validate().unwrap_err().to_string();
2155        assert!(err.contains("snapshot upload"), "{err}");
2156    }
2157
2158    #[test]
2159    fn validate_rejects_a_snapshot_store_without_a_backend() {
2160        let mut config = template_config();
2161        config.state_snapshot_write_config.object_store_config = Some(ObjectStoreConfig::default());
2162
2163        let err = config.validate().unwrap_err().to_string();
2164        assert!(err.contains("storage backend"), "{err}");
2165    }
2166
2167    #[test]
2168    fn validate_rejects_a_zero_checkpoint_retention() {
2169        let mut config = template_config();
2170        config
2171            .authority_store_pruning_config
2172            .set_num_epochs_to_retain_for_checkpoints(Some(0));
2173        let err = config.validate().unwrap_err().to_string();
2174        assert!(
2175            err.contains("num-epochs-to-retain-for-checkpoints"),
2176            "{err}"
2177        );
2178
2179        config
2180            .authority_store_pruning_config
2181            .set_num_epochs_to_retain_for_checkpoints(Some(1));
2182        config.validate().unwrap();
2183    }
2184
2185    /// The keys of the listeners' limits sections in a node config.
2186    const LISTENER_LIMITS_KEYS: [&str; 3] = [
2187        "validator-grpc-listener-limits",
2188        "json-rpc-listener-limits",
2189        "grpc-api-listener-limits",
2190    ];
2191
2192    /// The template config with `limits`, a YAML mapping, under `key`.
2193    fn config_with_listener_limits(key: &str, limits: &str) -> NodeConfig {
2194        serde_yaml::from_str(&format!("{TEMPLATE}\n{key}: {limits}\n")).unwrap()
2195    }
2196
2197    /// The pending-connection limit is on unless turned off, and only the
2198    /// handshake timeout frees its slots, so the timeout can be turned off
2199    /// only together with it. The template is a fullnode's, so this also
2200    /// covers the validator listener it starts only once it joins the
2201    /// committee.
2202    #[test]
2203    fn validate_rejects_a_handshake_timeout_turned_off_alone() {
2204        for key in LISTENER_LIMITS_KEYS {
2205            for limits in [
2206                "{handshake-timeout: null}",
2207                "{handshake-timeout: null, max-pending-connections: 1}",
2208            ] {
2209                let err = config_with_listener_limits(key, limits)
2210                    .validate()
2211                    .unwrap_err()
2212                    .to_string();
2213                assert!(
2214                    err.contains(&format!("`{key}.handshake-timeout` is `null`")),
2215                    "{limits}: {err}"
2216                );
2217            }
2218            config_with_listener_limits(
2219                key,
2220                "{handshake-timeout: null, max-pending-connections: null}",
2221            )
2222            .validate()
2223            .unwrap();
2224        }
2225    }
2226
2227    /// A zero deadline is reached at once and a zero interval never pauses,
2228    /// so the listener refuses either.
2229    #[test]
2230    fn validate_rejects_a_zero_listener_duration() {
2231        for key in LISTENER_LIMITS_KEYS {
2232            for name in [
2233                "handshake-timeout",
2234                "max-connection-idle",
2235                "http2-keepalive-interval",
2236                "http1-header-read-timeout",
2237            ] {
2238                let err =
2239                    config_with_listener_limits(key, &format!("{{{name}: {{secs: 0, nanos: 0}}}}"))
2240                        .validate()
2241                        .unwrap_err()
2242                        .to_string();
2243                assert!(err.contains(&format!("`{key}.{name}` is 0")), "{err}");
2244
2245                config_with_listener_limits(key, &format!("{{{name}: {{secs: 1, nanos: 0}}}}"))
2246                    .validate()
2247                    .unwrap();
2248            }
2249        }
2250    }
2251
2252    /// The listener accepts IPv6 prefix lengths from 32 to 128 bits.
2253    #[test]
2254    fn validate_rejects_an_ipv6_prefix_len_out_of_range() {
2255        for key in LISTENER_LIMITS_KEYS {
2256            for len in [0, 31, 129] {
2257                let err = config_with_listener_limits(key, &format!("{{ipv6-prefix-len: {len}}}"))
2258                    .validate()
2259                    .unwrap_err()
2260                    .to_string();
2261                assert!(
2262                    err.contains(&format!("`{key}.ipv6-prefix-len` is {len}")),
2263                    "{err}"
2264                );
2265            }
2266            for len in [32, 128] {
2267                config_with_listener_limits(key, &format!("{{ipv6-prefix-len: {len}}}"))
2268                    .validate()
2269                    .unwrap();
2270            }
2271        }
2272    }
2273
2274    #[test]
2275    fn enable_soft_locking_defaults_to_enabled() {
2276        // The template omits `enable-soft-locking`, so this exercises the serde
2277        // default and pins the documented "default: enabled" contract.
2278        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");
2279
2280        let config: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2281        assert!(config.enable_soft_locking);
2282    }
2283
2284    #[test]
2285    fn load_key_pairs_to_node_config() {
2286        let authority_key_pair: AuthorityKeyPair =
2287            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
2288        let protocol_private_key: NetworkPrivateKey =
2289            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
2290        let network_private_key: NetworkPrivateKey =
2291            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
2292
2293        write_authority_keypair_to_file(&authority_key_pair, PathBuf::from("authority.key"))
2294            .unwrap();
2295        write_keypair_to_file(
2296            &SimpleKeypair::from(protocol_private_key.clone()),
2297            PathBuf::from("protocol.key"),
2298        )
2299        .unwrap();
2300        write_keypair_to_file(
2301            &SimpleKeypair::from(network_private_key.clone()),
2302            PathBuf::from("network.key"),
2303        )
2304        .unwrap();
2305
2306        const TEMPLATE: &str = include_str!("../data/fullnode-template-with-path.yaml");
2307        let template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
2308        assert_eq!(
2309            template.authority_key_pair().public(),
2310            authority_key_pair.public()
2311        );
2312        assert_eq!(
2313            template.network_private_key().public_key(),
2314            network_private_key.public_key()
2315        );
2316        assert_eq!(
2317            template.protocol_private_key().public_key(),
2318            protocol_private_key.public_key()
2319        );
2320    }
2321
2322    #[test]
2323    fn a_policy_config_survives_a_round_trip_in_all_three_states() {
2324        let mut config = template_config();
2325
2326        config.policy_config = None;
2327        assert!(round_trip(&config).policy_config.is_none());
2328
2329        config.policy_config = default_traffic_controller_policy_config();
2330        assert_eq!(
2331            as_yaml(&round_trip(&config).policy_config),
2332            as_yaml(&default_traffic_controller_policy_config())
2333        );
2334
2335        let configured = PolicyConfig {
2336            dry_run: !PolicyConfig::default_dos_protection_policy().dry_run,
2337            ..PolicyConfig::default_dos_protection_policy()
2338        };
2339        config.policy_config = Some(configured.clone());
2340        assert_eq!(
2341            as_yaml(&round_trip(&config).policy_config),
2342            as_yaml(&Some(configured))
2343        );
2344    }
2345
2346    #[test]
2347    fn a_grpc_api_config_survives_a_round_trip_in_all_three_states() {
2348        let mut config = template_config();
2349
2350        config.grpc_api_config = None;
2351        assert!(round_trip(&config).grpc_api_config.is_none());
2352
2353        config.grpc_api_config = default_grpc_api_config();
2354        assert_eq!(
2355            as_yaml(&round_trip(&config).grpc_api_config),
2356            as_yaml(&default_grpc_api_config())
2357        );
2358
2359        let configured = GrpcApiConfig {
2360            max_message_size_bytes: 1234,
2361            ..GrpcApiConfig::default()
2362        };
2363        config.grpc_api_config = Some(configured.clone());
2364        assert_eq!(
2365            as_yaml(&round_trip(&config).grpc_api_config),
2366            as_yaml(&Some(configured))
2367        );
2368    }
2369
2370    #[test]
2371    fn the_default_pruning_config_agrees_with_the_serde_default() {
2372        assert_eq!(
2373            super::AuthorityStorePruningConfig::default().periodic_compaction_threshold_days,
2374            default_periodic_compaction_threshold_days()
2375        );
2376    }
2377
2378    #[test]
2379    fn a_compaction_threshold_survives_a_round_trip_in_all_three_states() {
2380        let mut config = template_config();
2381
2382        for state in [None, default_periodic_compaction_threshold_days(), Some(7)] {
2383            config
2384                .authority_store_pruning_config
2385                .periodic_compaction_threshold_days = state;
2386            assert_eq!(
2387                round_trip(&config)
2388                    .authority_store_pruning_config
2389                    .periodic_compaction_threshold_days,
2390                state
2391            );
2392        }
2393    }
2394
2395    #[test]
2396    fn a_default_value_is_omitted_and_a_disabled_one_is_written_as_null() {
2397        let mut config = template_config();
2398        config.policy_config = default_traffic_controller_policy_config();
2399        config.grpc_api_config = default_grpc_api_config();
2400        config
2401            .authority_store_pruning_config
2402            .periodic_compaction_threshold_days = default_periodic_compaction_threshold_days();
2403
2404        let written = serde_yaml::to_value(&config).unwrap();
2405        assert_eq!(written_at(&written, POLICY_CONFIG), None);
2406        assert_eq!(written_at(&written, GRPC_API_CONFIG), None);
2407        assert_eq!(written_at(&written, COMPACTION_THRESHOLD), None);
2408
2409        config.policy_config = None;
2410        config.grpc_api_config = None;
2411        config
2412            .authority_store_pruning_config
2413            .periodic_compaction_threshold_days = None;
2414
2415        let written = serde_yaml::to_value(&config).unwrap();
2416        assert_eq!(written_at(&written, POLICY_CONFIG), Some(Value::Null));
2417        assert_eq!(written_at(&written, GRPC_API_CONFIG), Some(Value::Null));
2418        assert_eq!(
2419            written_at(&written, COMPACTION_THRESHOLD),
2420            Some(Value::Null)
2421        );
2422    }
2423
2424    fn limits(yaml: &str) -> ListenerLimitsConfig {
2425        serde_yaml::from_str(yaml).unwrap()
2426    }
2427
2428    #[test]
2429    fn a_node_config_without_listener_limits_leaves_every_limit_unset() {
2430        let config = template_config();
2431        assert_eq!(
2432            config.validator_grpc_listener_limits,
2433            ListenerLimitsConfig::default()
2434        );
2435        assert_eq!(
2436            config.json_rpc_listener_limits,
2437            ListenerLimitsConfig::default()
2438        );
2439        assert_eq!(
2440            config.grpc_api_listener_limits,
2441            ListenerLimitsConfig::default()
2442        );
2443    }
2444
2445    #[test]
2446    fn a_listener_limit_left_out_is_unset_and_null_disables_it() {
2447        assert_eq!(
2448            limits("max-connections: 30\nmax-connection-idle: null"),
2449            ListenerLimitsConfig {
2450                max_connections: Setting::Value(NonZeroUsize::new(30).unwrap()),
2451                max_connection_idle: Setting::Disabled,
2452                ..Default::default()
2453            }
2454        );
2455    }
2456
2457    /// Every value is distinct, so a key read into the wrong field fails here.
2458    #[test]
2459    fn every_listener_limit_is_read_from_its_own_key() {
2460        let read = limits(
2461            "
2462            handshake-timeout: {secs: 1, nanos: 0}
2463            max-pending-connections: 2
2464            max-connections: 3
2465            max-connections-per-client-ip: 4
2466            ipv6-prefix-len: 48
2467            max-connection-idle: {secs: 5, nanos: 0}
2468            max-concurrent-streams: 6
2469            http2-keepalive-interval: {secs: 7, nanos: 0}
2470            http1-header-read-timeout: {secs: 8, nanos: 0}
2471            ",
2472        );
2473        assert_eq!(
2474            read,
2475            ListenerLimitsConfig {
2476                handshake_timeout: Setting::Value(Duration::from_secs(1)),
2477                max_pending_connections: Setting::Value(NonZeroUsize::new(2).unwrap()),
2478                max_connections: Setting::Value(NonZeroUsize::new(3).unwrap()),
2479                max_connections_per_client_ip: Setting::Value(NonZeroUsize::new(4).unwrap()),
2480                ipv6_prefix_len: Some(48),
2481                max_connection_idle: Setting::Value(Duration::from_secs(5)),
2482                max_concurrent_streams: Setting::Value(NonZeroU32::new(6).unwrap()),
2483                http2_keepalive_interval: Setting::Value(Duration::from_secs(7)),
2484                http1_header_read_timeout: Setting::Value(Duration::from_secs(8)),
2485            }
2486        );
2487    }
2488
2489    #[test]
2490    fn every_listener_limit_can_be_disabled() {
2491        let read = limits(
2492            "
2493            handshake-timeout: null
2494            max-pending-connections: null
2495            max-connections: null
2496            max-connections-per-client-ip: null
2497            ipv6-prefix-len: null
2498            max-connection-idle: null
2499            max-concurrent-streams: null
2500            http2-keepalive-interval: null
2501            http1-header-read-timeout: null
2502            ",
2503        );
2504        assert_eq!(
2505            read,
2506            ListenerLimitsConfig {
2507                handshake_timeout: Setting::Disabled,
2508                max_pending_connections: Setting::Disabled,
2509                max_connections: Setting::Disabled,
2510                max_connections_per_client_ip: Setting::Disabled,
2511                ipv6_prefix_len: None,
2512                max_connection_idle: Setting::Disabled,
2513                max_concurrent_streams: Setting::Disabled,
2514                http2_keepalive_interval: Setting::Disabled,
2515                http1_header_read_timeout: Setting::Disabled,
2516            }
2517        );
2518    }
2519
2520    #[test]
2521    fn listener_limits_are_written_only_when_set() {
2522        let mut config = template_config();
2523        let written = serde_yaml::to_value(&config).unwrap();
2524        for key in [
2525            "validator-grpc-listener-limits",
2526            "json-rpc-listener-limits",
2527            "grpc-api-listener-limits",
2528        ] {
2529            assert_eq!(written_at(&written, &[key]), None, "{key} was written");
2530        }
2531
2532        config.json_rpc_listener_limits.max_connections = Setting::Value(NonZeroUsize::MIN);
2533        config.grpc_api_listener_limits.max_connection_idle = Setting::Disabled;
2534        let read_back = round_trip(&config);
2535        assert_eq!(
2536            read_back.json_rpc_listener_limits,
2537            config.json_rpc_listener_limits
2538        );
2539        assert_eq!(
2540            read_back.grpc_api_listener_limits,
2541            config.grpc_api_listener_limits
2542        );
2543        assert!(read_back.validator_grpc_listener_limits.is_unset());
2544    }
2545
2546    /// With a limit of zero attestation dry runs at once, a validator could
2547    /// attest no transaction, so a config with that limit fails to load.
2548    #[test]
2549    fn config_with_zero_concurrent_attestations_fails_to_load() {
2550        let zero = serde_yaml::from_str::<super::AuthorityOverloadConfig>(
2551            "max-concurrent-attestations: 0",
2552        );
2553        assert!(zero.is_err(), "{zero:?}");
2554
2555        let one: super::AuthorityOverloadConfig =
2556            serde_yaml::from_str("max-concurrent-attestations: 1").unwrap();
2557        assert_eq!(one.max_concurrent_attestations, NonZeroUsize::new(1));
2558    }
2559}
2560
2561// RunWithRange is used to specify the ending epoch/checkpoint to process.
2562// this is intended for use with disaster recovery debugging and verification
2563// workflows, never in normal operations
2564#[derive(Clone, Copy, PartialEq, Debug, Serialize, Deserialize)]
2565pub enum RunWithRange {
2566    Epoch(EpochId),
2567    Checkpoint(CheckpointSequenceNumber),
2568}
2569
2570impl RunWithRange {
2571    // is epoch_id > RunWithRange::Epoch
2572    pub fn is_epoch_gt(&self, epoch_id: EpochId) -> bool {
2573        matches!(self, RunWithRange::Epoch(e) if epoch_id > *e)
2574    }
2575
2576    pub fn matches_checkpoint(&self, seq_num: CheckpointSequenceNumber) -> bool {
2577        matches!(self, RunWithRange::Checkpoint(seq) if *seq == seq_num)
2578    }
2579
2580    pub fn into_checkpoint_bound(self) -> Option<CheckpointSequenceNumber> {
2581        match self {
2582            RunWithRange::Epoch(_) => None,
2583            RunWithRange::Checkpoint(seq) => Some(seq),
2584        }
2585    }
2586}
2587
2588/// A serde helper module used with #[serde(with = "...")] to change the
2589/// de/serialization format of an `SimpleKeypair` to Bech32 when written to or
2590/// read from a node config.
2591mod bech32_formatted_keypair {
2592    use std::ops::Deref;
2593
2594    use fastcrypto::encoding::{Base64, Encoding};
2595    use iota_sdk_crypto::{ToFromBech32, simple::SimpleKeypair};
2596    use serde::{Deserialize, Deserializer, Serializer};
2597
2598    pub fn serialize<S, T>(kp: &T, serializer: S) -> Result<S::Ok, S::Error>
2599    where
2600        S: Serializer,
2601        T: Deref<Target = SimpleKeypair>,
2602    {
2603        use serde::ser::Error;
2604
2605        // Serialize the keypair to a Bech32 string
2606        let s = kp.to_bech32().map_err(Error::custom)?;
2607
2608        serializer.serialize_str(&s)
2609    }
2610
2611    pub fn deserialize<'de, D, T>(deserializer: D) -> Result<T, D::Error>
2612    where
2613        D: Deserializer<'de>,
2614        T: From<SimpleKeypair>,
2615    {
2616        use serde::de::Error;
2617
2618        let s = String::deserialize(deserializer)?;
2619
2620        // Try to deserialize the keypair from a Bech32 formatted string
2621        SimpleKeypair::from_bech32(&s)
2622            .map_err(Error::custom)
2623            .or_else(|_: D::Error| {
2624                // For backwards compatibility try Base64 if Bech32 failed
2625                let bytes = Base64::decode(&s).map_err(Error::custom)?;
2626                SimpleKeypair::from_bytes(&bytes).map_err(Error::custom)
2627            })
2628            .map(Into::into)
2629    }
2630}