iota_config/

node.rs

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2024 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

use std::{
    net::{IpAddr, Ipv4Addr, SocketAddr},
    path::{Path, PathBuf},
    sync::Arc,
    time::Duration,
};

use anyhow::Result;
use iota_keys::keypair_file::{read_authority_keypair_from_file, read_keypair_from_file};
use iota_metrics::MetricGroups;
use iota_names::config::IotaNamesConfig;
use iota_sdk_types::Address;
use iota_types::{
    committee::EpochId,
    crypto::{
        AccountKeyPair, AuthorityKeyPair, AuthorityPublicKeyBytes, IotaKeyPair, KeypairTraits,
        NetworkKeyPair, get_key_pair_from_rng,
    },
    messages_checkpoint::CheckpointSequenceNumber,
    multiaddr::Multiaddr,
    supported_protocol_versions::{Chain, SupportedProtocolVersions},
    traffic_control::{PolicyConfig, RemoteFirewallConfig},
};
use once_cell::sync::OnceCell;
use rand::rngs::OsRng;
use serde::{Deserialize, Serialize};
use starfish_config::Parameters as StarfishParameters;
use tracing::info;

use crate::{
    Config, certificate_deny_config::CertificateDenyConfig, genesis,
    migration_tx_data::MigrationTxData, object_storage_config::ObjectStoreConfig, p2p::P2pConfig,
    transaction_deny_config::TransactionDenyConfig, verifier_signing_config::VerifierSigningConfig,
};

// Default max number of concurrent requests served
pub const DEFAULT_GRPC_CONCURRENCY_LIMIT: usize = 20000000000;

/// Default gas price of 1000 Nanos
pub const DEFAULT_VALIDATOR_GAS_PRICE: u64 = iota_types::transaction::DEFAULT_VALIDATOR_GAS_PRICE;

/// Default commission rate of 2%
pub const DEFAULT_COMMISSION_RATE: u64 = 200;

/// Default budget in MiB for the in-memory full-checkpoint-contents cache.
pub const DEFAULT_FULL_CHECKPOINT_CONTENTS_CACHE_SIZE_MB: usize = 1024;

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct NodeConfig {
    /// The public key bytes corresponding to the private key that the validator
    /// holds to sign transactions.
    #[serde(default = "default_authority_key_pair")]
    pub authority_key_pair: AuthorityKeyPairWithPath,
    /// The public key bytes corresponding to the private key that the validator
    /// holds to sign consensus blocks.
    #[serde(default = "default_key_pair")]
    pub protocol_key_pair: KeyPairWithPath,
    #[serde(default = "default_key_pair")]
    pub account_key_pair: KeyPairWithPath,
    /// The public key bytes corresponding to the private key that the validator
    /// uses to establish TLS connections.
    #[serde(default = "default_key_pair")]
    pub network_key_pair: KeyPairWithPath,
    pub db_path: PathBuf,

    /// The network address for gRPC communication.
    ///
    /// Can be overwritten with args `listen-address` parameters.
    #[serde(default = "default_grpc_address")]
    pub network_address: Multiaddr,
    #[serde(default = "default_json_rpc_address")]
    pub json_rpc_address: SocketAddr,

    /// The address for Prometheus metrics.
    #[serde(default = "default_metrics_address")]
    pub metrics_address: SocketAddr,

    /// The address for the admin interface that is
    /// run in the metrics separate runtime and provides access to
    /// admin node commands such as logging and tracing options.
    #[serde(default = "default_admin_interface_address")]
    pub admin_interface_address: SocketAddr,

    /// Configuration struct for the consensus.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub consensus_config: Option<ConsensusConfig>,

    /// Flag to enable index processing for a full node.
    ///
    /// If set to true, node creates `IndexStore` for transaction
    /// data including ownership and balance information.
    #[serde(default = "default_enable_index_processing")]
    pub enable_index_processing: bool,

    // only allow websocket connections for jsonrpc traffic
    #[serde(default)]
    /// Determines the jsonrpc server type as either:
    /// - 'websocket' for a websocket based service (deprecated)
    /// - 'http' for an http based service
    /// - 'both' for both a websocket and http based service (deprecated)
    pub jsonrpc_server_type: Option<ServerType>,

    /// Flag to enable gRPC load shedding to manage and
    /// mitigate overload conditions by shedding excess
    /// load with `LoadShedLayer` middleware.
    #[serde(default)]
    pub grpc_load_shed: Option<bool>,

    #[serde(default = "default_concurrency_limit")]
    pub grpc_concurrency_limit: Option<usize>,

    /// Configuration struct for P2P.
    #[serde(default)]
    pub p2p_config: P2pConfig,

    /// Contains genesis location that might be `InPlace`
    /// for reading all genesis data to memory or `InFile`,
    /// and `OnceCell` pointer to a genesis struct.
    pub genesis: Genesis,

    /// Contains the path where to find the migration blob.
    pub migration_tx_data_path: Option<PathBuf>,

    /// Configuration for pruning of the authority store, to define when
    /// an old data is removed from the storage space.
    #[serde(default = "default_authority_store_pruning_config")]
    pub authority_store_pruning_config: AuthorityStorePruningConfig,

    /// Size of the broadcast channel used for notifying other systems of end of
    /// epoch.
    ///
    /// If unspecified, this will default to `128`.
    #[serde(default = "default_end_of_epoch_broadcast_channel_capacity")]
    pub end_of_epoch_broadcast_channel_capacity: usize,

    /// Configuration for the checkpoint executor for limiting
    /// the number of checkpoints to execute concurrently,
    /// and to allow for checkpoint post-processing.
    #[serde(default)]
    pub checkpoint_executor_config: CheckpointExecutorConfig,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub metrics: Option<MetricsConfig>,

    /// In a `iota-node` binary, this is set to
    /// SupportedProtocolVersions::SYSTEM_DEFAULT in iota-node/src/main.rs.
    /// It is present in the config so that it can be changed by tests in
    /// order to test protocol upgrades.
    #[serde(skip)]
    pub supported_protocol_versions: Option<SupportedProtocolVersions>,

    /// Configuration to manage database checkpoints,
    /// including whether to perform checkpoints at the end of an epoch,
    /// the path for storing checkpoints, and other related settings.
    #[serde(default)]
    pub db_checkpoint_config: DBCheckpointConfig,

    /// Configuration for enabling/disabling expensive safety checks.
    #[serde(default)]
    pub expensive_safety_check_config: ExpensiveSafetyCheckConfig,

    /// Configuration to specify rules for denying transactions
    /// based on `objectsIDs`, `addresses`, or enable/disable many
    /// features such as publishing new packages or using shared objects.
    #[serde(default)]
    pub transaction_deny_config: TransactionDenyConfig,

    /// Config used to deny execution for certificate digests
    /// know for crashing or hanging validator nodes.
    ///
    /// Should be used for a fast temporary fixes and
    /// removed once the issue is fixed.
    #[serde(default)]
    pub certificate_deny_config: CertificateDenyConfig,

    /// Used to determine how state debug information is dumped
    /// when a node forks.
    #[serde(default)]
    pub state_debug_dump_config: StateDebugDumpConfig,

    #[serde(default)]
    pub checkpoint_archive_config: Option<CheckpointArchiveConfig>,

    /// Determines if snapshot should be uploaded to the remote storage.
    #[serde(default)]
    pub state_snapshot_write_config: StateSnapshotConfig,

    #[serde(default)]
    pub indexer_max_subscriptions: Option<usize>,

    #[serde(default = "default_transaction_kv_store_config")]
    pub transaction_kv_store_read_config: TransactionKeyValueStoreReadConfig,

    // TODO: write config seem to be unused.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub transaction_kv_store_write_config: Option<TransactionKeyValueStoreWriteConfig>,

    /// Configuration for defining thresholds and settings
    /// for managing system overload conditions in a node.
    #[serde(default = "default_authority_overload_config")]
    pub authority_overload_config: AuthorityOverloadConfig,

    /// Specifies the ending epoch for a node for debugging purposes.
    ///
    ///  Ignored if set by config, can be configured only by cli arguments.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub run_with_range: Option<RunWithRange>,

    // For killswitch use None
    #[serde(
        skip_serializing_if = "Option::is_none",
        default = "default_traffic_controller_policy_config"
    )]
    pub policy_config: Option<PolicyConfig>,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub firewall_config: Option<RemoteFirewallConfig>,

    #[serde(default)]
    pub execution_cache_config: ExecutionCacheConfig,

    /// Memory budget in MiB for the in-memory cache of full checkpoint
    /// contents, which serves the checkpoint executor's bulk transaction
    /// loads and checkpoint-contents requests from state-sync peers. When
    /// the budget is exceeded, the oldest checkpoints are evicted first.
    /// Set to 0 to disable the cache; consumers then fall back to
    /// reconstructing contents from the transaction and effects stores.
    ///
    /// The budget is accounted in serialized (BCS) bytes; the resident
    /// memory of a full cache is somewhat higher than the configured value
    /// due to in-memory representation overhead.
    #[serde(default = "default_full_checkpoint_contents_cache_size_mb")]
    pub full_checkpoint_contents_cache_size_mb: usize,

    #[serde(default = "bool_true")]
    pub enable_validator_tx_finalizer: bool,

    /// Enables the pre-consensus soft-locking mechanism used by the
    /// certificate-less (pcool) transaction flow (default: enabled).
    ///
    /// When disabled, post-consensus validation alone resolves owned-object
    /// conflicts. Has no effect unless the pcool flow is enabled.
    #[serde(default = "bool_true")]
    pub enable_soft_locking: bool,

    #[serde(default)]
    pub verifier_signing_config: VerifierSigningConfig,

    /// If a value is set, it determines if writes to DB can stall, which can
    /// halt the whole process. By default, write stall is enabled on
    /// validators but not on fullnodes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_db_write_stall: Option<bool>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub iota_names_config: Option<IotaNamesConfig>,

    /// Flag to enable the gRPC API.
    #[serde(default)]
    pub enable_grpc_api: bool,
    #[serde(
        default = "default_grpc_api_config",
        skip_serializing_if = "Option::is_none"
    )]
    pub grpc_api_config: Option<GrpcApiConfig>,

    /// Allow overriding the chain for testing purposes. For instance, it allows
    /// you to create a test network that believes it is mainnet or testnet.
    /// Attempting to override this value on production networks will result
    /// in an error.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub chain_override_for_testing: Option<Chain>,

    /// Configuration for the validator client monitor that tracks
    /// client-observed performance metrics for validators.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validator_client_monitor_config:
        Option<crate::validator_client_monitor_config::ValidatorClientMonitorConfig>,
}

