casper-execution-engine 9.0.0

//! Support for runtime configuration of the execution engine - as an integral property of the
//! `EngineState` instance.

use std::collections::BTreeSet;

use num_rational::Ratio;
use num_traits::One;

use casper_types::{
    account::AccountHash, FeeHandling, ProtocolVersion, PublicKey, RefundHandling, RewardsHandling,
    StorageCosts, SystemConfig, TimeDiff, WasmConfig, DEFAULT_FEE_HANDLING,
    DEFAULT_MINIMUM_BID_AMOUNT, DEFAULT_REFUND_HANDLING,
};

/// Default value for a maximum query depth configuration option.
pub const DEFAULT_MAX_QUERY_DEPTH: u64 = 5;
/// Default value for maximum associated keys configuration option.
pub const DEFAULT_MAX_ASSOCIATED_KEYS: u32 = 100;
/// Default value for maximum runtime call stack height configuration option.
pub const DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT: u32 = 12;
/// Default max serialized size of `StoredValue`s.
#[deprecated(
    since = "3.2.0",
    note = "not used in `casper-execution-engine` config anymore"
)]
pub const DEFAULT_MAX_STORED_VALUE_SIZE: u32 = 8 * 1024 * 1024;
/// Default value for minimum delegation amount in motes.
pub const DEFAULT_MINIMUM_DELEGATION_AMOUNT: u64 = 500 * 1_000_000_000;
/// Default value for maximum delegation amount in motes.
pub const DEFAULT_MAXIMUM_DELEGATION_AMOUNT: u64 = 1_000_000_000 * 1_000_000_000;
/// Default value for strict argument checking.
pub const DEFAULT_STRICT_ARGUMENT_CHECKING: bool = false;
/// 91 days / 7 days in a week = 13 weeks
/// Length of total vesting schedule in days.
const VESTING_SCHEDULE_LENGTH_DAYS: usize = 91;
const DAY_MILLIS: usize = 24 * 60 * 60 * 1000;
/// Default length of total vesting schedule period expressed in days.
pub const DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS: u64 =
    VESTING_SCHEDULE_LENGTH_DAYS as u64 * DAY_MILLIS as u64;
/// Default maximum number of delegators per validator.
pub const DEFAULT_MAX_DELEGATORS_PER_VALIDATOR: u32 = 1200;
/// Default value for allowing auction bids.
pub const DEFAULT_ALLOW_AUCTION_BIDS: bool = true;
/// Default value for allowing unrestricted transfers.
pub const DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS: bool = true;
/// Default compute rewards.
pub const DEFAULT_COMPUTE_REWARDS: bool = true;
/// Default protocol version.
pub const DEFAULT_PROTOCOL_VERSION: ProtocolVersion = ProtocolVersion::V2_0_0;
/// Default period for balance holds to decay (currently 24 hours).
pub const DEFAULT_BALANCE_HOLD_INTERVAL: TimeDiff = TimeDiff::from_seconds(24 * 60 * 60);

/// Default entity flag.
pub const DEFAULT_ENABLE_ENTITY: bool = false;

pub(crate) const DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION: bool = false;

/// The runtime configuration of the execution engine
#[derive(Debug, Clone)]
pub struct EngineConfig {
    /// Maximum number of associated keys (i.e. map of
    /// [`AccountHash`](AccountHash)s to
    /// [`Weight`](casper_types::account::Weight)s) for a single account.
    max_associated_keys: u32,
    max_runtime_call_stack_height: u32,
    minimum_delegation_amount: u64,
    maximum_delegation_amount: u64,
    minimum_bid_amount: u64,
    /// This flag indicates if arguments passed to contracts are checked against the defined types.
    strict_argument_checking: bool,
    /// Vesting schedule period in milliseconds.
    vesting_schedule_period_millis: u64,
    max_delegators_per_validator: u32,
    wasm_config: WasmConfig,
    system_config: SystemConfig,
    protocol_version: ProtocolVersion,
    /// A private network specifies a list of administrative accounts.
    pub(crate) administrative_accounts: BTreeSet<AccountHash>,
    /// Auction entrypoints such as "add_bid" or "delegate" are disabled if this flag is set to
    /// `false`.
    pub(crate) allow_auction_bids: bool,
    /// Allow unrestricted transfers between normal accounts.
    ///
    /// If set to `true` accounts can transfer tokens between themselves without restrictions. If
    /// set to `false` tokens can be transferred only from normal accounts to administrators
    /// and administrators to normal accounts but not normal accounts to normal accounts.
    pub(crate) allow_unrestricted_transfers: bool,
    /// Refund handling config.
    pub(crate) refund_handling: RefundHandling,
    /// Fee handling.
    pub(crate) fee_handling: FeeHandling,
    /// Compute auction rewards.
    pub(crate) compute_rewards: bool,
    pub(crate) enable_entity: bool,
    pub(crate) trap_on_ambiguous_entity_version: bool,
    pub(crate) rewards_handling: RewardsHandling,
    storage_costs: StorageCosts,
}

