Expand description

Primitives for transaction weighting.

Every dispatchable function is responsible for providing #[weight = $x] attribute. In this snipped, $x can be any user provided struct that implements the following traits:

Substrate then bundles the output information of the three traits into DispatchInfo struct and provides it by implementing the GetDispatchInfo for all Call both inner and outer call types.

Substrate provides two pre-defined ways to annotate weight:

1. Fixed values

This can only be used when all 3 traits can be resolved statically. You have 3 degrees of configuration:

  1. Define only weight, in which case ClassifyDispatch will be Normal and PaysFee will be Yes.
frame_support::decl_module! {
    pub struct Module<T: Config> for enum Call where origin: T::Origin {
        #[weight = 1000]
        fn dispatching(origin) { unimplemented!() }
    }
}

2.1 Define weight and class, in which case PaysFee would be Yes.

frame_support::decl_module! {
    pub struct Module<T: Config> for enum Call where origin: T::Origin {
        #[weight = (1000, DispatchClass::Operational)]
        fn dispatching(origin) { unimplemented!() }
    }
}

2.2 Define weight and PaysFee, in which case ClassifyDispatch would be Normal.

frame_support::decl_module! {
    pub struct Module<T: Config> for enum Call where origin: T::Origin {
        #[weight = (1000, Pays::No)]
        fn dispatching(origin) { unimplemented!() }
    }
}
  1. Define all 3 parameters.
frame_support::decl_module! {
    pub struct Module<T: Config> for enum Call where origin: T::Origin {
        #[weight = (1000, DispatchClass::Operational, Pays::No)]
        fn dispatching(origin) { unimplemented!() }
    }
}

2. Define weights as a function of input arguments using FunctionOf tuple struct.

This struct works in a similar manner as above. 3 items must be provided and each can be either a fixed value or a function/closure with the same parameters list as the dispatchable function itself, wrapper in a tuple.

Using this only makes sense if you want to use a function for at least one of the elements. If all 3 are static values, providing a raw tuple is easier.

frame_support::decl_module! {
    pub struct Module<T: Config> for enum Call where origin: T::Origin {
        #[weight = FunctionOf(
			// weight, function.
			|args: (&u32, &u64)| *args.0 as u64 + args.1,
			// class, fixed.
			DispatchClass::Operational,
			// pays fee, function.
			|args: (&u32, &u64)| if *args.0 > 1000 { Pays::Yes } else { Pays::No },
		)]
        fn dispatching(origin, a: u32, b: u64) { unimplemented!() }
    }
}

FRAME assumes a weight of 1_000_000_000_000 equals 1 second of compute on a standard machine.

Latest machine specification used to benchmark are:

  • Digital Ocean: ubuntu-s-2vcpu-4gb-ams3-01
  • 2x Intel(R) Xeon(R) CPU E5-2650 v4 @ 2.20GHz
  • 4GB RAM
  • Ubuntu 19.10 (GNU/Linux 5.3.0-18-generic x86_64)
  • rustc 1.42.0 (b8cedc004 2020-03-09)

Modules

These constants are specific to FRAME, and the current implementation of its various components. For example: FRAME System, FRAME Executive, our FRAME support libraries, etc…

Structs

A bundle of static information collected from the #[weight = $x] attributes.

FunctionOfDeprecated

A struct to represent a weight which is a function of the input arguments. The given items have the following types:

Implementor of WeightToFeePolynomial that maps one unit of weight to one unit of fee.

A struct holding value for each DispatchClass.

Weight information that is only available post dispatch. NOTE: This can only be used to reduce the weight or fee, not increase it.

The weight of database operations that the runtime can invoke.

One coefficient and its position in the WeightToFeePolynomial.

Enums

A generalized group of dispatch types.

Explicit enum to denote if a transaction pays fee or not.

Traits

Means of classifying a dispatchable function.

A Dispatchable function (aka transaction) that can carry some static information along with it, using the #[weight] attribute.

A trait that represents one or many values of given type.

Indicates if dispatch function should pay fees or not. If set to Pays::No, the block resource limits are applied, yet no fee is deducted.

Means of weighing some particular kind of data (T).

A trait that describes the weight to fee calculation as polynomial.

Allows easy conversion from DispatchError to DispatchErrorWithPostInfo for dispatchables that want to return a custom a posterior weight on error.

Functions

Extract the actual weight from a dispatch result if any or fall back to the default weight.

Type Definitions

Re-export priority as type Priority for a transaction. Additive. Higher is better.

Numeric range of a transaction weight.

A list of coefficients that represent one polynomial.