#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct TlsConfig {
    /// File path to a PEM formatted TLS certificate chain
    cert: String,
    /// File path to a PEM formatted TLS private key
    key: String,
}

impl TlsConfig {
    pub fn cert(&self) -> &str {
        &self.cert
    }

    pub fn key(&self) -> &str {
        &self.key
    }
}

/// Configuration for the gRPC API service
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct GrpcApiConfig {
    /// The address to bind the gRPC server to
    #[serde(default = "default_grpc_api_address")]
    pub address: SocketAddr,

    /// TLS configuration for the gRPC server.
    ///
    /// If not provided, the gRPC server will use plain TCP without TLS.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tls: Option<TlsConfig>,

    /// Maximum message size for gRPC responses (in bytes)
    #[serde(default = "default_grpc_api_max_message_size_bytes")]
    pub max_message_size_bytes: u32,

    /// Buffer size for broadcast channels used for streaming
    #[serde(default = "default_grpc_api_broadcast_buffer_size")]
    pub broadcast_buffer_size: u32,

    /// Maximum number of concurrent subscribers to checkpoint streaming RPCs.
    /// Once the cap is reached, additional subscribe requests are rejected
    /// with `Unavailable` to protect the server from being overwhelmed by
    /// unbounded streaming clients. Values below 1 are clamped to 1 at
    /// server startup.
    #[serde(default = "default_grpc_api_max_concurrent_stream_subscribers")]
    pub max_concurrent_stream_subscribers: u32,

    /// Maximum size for Move values when rendering to JSON
    /// in bytes.
    #[serde(default = "default_grpc_api_max_json_move_value_size")]
    pub max_json_move_value_size: usize,

    /// Maximum number of transactions allowed in a single ExecuteTransactions
    /// batch request.
    #[serde(default = "default_grpc_api_max_execute_transaction_batch_size")]
    pub max_execute_transaction_batch_size: u32,

    /// Maximum number of transactions allowed in a single SimulateTransactions
    /// batch request.
    #[serde(default = "default_grpc_api_max_simulate_transaction_batch_size")]
    pub max_simulate_transaction_batch_size: u32,

    /// Maximum allowed timeout in milliseconds for waiting for checkpoint
    /// inclusion in ExecuteTransactions requests. Client-specified timeouts
    /// are clamped to this value.
    #[serde(default = "default_grpc_api_max_checkpoint_inclusion_timeout_ms")]
    pub max_checkpoint_inclusion_timeout_ms: u64,
}

fn default_grpc_api_address() -> SocketAddr {
    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 50051)
}

fn default_grpc_api_broadcast_buffer_size() -> u32 {
    100
}