impl Default for EngineConfig {
    fn default() -> Self {
        EngineConfig {
            max_associated_keys: DEFAULT_MAX_ASSOCIATED_KEYS,
            max_runtime_call_stack_height: DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT,
            minimum_delegation_amount: DEFAULT_MINIMUM_DELEGATION_AMOUNT,
            maximum_delegation_amount: DEFAULT_MAXIMUM_DELEGATION_AMOUNT,
            minimum_bid_amount: DEFAULT_MINIMUM_BID_AMOUNT,
            strict_argument_checking: DEFAULT_STRICT_ARGUMENT_CHECKING,
            vesting_schedule_period_millis: DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS,
            max_delegators_per_validator: DEFAULT_MAX_DELEGATORS_PER_VALIDATOR,
            wasm_config: WasmConfig::default(),
            system_config: SystemConfig::default(),
            administrative_accounts: Default::default(),
            allow_auction_bids: DEFAULT_ALLOW_AUCTION_BIDS,
            allow_unrestricted_transfers: DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS,
            refund_handling: DEFAULT_REFUND_HANDLING,
            fee_handling: DEFAULT_FEE_HANDLING,
            compute_rewards: DEFAULT_COMPUTE_REWARDS,
            protocol_version: DEFAULT_PROTOCOL_VERSION,
            enable_entity: DEFAULT_ENABLE_ENTITY,
            trap_on_ambiguous_entity_version: DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION,
            rewards_handling: RewardsHandling::Standard,
            storage_costs: Default::default(),
        }
    }
}

impl EngineConfig {
    /// Returns the current max associated keys config.
    pub fn max_associated_keys(&self) -> u32 {
        self.max_associated_keys
    }

    /// Returns the current max runtime call stack height config.
    pub fn max_runtime_call_stack_height(&self) -> u32 {
        self.max_runtime_call_stack_height
    }

    /// Returns the current wasm config.
    pub fn wasm_config(&self) -> &WasmConfig {
        &self.wasm_config
    }

    /// Returns the current system config.
    pub fn system_config(&self) -> &SystemConfig {
        &self.system_config
    }

    /// Returns the current protocol version.
    pub fn protocol_version(&self) -> ProtocolVersion {
        self.protocol_version
    }

    /// Returns the minimum delegation amount in motes.
    pub fn minimum_delegation_amount(&self) -> u64 {
        self.minimum_delegation_amount
    }

    /// Returns the maximum delegation amount in motes.
    pub fn maximum_delegation_amount(&self) -> u64 {
        self.maximum_delegation_amount
    }

    /// Returns the minimum delegation amount in motes.
    pub fn minimum_bid_amount(&self) -> u64 {
        self.minimum_bid_amount
    }

    /// Get the engine config's strict argument checking flag.
    pub fn strict_argument_checking(&self) -> bool {
        self.strict_argument_checking
    }

    /// Get the vesting schedule period.
    pub fn vesting_schedule_period_millis(&self) -> u64 {
        self.vesting_schedule_period_millis
    }

    /// Get the max delegators per validator
    pub fn max_delegators_per_validator(&self) -> u32 {
        self.max_delegators_per_validator
    }

