Struct frame_system::limits::BlockWeights

pub struct BlockWeights {
    pub base_block: Weight,
    pub max_block: Weight,
    pub per_class: PerDispatchClass<WeightsPerClass>,
}

Block weight limits & base values configuration.

This object is responsible for defining weight limits and base weight values tracked during extrinsic execution.

Each block starts with base_block weight being consumed right away. Next up the on_initialize pallet callbacks are invoked and their cost is added before any extrinsic is executed. This cost is tracked as Mandatory dispatch class.

|   | `max_block`    |   |
|   |                |   |
|   |                |   |
|   |                |   |
|   |                |  #| `on_initialize`
|  #| `base_block`   |  #|
|NOM|                |NOM|
 ||\_ Mandatory
 |\__ Operational
 \___ Normal

The remaining capacity can be used to dispatch extrinsics. Note that each dispatch class is being tracked separately, but the sum can’t exceed max_block (except for reserved). Below you can see a picture representing full block with 3 extrinsics (two Operational and one Normal). Each class has it’s own limit max_total, but also the sum cannot exceed max_block value.

                         -- `Mandatory` limit (unlimited)
| # |                 |   |
| # | `Ext3`          | - - `Operational` limit
|#  | `Ext2`          |-  - `Normal` limit
| # | `Ext1`          | # |
|  #| `on_initialize` | ##|
|  #| `base_block`    |###|
|NOM|                 |NOM|

It should be obvious now that it’s possible for one class to reach it’s limit (say Normal), while the block has still capacity to process more transactions (max_block not reached, Operational transactions can still go in). Setting max_total to None disables the per-class limit. This is generally highly recommended for Mandatory dispatch class, while it can be dangerous for Normal class and should only be done with extra care and consideration.

Often it’s desirable for some class of transactions to be added to the block despite it being full. For instance one might want to prevent high-priority Normal transactions from pushing out lower-priority Operational transactions. In such cases you might add a reserved capacity for given class.

             _
  #           \
  #   `Ext8`   - `reserved`
  #          _/
| # | `Ext7                 | - - `Operational` limit
|#  | `Ext6`                |   |
|#  | `Ext5`                |-# - `Normal` limit
|#  | `Ext4`                |## |
|  #| `on_initialize`       |###|
|  #| `base_block`          |###|
|NOM|                       |NOM|

In the above example, Ext4-6 fill up the block almost up to max_block. Ext7 would not fit if there wasn’t the extra reserved space for Operational transactions. Note that max_total limit applies to reserved space as well (i.e. the sum of weights of Ext7 & Ext8 mustn’t exceed it). Setting reserved to None allows the extrinsics to always get into the block up to their max_total limit. If max_total is set to None as well, all extrinsics witch dispatchables of given class will always end up in the block (recommended for Mandatory dispatch class).

As a consequence of reserved space, total consumed block weight might exceed max_block value, so this parameter should rather be thought of as “target block weight” than a hard limit.

Fields

base_block: Weight

Base weight of block execution.

max_block: Weight

Maximal total weight consumed by all kinds of extrinsics (without reserved space).

per_class: PerDispatchClass<WeightsPerClass>

Weight limits for extrinsics of given dispatch class.

Implementations

impl BlockWeights

pub fn get(&self, class: DispatchClass) -> &WeightsPerClass

Get per-class weight settings.

Examples found in repository