fn default_grpc_api_max_concurrent_stream_subscribers() -> u32 {
    1024
}

fn default_grpc_api_max_message_size_bytes() -> u32 {
    128 * 1024 * 1024 // 128MB
}

fn default_grpc_api_max_json_move_value_size() -> usize {
    1024 * 1024 // 1 MB
}

fn default_grpc_api_max_execute_transaction_batch_size() -> u32 {
    20
}

fn default_grpc_api_max_simulate_transaction_batch_size() -> u32 {
    20
}

fn default_grpc_api_max_checkpoint_inclusion_timeout_ms() -> u64 {
    60_000 // 60 seconds
}

impl Default for GrpcApiConfig {
    fn default() -> Self {
        Self {
            address: default_grpc_api_address(),
            tls: None,
            max_message_size_bytes: default_grpc_api_max_message_size_bytes(),
            broadcast_buffer_size: default_grpc_api_broadcast_buffer_size(),
            max_concurrent_stream_subscribers: default_grpc_api_max_concurrent_stream_subscribers(),
            max_json_move_value_size: default_grpc_api_max_json_move_value_size(),
            max_execute_transaction_batch_size: default_grpc_api_max_execute_transaction_batch_size(
            ),
            max_simulate_transaction_batch_size:
                default_grpc_api_max_simulate_transaction_batch_size(),
            max_checkpoint_inclusion_timeout_ms:
                default_grpc_api_max_checkpoint_inclusion_timeout_ms(),
        }
    }
}

impl GrpcApiConfig {
    // The default maximum uncompressed size in bytes for a message, based on
    // tonic's default.
    const GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE: u32 = 4 * 1024 * 1024; // 4MB
    const GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES: u32 =
        Self::GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE;

    pub fn tls_config(&self) -> Option<&TlsConfig> {
        self.tls.as_ref()
    }

    pub fn max_message_size_bytes(&self) -> u32 {
        // Ensure max message size is at least the minimum allowed
        self.max_message_size_bytes
            .max(Self::GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES)
    }

    /// Calculate the maximum size for a message that can be
    /// sent to a client, taking into account the client's max message size
    /// preference.
    pub fn max_message_size_client_bytes(&self, client_max_message_size_bytes: Option<u32>) -> u32 {
        client_max_message_size_bytes
            // if the client did not specify a max message size, use the tonic default receive
            // message size
            .unwrap_or(Self::GRPC_TONIC_DEFAULT_MAX_RECV_MESSAGE_SIZE)
            // clamp the value between the tonic default and the service max message size
            .clamp(
                Self::GRPC_MIN_CLIENT_MAX_MESSAGE_SIZE_BYTES,
                self.max_message_size_bytes(),
            )
    }
}

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct ExecutionCacheConfig {
    #[serde(default)]
    pub writeback_cache: WritebackCacheConfig,
}

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct WritebackCacheConfig {
    /// Maximum number of entries in each cache. (There are several
    /// different caches).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_cache_size: Option<u64>, // defaults to 100000

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub package_cache_size: Option<u64>, // defaults to 1000

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub object_cache_size: Option<u64>, // defaults to max_cache_size
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub marker_cache_size: Option<u64>, // defaults to object_cache_size
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub object_by_id_cache_size: Option<u64>, // defaults to object_cache_size

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub transaction_cache_size: Option<u64>, // defaults to max_cache_size
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub executed_effect_cache_size: Option<u64>, // defaults to transaction_cache_size
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub effect_cache_size: Option<u64>, // defaults to executed_effect_cache_size

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub events_cache_size: Option<u64>, // defaults to transaction_cache_size

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub transaction_objects_cache_size: Option<u64>, // defaults to 1000

    /// Number of uncommitted transactions at which to pause consensus
    /// handler.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backpressure_threshold: Option<u64>, // defaults to 100_000

    /// Number of uncommitted transactions at which to refuse new
    /// transaction submissions. Defaults to backpressure_threshold
    /// if unset.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backpressure_threshold_for_rpc: Option<u64>, // defaults to backpressure_threshold

    /// Percentage of `backpressure_threshold` at which graduated load shedding
    /// based on writeback-cache pending transaction count begins. The
    /// locally-calculated shedding percentage increases linearly from 0% at
    /// `backpressure_threshold * backpressure_soft_limit_pct / 100` up to
    /// 100% at the `backpressure_threshold` if the cache size continues to
    /// increase. The calculated shedding percentage is broadcast to other
    /// validators for a coordinated response. Defaults to 50.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backpressure_soft_limit_pct: Option<u32>,
}

impl WritebackCacheConfig {
    pub fn max_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MAX")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.max_cache_size)
            .unwrap_or(100000)
    }

    pub fn package_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_PACKAGE")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.package_cache_size)
            .unwrap_or(1000)
    }

    pub fn object_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.object_cache_size)
            .unwrap_or_else(|| self.max_cache_size())
    }

    pub fn marker_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_MARKER")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.marker_cache_size)
            .unwrap_or_else(|| self.object_cache_size())
    }

    pub fn object_by_id_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_OBJECT_BY_ID")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.object_by_id_cache_size)
            .unwrap_or_else(|| self.object_cache_size())
    }

    pub fn transaction_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.transaction_cache_size)
            .unwrap_or_else(|| self.max_cache_size())
    }

    pub fn executed_effect_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EXECUTED_EFFECT")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.executed_effect_cache_size)
            .unwrap_or_else(|| self.transaction_cache_size())
    }

    pub fn effect_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EFFECT")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.effect_cache_size)
            .unwrap_or_else(|| self.executed_effect_cache_size())
    }

    pub fn events_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_EVENTS")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.events_cache_size)
            .unwrap_or_else(|| self.transaction_cache_size())
    }

    pub fn transaction_objects_cache_size(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_SIZE_TRANSACTION_OBJECTS")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.transaction_objects_cache_size)
            .unwrap_or(1000)
    }

    pub fn backpressure_threshold(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.backpressure_threshold)
            .unwrap_or(100_000)
    }

    pub fn backpressure_threshold_for_rpc(&self) -> u64 {
        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_THRESHOLD_FOR_RPC")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.backpressure_threshold_for_rpc)
            .unwrap_or(self.backpressure_threshold())
    }

    pub fn backpressure_soft_limit_pct(&self) -> u32 {
        std::env::var("IOTA_CACHE_WRITEBACK_BACKPRESSURE_SOFT_LIMIT_PCT")
            .ok()
            .and_then(|s| s.parse().ok())
            .or(self.backpressure_soft_limit_pct)
            .unwrap_or(50)
            .min(100)
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ServerType {
    WebSocket,
    Http,
    Both,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct TransactionKeyValueStoreReadConfig {
    #[serde(default = "default_base_url")]
    pub base_url: String,

    #[serde(default = "default_cache_size")]
    pub cache_size: u64,
}

impl Default for TransactionKeyValueStoreReadConfig {
    fn default() -> Self {
        Self {
            base_url: default_base_url(),
            cache_size: default_cache_size(),
        }
    }
}

fn default_base_url() -> String {
    "".to_string()
}

fn default_cache_size() -> u64 {
    100_000
}

fn default_transaction_kv_store_config() -> TransactionKeyValueStoreReadConfig {
    TransactionKeyValueStoreReadConfig::default()
}

fn default_authority_store_pruning_config() -> AuthorityStorePruningConfig {
    AuthorityStorePruningConfig::default()
}

pub fn default_enable_index_processing() -> bool {
    true
}

fn default_grpc_address() -> Multiaddr {
    "/ip4/0.0.0.0/tcp/8080".parse().unwrap()
}
fn default_authority_key_pair() -> AuthorityKeyPairWithPath {
    AuthorityKeyPairWithPath::new(get_key_pair_from_rng::<AuthorityKeyPair, _>(&mut OsRng).1)
}

fn default_key_pair() -> KeyPairWithPath {
    KeyPairWithPath::new(
        get_key_pair_from_rng::<AccountKeyPair, _>(&mut OsRng)
            .1
            .into(),
    )
}

fn default_metrics_address() -> SocketAddr {
    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9184)
}

pub fn default_admin_interface_address() -> SocketAddr {
    SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 1337)
}

