frame_support/
inherent.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
18pub use sp_inherents::{
19	CheckInherentsResult, InherentData, InherentIdentifier, IsFatalError, MakeFatalError,
20};
21
22/// A pallet that provides or verifies an inherent extrinsic will implement this trait.
23///
24/// The pallet may provide an inherent, verify an inherent, or both provide and verify.
25///
26/// Briefly, inherent extrinsics ("inherents") are extrinsics that are added to a block by the block
27/// producer. See [`sp_inherents`] for more documentation on inherents.
28pub trait ProvideInherent {
29	/// The call type of the pallet.
30	type Call;
31	/// The error returned by `check_inherent`.
32	type Error: codec::Encode + IsFatalError;
33	/// The inherent identifier used by this inherent.
34	const INHERENT_IDENTIFIER: self::InherentIdentifier;
35
36	/// Create an inherent out of the given `InherentData`.
37	///
38	/// NOTE: All checks necessary to ensure that the inherent is correct and that can be done in
39	/// the runtime should happen in the returned `Call`.
40	/// E.g. if this provides the timestamp, the call will check that the given timestamp is
41	/// increasing the old timestamp by more than a minimum and it will also check that the
42	/// timestamp hasn't already been set in the current block.
43	fn create_inherent(data: &InherentData) -> Option<Self::Call>;
44
45	/// Determines whether this inherent is required in this block.
46	///
47	/// - `Ok(None)` indicates that this inherent is not required in this block. The default
48	/// implementation returns this.
49	///
50	/// - `Ok(Some(e))` indicates that this inherent is required in this block. `construct_runtime!`
51	/// will call this function in its implementation of `fn check_extrinsics`.
52	/// If the inherent is not present, it will return `e`.
53	///
54	/// - `Err(_)` indicates that this function failed and further operations should be aborted.
55	///
56	/// NOTE: If the inherent is required then the runtime asserts that the block contains at least
57	/// one inherent for which:
58	/// * type is [`Self::Call`],
59	/// * [`Self::is_inherent`] returns true.
60	///
61	/// NOTE: This is currently only checked by block producers, not all full nodes.
62	fn is_inherent_required(_: &InherentData) -> Result<Option<Self::Error>, Self::Error> {
63		Ok(None)
64	}
65
66	/// Check whether the given inherent is valid. Checking the inherent is optional and can be
67	/// omitted by using the default implementation.
68	///
69	/// When checking an inherent, the first parameter represents the inherent that is actually
70	/// included in the block by its author. Whereas the second parameter represents the inherent
71	/// data that the verifying node calculates.
72	///
73	/// This is intended to allow for checks that cannot be done within the runtime such as, e.g.,
74	/// the timestamp.
75	///
76	/// # Warning
77	///
78	/// This check is not guaranteed to be run by all full nodes and cannot be relied upon for
79	/// ensuring that the block is correct.
80	fn check_inherent(_: &Self::Call, _: &InherentData) -> Result<(), Self::Error> {
81		Ok(())
82	}
83
84	/// Return whether the call is an inherent call.
85	///
86	/// NOTE: Signed extrinsics are not inherents, but a signed extrinsic with the given call
87	/// variant can be dispatched.
88	///
89	/// # Warning
90	///
91	/// In FRAME, inherents are enforced to be executed before other extrinsics. For this reason,
92	/// pallets with unsigned transactions **must ensure** that no unsigned transaction call
93	/// is an inherent call, when implementing `ValidateUnsigned::validate_unsigned`.
94	/// Otherwise block producers can produce invalid blocks by including them after non inherents.
95	fn is_inherent(call: &Self::Call) -> bool;
96}
frame_support/inherent.rs

frame_support/
inherent.rs