src/extensions/check_weight.rs (line 51)

	fn check_extrinsic_weight(
		info: &DispatchInfoOf<T::RuntimeCall>,
	) -> Result<(), TransactionValidityError> {
		let max = T::BlockWeights::get().get(info.class).max_extrinsic;
		match max {
			Some(max) if info.weight.any_gt(max) =>
				Err(InvalidTransaction::ExhaustsResources.into()),
			_ => Ok(()),
		}
	}

	/// Checks if the current extrinsic can fit into the block with respect to block weight limits.
	///
	/// Upon successes, it returns the new block weight as a `Result`.
	fn check_block_weight(
		info: &DispatchInfoOf<T::RuntimeCall>,
	) -> Result<crate::ConsumedWeight, TransactionValidityError> {
		let maximum_weight = T::BlockWeights::get();
		let all_weight = Pallet::<T>::block_weight();
		calculate_consumed_weight::<T::RuntimeCall>(maximum_weight, all_weight, info)
	}

	/// Checks if the current extrinsic can fit into the block with respect to block length limits.
	///
	/// Upon successes, it returns the new block length as a `Result`.
	fn check_block_length(
		info: &DispatchInfoOf<T::RuntimeCall>,
		len: usize,
	) -> Result<u32, TransactionValidityError> {
		let length_limit = T::BlockLength::get();
		let current_len = Pallet::<T>::all_extrinsics_len();
		let added_len = len as u32;
		let next_len = current_len.saturating_add(added_len);
		if next_len > *length_limit.max.get(info.class) {
			Err(InvalidTransaction::ExhaustsResources.into())
		} else {
			Ok(next_len)
		}
	}

	/// Creates new `SignedExtension` to check weight of the extrinsic.
	pub fn new() -> Self {
		Self(Default::default())
	}

	/// Do the pre-dispatch checks. This can be applied to both signed and unsigned.
	///
	/// It checks and notes the new weight and length.
	pub fn do_pre_dispatch(
		info: &DispatchInfoOf<T::RuntimeCall>,
		len: usize,
	) -> Result<(), TransactionValidityError> {
		let next_len = Self::check_block_length(info, len)?;
		let next_weight = Self::check_block_weight(info)?;
		Self::check_extrinsic_weight(info)?;

		crate::AllExtrinsicsLen::<T>::put(next_len);
		crate::BlockWeight::<T>::put(next_weight);
		Ok(())
	}

	/// Do the validate checks. This can be applied to both signed and unsigned.
	///
	/// It only checks that the block weight and length limit will not exceed.
	pub fn do_validate(info: &DispatchInfoOf<T::RuntimeCall>, len: usize) -> TransactionValidity {
		// ignore the next length. If they return `Ok`, then it is below the limit.
		let _ = Self::check_block_length(info, len)?;
		// during validation we skip block limit check. Since the `validate_transaction`
		// call runs on an empty block anyway, by this we prevent `on_initialize` weight
		// consumption from causing false negatives.
		Self::check_extrinsic_weight(info)?;

		Ok(Default::default())
	}
}

pub fn calculate_consumed_weight<Call>(
	maximum_weight: BlockWeights,
	mut all_weight: crate::ConsumedWeight,
	info: &DispatchInfoOf<Call>,
) -> Result<crate::ConsumedWeight, TransactionValidityError>
where
	Call: Dispatchable<Info = DispatchInfo, PostInfo = PostDispatchInfo>,
{
	let extrinsic_weight =
		info.weight.saturating_add(maximum_weight.get(info.class).base_extrinsic);
	let limit_per_class = maximum_weight.get(info.class);

	// add the weight. If class is unlimited, use saturating add instead of checked one.
	if limit_per_class.max_total.is_none() && limit_per_class.reserved.is_none() {
		all_weight.add(extrinsic_weight, info.class)
	} else {
		all_weight
			.checked_add(extrinsic_weight, info.class)
			.map_err(|_| InvalidTransaction::ExhaustsResources)?;
	}

	let per_class = *all_weight.get(info.class);

	// Check if we don't exceed per-class allowance
	match limit_per_class.max_total {
		Some(max) if per_class.any_gt(max) =>
			return Err(InvalidTransaction::ExhaustsResources.into()),
		// There is no `max_total` limit (`None`),
		// or we are below the limit.
		_ => {},
	}

	// In cases total block weight is exceeded, we need to fall back
	// to `reserved` pool if there is any.
	if all_weight.total().any_gt(maximum_weight.max_block) {
		match limit_per_class.reserved {
			// We are over the limit in reserved pool.
			Some(reserved) if per_class.any_gt(reserved) =>
				return Err(InvalidTransaction::ExhaustsResources.into()),
			// There is either no limit in reserved pool (`None`),
			// or we are below the limit.
			_ => {},
		}
	}

	Ok(all_weight)
}

