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}