casper_execution_engine/engine_state/
engine_config.rs

1//! Support for runtime configuration of the execution engine - as an integral property of the
2//! `EngineState` instance.
3
4use std::collections::BTreeSet;
5
6use num_rational::Ratio;
7use num_traits::One;
8
9use casper_types::{
10    account::AccountHash, FeeHandling, ProtocolVersion, PublicKey, RefundHandling, StorageCosts,
11    SystemConfig, TimeDiff, WasmConfig, DEFAULT_FEE_HANDLING, DEFAULT_MINIMUM_BID_AMOUNT,
12    DEFAULT_REFUND_HANDLING,
13};
14
15/// Default value for a maximum query depth configuration option.
16pub const DEFAULT_MAX_QUERY_DEPTH: u64 = 5;
17/// Default value for maximum associated keys configuration option.
18pub const DEFAULT_MAX_ASSOCIATED_KEYS: u32 = 100;
19/// Default value for maximum runtime call stack height configuration option.
20pub const DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT: u32 = 12;
21/// Default max serialized size of `StoredValue`s.
22#[deprecated(
23    since = "3.2.0",
24    note = "not used in `casper-execution-engine` config anymore"
25)]
26pub const DEFAULT_MAX_STORED_VALUE_SIZE: u32 = 8 * 1024 * 1024;
27/// Default value for minimum delegation amount in motes.
28pub const DEFAULT_MINIMUM_DELEGATION_AMOUNT: u64 = 500 * 1_000_000_000;
29/// Default value for maximum delegation amount in motes.
30pub const DEFAULT_MAXIMUM_DELEGATION_AMOUNT: u64 = 1_000_000_000 * 1_000_000_000;
31/// Default value for strict argument checking.
32pub const DEFAULT_STRICT_ARGUMENT_CHECKING: bool = false;
33/// 91 days / 7 days in a week = 13 weeks
34/// Length of total vesting schedule in days.
35const VESTING_SCHEDULE_LENGTH_DAYS: usize = 91;
36const DAY_MILLIS: usize = 24 * 60 * 60 * 1000;
37/// Default length of total vesting schedule period expressed in days.
38pub const DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS: u64 =
39    VESTING_SCHEDULE_LENGTH_DAYS as u64 * DAY_MILLIS as u64;
40/// Default maximum number of delegators per validator.
41pub const DEFAULT_MAX_DELEGATORS_PER_VALIDATOR: u32 = 1200;
42/// Default value for allowing auction bids.
43pub const DEFAULT_ALLOW_AUCTION_BIDS: bool = true;
44/// Default value for allowing unrestricted transfers.
45pub const DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS: bool = true;
46/// Default compute rewards.
47pub const DEFAULT_COMPUTE_REWARDS: bool = true;
48/// Default protocol version.
49pub const DEFAULT_PROTOCOL_VERSION: ProtocolVersion = ProtocolVersion::V2_0_0;
50/// Default period for balance holds to decay (currently 24 hours).
51pub const DEFAULT_BALANCE_HOLD_INTERVAL: TimeDiff = TimeDiff::from_seconds(24 * 60 * 60);
52
53/// Default entity flag.
54pub const DEFAULT_ENABLE_ENTITY: bool = false;
55
56pub(crate) const DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION: bool = false;
57
58/// The runtime configuration of the execution engine
59#[derive(Debug, Clone)]
60pub struct EngineConfig {
61    /// Maximum number of associated keys (i.e. map of
62    /// [`AccountHash`](AccountHash)s to
63    /// [`Weight`](casper_types::account::Weight)s) for a single account.
64    max_associated_keys: u32,
65    max_runtime_call_stack_height: u32,
66    minimum_delegation_amount: u64,
67    maximum_delegation_amount: u64,
68    minimum_bid_amount: u64,
69    /// This flag indicates if arguments passed to contracts are checked against the defined types.
70    strict_argument_checking: bool,
71    /// Vesting schedule period in milliseconds.
72    vesting_schedule_period_millis: u64,
73    max_delegators_per_validator: u32,
74    wasm_config: WasmConfig,
75    system_config: SystemConfig,
76    protocol_version: ProtocolVersion,
77    /// A private network specifies a list of administrative accounts.
78    pub(crate) administrative_accounts: BTreeSet<AccountHash>,
79    /// Auction entrypoints such as "add_bid" or "delegate" are disabled if this flag is set to
80    /// `false`.
81    pub(crate) allow_auction_bids: bool,
82    /// Allow unrestricted transfers between normal accounts.
83    ///
84    /// If set to `true` accounts can transfer tokens between themselves without restrictions. If
85    /// set to `false` tokens can be transferred only from normal accounts to administrators
86    /// and administrators to normal accounts but not normal accounts to normal accounts.
87    pub(crate) allow_unrestricted_transfers: bool,
88    /// Refund handling config.
89    pub(crate) refund_handling: RefundHandling,
90    /// Fee handling.
91    pub(crate) fee_handling: FeeHandling,
92    /// Compute auction rewards.
93    pub(crate) compute_rewards: bool,
94    pub(crate) enable_entity: bool,
95    pub(crate) trap_on_ambiguous_entity_version: bool,
96    storage_costs: StorageCosts,
97}
98
99impl Default for EngineConfig {
100    fn default() -> Self {
101        EngineConfig {
102            max_associated_keys: DEFAULT_MAX_ASSOCIATED_KEYS,
103            max_runtime_call_stack_height: DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT,
104            minimum_delegation_amount: DEFAULT_MINIMUM_DELEGATION_AMOUNT,
105            maximum_delegation_amount: DEFAULT_MAXIMUM_DELEGATION_AMOUNT,
106            minimum_bid_amount: DEFAULT_MINIMUM_BID_AMOUNT,
107            strict_argument_checking: DEFAULT_STRICT_ARGUMENT_CHECKING,
108            vesting_schedule_period_millis: DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS,
109            max_delegators_per_validator: DEFAULT_MAX_DELEGATORS_PER_VALIDATOR,
110            wasm_config: WasmConfig::default(),
111            system_config: SystemConfig::default(),
112            administrative_accounts: Default::default(),
113            allow_auction_bids: DEFAULT_ALLOW_AUCTION_BIDS,
114            allow_unrestricted_transfers: DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS,
115            refund_handling: DEFAULT_REFUND_HANDLING,
116            fee_handling: DEFAULT_FEE_HANDLING,
117            compute_rewards: DEFAULT_COMPUTE_REWARDS,
118            protocol_version: DEFAULT_PROTOCOL_VERSION,
119            enable_entity: DEFAULT_ENABLE_ENTITY,
120            trap_on_ambiguous_entity_version: DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION,
121            storage_costs: Default::default(),
122        }
123    }
124}
125
126impl EngineConfig {
127    /// Returns the current max associated keys config.
128    pub fn max_associated_keys(&self) -> u32 {
129        self.max_associated_keys
130    }
131
132    /// Returns the current max runtime call stack height config.
133    pub fn max_runtime_call_stack_height(&self) -> u32 {
134        self.max_runtime_call_stack_height
135    }
136
137    /// Returns the current wasm config.
138    pub fn wasm_config(&self) -> &WasmConfig {
139        &self.wasm_config
140    }
141
142    /// Returns the current system config.
143    pub fn system_config(&self) -> &SystemConfig {
144        &self.system_config
145    }
146
147    /// Returns the current protocol version.
148    pub fn protocol_version(&self) -> ProtocolVersion {
149        self.protocol_version
150    }
151
152    /// Returns the minimum delegation amount in motes.
153    pub fn minimum_delegation_amount(&self) -> u64 {
154        self.minimum_delegation_amount
155    }
156
157    /// Returns the maximum delegation amount in motes.
158    pub fn maximum_delegation_amount(&self) -> u64 {
159        self.maximum_delegation_amount
160    }
161
162    /// Returns the minimum delegation amount in motes.
163    pub fn minimum_bid_amount(&self) -> u64 {
164        self.minimum_bid_amount
165    }
166
167    /// Get the engine config's strict argument checking flag.
168    pub fn strict_argument_checking(&self) -> bool {
169        self.strict_argument_checking
170    }
171
172    /// Get the vesting schedule period.
173    pub fn vesting_schedule_period_millis(&self) -> u64 {
174        self.vesting_schedule_period_millis
175    }
176
177    /// Get the max delegators per validator
178    pub fn max_delegators_per_validator(&self) -> u32 {
179        self.max_delegators_per_validator
180    }
181
182    /// Returns the engine config's administrative accounts.
183    pub fn administrative_accounts(&self) -> &BTreeSet<AccountHash> {
184        &self.administrative_accounts
185    }
186
187    /// Returns true if auction bids are allowed.
188    pub fn allow_auction_bids(&self) -> bool {
189        self.allow_auction_bids
190    }
191
192    /// Returns true if unrestricted transfers are allowed.
193    pub fn allow_unrestricted_transfers(&self) -> bool {
194        self.allow_unrestricted_transfers
195    }
196
197    /// Checks if an account hash is an administrator.
198    pub(crate) fn is_administrator(&self, account_hash: &AccountHash) -> bool {
199        self.administrative_accounts.contains(account_hash)
200    }
201
202    /// Returns the engine config's refund ratio.
203    pub fn refund_handling(&self) -> RefundHandling {
204        self.refund_handling
205    }
206
207    /// Returns the engine config's fee handling strategy.
208    pub fn fee_handling(&self) -> FeeHandling {
209        self.fee_handling
210    }
211
212    /// Returns the engine config's storage_costs.
213    pub fn storage_costs(&self) -> &StorageCosts {
214        &self.storage_costs
215    }
216
217    /// Returns the engine config's compute rewards flag.
218    pub fn compute_rewards(&self) -> bool {
219        self.compute_rewards
220    }
221
222    /// Returns the `trap_on_ambiguous_entity_version` flag.
223    pub fn trap_on_ambiguous_entity_version(&self) -> bool {
224        self.trap_on_ambiguous_entity_version
225    }
226
227    /// Sets the protocol version of the config.
228    ///
229    /// NOTE: This is only useful to the WasmTestBuilder for emulating a network upgrade, and hence
230    /// is subject to change or deletion without notice.
231    #[doc(hidden)]
232    pub fn set_protocol_version(&mut self, protocol_version: ProtocolVersion) {
233        self.protocol_version = protocol_version;
234    }
235
236    /// Sets the `wasm_config.max_memory` to `new_value`.
237    #[cfg(feature = "test-support")]
238    pub fn set_max_memory(&mut self, new_value: u32) {
239        *self.wasm_config.v1_mut().max_memory_mut() = new_value;
240    }
241}
242
243/// A builder for an [`EngineConfig`].
244///
245/// Any field that isn't specified will be defaulted.  See [the module docs](index.html) for the set
246/// of default values.
247#[derive(Default, Debug)]
248pub struct EngineConfigBuilder {
249    max_query_depth: Option<u64>,
250    max_associated_keys: Option<u32>,
251    max_runtime_call_stack_height: Option<u32>,
252    minimum_delegation_amount: Option<u64>,
253    maximum_delegation_amount: Option<u64>,
254    minimum_bid_amount: Option<u64>,
255    strict_argument_checking: Option<bool>,
256    vesting_schedule_period_millis: Option<u64>,
257    max_delegators_per_validator: Option<u32>,
258    wasm_config: Option<WasmConfig>,
259    system_config: Option<SystemConfig>,
260    protocol_version: Option<ProtocolVersion>,
261    administrative_accounts: Option<BTreeSet<PublicKey>>,
262    allow_auction_bids: Option<bool>,
263    allow_unrestricted_transfers: Option<bool>,
264    refund_handling: Option<RefundHandling>,
265    fee_handling: Option<FeeHandling>,
266    compute_rewards: Option<bool>,
267    balance_hold_interval: Option<TimeDiff>,
268    enable_entity: Option<bool>,
269    trap_on_ambiguous_entity_version: Option<bool>,
270    storage_costs: Option<StorageCosts>,
271}
272
273impl EngineConfigBuilder {
274    /// Creates a new `EngineConfig` builder.
275    pub fn new() -> Self {
276        EngineConfigBuilder::default()
277    }
278
279    /// Sets the max query depth config option.
280    pub fn with_max_query_depth(mut self, max_query_depth: u64) -> Self {
281        self.max_query_depth = Some(max_query_depth);
282        self
283    }
284
285    /// Sets the max associated keys config option.
286    pub fn with_max_associated_keys(mut self, max_associated_keys: u32) -> Self {
287        self.max_associated_keys = Some(max_associated_keys);
288        self
289    }
290
291    /// Sets the max runtime call stack height config option.
292    pub fn with_max_runtime_call_stack_height(
293        mut self,
294        max_runtime_call_stack_height: u32,
295    ) -> Self {
296        self.max_runtime_call_stack_height = Some(max_runtime_call_stack_height);
297        self
298    }
299
300    /// Sets the strict argument checking config option.
301    pub fn with_strict_argument_checking(mut self, value: bool) -> Self {
302        self.strict_argument_checking = Some(value);
303        self
304    }
305
306    /// Sets the vesting schedule period millis config option.
307    pub fn with_vesting_schedule_period_millis(mut self, value: u64) -> Self {
308        self.vesting_schedule_period_millis = Some(value);
309        self
310    }
311
312    /// Sets the max delegators per validator config option.
313    pub fn with_max_delegators_per_validator(mut self, value: u32) -> Self {
314        self.max_delegators_per_validator = Some(value);
315        self
316    }
317
318    /// Sets the wasm config options.
319    pub fn with_wasm_config(mut self, wasm_config: WasmConfig) -> Self {
320        self.wasm_config = Some(wasm_config);
321        self
322    }
323
324    /// Sets the system config options.
325    pub fn with_system_config(mut self, system_config: SystemConfig) -> Self {
326        self.system_config = Some(system_config);
327        self
328    }
329
330    /// Sets the protocol version.
331    pub fn with_protocol_version(mut self, protocol_version: ProtocolVersion) -> Self {
332        self.protocol_version = Some(protocol_version);
333        self
334    }
335
336    /// Sets the maximum wasm stack height config option.
337    pub fn with_wasm_max_stack_height(mut self, wasm_stack_height: u32) -> Self {
338        let wasm_config = self.wasm_config.get_or_insert_with(WasmConfig::default);
339        *wasm_config.v1_mut().max_stack_height_mut() = wasm_stack_height;
340        self
341    }
342
343    /// Sets the minimum delegation amount config option.
344    pub fn with_minimum_delegation_amount(mut self, minimum_delegation_amount: u64) -> Self {
345        self.minimum_delegation_amount = Some(minimum_delegation_amount);
346        self
347    }
348
349    /// Sets the maximum delegation amount config option.
350    pub fn with_maximum_delegation_amount(mut self, maximum_delegation_amount: u64) -> Self {
351        self.maximum_delegation_amount = Some(maximum_delegation_amount);
352        self
353    }
354
355    /// Sets the minimum bid amount config option.
356    pub fn with_minimum_bid_amount(mut self, minimum_bid_amount: u64) -> Self {
357        self.minimum_bid_amount = Some(minimum_bid_amount);
358        self
359    }
360
361    /// Sets the administrative accounts.
362    pub fn with_administrative_accounts(
363        mut self,
364        administrator_accounts: BTreeSet<PublicKey>,
365    ) -> Self {
366        self.administrative_accounts = Some(administrator_accounts);
367        self
368    }
369
370    /// Sets the allow auction bids config option.
371    pub fn with_allow_auction_bids(mut self, allow_auction_bids: bool) -> Self {
372        self.allow_auction_bids = Some(allow_auction_bids);
373        self
374    }
375
376    /// Sets the allow unrestricted transfers config option.
377    pub fn with_allow_unrestricted_transfers(mut self, allow_unrestricted_transfers: bool) -> Self {
378        self.allow_unrestricted_transfers = Some(allow_unrestricted_transfers);
379        self
380    }
381
382    /// Sets the refund handling config option.
383    pub fn with_refund_handling(mut self, refund_handling: RefundHandling) -> Self {
384        match refund_handling {
385            RefundHandling::Refund { refund_ratio } | RefundHandling::Burn { refund_ratio } => {
386                debug_assert!(
387                    refund_ratio <= Ratio::one(),
388                    "refund ratio should be in the range of [0, 1]"
389                );
390            }
391            RefundHandling::NoRefund => {
392                //noop
393            }
394        }
395
396        self.refund_handling = Some(refund_handling);
397        self
398    }
399
400    /// Sets fee handling config option.
401    pub fn with_fee_handling(mut self, fee_handling: FeeHandling) -> Self {
402        self.fee_handling = Some(fee_handling);
403        self
404    }
405
406    /// Sets compute rewards config option.
407    pub fn with_compute_rewards(mut self, compute_rewards: bool) -> Self {
408        self.compute_rewards = Some(compute_rewards);
409        self
410    }
411
412    /// Sets balance hold interval config option.
413    pub fn balance_hold_interval(mut self, balance_hold_interval: TimeDiff) -> Self {
414        self.balance_hold_interval = Some(balance_hold_interval);
415        self
416    }
417
418    /// Sets the enable entity flag.
419    pub fn with_enable_entity(mut self, enable_entity: bool) -> Self {
420        self.enable_entity = Some(enable_entity);
421        self
422    }
423
424    /// Sets the flag if the runtime returns an error on entity version collision.
425    pub fn with_trap_on_ambiguous_entity_version(
426        mut self,
427        trap_on_ambiguous_entity_version: bool,
428    ) -> Self {
429        self.trap_on_ambiguous_entity_version = Some(trap_on_ambiguous_entity_version);
430        self
431    }
432
433    /// Sets the storage_costs config option.
434    pub fn with_storage_costs(mut self, storage_costs: StorageCosts) -> Self {
435        self.storage_costs = Some(storage_costs);
436        self
437    }
438
439    /// Builds a new [`EngineConfig`] object.
440    pub fn build(self) -> EngineConfig {
441        let max_associated_keys = self
442            .max_associated_keys
443            .unwrap_or(DEFAULT_MAX_ASSOCIATED_KEYS);
444        let max_runtime_call_stack_height = self
445            .max_runtime_call_stack_height
446            .unwrap_or(DEFAULT_MAX_RUNTIME_CALL_STACK_HEIGHT);
447        let minimum_delegation_amount = self
448            .minimum_delegation_amount
449            .unwrap_or(DEFAULT_MINIMUM_DELEGATION_AMOUNT);
450        let maximum_delegation_amount = self
451            .maximum_delegation_amount
452            .unwrap_or(DEFAULT_MAXIMUM_DELEGATION_AMOUNT);
453        let minimum_bid_amount = self
454            .minimum_bid_amount
455            .unwrap_or(DEFAULT_MINIMUM_BID_AMOUNT);
456        let wasm_config = self.wasm_config.unwrap_or_default();
457        let system_config = self.system_config.unwrap_or_default();
458        let protocol_version = self.protocol_version.unwrap_or(DEFAULT_PROTOCOL_VERSION);
459        let administrative_accounts = {
460            self.administrative_accounts
461                .unwrap_or_default()
462                .iter()
463                .map(PublicKey::to_account_hash)
464                .collect()
465        };
466        let allow_auction_bids = self
467            .allow_auction_bids
468            .unwrap_or(DEFAULT_ALLOW_AUCTION_BIDS);
469        let allow_unrestricted_transfers = self
470            .allow_unrestricted_transfers
471            .unwrap_or(DEFAULT_ALLOW_UNRESTRICTED_TRANSFERS);
472        let refund_handling = self.refund_handling.unwrap_or(DEFAULT_REFUND_HANDLING);
473        let fee_handling = self.fee_handling.unwrap_or(DEFAULT_FEE_HANDLING);
474
475        let strict_argument_checking = self
476            .strict_argument_checking
477            .unwrap_or(DEFAULT_STRICT_ARGUMENT_CHECKING);
478        let vesting_schedule_period_millis = self
479            .vesting_schedule_period_millis
480            .unwrap_or(DEFAULT_VESTING_SCHEDULE_LENGTH_MILLIS);
481        let max_delegators_per_validator = self
482            .max_delegators_per_validator
483            .unwrap_or(DEFAULT_MAX_DELEGATORS_PER_VALIDATOR);
484        let compute_rewards = self.compute_rewards.unwrap_or(DEFAULT_COMPUTE_REWARDS);
485        let enable_entity = self.enable_entity.unwrap_or(DEFAULT_ENABLE_ENTITY);
486        let trap_on_ambiguous_entity_version = self
487            .trap_on_ambiguous_entity_version
488            .unwrap_or(DEFAULT_TRAP_ON_AMBIGUOUS_ENTITY_VERSION);
489        let storage_costs = self.storage_costs.unwrap_or_default();
490
491        EngineConfig {
492            max_associated_keys,
493            max_runtime_call_stack_height,
494            minimum_delegation_amount,
495            maximum_delegation_amount,
496            minimum_bid_amount,
497            wasm_config,
498            system_config,
499            protocol_version,
500            administrative_accounts,
501            allow_auction_bids,
502            allow_unrestricted_transfers,
503            refund_handling,
504            fee_handling,
505            strict_argument_checking,
506            vesting_schedule_period_millis,
507            max_delegators_per_validator,
508            compute_rewards,
509            enable_entity,
510            trap_on_ambiguous_entity_version,
511            storage_costs,
512        }
513    }
514}
casper_execution_engine/engine_state/engine_config.rs

casper_execution_engine/engine_state/
engine_config.rs