src/lib.rs (line 1358)

	pub fn finalize() -> T::Header {
		log::debug!(
			target: "runtime::system",
			"[{:?}] {} extrinsics, length: {} (normal {}%, op: {}%, mandatory {}%) / normal weight:\
			 {} ({}%) op weight {} ({}%) / mandatory weight {} ({}%)",
			Self::block_number(),
			Self::extrinsic_index().unwrap_or_default(),
			Self::all_extrinsics_len(),
			sp_runtime::Percent::from_rational(
				Self::all_extrinsics_len(),
				*T::BlockLength::get().max.get(DispatchClass::Normal)
			).deconstruct(),
			sp_runtime::Percent::from_rational(
				Self::all_extrinsics_len(),
				*T::BlockLength::get().max.get(DispatchClass::Operational)
			).deconstruct(),
			sp_runtime::Percent::from_rational(
				Self::all_extrinsics_len(),
				*T::BlockLength::get().max.get(DispatchClass::Mandatory)
			).deconstruct(),
			Self::block_weight().get(DispatchClass::Normal),
			sp_runtime::Percent::from_rational(
				Self::block_weight().get(DispatchClass::Normal).ref_time(),
				T::BlockWeights::get().get(DispatchClass::Normal).max_total.unwrap_or(Bounded::max_value()).ref_time()
			).deconstruct(),
			Self::block_weight().get(DispatchClass::Operational),
			sp_runtime::Percent::from_rational(
				Self::block_weight().get(DispatchClass::Operational).ref_time(),
				T::BlockWeights::get().get(DispatchClass::Operational).max_total.unwrap_or(Bounded::max_value()).ref_time()
			).deconstruct(),
			Self::block_weight().get(DispatchClass::Mandatory),
			sp_runtime::Percent::from_rational(
				Self::block_weight().get(DispatchClass::Mandatory).ref_time(),
				T::BlockWeights::get().get(DispatchClass::Mandatory).max_total.unwrap_or(Bounded::max_value()).ref_time()
			).deconstruct(),
		);
		ExecutionPhase::<T>::kill();
		AllExtrinsicsLen::<T>::kill();

		// The following fields
		//
		// - <Events<T>>
		// - <EventCount<T>>
		// - <EventTopics<T>>
		// - <Number<T>>
		// - <ParentHash<T>>
		// - <Digest<T>>
		//
		// stay to be inspected by the client and will be cleared by `Self::initialize`.
		let number = <Number<T>>::get();
		let parent_hash = <ParentHash<T>>::get();
		let digest = <Digest<T>>::get();

		let extrinsics = (0..ExtrinsicCount::<T>::take().unwrap_or_default())
			.map(ExtrinsicData::<T>::take)
			.collect();
		let extrinsics_root = extrinsics_data_root::<T::Hashing>(extrinsics);

		// move block hash pruning window by one block
		let block_hash_count = T::BlockHashCount::get();
		let to_remove = number.saturating_sub(block_hash_count).saturating_sub(One::one());

		// keep genesis hash
		if !to_remove.is_zero() {
			<BlockHash<T>>::remove(to_remove);
		}

		let version = T::Version::get().state_version();
		let storage_root = T::Hash::decode(&mut &sp_io::storage::root(version)[..])
			.expect("Node is configured to use the same hash; qed");

		<T::Header as traits::Header>::new(
			number,
			extrinsics_root,
			storage_root,
			parent_hash,
			digest,
		)
	}

	/// Deposits a log and ensures it matches the block's log data.
	///
	/// # <weight>
	/// - `O(1)`
	/// - 1 storage write (codec `O(1)`)
	/// # </weight>
	pub fn deposit_log(item: generic::DigestItem) {
		<Digest<T>>::append(item);
	}

	/// Get the basic externalities for this pallet, useful for tests.
	#[cfg(any(feature = "std", test))]
	pub fn externalities() -> TestExternalities {
		TestExternalities::new(sp_core::storage::Storage {
			top: map![
				<BlockHash<T>>::hashed_key_for(T::BlockNumber::zero()) => [69u8; 32].encode(),
				<Number<T>>::hashed_key().to_vec() => T::BlockNumber::one().encode(),
				<ParentHash<T>>::hashed_key().to_vec() => [69u8; 32].encode()
			],
			children_default: map![],
		})
	}

	/// Get the current events deposited by the runtime.
	///
	/// NOTE: This should only be used in tests. Reading events from the runtime can have a large
	/// impact on the PoV size of a block. Users should use alternative and well bounded storage
	/// items for any behavior like this.
	#[cfg(any(feature = "std", feature = "runtime-benchmarks", test))]
	pub fn events() -> Vec<EventRecord<T::RuntimeEvent, T::Hash>> {
		// Dereferencing the events here is fine since we are not in the
		// memory-restricted runtime.
		Self::read_events_no_consensus().map(|e| *e).collect()
	}

	/// Get the current events deposited by the runtime.
	///
	/// Should only be called if you know what you are doing and outside of the runtime block
	/// execution else it can have a large impact on the PoV size of a block.
	pub fn read_events_no_consensus(
	) -> impl sp_std::iter::Iterator<Item = Box<EventRecord<T::RuntimeEvent, T::Hash>>> {
		Events::<T>::stream_iter()
	}

	/// Set the block number to something in particular. Can be used as an alternative to
	/// `initialize` for tests that don't need to bother with the other environment entries.
	#[cfg(any(feature = "std", feature = "runtime-benchmarks", test))]
	pub fn set_block_number(n: T::BlockNumber) {
		<Number<T>>::put(n);
	}

	/// Sets the index of extrinsic that is currently executing.
	#[cfg(any(feature = "std", test))]
	pub fn set_extrinsic_index(extrinsic_index: u32) {
		storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &extrinsic_index)
	}

	/// Set the parent hash number to something in particular. Can be used as an alternative to
	/// `initialize` for tests that don't need to bother with the other environment entries.
	#[cfg(any(feature = "std", test))]
	pub fn set_parent_hash(n: T::Hash) {
		<ParentHash<T>>::put(n);
	}

	/// Set the current block weight. This should only be used in some integration tests.
	#[cfg(any(feature = "std", test))]
	pub fn set_block_consumed_resources(weight: Weight, len: usize) {
		BlockWeight::<T>::mutate(|current_weight| {
			current_weight.set(weight, DispatchClass::Normal)
		});
		AllExtrinsicsLen::<T>::put(len as u32);
	}

	/// Reset events.
	///
	/// This needs to be used in prior calling [`initialize`](Self::initialize) for each new block
	/// to clear events from previous block.
	pub fn reset_events() {
		<Events<T>>::kill();
		EventCount::<T>::kill();
		let _ = <EventTopics<T>>::clear(u32::max_value(), None);
	}

	/// Assert the given `event` exists.
	#[cfg(any(feature = "std", feature = "runtime-benchmarks", test))]
	pub fn assert_has_event(event: T::RuntimeEvent) {
		assert!(Self::events().iter().any(|record| record.event == event))
	}

	/// Assert the last event equal to the given `event`.
	#[cfg(any(feature = "std", feature = "runtime-benchmarks", test))]
	pub fn assert_last_event(event: T::RuntimeEvent) {
		assert_eq!(Self::events().last().expect("events expected").event, event);
	}

	/// Return the chain's current runtime version.
	pub fn runtime_version() -> RuntimeVersion {
		T::Version::get()
	}

	/// Retrieve the account transaction counter from storage.
	pub fn account_nonce(who: impl EncodeLike<T::AccountId>) -> T::Index {
		Account::<T>::get(who).nonce
	}

	/// Increment a particular account's nonce by 1.
	pub fn inc_account_nonce(who: impl EncodeLike<T::AccountId>) {
		Account::<T>::mutate(who, |a| a.nonce += T::Index::one());
	}

	/// Note what the extrinsic data of the current extrinsic index is.
	///
	/// This is required to be called before applying an extrinsic. The data will used
	/// in [`Self::finalize`] to calculate the correct extrinsics root.
	pub fn note_extrinsic(encoded_xt: Vec<u8>) {
		ExtrinsicData::<T>::insert(Self::extrinsic_index().unwrap_or_default(), encoded_xt);
	}

	/// To be called immediately after an extrinsic has been applied.
	///
	/// Emits an `ExtrinsicSuccess` or `ExtrinsicFailed` event depending on the outcome.
	/// The emitted event contains the post-dispatch corrected weight including
	/// the base-weight for its dispatch class.
	pub fn note_applied_extrinsic(r: &DispatchResultWithPostInfo, mut info: DispatchInfo) {
		info.weight = extract_actual_weight(r, &info)
			.saturating_add(T::BlockWeights::get().get(info.class).base_extrinsic);
		info.pays_fee = extract_actual_pays_fee(r, &info);

		Self::deposit_event(match r {
			Ok(_) => Event::ExtrinsicSuccess { dispatch_info: info },
			Err(err) => {
				log::trace!(
					target: "runtime::system",
					"Extrinsic failed at block({:?}): {:?}",
					Self::block_number(),
					err,
				);
				Event::ExtrinsicFailed { dispatch_error: err.error, dispatch_info: info }
			},
		});

		let next_extrinsic_index = Self::extrinsic_index().unwrap_or_default() + 1u32;

		storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &next_extrinsic_index);
		ExecutionPhase::<T>::put(Phase::ApplyExtrinsic(next_extrinsic_index));
	}

