referrerpolicy=no-referrer-when-downgrade

pallet_revive/metering/
weight.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18#[cfg(test)]
19mod tests;
20
21use super::math::eip_150::{self, Peak, WeightEip150};
22use crate::{Config, Error, limits::code::BASIC_BLOCK_SIZE, vm::evm::Halt, weights::WeightInfo};
23use core::{marker::PhantomData, ops::ControlFlow};
24use frame_support::{DefaultNoBound, weights::Weight};
25use sp_runtime::{DispatchError, SaturatedConversion};
26
27#[cfg(test)]
28use std::{any::Any, fmt::Debug};
29
30#[derive(Debug, PartialEq, Eq)]
31pub struct ChargedAmount(Weight);
32
33impl ChargedAmount {
34	pub fn amount(&self) -> Weight {
35		self.0
36	}
37}
38
39/// The slope of a `WeightInfo` function at `x` units.
40///
41/// It is the part of the weight that scales with the component: `weight(x) - weight(0)`, the
42/// weight of `x` units with the intercept removed. Saturates at zero.
43pub fn slope(weight: fn(u32) -> Weight, x: u32) -> Weight {
44	weight(x).saturating_sub(weight(0))
45}
46
47/// Meter for syncing the gas between the executor and the weight meter.
48pub struct EngineMeter<T: Config> {
49	fuel: u64,
50	/// The cached [`Self::ref_time_per_fuel`].
51	///
52	/// It is computed once when the meter is created, since `set_fuel` runs on every host call.
53	ref_time_per_fuel: u64,
54	_phantom: PhantomData<T>,
55}
56
57impl<T: Config> Default for EngineMeter<T> {
58	fn default() -> Self {
59		Self::new()
60	}
61}
62
63impl<T: Config> EngineMeter<T> {
64	/// Create a meter with no fuel.
65	fn new() -> Self {
66		Self { fuel: 0, ref_time_per_fuel: Self::ref_time_per_fuel(), _phantom: PhantomData }
67	}
68
69	/// Set the fuel left to the given value.
70	/// Returns the amount of Weight consumed since the last update.
71	fn set_fuel(&mut self, fuel: u64) -> Weight {
72		let consumed = self.fuel.saturating_sub(fuel).saturating_mul(self.ref_time_per_fuel);
73		self.fuel = fuel;
74		Weight::from_parts(consumed, 0)
75	}
76
77	/// Charge the given amount of ref time.
78	/// Returns the amount of fuel left.
79	fn sync_remaining_ref_time(&mut self, remaining_ref_time: u64) -> polkavm::Gas {
80		self.fuel = remaining_ref_time.saturating_div(self.ref_time_per_fuel);
81		self.fuel.try_into().unwrap_or(polkavm::Gas::MAX)
82	}
83
84	/// How much ref time each PolkaVM gas corresponds to.
85	///
86	/// It is the largest ref time per gas of nine benchmarks, each rounded up. All run only
87	/// instructions that cost one gas each, so the slope of one iteration divided by its gas is
88	/// the time of one gas:
89	///
90	/// - `instr_load_chain_<m>` for `m` in `0..8`: dependent 8 byte loads through a random cycle
91	///   that stays in the L2 but not in the L1 data cache of the reference hardware, the cache
92	///   level the cost per gas assumes contract memory to be in. The variants place the values at
93	///   the 8 offsets modulo 64 an 8 byte aligned host buffer can give them, so in one variant
94	///   every load spans two cache lines. The slope of one iteration is divided by
95	///   [`LOAD_CHAIN_GAS`].
96	/// - `instr_indirect_jump`: indirect jumps through a random cycle of compiled basic blocks,
97	///   whose interpreter data stays in the L2 but not in the L1 data cache of the reference
98	///   hardware. The slope of one lap is divided by [`INDIRECT_JUMP_GAS`].
99	pub fn ref_time_per_fuel() -> u64 {
100		let per_gas = |weight: fn(u32) -> Weight, gas: u32| {
101			slope(weight, 1).ref_time().div_ceil(u64::from(gas))
102		};
103		let load_chains: [fn(u32) -> Weight; 8] = [
104			T::WeightInfo::instr_load_chain_0,
105			T::WeightInfo::instr_load_chain_1,
106			T::WeightInfo::instr_load_chain_2,
107			T::WeightInfo::instr_load_chain_3,
108			T::WeightInfo::instr_load_chain_4,
109			T::WeightInfo::instr_load_chain_5,
110			T::WeightInfo::instr_load_chain_6,
111			T::WeightInfo::instr_load_chain_7,
112		];
113		load_chains
114			.into_iter()
115			.map(|weight| per_gas(weight, LOAD_CHAIN_GAS))
116			.fold(per_gas(T::WeightInfo::instr_indirect_jump, INDIRECT_JUMP_GAS), u64::max)
117	}
118
119	/// The gas the PolkaVM interpreter charges for compiling code, derived from the weights.
120	///
121	/// Each part is the slope of a benchmark, converted with [`Self::ref_time_per_fuel`]:
122	///
123	/// - `per_instruction_millis`: `interpreter_compile_per_instruction`.
124	/// - `per_block`: `interpreter_compile_per_block`, which compiles and executes blocks of one
125	///   instruction, minus the compilation of that instruction (`per_instruction_millis`) and
126	///   minus one gas for its execution.
127	/// - `per_code_byte_millis`: `interpreter_code_map_per_byte`. The interpreter charges it for
128	///   the whole code section when it allocates or rewrites its map of compiled blocks. The first
129	///   allocation of a call is paid by the caller with the code load, and the callee's instance
130	///   starts with a gas credit for it. The contract pays the rewrites after many cache resets,
131	///   and the allocation when it resumes from a call, delegate call or instantiation during
132	///   which a PVM frame started: that frame resets the cache of the contract.
133	pub fn interpreter_compilation_cost() -> polkavm::InterpreterCompilationCost {
134		let ref_time_slope = |weight: fn(u32) -> Weight| slope(weight, 1).ref_time();
135		let ref_time_per_fuel = Self::ref_time_per_fuel();
136		let per_instruction = ref_time_slope(T::WeightInfo::interpreter_compile_per_instruction);
137		let per_block = ref_time_slope(T::WeightInfo::interpreter_compile_per_block)
138			.saturating_sub(per_instruction)
139			.saturating_sub(ref_time_per_fuel);
140		let per_code_byte = ref_time_slope(T::WeightInfo::interpreter_code_map_per_byte);
141		Self::compilation_cost_from_ref_time(
142			per_block,
143			per_instruction,
144			per_code_byte,
145			ref_time_per_fuel,
146		)
147	}
148
149	/// Converts ref time to whole gas for `per_block` and thousandths of gas for the other parts,
150	/// rounding up and saturating at `u32::MAX`.
151	///
152	/// `ref_time_per_fuel` must not be zero, as in [`Self::sync_remaining_ref_time`].
153	fn compilation_cost_from_ref_time(
154		per_block: u64,
155		per_instruction: u64,
156		per_code_byte: u64,
157		ref_time_per_fuel: u64,
158	) -> polkavm::InterpreterCompilationCost {
159		let gas = |ref_time: u64| ref_time.div_ceil(ref_time_per_fuel).saturated_into();
160		let millis = |ref_time: u64| gas(ref_time.saturating_mul(1000));
161		polkavm::InterpreterCompilationCost {
162			per_block: gas(per_block),
163			per_instruction_millis: millis(per_instruction),
164			per_code_byte_millis: millis(per_code_byte),
165		}
166	}
167}
168
169/// Gas of one iteration of the `instr_load_chain_<m>` benchmarks.
170///
171/// An iteration is a basic block holding the loop condition, and a basic block holding
172/// `LOAD_CHAIN_GAS - 3` dependent loads, the counter increment and the jump back. Every
173/// instruction costs one gas. The second block has `BASIC_BLOCK_SIZE` instructions.
174pub const LOAD_CHAIN_GAS: u32 = BASIC_BLOCK_SIZE + 1;
175
176/// Gas of one lap of the `instr_indirect_jump` benchmark.
177///
178/// A lap is the loop condition, the counter increment, and `INDIRECT_JUMP_GAS - 2` indirect
179/// jumps: one into a cycle of `INDIRECT_JUMP_GAS - 3` basic blocks and one out of each of them.
180/// Every instruction costs one gas. The cycle is sized so that the interpreter data a lap reads
181/// stays in the L2 but not in the L1 data cache of the reference hardware. The cost per gas
182/// assumes interpreter data to be in the L2, so a working set larger than the L2, which the
183/// interpreter cache limit allows, is charged at the L2 rate.
184pub const INDIRECT_JUMP_GAS: u32 = 3_003;
185
186/// Resource that needs to be synced to the executor.
187///
188/// Wrapped to make sure that the resource will be synced back to the executor.
189#[must_use]
190pub struct Syncable(polkavm::Gas);
191
192impl From<Syncable> for polkavm::Gas {
193	fn from(from: Syncable) -> Self {
194		from.0
195	}
196}
197
198#[cfg(not(test))]
199pub trait TestAuxiliaries {}
200#[cfg(not(test))]
201impl<T> TestAuxiliaries for T {}
202
203#[cfg(test)]
204pub trait TestAuxiliaries: Any + Debug + PartialEq + Eq {}
205#[cfg(test)]
206impl<T: Any + Debug + PartialEq + Eq> TestAuxiliaries for T {}
207
208/// This trait represents a token that can be used for charging `WeightMeter`.
209/// There is no other way of charging it.
210///
211/// Implementing type is expected to be super lightweight hence `Copy` (`Clone` is added
212/// for consistency). If inlined there should be no observable difference compared
213/// to a hand-written code.
214pub trait Token<T: Config>: Copy + Clone + TestAuxiliaries {
215	/// Return the amount of weight that should be taken by this token.
216	///
217	/// This function should be really lightweight and must not fail. It is not
218	/// expected that implementors will query the storage or do any kinds of heavy operations.
219	///
220	/// That said, implementors of this function still can run into overflows
221	/// while calculating the amount. In this case it is ok to use saturating operations
222	/// since on overflow they will return `max_value` which should consume all weight.
223	fn weight(&self) -> Weight;
224
225	/// Returns true if this token is expected to influence the lowest weight limit.
226	fn influence_lowest_weight_limit(&self) -> bool {
227		true
228	}
229}
230
231/// A wrapper around a type-erased trait object of what used to be a `Token`.
232#[cfg(test)]
233pub struct ErasedToken {
234	pub description: String,
235	pub token: Box<dyn Any>,
236}
237
238#[derive(DefaultNoBound)]
239pub struct WeightMeter<T: Config> {
240	/// The overall weight limit of this weight meter.
241	pub weight_limit: Weight,
242	/// The current actual effective weight limit. Used to check whether the weight meter ran out
243	/// of resources. This weight limit needs to be adapted whenever the metering runs in ethereum
244	/// mode and there is a charge on the deposit meter.
245	effective_weight_limit: Weight,
246	/// Amount of weight already consumed. Must be < `weight_limit`.
247	weight_consumed: Weight,
248	/// Due to `adjust_weight` and `nested` the `weight_consumed` can temporarily peak above its
249	/// final value.
250	weight_consumed_highest: Weight,
251	/// The amount of resources that was consumed by the execution engine.
252	/// We have to track it separately in order to avoid the loss of precision that happens when
253	/// converting from ref_time to the execution engine unit.
254	engine_meter: EngineMeter<T>,
255	/// EIP-150 63/64 peak tracking for dry-run weight estimation.
256	eip_150_peak: Peak<WeightEip150>,
257	/// The call stipend this meter got on top of its 63/64 share (zero without one).
258	stipend: Weight,
259	_phantom: PhantomData<T>,
260	#[cfg(test)]
261	tokens: Vec<ErasedToken>,
262}
263
264impl<T: Config> WeightMeter<T> {
265	pub fn new(weight_limit: Weight, stipend: Option<Weight>) -> Self {
266		let stipend = stipend.unwrap_or_default();
267		WeightMeter {
268			weight_limit,
269			effective_weight_limit: weight_limit,
270			weight_consumed: Default::default(),
271			weight_consumed_highest: stipend,
272			engine_meter: EngineMeter::new(),
273			eip_150_peak: Default::default(),
274			stipend,
275			_phantom: PhantomData,
276			#[cfg(test)]
277			tokens: Vec::new(),
278		}
279	}
280
281	pub fn set_effective_weight_limit(&mut self, limit: Weight) {
282		self.effective_weight_limit = limit;
283	}
284
285	/// Absorb the remaining weight of a nested meter after we are done using it.
286	///
287	/// `rule` must be the `State::EIP_150_RULE` of the meter that created `nested`.
288	pub fn absorb_nested(&mut self, nested: Self, rule: eip_150::Rule) {
289		let current_weight_consumed_highest =
290			self.weight_consumed.saturating_add(nested.weight_required());
291
292		// Include the nested call's cumulative EIP-150 63/64 overhead.
293		let current_eip_150_peak =
294			current_weight_consumed_highest.saturating_add(nested.eip_150_total_overhead(rule));
295		self.eip_150_peak.update(current_eip_150_peak);
296
297		self.weight_consumed_highest =
298			current_weight_consumed_highest.max(self.weight_consumed_highest);
299		self.weight_consumed = self.weight_consumed.saturating_add(nested.weight_consumed);
300	}
301
302	/// Returns the extra weight the parent needs beyond `weight_required()` to cover the part
303	/// each caller keeps at and below this level.
304	///
305	/// `rule` must be the `State::EIP_150_RULE` of the meter that created this one.
306	fn eip_150_total_overhead(&self, rule: eip_150::Rule) -> Weight {
307		self.eip_150_peak.total_overhead(self.weight_required(), rule, self.stipend)
308	}
309
310	/// Account for used weight.
311	///
312	/// Amount is calculated by the given `token`.
313	///
314	/// Returns `OutOfGas` if there is not enough weight or addition of the specified
315	/// amount of weight has lead to overflow.
316	///
317	/// NOTE that amount isn't consumed if there is not enough weight. This is considered
318	/// safe because we always charge weight before performing any resource-spending action.
319	#[inline]
320	pub fn charge<Tok: Token<T>>(&mut self, token: Tok) -> Result<ChargedAmount, DispatchError> {
321		#[cfg(test)]
322		{
323			// Unconditionally add the token to the storage.
324			let erased_tok =
325				ErasedToken { description: format!("{:?}", token), token: Box::new(token) };
326			self.tokens.push(erased_tok);
327		}
328
329		let amount = token.weight();
330		// It is OK to not charge anything on failure because we always charge _before_ we perform
331		// any action
332		let new_consumed = self.weight_consumed.saturating_add(amount);
333		if new_consumed.any_gt(self.effective_weight_limit) {
334			return Err(<Error<T>>::OutOfGas.into());
335		}
336
337		self.weight_consumed = new_consumed;
338		Ok(ChargedAmount(amount))
339	}
340
341	/// Charge the specified token amount of weight or halt if not enough weight is left.
342	#[inline]
343	pub fn charge_or_halt<Tok: Token<T>>(
344		&mut self,
345		token: Tok,
346	) -> ControlFlow<Halt, ChargedAmount> {
347		self.charge(token)
348			.map_or_else(|_| ControlFlow::Break(Error::<T>::OutOfGas.into()), ControlFlow::Continue)
349	}
350
351	/// Adjust a previously charged amount down to its actual amount.
352	///
353	/// This is when a maximum a priori amount was charged and then should be partially
354	/// refunded to match the actual amount.
355	pub fn adjust_weight<Tok: Token<T>>(&mut self, charged_amount: ChargedAmount, token: Tok) {
356		if token.influence_lowest_weight_limit() {
357			self.weight_consumed_highest = self.weight_required();
358		}
359		let adjustment = charged_amount.0.saturating_sub(token.weight());
360		self.weight_consumed = self.weight_consumed.saturating_sub(adjustment);
361	}
362
363	/// Hand over the gas metering responsibility from the executor to this meter.
364	///
365	/// Needs to be called when entering a host function to update this meter with the
366	/// gas that was tracked by the executor. It tracks the latest seen total value
367	/// in order to compute the delta that needs to be charged.
368	///
369	/// The executor can leave its gas negative when it charges more than is left. All of the
370	/// gas it was given is then consumed and `OutOfGas` is returned.
371	pub fn sync_from_executor(&mut self, engine_fuel: polkavm::Gas) -> Result<(), DispatchError> {
372		let fuel_left = u64::try_from(engine_fuel).ok();
373		let weight_consumed = self.engine_meter.set_fuel(fuel_left.unwrap_or(0));
374
375		self.weight_consumed.saturating_accrue(weight_consumed);
376		if self.weight_consumed.any_gt(self.effective_weight_limit) {
377			self.weight_consumed = self.effective_weight_limit;
378			return Err(<Error<T>>::OutOfGas.into());
379		}
380
381		match fuel_left {
382			Some(_) => Ok(()),
383			None => Err(<Error<T>>::OutOfGas.into()),
384		}
385	}
386
387	/// Hand over the gas metering responsibility from this meter to the executor.
388	///
389	/// Needs to be called when leaving a host function in order to calculate how much
390	/// gas needs to be charged from the **executor**. It updates the last seen executor
391	/// total value so that it is correct when `sync_from_executor` is called the next time.
392	///
393	/// It is important that this does **not** actually sync with the executor. That has
394	/// to be done by the caller.
395	pub fn sync_to_executor(&mut self) -> polkavm::Gas {
396		self.engine_meter.sync_remaining_ref_time(self.weight_left().ref_time())
397	}
398
399	/// Returns the amount of weight that is required to run the same call.
400	///
401	/// This can be different from `weight_spent` because due to `adjust_weight` the amount of
402	/// spent weight can temporarily drop and be refunded later.
403	pub fn weight_required(&self) -> Weight {
404		self.weight_consumed_highest.max(self.weight_consumed)
405	}
406
407	/// Returns the weight required, including the part each caller keeps under the 63/64 rule.
408	pub fn weight_required_with_eip_150(&self) -> Weight {
409		self.weight_required().max(self.eip_150_peak.get())
410	}
411
412	/// Returns how much weight was spent
413	pub fn weight_consumed(&self) -> Weight {
414		self.weight_consumed
415	}
416
417	pub fn consume_all(&mut self) {
418		self.weight_consumed = self.effective_weight_limit;
419	}
420
421	/// Returns how much weight left from the initial budget.
422	pub fn weight_left(&self) -> Weight {
423		self.effective_weight_limit.saturating_sub(self.weight_consumed)
424	}
425
426	#[cfg(test)]
427	pub fn tokens(&self) -> &[ErasedToken] {
428		&self.tokens
429	}
430
431	#[cfg(test)]
432	pub fn nested(&mut self, amount: Weight) -> Self {
433		Self::new(self.weight_left().min(amount), None)
434	}
435}