pub fn default_json_rpc_address() -> SocketAddr {
    SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), 9000)
}

pub fn default_grpc_api_config() -> Option<GrpcApiConfig> {
    Some(GrpcApiConfig::default())
}

pub fn default_concurrency_limit() -> Option<usize> {
    Some(DEFAULT_GRPC_CONCURRENCY_LIMIT)
}

pub fn default_end_of_epoch_broadcast_channel_capacity() -> usize {
    128
}

pub fn default_full_checkpoint_contents_cache_size_mb() -> usize {
    DEFAULT_FULL_CHECKPOINT_CONTENTS_CACHE_SIZE_MB
}

pub fn bool_true() -> bool {
    true
}

impl Config for NodeConfig {}

impl NodeConfig {
    pub fn authority_key_pair(&self) -> &AuthorityKeyPair {
        self.authority_key_pair.authority_keypair()
    }

    pub fn protocol_key_pair(&self) -> &NetworkKeyPair {
        match self.protocol_key_pair.keypair() {
            IotaKeyPair::Ed25519(kp) => kp,
            other => {
                panic!("invalid keypair type: {other:?}, only Ed25519 is allowed for protocol key")
            }
        }
    }

    pub fn network_key_pair(&self) -> &NetworkKeyPair {
        match self.network_key_pair.keypair() {
            IotaKeyPair::Ed25519(kp) => kp,
            other => {
                panic!("invalid keypair type: {other:?}, only Ed25519 is allowed for network key")
            }
        }
    }

    pub fn authority_public_key(&self) -> AuthorityPublicKeyBytes {
        self.authority_key_pair().public().into()
    }

    pub fn db_path(&self) -> PathBuf {
        self.db_path.join("live")
    }

    pub fn db_checkpoint_path(&self) -> PathBuf {
        self.db_path.join("db_checkpoints")
    }

    pub fn snapshot_path(&self) -> PathBuf {
        self.db_path.join("snapshot")
    }

    pub fn network_address(&self) -> &Multiaddr {
        &self.network_address
    }

    pub fn consensus_config(&self) -> Option<&ConsensusConfig> {
        self.consensus_config.as_ref()
    }

    pub fn genesis(&self) -> Result<&genesis::Genesis> {
        self.genesis.genesis()
    }

    pub fn load_migration_tx_data(&self) -> Result<MigrationTxData> {
        let Some(location) = &self.migration_tx_data_path else {
            anyhow::bail!("no file location set");
        };

        // Load from file
        let migration_tx_data = MigrationTxData::load(location)?;

        // Validate migration content in order to avoid corrupted or malicious data
        migration_tx_data.validate_from_genesis(self.genesis.genesis()?)?;
        Ok(migration_tx_data)
    }

    pub fn iota_address(&self) -> Address {
        (&self.account_key_pair.keypair().public()).into()
    }

    pub fn checkpoint_archive_config(&self) -> Option<&CheckpointArchiveConfig> {
        self.checkpoint_archive_config.as_ref()
    }