    /// Returns the engine config's administrative accounts.
    pub fn administrative_accounts(&self) -> &BTreeSet<AccountHash> {
        &self.administrative_accounts
    }

    /// Returns true if auction bids are allowed.
    pub fn allow_auction_bids(&self) -> bool {
        self.allow_auction_bids
    }

    /// Returns true if unrestricted transfers are allowed.
    pub fn allow_unrestricted_transfers(&self) -> bool {
        self.allow_unrestricted_transfers
    }

    /// Checks if an account hash is an administrator.
    pub(crate) fn is_administrator(&self, account_hash: &AccountHash) -> bool {
        self.administrative_accounts.contains(account_hash)
    }

    /// Returns the engine config's refund ratio.
    pub fn refund_handling(&self) -> RefundHandling {
        self.refund_handling
    }

    /// Returns the engine config's fee handling strategy.
    pub fn fee_handling(&self) -> FeeHandling {
        self.fee_handling
    }

    /// Returns the engine config's storage_costs.
    pub fn storage_costs(&self) -> &StorageCosts {
        &self.storage_costs
    }

    /// Returns the engine config's compute rewards flag.
    pub fn compute_rewards(&self) -> bool {
        self.compute_rewards
    }

    /// Returns the `trap_on_ambiguous_entity_version` flag.
    pub fn trap_on_ambiguous_entity_version(&self) -> bool {
        self.trap_on_ambiguous_entity_version
    }

    /// Returns the current configuration for rewards handling.
    pub fn rewards_handling(&self) -> RewardsHandling {
        self.rewards_handling.clone()
    }

    /// Sets the protocol version of the config.
    ///
    /// NOTE: This is only useful to the WasmTestBuilder for emulating a network upgrade, and hence
    /// is subject to change or deletion without notice.
    #[doc(hidden)]
    pub fn set_protocol_version(&mut self, protocol_version: ProtocolVersion) {
        self.protocol_version = protocol_version;
    }

    /// Sets the `wasm_config.max_memory` to `new_value`.
    #[cfg(feature = "test-support")]
    pub fn set_max_memory(&mut self, new_value: u32) {
        *self.wasm_config.v1_mut().max_memory_mut() = new_value;
    }
}

/// A builder for an [`EngineConfig`].
///
/// Any field that isn't specified will be defaulted.  See [the module docs](index.html) for the set
/// of default values.
#[derive(Default, Debug)]
pub struct EngineConfigBuilder {
    max_query_depth: Option<u64>,
    max_associated_keys: Option<u32>,
    max_runtime_call_stack_height: Option<u32>,
    minimum_delegation_amount: Option<u64>,
    maximum_delegation_amount: Option<u64>,
    minimum_bid_amount: Option<u64>,
    strict_argument_checking: Option<bool>,
    vesting_schedule_period_millis: Option<u64>,
    max_delegators_per_validator: Option<u32>,
    wasm_config: Option<WasmConfig>,
    system_config: Option<SystemConfig>,
    protocol_version: Option<ProtocolVersion>,
    administrative_accounts: Option<BTreeSet<PublicKey>>,
    allow_auction_bids: Option<bool>,
    allow_unrestricted_transfers: Option<bool>,
    refund_handling: Option<RefundHandling>,
    fee_handling: Option<FeeHandling>,
    compute_rewards: Option<bool>,
    balance_hold_interval: Option<TimeDiff>,
    enable_entity: Option<bool>,
    trap_on_ambiguous_entity_version: Option<bool>,
    rewards_handling: Option<RewardsHandling>,
    storage_costs: Option<StorageCosts>,
}

impl EngineConfigBuilder {
    /// Creates a new `EngineConfig` builder.
    pub fn new() -> Self {
        EngineConfigBuilder::default()
    }

    /// Sets the max query depth config option.
    pub fn with_max_query_depth(mut self, max_query_depth: u64) -> Self {
        self.max_query_depth = Some(max_query_depth);
        self
    }

    /// Sets the max associated keys config option.
    pub fn with_max_associated_keys(mut self, max_associated_keys: u32) -> Self {
        self.max_associated_keys = Some(max_associated_keys);
        self
    }