pub fn validate(self) -> ValidationResult

Verifies correctness of this BlockWeights object.

Examples found in repository

src/lib.rs (line 364)

		fn integrity_test() {
			T::BlockWeights::get().validate().expect("The weights are invalid.");
		}

src/limits.rs (line 429)

	pub fn build(self) -> ValidationResult {
		// compute max extrinsic size
		let Self { mut weights, init_cost } = self;

		// compute max block size.
		for class in DispatchClass::all() {
			weights.max_block = match weights.per_class.get(*class).max_total {
				Some(max) => max.max(weights.max_block),
				_ => weights.max_block,
			};
		}
		// compute max size of single extrinsic
		if let Some(init_weight) = init_cost.map(|rate| rate * weights.max_block) {
			for class in DispatchClass::all() {
				let per_class = weights.per_class.get_mut(*class);
				if per_class.max_extrinsic.is_none() && init_cost.is_some() {
					per_class.max_extrinsic = per_class
						.max_total
						.map(|x| x.saturating_sub(init_weight))
						.map(|x| x.saturating_sub(per_class.base_extrinsic));
				}
			}
		}

		// Validate the result
		weights.validate()
	}

pub fn simple_max(block_weight: Weight) -> Self

Create new weights definition, with both Normal and Operational classes limited to given weight.