    pub fn jsonrpc_server_type(&self) -> ServerType {
        self.jsonrpc_server_type.unwrap_or(ServerType::Http)
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct ConsensusConfig {
    /// Base consensus DB path for all epochs.
    pub db_path: PathBuf,

    /// The number of epochs for which to retain the consensus DBs.
    /// Setting it to 0 will make a consensus DB getting dropped
    /// as soon as system is switched to a new epoch.
    pub db_retention_epochs: Option<u64>,

    /// Pruner will run on every epoch change but it will also check
    /// periodically on every `db_pruner_period_secs` seconds to see
    /// if there are any epoch DBs to remove.
    pub db_pruner_period_secs: Option<u64>,

    /// Hard limit on the number of pending transactions to submit to
    /// consensus, including those in submission wait. Used as the upper
    /// bound for graduated pre-consensus load shedding
    /// (`graduated_load_shedding_soft_limit_pct`) in the certificate-less
    /// (P-COOL) mode, and as the threshold for the binary
    /// cutoff in `ConsensusAdapter::check_consensus_overload()` in both
    /// certificate-less and certificate-based flows.
    ///
    /// Default to 20_000 inflight limit, assuming 20_000 txn tps * 1 sec
    /// consensus latency.
    pub max_pending_transactions: Option<usize>,

    /// When defined caps the calculated submission position to the
    /// max_submit_position.
    ///
    /// Even if the is elected to submit from a higher
    /// position than this, it will "reset" to the max_submit_position.
    pub max_submit_position: Option<usize>,

    /// The submit delay step to consensus defined in milliseconds.
    ///
    /// When provided it will override the current back off logic otherwise the
    /// default backoff logic will be applied based on consensus latency
    /// estimates.
    pub submit_delay_step_override_millis: Option<u64>,

    /// Parameters for Starfish consensus
    #[serde(skip_serializing_if = "Option::is_none", alias = "starfish_parameters")]
    pub parameters: Option<StarfishParameters>,

    /// Percentage of `max_pending_transactions` (hard limit) defining the soft
    /// limit at which graduated pre-consensus load shedding begins. When
    /// in-flight transactions are at or below the soft limit, no shedding
    /// occurs; above it, the shedding rate scales linearly from 0% to 100% at
    /// `max_pending_transactions`. Used in the certificate-less (P-COOL) mode.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub graduated_load_shedding_soft_limit_pct: Option<u32>,
}

impl ConsensusConfig {
    pub fn db_path(&self) -> &Path {
        &self.db_path
    }

    /// Returns the hard limit on the number of pending transactions to submit
    /// to consensus, including those in submission wait. Defaults to 20_000
    /// inflight limit, assuming 20_000 txn tps * 1 sec consensus latency.
    pub fn max_pending_transactions(&self) -> usize {
        self.max_pending_transactions.unwrap_or(20_000)
    }

    /// Returns the percentage of `max_pending_transactions` (hard limit)
    /// defining the soft limit at which graduated pre-consensus load
    /// shedding begins. Defaults to 50%. Used in the certificate-less
    /// (P-COOL) mode.
    pub fn graduated_load_shedding_soft_limit_pct(&self) -> u32 {
        self.graduated_load_shedding_soft_limit_pct
            .unwrap_or(50)
            .min(100)
    }

    pub fn submit_delay_step_override(&self) -> Option<Duration> {
        self.submit_delay_step_override_millis
            .map(Duration::from_millis)
    }

    pub fn db_retention_epochs(&self) -> u64 {
        self.db_retention_epochs.unwrap_or(0)
    }

    pub fn db_pruner_period(&self) -> Duration {
        // Default to 1 hour
        self.db_pruner_period_secs
            .map(Duration::from_secs)
            .unwrap_or(Duration::from_secs(3_600))
    }
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct CheckpointExecutorConfig {
    /// Upper bound on the number of checkpoints that can be concurrently
    /// executed.
    ///
    /// If unspecified, this will default to `200`
    #[serde(default = "default_checkpoint_execution_max_concurrency")]
    pub checkpoint_execution_max_concurrency: usize,

    /// Number of seconds to wait for effects of a batch of transactions
    /// before logging a warning. Note that we will continue to retry
    /// indefinitely.
    ///
    /// If unspecified, this will default to `10`.
    #[serde(default = "default_local_execution_timeout_sec")]
    pub local_execution_timeout_sec: u64,

    /// Optional directory used for data ingestion pipeline.
    ///
    /// When specified, each executed checkpoint will be saved in a local
    /// directory for post-processing
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data_ingestion_dir: Option<PathBuf>,
}

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct ExpensiveSafetyCheckConfig {
    /// If enabled, at epoch boundary, we will check that the storage
    /// fund balance is always identical to the sum of the storage
    /// rebate of all live objects, and that the total IOTA in the network
    /// remains the same.
    #[serde(default)]
    enable_epoch_iota_conservation_check: bool,

    /// If enabled, we will check that the total IOTA in all input objects of a
    /// tx (both the Move part and the storage rebate) matches the total IOTA
    /// in all output objects of the tx + gas fees.
    #[serde(default)]
    enable_deep_per_tx_iota_conservation_check: bool,

    /// Disable epoch IOTA conservation check even when we are running in debug
    /// mode.
    #[serde(default)]
    force_disable_epoch_iota_conservation_check: bool,

    /// If enabled, at epoch boundary, we will check that the accumulated
    /// live object state matches the end of epoch root state digest.
    #[serde(default)]
    enable_state_consistency_check: bool,

    /// Disable state consistency check even when we are running in debug mode.
    #[serde(default)]
    force_disable_state_consistency_check: bool,

    #[serde(default)]
    enable_secondary_index_checks: bool,
    // TODO: Add more expensive checks here
}

impl ExpensiveSafetyCheckConfig {
    pub fn new_enable_all() -> Self {
        Self {
            enable_epoch_iota_conservation_check: true,
            enable_deep_per_tx_iota_conservation_check: true,
            force_disable_epoch_iota_conservation_check: false,
            enable_state_consistency_check: true,
            force_disable_state_consistency_check: false,
            enable_secondary_index_checks: false, // Disable by default for now
        }
    }

    pub fn new_disable_all() -> Self {
        Self {
            enable_epoch_iota_conservation_check: false,
            enable_deep_per_tx_iota_conservation_check: false,
            force_disable_epoch_iota_conservation_check: true,
            enable_state_consistency_check: false,
            force_disable_state_consistency_check: true,
            enable_secondary_index_checks: false,
        }
    }

    pub fn force_disable_epoch_iota_conservation_check(&mut self) {
        self.force_disable_epoch_iota_conservation_check = true;
    }

    pub fn enable_epoch_iota_conservation_check(&self) -> bool {
        (self.enable_epoch_iota_conservation_check || cfg!(debug_assertions))
            && !self.force_disable_epoch_iota_conservation_check
    }

    pub fn force_disable_state_consistency_check(&mut self) {
        self.force_disable_state_consistency_check = true;
    }

    pub fn enable_state_consistency_check(&self) -> bool {
        (self.enable_state_consistency_check || cfg!(debug_assertions))
            && !self.force_disable_state_consistency_check
    }

    pub fn enable_deep_per_tx_iota_conservation_check(&self) -> bool {
        self.enable_deep_per_tx_iota_conservation_check || cfg!(debug_assertions)
    }

    pub fn enable_secondary_index_checks(&self) -> bool {
        self.enable_secondary_index_checks
    }
}

fn default_checkpoint_execution_max_concurrency() -> usize {
    4
}

fn default_local_execution_timeout_sec() -> u64 {
    30
}

impl Default for CheckpointExecutorConfig {
    fn default() -> Self {
        Self {
            checkpoint_execution_max_concurrency: default_checkpoint_execution_max_concurrency(),
            local_execution_timeout_sec: default_local_execution_timeout_sec(),
            data_ingestion_dir: None,
        }
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct AuthorityStorePruningConfig {
    /// number of the latest epoch dbs to retain
    #[serde(default = "default_num_latest_epoch_dbs_to_retain")]
    pub num_latest_epoch_dbs_to_retain: usize,
    /// number of epochs to keep the latest version of objects for.
    /// Note that a zero value corresponds to an aggressive pruner.
    /// This mode is experimental and needs to be used with caution.
    /// Use `u64::MAX` to disable the pruner for the objects.
    #[serde(default)]
    pub num_epochs_to_retain: u64,
    /// enables periodic background compaction for old SST files whose last
    /// modified time is older than `periodic_compaction_threshold_days`
    /// days. That ensures that all sst files eventually go through the
    /// compaction process
    #[serde(
        default = "default_periodic_compaction_threshold_days",
        skip_serializing_if = "Option::is_none"
    )]
    pub periodic_compaction_threshold_days: Option<usize>,
    /// number of epochs to keep the latest version of transactions and effects
    /// for
    #[serde(skip_serializing_if = "Option::is_none")]
    pub num_epochs_to_retain_for_checkpoints: Option<u64>,
    /// Enables the compaction filter for pruning the objects table.
    /// If disabled, a range deletion approach is used instead.
    /// While it is generally safe to switch between the two modes,
    /// switching from the compaction filter approach back to range deletion
    /// may result in some old versions that will never be pruned.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub enable_compaction_filter: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub num_epochs_to_retain_for_indexes: Option<u64>,
}

fn default_num_latest_epoch_dbs_to_retain() -> usize {
    3
}

fn default_periodic_compaction_threshold_days() -> Option<usize> {
    Some(1)
}

impl Default for AuthorityStorePruningConfig {
    fn default() -> Self {
        Self {
            num_latest_epoch_dbs_to_retain: default_num_latest_epoch_dbs_to_retain(),
            num_epochs_to_retain: 0,
            periodic_compaction_threshold_days: None,
            num_epochs_to_retain_for_checkpoints: if cfg!(msim) { Some(2) } else { None },
            enable_compaction_filter: cfg!(test) || cfg!(msim),
            num_epochs_to_retain_for_indexes: None,
        }
    }
}

impl AuthorityStorePruningConfig {
    pub fn set_num_epochs_to_retain(&mut self, num_epochs_to_retain: u64) {
        self.num_epochs_to_retain = num_epochs_to_retain;
    }

    pub fn set_num_epochs_to_retain_for_checkpoints(&mut self, num_epochs_to_retain: Option<u64>) {
        self.num_epochs_to_retain_for_checkpoints = num_epochs_to_retain;
    }

    pub fn num_epochs_to_retain_for_checkpoints(&self) -> Option<u64> {
        self.num_epochs_to_retain_for_checkpoints
            // if n less than 2, coerce to 2 and log
            .map(|n| {
                if n < 2 {
                    info!("num_epochs_to_retain_for_checkpoints must be at least 2, rounding up from {}", n);
                    2
                } else {
                    n
                }
            })
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct MetricsConfig {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub push_interval_seconds: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub push_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub groups: Option<MetricGroups>,
}

#[derive(Default, Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct DBCheckpointConfig {
    #[serde(default)]
    pub perform_db_checkpoints_at_epoch_end: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint_path: Option<PathBuf>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub object_store_config: Option<ObjectStoreConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub perform_index_db_checkpoints_at_epoch_end: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prune_and_compact_before_upload: Option<bool>,
}

fn default_checkpoint_archive_download_concurrency() -> usize {
    10
}

/// Configuration for backfilling checkpoint contents from the
/// checkpoint archive when peers no longer serve the required range.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct CheckpointArchiveConfig {
    /// URL of the checkpoint archive to backfill from.
    pub url: String,
    /// Non-zero number of checkpoints to download in parallel.
    #[serde(default = "default_checkpoint_archive_download_concurrency")]
    pub download_concurrency: usize,
}

/// Configuration for the per-epoch state-snapshot publisher.
///
/// **Operator note (V2 snapshot publishing).** A node configured to publish
/// V2 snapshots must have a perpetual store containing no pre-V2
/// (`StoreObjectV1`) rows. This means a snapshot-publishing node must have
/// either synced from genesis under V2 or been restored from a V2 snapshot.
/// There is no on-disk backfill: a fresh sync is the only supported path.
#[derive(Default, Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct StateSnapshotConfig {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub object_store_config: Option<ObjectStoreConfig>,
    pub concurrency: usize,
}

#[derive(Default, Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct TransactionKeyValueStoreWriteConfig {
    pub aws_access_key_id: String,
    pub aws_secret_access_key: String,
    pub aws_region: String,
    pub table_name: String,
    pub bucket_name: String,
    pub concurrency: usize,
}

/// Configuration for the threshold(s) at which we consider the system
/// to be overloaded. When one of the threshold is passed, the node may
/// stop processing new transactions and/or certificates until the congestion
/// resolves.
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct AuthorityOverloadConfig {
    /// Maximum time a transaction can wait in the transaction manager execution
    /// queue before it triggers an overload detection on the object it depends
    /// on.
    #[serde(default = "default_max_txn_age_in_queue")]
    pub max_txn_age_in_queue: Duration,

    /// The interval of checking overload signal.
    #[serde(default = "default_overload_monitor_interval")]
    pub overload_monitor_interval: Duration,

    /// The execution queueing latency when entering load shedding mode.
    #[serde(default = "default_execution_queue_latency_soft_limit")]
    pub execution_queue_latency_soft_limit: Duration,

    /// The execution queueing latency when entering aggressive load shedding
    /// mode.
    #[serde(default = "default_execution_queue_latency_hard_limit")]
    pub execution_queue_latency_hard_limit: Duration,

    /// The maximum percentage of transactions to shed in load shedding mode.
    #[serde(default = "default_max_load_shedding_percentage")]
    pub max_load_shedding_percentage: u32,

    /// When in aggressive load shedding mode, the minimum percentage of
    /// transactions to shed.
    #[serde(default = "default_min_load_shedding_percentage_above_hard_limit")]
    pub min_load_shedding_percentage_above_hard_limit: u32,

    /// If transaction ready rate is below this rate, we consider the validator
    /// is well under used, and will not enter load shedding mode.
    #[serde(default = "default_safe_transaction_ready_rate")]
    pub safe_transaction_ready_rate: u32,

    /// When set to true, transaction signing may be rejected when the validator
    /// is overloaded.
    #[serde(default = "default_check_system_overload_at_signing")]
    pub check_system_overload_at_signing: bool,

    /// When set to true, transaction execution may be rejected when the
    /// validator is overloaded.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub check_system_overload_at_execution: bool,

    /// Reject a transaction if transaction manager queue length is above this
    /// threshold. 100_000 = 10k TPS * 5s resident time in transaction
    /// manager (pending + executing) * 2.
    #[serde(default = "default_max_transaction_manager_queue_length")]
    pub max_transaction_manager_queue_length: usize,

    /// Reject a transaction if the number of pending transactions depending on
    /// the object is above the threshold.
    #[serde(default = "default_max_transaction_manager_per_object_queue_length")]
    pub max_transaction_manager_per_object_queue_length: usize,

    /// Percentage of `max_transaction_manager_queue_length` at which graduated
    /// load shedding begins in the certificate-less (P-COOL) mode. Read
    /// via the same-named accessor, which clamps the value to <=100.
    #[serde(default = "default_max_transaction_manager_queue_length_soft_limit_pct")]
    pub max_transaction_manager_queue_length_soft_limit_pct: u32,
}

impl AuthorityOverloadConfig {
    /// Returns the soft-limit percentage, clamped to <=100 to guard against
    /// out-of-range operator-supplied values.
    pub fn max_transaction_manager_queue_length_soft_limit_pct(&self) -> u32 {
        self.max_transaction_manager_queue_length_soft_limit_pct
            .min(100)
    }
}

fn default_max_txn_age_in_queue() -> Duration {
    Duration::from_millis(500)
}

fn default_overload_monitor_interval() -> Duration {
    Duration::from_secs(10)
}

fn default_execution_queue_latency_soft_limit() -> Duration {
    Duration::from_secs(1)
}

fn default_execution_queue_latency_hard_limit() -> Duration {
    Duration::from_secs(10)
}

fn default_max_load_shedding_percentage() -> u32 {
    95
}

fn default_min_load_shedding_percentage_above_hard_limit() -> u32 {
    50
}

fn default_safe_transaction_ready_rate() -> u32 {
    100
}

fn default_check_system_overload_at_signing() -> bool {
    true
}

fn default_max_transaction_manager_queue_length() -> usize {
    100_000
}

fn default_max_transaction_manager_queue_length_soft_limit_pct() -> u32 {
    50
}

fn default_max_transaction_manager_per_object_queue_length() -> usize {
    20
}

impl Default for AuthorityOverloadConfig {
    fn default() -> Self {
        Self {
            max_txn_age_in_queue: default_max_txn_age_in_queue(),
            overload_monitor_interval: default_overload_monitor_interval(),
            execution_queue_latency_soft_limit: default_execution_queue_latency_soft_limit(),
            execution_queue_latency_hard_limit: default_execution_queue_latency_hard_limit(),
            max_load_shedding_percentage: default_max_load_shedding_percentage(),
            min_load_shedding_percentage_above_hard_limit:
                default_min_load_shedding_percentage_above_hard_limit(),
            safe_transaction_ready_rate: default_safe_transaction_ready_rate(),
            check_system_overload_at_signing: true,
            check_system_overload_at_execution: false,
            max_transaction_manager_queue_length: default_max_transaction_manager_queue_length(),
            max_transaction_manager_queue_length_soft_limit_pct:
                default_max_transaction_manager_queue_length_soft_limit_pct(),
            max_transaction_manager_per_object_queue_length:
                default_max_transaction_manager_per_object_queue_length(),
        }
    }
}

fn default_authority_overload_config() -> AuthorityOverloadConfig {
    AuthorityOverloadConfig::default()
}

fn default_traffic_controller_policy_config() -> Option<PolicyConfig> {
    Some(PolicyConfig::default_dos_protection_policy())
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
pub struct Genesis {
    #[serde(flatten)]
    location: Option<GenesisLocation>,

    #[serde(skip)]
    genesis: once_cell::sync::OnceCell<genesis::Genesis>,
}

impl Genesis {
    pub fn new(genesis: genesis::Genesis) -> Self {
        Self {
            location: Some(GenesisLocation::InPlace {
                genesis: Box::new(genesis),
            }),
            genesis: Default::default(),
        }
    }

    pub fn new_from_file<P: Into<PathBuf>>(path: P) -> Self {
        Self {
            location: Some(GenesisLocation::File {
                genesis_file_location: path.into(),
            }),
            genesis: Default::default(),
        }
    }

    pub fn new_empty() -> Self {
        Self {
            location: None,
            genesis: Default::default(),
        }
    }

    pub fn genesis(&self) -> Result<&genesis::Genesis> {
        match &self.location {
            Some(GenesisLocation::InPlace { genesis }) => Ok(genesis),
            Some(GenesisLocation::File {
                genesis_file_location,
            }) => self
                .genesis
                .get_or_try_init(|| genesis::Genesis::load(genesis_file_location)),
            None => anyhow::bail!("no genesis location set"),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
#[serde(untagged)]
enum GenesisLocation {
    InPlace {
        genesis: Box<genesis::Genesis>,
    },
    File {
        #[serde(rename = "genesis-file-location")]
        genesis_file_location: PathBuf,
    },
}

/// Wrapper struct for IotaKeyPair that can be deserialized from a file path.
/// Used by network, worker, and account keypair.
#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
pub struct KeyPairWithPath {
    #[serde(flatten)]
    location: KeyPairLocation,

    #[serde(skip)]
    keypair: OnceCell<Arc<IotaKeyPair>>,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
#[serde(untagged)]
enum KeyPairLocation {
    InPlace {
        #[serde(with = "bech32_formatted_keypair")]
        value: Arc<IotaKeyPair>,
    },
    File {
        path: PathBuf,
    },
}

impl KeyPairWithPath {
    pub fn new(kp: IotaKeyPair) -> Self {
        let cell: OnceCell<Arc<IotaKeyPair>> = OnceCell::new();
        let arc_kp = Arc::new(kp);
        // OK to unwrap panic because authority should not start without all keypairs
        // loaded.
        cell.set(arc_kp.clone()).expect("failed to set keypair");
        Self {
            location: KeyPairLocation::InPlace { value: arc_kp },
            keypair: cell,
        }
    }

    pub fn new_from_path(path: PathBuf) -> Self {
        let cell: OnceCell<Arc<IotaKeyPair>> = OnceCell::new();
        // OK to unwrap panic because authority should not start without all keypairs
        // loaded.
        cell.set(Arc::new(read_keypair_from_file(&path).unwrap_or_else(
            |e| panic!("invalid keypair file at path {path:?}: {e}"),
        )))
        .expect("failed to set keypair");
        Self {
            location: KeyPairLocation::File { path },
            keypair: cell,
        }
    }

    pub fn keypair(&self) -> &IotaKeyPair {
        self.keypair
            .get_or_init(|| match &self.location {
                KeyPairLocation::InPlace { value } => value.clone(),
                KeyPairLocation::File { path } => {
                    // OK to unwrap panic because authority should not start without all keypairs
                    // loaded.
                    Arc::new(
                        read_keypair_from_file(path).unwrap_or_else(|e| {
                            panic!("invalid keypair file at path {path:?}: {e}")
                        }),
                    )
                }
            })
            .as_ref()
    }
}

/// Wrapper struct for AuthorityKeyPair that can be deserialized from a file
/// path.
#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
pub struct AuthorityKeyPairWithPath {
    #[serde(flatten)]
    location: AuthorityKeyPairLocation,

    #[serde(skip)]
    keypair: OnceCell<Arc<AuthorityKeyPair>>,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Eq)]
#[serde(untagged)]
enum AuthorityKeyPairLocation {
    InPlace { value: Arc<AuthorityKeyPair> },
    File { path: PathBuf },
}

impl AuthorityKeyPairWithPath {
    pub fn new(kp: AuthorityKeyPair) -> Self {
        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
        let arc_kp = Arc::new(kp);
        // OK to unwrap panic because authority should not start without all keypairs
        // loaded.
        cell.set(arc_kp.clone())
            .expect("failed to set authority keypair");
        Self {
            location: AuthorityKeyPairLocation::InPlace { value: arc_kp },
            keypair: cell,
        }
    }

    pub fn new_from_path(path: PathBuf) -> Self {
        let cell: OnceCell<Arc<AuthorityKeyPair>> = OnceCell::new();
        // OK to unwrap panic because authority should not start without all keypairs
        // loaded.
        cell.set(Arc::new(
            read_authority_keypair_from_file(&path)
                .unwrap_or_else(|_| panic!("invalid authority keypair file at path {path:?}")),
        ))
        .expect("failed to set authority keypair");
        Self {
            location: AuthorityKeyPairLocation::File { path },
            keypair: cell,
        }
    }

    pub fn authority_keypair(&self) -> &AuthorityKeyPair {
        self.keypair
            .get_or_init(|| match &self.location {
                AuthorityKeyPairLocation::InPlace { value } => value.clone(),
                AuthorityKeyPairLocation::File { path } => {
                    // OK to unwrap panic because authority should not start without all keypairs
                    // loaded.
                    Arc::new(
                        read_authority_keypair_from_file(path)
                            .unwrap_or_else(|_| panic!("invalid authority keypair file {path:?}")),
                    )
                }
            })
            .as_ref()
    }
}

/// Configurations which determine how we dump state debug info.
/// Debug info is dumped when a node forks.
#[derive(Clone, Debug, Deserialize, Serialize, Default)]
#[serde(rename_all = "kebab-case")]
pub struct StateDebugDumpConfig {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dump_file_directory: Option<PathBuf>,
}

#[cfg(test)]
mod tests {
    use std::path::PathBuf;

    use fastcrypto::traits::KeyPair;
    use iota_keys::keypair_file::{write_authority_keypair_to_file, write_keypair_to_file};
    use iota_types::crypto::{
        AuthorityKeyPair, IotaKeyPair, NetworkKeyPair, get_key_pair_from_rng,
    };
    use rand::{SeedableRng, rngs::StdRng};

    use super::Genesis;
    use crate::NodeConfig;

    #[test]
    fn serialize_genesis_from_file() {
        let g = Genesis::new_from_file("path/to/file");

        let s = serde_yaml::to_string(&g).unwrap();
        assert_eq!("---\ngenesis-file-location: path/to/file\n", s);
        let loaded_genesis: Genesis = serde_yaml::from_str(&s).unwrap();
        assert_eq!(g, loaded_genesis);
    }

    #[test]
    fn fullnode_template() {
        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");

        let _template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
    }

    #[test]
    fn enable_soft_locking_defaults_to_enabled() {
        // The template omits `enable-soft-locking`, so this exercises the serde
        // default and pins the documented "default: enabled" contract.
        const TEMPLATE: &str = include_str!("../data/fullnode-template.yaml");

        let config: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
        assert!(config.enable_soft_locking);
    }

    #[test]
    fn load_key_pairs_to_node_config() {
        let authority_key_pair: AuthorityKeyPair =
            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
        let protocol_key_pair: NetworkKeyPair =
            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;
        let network_key_pair: NetworkKeyPair =
            get_key_pair_from_rng(&mut StdRng::from_seed([0; 32])).1;

        write_authority_keypair_to_file(&authority_key_pair, PathBuf::from("authority.key"))
            .unwrap();
        write_keypair_to_file(
            &IotaKeyPair::Ed25519(protocol_key_pair.copy()),
            PathBuf::from("protocol.key"),
        )
        .unwrap();
        write_keypair_to_file(
            &IotaKeyPair::Ed25519(network_key_pair.copy()),
            PathBuf::from("network.key"),
        )
        .unwrap();

        const TEMPLATE: &str = include_str!("../data/fullnode-template-with-path.yaml");
        let template: NodeConfig = serde_yaml::from_str(TEMPLATE).unwrap();
        assert_eq!(
            template.authority_key_pair().public(),
            authority_key_pair.public()
        );
        assert_eq!(
            template.network_key_pair().public(),
            network_key_pair.public()
        );
        assert_eq!(
            template.protocol_key_pair().public(),
            protocol_key_pair.public()
        );
    }
}

// RunWithRange is used to specify the ending epoch/checkpoint to process.
// this is intended for use with disaster recovery debugging and verification
// workflows, never in normal operations
#[derive(Clone, Copy, PartialEq, Debug, Serialize, Deserialize)]
pub enum RunWithRange {
    Epoch(EpochId),
    Checkpoint(CheckpointSequenceNumber),
}

impl RunWithRange {
    // is epoch_id > RunWithRange::Epoch
    pub fn is_epoch_gt(&self, epoch_id: EpochId) -> bool {
        matches!(self, RunWithRange::Epoch(e) if epoch_id > *e)
    }

    pub fn matches_checkpoint(&self, seq_num: CheckpointSequenceNumber) -> bool {
        matches!(self, RunWithRange::Checkpoint(seq) if *seq == seq_num)
    }

    pub fn into_checkpoint_bound(self) -> Option<CheckpointSequenceNumber> {
        match self {
            RunWithRange::Epoch(_) => None,
            RunWithRange::Checkpoint(seq) => Some(seq),
        }
    }
}

/// A serde helper module used with #[serde(with = "...")] to change the
/// de/serialization format of an `IotaKeyPair` to Bech32 when written to or
/// read from a node config.
mod bech32_formatted_keypair {
    use std::ops::Deref;

    use iota_types::crypto::{EncodeDecodeBase64, IotaKeyPair};
    use serde::{Deserialize, Deserializer, Serializer};

    pub fn serialize<S, T>(kp: &T, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
        T: Deref<Target = IotaKeyPair>,
    {
        use serde::ser::Error;

        // Serialize the keypair to a Bech32 string
        let s = kp.encode().map_err(Error::custom)?;

        serializer.serialize_str(&s)
    }

    pub fn deserialize<'de, D, T>(deserializer: D) -> Result<T, D::Error>
    where
        D: Deserializer<'de>,
        T: From<IotaKeyPair>,
    {
        use serde::de::Error;

        let s = String::deserialize(deserializer)?;

        // Try to deserialize the keypair from a Bech32 formatted string
        IotaKeyPair::decode(&s)
            .or_else(|_| {
                // For backwards compatibility try Base64 if Bech32 failed
                IotaKeyPair::decode_base64(&s)
            })
            .map(Into::into)
            .map_err(Error::custom)
    }
}