    /// Sets the max runtime call stack height config option.
    pub fn with_max_runtime_call_stack_height(
        mut self,
        max_runtime_call_stack_height: u32,
    ) -> Self {
        self.max_runtime_call_stack_height = Some(max_runtime_call_stack_height);
        self
    }

    /// Sets the strict argument checking config option.
    pub fn with_strict_argument_checking(mut self, value: bool) -> Self {
        self.strict_argument_checking = Some(value);
        self
    }

    /// Sets the vesting schedule period millis config option.
    pub fn with_vesting_schedule_period_millis(mut self, value: u64) -> Self {
        self.vesting_schedule_period_millis = Some(value);
        self
    }

    /// Sets the max delegators per validator config option.
    pub fn with_max_delegators_per_validator(mut self, value: u32) -> Self {
        self.max_delegators_per_validator = Some(value);
        self
    }

    /// Sets the wasm config options.
    pub fn with_wasm_config(mut self, wasm_config: WasmConfig) -> Self {
        self.wasm_config = Some(wasm_config);
        self
    }

    /// Sets the system config options.
    pub fn with_system_config(mut self, system_config: SystemConfig) -> Self {
        self.system_config = Some(system_config);
        self
    }

    /// Sets the protocol version.
    pub fn with_protocol_version(mut self, protocol_version: ProtocolVersion) -> Self {
        self.protocol_version = Some(protocol_version);
        self
    }

    /// Sets the maximum wasm stack height config option.
    pub fn with_wasm_max_stack_height(mut self, wasm_stack_height: u32) -> Self {
        let wasm_config = self.wasm_config.get_or_insert_with(WasmConfig::default);
        *wasm_config.v1_mut().max_stack_height_mut() = wasm_stack_height;
        self
    }

    /// Sets the minimum delegation amount config option.
    pub fn with_minimum_delegation_amount(mut self, minimum_delegation_amount: u64) -> Self {
        self.minimum_delegation_amount = Some(minimum_delegation_amount);
        self
    }

    /// Sets the maximum delegation amount config option.
    pub fn with_maximum_delegation_amount(mut self, maximum_delegation_amount: u64) -> Self {
        self.maximum_delegation_amount = Some(maximum_delegation_amount);
        self
    }

    /// Sets the minimum bid amount config option.
    pub fn with_minimum_bid_amount(mut self, minimum_bid_amount: u64) -> Self {
        self.minimum_bid_amount = Some(minimum_bid_amount);
        self
    }

    /// Sets the administrative accounts.
    pub fn with_administrative_accounts(
        mut self,
        administrator_accounts: BTreeSet<PublicKey>,
    ) -> Self {
        self.administrative_accounts = Some(administrator_accounts);
        self
    }

    /// Sets the allow auction bids config option.
    pub fn with_allow_auction_bids(mut self, allow_auction_bids: bool) -> Self {
        self.allow_auction_bids = Some(allow_auction_bids);
        self
    }

    /// Sets the allow unrestricted transfers config option.
    pub fn with_allow_unrestricted_transfers(mut self, allow_unrestricted_transfers: bool) -> Self {
        self.allow_unrestricted_transfers = Some(allow_unrestricted_transfers);
        self
    }

    /// Sets the refund handling config option.
    pub fn with_refund_handling(mut self, refund_handling: RefundHandling) -> Self {
        match refund_handling {
            RefundHandling::Refund { refund_ratio } | RefundHandling::Burn { refund_ratio } => {
                debug_assert!(
                    refund_ratio <= Ratio::one(),
                    "refund ratio should be in the range of [0, 1]"
                );
            }
            RefundHandling::NoRefund => {
                //noop
            }
        }

        self.refund_handling = Some(refund_handling);
        self
    }

    /// Sets fee handling config option.
    pub fn with_fee_handling(mut self, fee_handling: FeeHandling) -> Self {
        self.fee_handling = Some(fee_handling);
        self
    }

    /// Sets compute rewards config option.
    pub fn with_compute_rewards(mut self, compute_rewards: bool) -> Self {
        self.compute_rewards = Some(compute_rewards);
        self
    }

