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

casper_execution_engine/engine_state/
engine_config.rs
