Module frame_support::weights

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:

• WeighData: the weight amount.
• ClassifyDispatch: class of the dispatch.
• PaysFee: whether this weight should be translated to fee and deducted upon dispatch.

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!() }
    }
}

3. 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

constants

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

DispatchInfo

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:

IdentityFee

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

PerDispatchClass

A struct holding value for each DispatchClass.

PostDispatchInfo

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

RuntimeDbWeight

The weight of database operations that the runtime can invoke.

WeightToFeeCoefficient

One coefficient and its position in the WeightToFeePolynomial.

Enums

DispatchClass

A generalized group of dispatch types.

Pays

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

Traits

ClassifyDispatch

Means of classifying a dispatchable function.

GetDispatchInfo

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

OneOrMany

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

PaysFee

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.

WeighData

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

WeightToFeePolynomial

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

WithPostDispatchInfo

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

Functions

extract_actual_weight

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

Type Definitions

TransactionPriority

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

Weight

Numeric range of a transaction weight.

WeightToFeeCoefficients

A list of coefficients that represent one polynomial.