    /// Sets balance hold interval config option.
    pub fn balance_hold_interval(mut self, balance_hold_interval: TimeDiff) -> Self {
        self.balance_hold_interval = Some(balance_hold_interval);
        self
    }

    /// Sets the enable entity flag.
    pub fn with_enable_entity(mut self, enable_entity: bool) -> Self {
        self.enable_entity = Some(enable_entity);
        self
    }

    /// Sets the flag if the runtime returns an error on entity version collision.
    pub fn with_trap_on_ambiguous_entity_version(
        mut self,
        trap_on_ambiguous_entity_version: bool,
    ) -> Self {
        self.trap_on_ambiguous_entity_version = Some(trap_on_ambiguous_entity_version);
        self
    }

    /// Sets the storage_costs config option.
    pub fn with_storage_costs(mut self, storage_costs: StorageCosts) -> Self {
        self.storage_costs = Some(storage_costs);
        self
    }

    /// Builds a new [`EngineConfig`] object.
    pub fn build(self) -> EngineConfig {
        let max_associated_keys = self
            .max_associated_keys
            .unwrap_or(DEFAULT_MAX_ASSOCIATED_KEYS);
        let max_runtime_call_stack_height = self
            .max_runtime_call_stack_height
            .unwrap_or(DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT);
        let minimum_delegation_amount = self
            .minimum_delegation_amount
            .unwrap_or(DEFAULT_MINIMUM_DELEGATION_AMOUNT);
        let maximum_delegation_amount = self
            .maximum_delegation_amount
            .unwrap_or(DEFAULT_MAXIMUM_DELEGATION_AMOUNT);
        let minimum_bid_amount = self
            .minimum_bid_amount
            .unwrap_or(DEFAULT_MINIMUM_BID_AMOUNT);
        let wasm_config = self.wasm_config.unwrap_or_default();
        let system_config = self.system_config.unwrap_or_default();
        let protocol_version = self.protocol_version.unwrap_or(DEFAULT_PROTOCOL_VERSION);
        let administrative_accounts = {
            self.administrative_accounts
                .unwrap_or_default()
                .iter()
                .map(PublicKey::to_account_hash)
                .collect()
        };
        let allow_auction_bids = self
            .allow_auction_bids
            .unwrap_or(DEFAULT_ALLOW_AUCTION_BIDS);
        let allow_unrestricted_transfers = self
            .allow_unrestricted_transfers
            .unwrap_or(DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS);
        let refund_handling = self.refund_handling.unwrap_or(DEFAULT_REFUND_HANDLING);
        let fee_handling = self.fee_handling.unwrap_or(DEFAULT_FEE_HANDLING);

        let strict_argument_checking = self
            .strict_argument_checking
            .unwrap_or(DEFAULT_STRICT_ARGUMENT_CHECKING);
        let vesting_schedule_period_millis = self
            .vesting_schedule_period_millis
            .unwrap_or(DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS);
        let max_delegators_per_validator = self
            .max_delegators_per_validator
            .unwrap_or(DEFAULT_MAX_DELEGATORS_PER_VALIDATOR);
        let compute_rewards = self.compute_rewards.unwrap_or(DEFAULT_COMPUTE_REWARDS);
        let enable_entity = self.enable_entity.unwrap_or(DEFAULT_ENABLE_ENTITY);
        let trap_on_ambiguous_entity_version = self
            .trap_on_ambiguous_entity_version
            .unwrap_or(DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION);
        let storage_costs = self.storage_costs.unwrap_or_default();
        let rewards_handling = self.rewards_handling.unwrap_or(RewardsHandling::Standard);

        EngineConfig {
            max_associated_keys,
            max_runtime_call_stack_height,
            minimum_delegation_amount,
            maximum_delegation_amount,
            minimum_bid_amount,
            wasm_config,
            system_config,
            protocol_version,
            administrative_accounts,
            allow_auction_bids,
            allow_unrestricted_transfers,
            refund_handling,
            fee_handling,
            strict_argument_checking,
            vesting_schedule_period_millis,
            max_delegators_per_validator,
            compute_rewards,
            enable_entity,
            trap_on_ambiguous_entity_version,
            rewards_handling,
            storage_costs,
        }
    }
}