Note there is no reservation for Operational class, so this constructor is not suitable for production deployments.

pub fn with_sensible_defaults(
    expected_block_weight: Weight,
    normal_ratio: Perbill
) -> Self

Create a sensible default weights system given only expected maximal block weight and the ratio that Normal extrinsics should occupy.

Assumptions:

• Average block initialization is assumed to be 10%.
• Operational transactions have reserved allowance (1.0 - normal_ratio)

Examples found in repository

src/limits.rs (lines 210-213)

	fn default() -> Self {
		Self::with_sensible_defaults(
			Weight::from_parts(constants::WEIGHT_REF_TIME_PER_SECOND, u64::MAX),
			DEFAULT_NORMAL_RATIO,
		)
	}

pub fn builder() -> BlockWeightsBuilder

Start constructing new BlockWeights object.

By default all kinds except of Mandatory extrinsics are disallowed.

Examples found in repository

src/limits.rs (line 305)

	pub fn simple_max(block_weight: Weight) -> Self {
		Self::builder()
			.base_block(Weight::zero())
			.for_class(DispatchClass::all(), |weights| {
				weights.base_extrinsic = Weight::zero();
			})
			.for_class(DispatchClass::non_mandatory(), |weights| {
				weights.max_total = block_weight.into();
			})
			.build()
			.expect("We only specify max_total and leave base values as defaults; qed")
	}

	/// Create a sensible default weights system given only expected maximal block weight and the
	/// ratio that `Normal` extrinsics should occupy.
	///
	/// Assumptions:
	///  - Average block initialization is assumed to be `10%`.
	///  - `Operational` transactions have reserved allowance (`1.0 - normal_ratio`)
	pub fn with_sensible_defaults(expected_block_weight: Weight, normal_ratio: Perbill) -> Self {
		let normal_weight = normal_ratio * expected_block_weight;
		Self::builder()
			.for_class(DispatchClass::Normal, |weights| {
				weights.max_total = normal_weight.into();
			})
			.for_class(DispatchClass::Operational, |weights| {
				weights.max_total = expected_block_weight.into();
				weights.reserved = (expected_block_weight - normal_weight).into();
			})
			.avg_block_initialization(Perbill::from_percent(10))
			.build()
			.expect("Sensible defaults are tested to be valid; qed")
	}

Trait Implementations

impl Clone for BlockWeights

fn clone(&self) -> BlockWeights

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlockWeights

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Decode for BlockWeights

fn decode<__CodecInputEdqy: Input>(
    __codec_input_edqy: &mut __CodecInputEdqy
) -> Result<Self, Error>

Attempt to deserialise the value from input.

fn skip<I>(input: &mut I) -> Result<(), Error>where
    I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl Default for BlockWeights

fn default() -> Self

Returns the “default value” for a type.

impl Encode for BlockWeights

fn encode_to<__CodecOutputEdqy: Output + ?Sized>(
    &self,
    __codec_dest_edqy: &mut __CodecOutputEdqy
)

Convert self to a slice and append it to the destination.

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode(&self) -> Vec<u8, Global>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> Rwhere
    F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl TypeInfo for BlockWeights

type Identity = BlockWeights

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl EncodeLike<BlockWeights> for BlockWeights