referrerpolicy=no-referrer-when-downgrade

sp_inherents/
lib.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//! Substrate Inherent Extrinsics
19//!
20//! Inherent extrinsics are extrinsics that are inherently added to each block. However, it is up to
21//! the runtime implementation to require an inherent for each block or to make it optional.
22//! Inherents are mainly used to pass data from the block producer to the runtime. So, inherents
23//! require some part that is running on the client side and some part that is running on the
24//! runtime side. Any data that is required by an inherent is passed as [`InherentData`] from the
25//! client to the runtime when the inherents are constructed.
26//!
27//! The process of constructing and applying inherents is the following:
28//!
29//! 1. The block producer first creates the [`InherentData`] by using the inherent data providers
30//! that are created by [`CreateInherentDataProviders`].
31//!
32//! 2. The [`InherentData`] is passed to the `inherent_extrinsics` function of the `BlockBuilder`
33//! runtime api. This will call the runtime which will create all the inherents that should be
34//! applied to the block.
35//!
36//! 3. Apply each inherent to the block like any normal extrinsic.
37//!
38//! On block import the inherents in the block are checked by calling the `check_inherents` runtime
39//! API. This will also pass an instance of [`InherentData`] which the runtime can use to validate
40//! all inherents. If some inherent data isn't required for validating an inherent, it can be
41//! omitted when providing the inherent data providers for block import.
42//!
43//! # Providing inherent data
44//!
45//! To provide inherent data from the client side, [`InherentDataProvider`] should be implemented.
46//!
47//! ```
48//! use codec::Decode;
49//! use sp_inherents::{InherentIdentifier, InherentData};
50//!
51//! // This needs to be unique for the runtime.
52//! const INHERENT_IDENTIFIER: InherentIdentifier = *b"testinh0";
53//!
54//! /// Some custom inherent data provider
55//! struct InherentDataProvider;
56//!
57//! #[async_trait::async_trait]
58//! impl sp_inherents::InherentDataProvider for InherentDataProvider {
59//! 	async fn provide_inherent_data(
60//! 		&self,
61//! 		inherent_data: &mut InherentData,
62//! 	) -> Result<(), sp_inherents::Error> {
63//! 		// We can insert any data that implements [`codec::Encode`].
64//! 		inherent_data.put_data(INHERENT_IDENTIFIER, &"hello")
65//! 	}
66//!
67//! 	/// When validating the inherents, the runtime implementation can throw errors. We support
68//! 	/// two error modes, fatal and non-fatal errors. A fatal error means that the block is invalid
69//! 	/// and this function here should return `Err(_)` to not import the block. Non-fatal errors
70//! 	/// are allowed to be handled here in this function and the function should return `Ok(())`
71//! 	/// if it could be handled. A non-fatal error is for example that a block is in the future
72//! 	/// from the point of view of the local node. In such a case the block import for example
73//! 	/// should be delayed until the block is valid.
74//! 	///
75//! 	/// If this functions returns `None`, it means that it is not responsible for this error or
76//! 	/// that the error could not be interpreted.
77//! 	async fn try_handle_error(
78//! 		&self,
79//! 		identifier: &InherentIdentifier,
80//! 		mut error: &[u8],
81//! 	) -> Option<Result<(), sp_inherents::Error>> {
82//! 		// Check if this error belongs to us.
83//! 		if *identifier != INHERENT_IDENTIFIER {
84//! 			return None;
85//! 		}
86//!
87//! 		// For demonstration purposes we are using a `String` as error type. In real
88//! 		// implementations it is advised to not use `String`.
89//! 		Some(Err(
90//! 			sp_inherents::Error::Application(Box::from(String::decode(&mut error).ok()?))
91//! 		))
92//! 	}
93//! }
94//! ```
95//!
96//! In the service the relevant inherent data providers need to be passed the block production and
97//! the block import. As already highlighted above, the providers can be different between import
98//! and production.
99//!
100//! ```
101//! # use sp_runtime::testing::{MockCallU64, TestXt};
102//! # use sp_inherents::{InherentIdentifier, InherentData};
103//! # use futures::FutureExt;
104//! # type Block = sp_runtime::testing::Block<TestXt<MockCallU64, ()>>;
105//! # const INHERENT_IDENTIFIER: InherentIdentifier = *b"testinh0";
106//! # struct InherentDataProvider;
107//! # #[async_trait::async_trait]
108//! # impl sp_inherents::InherentDataProvider for InherentDataProvider {
109//! # 	async fn provide_inherent_data(&self, inherent_data: &mut InherentData) -> Result<(), sp_inherents::Error> {
110//! # 		inherent_data.put_data(INHERENT_IDENTIFIER, &"hello")
111//! # 	}
112//! # 	async fn try_handle_error(
113//! # 		&self,
114//! # 		_: &InherentIdentifier,
115//! # 		_: &[u8],
116//! # 	) -> Option<Result<(), sp_inherents::Error>> {
117//! # 		None
118//! # 	}
119//! # }
120//!
121//! async fn cool_consensus_block_production(
122//! 	// The second parameter to the trait are parameters that depend on what the caller
123//! 	// can provide on extra data.
124//! 	_: impl sp_inherents::CreateInherentDataProviders<Block, ()>,
125//! ) {
126//! 	// do cool stuff
127//! }
128//!
129//! async fn cool_consensus_block_import(
130//! 	_: impl sp_inherents::CreateInherentDataProviders<Block, ()>,
131//! ) {
132//! 	// do cool stuff
133//! }
134//!
135//! async fn build_service(is_validator: bool) {
136//! 	// For block import we don't pass any inherent data provider, because our runtime
137//! 	// does not need any inherent data to validate the inherents.
138//! 	let block_import = cool_consensus_block_import(|_parent, ()| async { Ok(()) });
139//!
140//! 	let block_production = if is_validator {
141//! 		// For block production we want to provide our inherent data provider
142//! 		cool_consensus_block_production(|_parent, ()| async {
143//! 			Ok(InherentDataProvider)
144//! 		}).boxed()
145//! 	} else {
146//! 		futures::future::pending().boxed()
147//! 	};
148//!
149//! 	futures::pin_mut!(block_import);
150//!
151//! 	futures::future::select(block_import, block_production).await;
152//! }
153//! ```
154//!
155//! # Creating the inherent
156//!
157//! As the inherents are created by the runtime, it depends on the runtime implementation on how
158//! to create the inherents. As already described above the client side passes the [`InherentData`]
159//! and expects the runtime to construct the inherents out of it. When validating the inherents,
160//! [`CheckInherentsResult`] is used to communicate the result client side.
161
162#![cfg_attr(not(feature = "std"), no_std)]
163#![warn(missing_docs)]
164
165extern crate alloc;
166
167use codec::{Decode, Encode};
168
169use alloc::{
170	collections::btree_map::{BTreeMap, Entry, IntoIter},
171	vec::Vec,
172};
173
174#[cfg(feature = "std")]
175mod client_side;
176
177#[cfg(feature = "std")]
178pub use client_side::*;
179
180/// Errors that occur in context of inherents.
181#[derive(Debug)]
182#[cfg_attr(feature = "std", derive(thiserror::Error))]
183#[allow(missing_docs)]
184pub enum Error {
185	#[cfg_attr(
186		feature = "std",
187		error("Inherent data already exists for identifier: {}", "String::from_utf8_lossy(_0)")
188	)]
189	InherentDataExists(InherentIdentifier),
190	#[cfg_attr(
191		feature = "std",
192		error("Failed to decode inherent data for identifier: {}", "String::from_utf8_lossy(_1)")
193	)]
194	DecodingFailed(#[cfg_attr(feature = "std", source)] codec::Error, InherentIdentifier),
195	#[cfg_attr(
196		feature = "std",
197		error("There was already a fatal error reported and no other errors are allowed")
198	)]
199	FatalErrorReported,
200	#[cfg(feature = "std")]
201	#[error(transparent)]
202	Application(#[from] Box<dyn std::error::Error + Send + Sync>),
203}
204
205/// An identifier for an inherent.
206pub type InherentIdentifier = [u8; 8];
207
208/// Inherent data to include in a block.
209#[derive(Clone, Default, Encode, Decode, scale_info::TypeInfo)]
210pub struct InherentData {
211	/// All inherent data encoded with parity-scale-codec and an identifier.
212	data: BTreeMap<InherentIdentifier, Vec<u8>>,
213}
214
215impl InherentData {
216	/// Create a new instance.
217	pub fn new() -> Self {
218		Self::default()
219	}
220
221	/// Put data for an inherent into the internal storage.
222	///
223	/// # Return
224	///
225	/// Returns `Ok(())` if the data could be inserted and no data for an inherent with the same
226	/// identifier existed, otherwise an error is returned.
227	///
228	/// Inherent identifiers need to be unique, otherwise decoding of these values will not work!
229	pub fn put_data<I: codec::Encode>(
230		&mut self,
231		identifier: InherentIdentifier,
232		inherent: &I,
233	) -> Result<(), Error> {
234		match self.data.entry(identifier) {
235			Entry::Vacant(entry) => {
236				entry.insert(inherent.encode());
237				Ok(())
238			},
239			Entry::Occupied(_) => Err(Error::InherentDataExists(identifier)),
240		}
241	}
242
243	/// Replace the data for an inherent.
244	///
245	/// If it does not exist, the data is just inserted.
246	pub fn replace_data<I: codec::Encode>(&mut self, identifier: InherentIdentifier, inherent: &I) {
247		self.data.insert(identifier, inherent.encode());
248	}
249
250	/// Returns the data for the requested inherent.
251	///
252	/// # Return
253	///
254	/// - `Ok(Some(I))` if the data could be found and deserialized.
255	/// - `Ok(None)` if the data could not be found.
256	/// - `Err(_)` if the data could be found, but deserialization did not work.
257	pub fn get_data<I: codec::Decode>(
258		&self,
259		identifier: &InherentIdentifier,
260	) -> Result<Option<I>, Error> {
261		match self.data.get(identifier) {
262			Some(inherent) => I::decode(&mut &inherent[..])
263				.map_err(|e| Error::DecodingFailed(e, *identifier))
264				.map(Some),
265			None => Ok(None),
266		}
267	}
268
269	/// Get the number of inherents in this instance
270	pub fn len(&self) -> usize {
271		self.data.len()
272	}
273
274	/// Get the identifiers of stored inherent data
275	pub fn identifiers(&self) -> impl Iterator<Item = &InherentIdentifier> {
276		self.data.keys()
277	}
278}
279
280/// The result of checking inherents.
281///
282/// It either returns okay for all checks, stores all occurred errors or just one fatal error.
283///
284/// When a fatal error occurs, all other errors are removed and the implementation needs to
285/// abort checking inherents.
286#[derive(Encode, Decode, Clone, scale_info::TypeInfo)]
287pub struct CheckInherentsResult {
288	/// Did the check succeed?
289	okay: bool,
290	/// Did we encounter a fatal error?
291	fatal_error: bool,
292	/// We use the `InherentData` to store our errors.
293	errors: InherentData,
294}
295
296impl Default for CheckInherentsResult {
297	fn default() -> Self {
298		Self { okay: true, errors: InherentData::new(), fatal_error: false }
299	}
300}
301
302impl CheckInherentsResult {
303	/// Create a new instance.
304	pub fn new() -> Self {
305		Self::default()
306	}
307
308	/// Put an error into the result.
309	///
310	/// This makes this result resolve to `ok() == false`.
311	///
312	/// # Parameters
313	///
314	/// - identifier - The identifier of the inherent that generated the error.
315	/// - error - The error that will be encoded.
316	pub fn put_error<E: codec::Encode + IsFatalError>(
317		&mut self,
318		identifier: InherentIdentifier,
319		error: &E,
320	) -> Result<(), Error> {
321		// Don't accept any other error
322		if self.fatal_error {
323			return Err(Error::FatalErrorReported)
324		}
325
326		self.okay = false;
327		if error.is_fatal_error() {
328			self.fatal_error = true;
329			// remove the other errors.
330			self.errors.data.clear();
331		}
332		self.errors.put_data(identifier, error)?;
333
334		Ok(())
335	}
336
337	/// Get an error out of the result.
338	///
339	/// # Return
340	///
341	/// - `Ok(Some(I))` if the error could be found and deserialized.
342	/// - `Ok(None)` if the error could not be found.
343	/// - `Err(_)` if the error could be found, but deserialization did not work.
344	pub fn get_error<E: codec::Decode>(
345		&self,
346		identifier: &InherentIdentifier,
347	) -> Result<Option<E>, Error> {
348		self.errors.get_data(identifier)
349	}
350
351	/// Convert into an iterator over all contained errors.
352	pub fn into_errors(self) -> IntoIter<InherentIdentifier, Vec<u8>> {
353		self.errors.data.into_iter()
354	}
355
356	/// Is this result ok?
357	pub fn ok(&self) -> bool {
358		self.okay
359	}
360
361	/// Is this a fatal error?
362	pub fn fatal_error(&self) -> bool {
363		self.fatal_error
364	}
365}
366
367#[cfg(feature = "std")]
368impl PartialEq for CheckInherentsResult {
369	fn eq(&self, other: &Self) -> bool {
370		self.fatal_error == other.fatal_error &&
371			self.okay == other.okay &&
372			self.errors.data == other.errors.data
373	}
374}
375
376/// Did we encounter a fatal error while checking an inherent?
377///
378/// A fatal error is everything that fails while checking an inherent error, e.g. the inherent
379/// was not found, could not be decoded etc.
380/// Then there are cases where you not want the inherent check to fail, but report that there is an
381/// action required. For example a timestamp of a block is in the future, the timestamp is still
382/// correct, but it is required to verify the block at a later time again and then the inherent
383/// check will succeed.
384pub trait IsFatalError {
385	/// Is this a fatal error?
386	fn is_fatal_error(&self) -> bool;
387}
388
389/// Auxiliary to make any given error resolve to `is_fatal_error() == true` for [`IsFatalError`].
390#[derive(codec::Encode)]
391pub struct MakeFatalError<E>(E);
392
393impl<E: codec::Encode> From<E> for MakeFatalError<E> {
394	fn from(err: E) -> Self {
395		MakeFatalError(err)
396	}
397}
398
399impl<E: codec::Encode> IsFatalError for MakeFatalError<E> {
400	fn is_fatal_error(&self) -> bool {
401		true
402	}
403}
404
405#[cfg(test)]
406mod tests {
407	use super::*;
408	use codec::{Decode, Encode};
409
410	const TEST_INHERENT_0: InherentIdentifier = *b"testinh0";
411	const TEST_INHERENT_1: InherentIdentifier = *b"testinh1";
412
413	#[derive(Encode)]
414	struct NoFatalError<E: codec::Encode>(E);
415	impl<E: codec::Encode> IsFatalError for NoFatalError<E> {
416		fn is_fatal_error(&self) -> bool {
417			false
418		}
419	}
420
421	#[test]
422	fn inherent_data_encodes_and_decodes() {
423		let inherent_0 = vec![1, 2, 3];
424		let inherent_1: u32 = 7;
425
426		let mut data = InherentData::new();
427		data.put_data(TEST_INHERENT_0, &inherent_0).unwrap();
428		data.put_data(TEST_INHERENT_1, &inherent_1).unwrap();
429
430		let encoded = data.encode();
431
432		let decoded = InherentData::decode(&mut &encoded[..]).unwrap();
433
434		assert_eq!(decoded.get_data::<Vec<u32>>(&TEST_INHERENT_0).unwrap().unwrap(), inherent_0);
435		assert_eq!(decoded.get_data::<u32>(&TEST_INHERENT_1).unwrap().unwrap(), inherent_1);
436	}
437
438	#[test]
439	fn adding_same_inherent_returns_an_error() {
440		let mut data = InherentData::new();
441		data.put_data(TEST_INHERENT_0, &8).unwrap();
442		assert!(data.put_data(TEST_INHERENT_0, &10).is_err());
443	}
444
445	#[derive(Clone)]
446	struct TestInherentDataProvider;
447
448	const ERROR_TO_STRING: &str = "Found error!";
449
450	#[async_trait::async_trait]
451	impl InherentDataProvider for TestInherentDataProvider {
452		async fn provide_inherent_data(&self, data: &mut InherentData) -> Result<(), Error> {
453			data.put_data(TEST_INHERENT_0, &42)
454		}
455
456		async fn try_handle_error(
457			&self,
458			_: &InherentIdentifier,
459			_: &[u8],
460		) -> Option<Result<(), Error>> {
461			Some(Err(Error::Application(Box::from(ERROR_TO_STRING))))
462		}
463	}
464
465	#[test]
466	fn create_inherent_data() {
467		let provider = TestInherentDataProvider;
468
469		let inherent_data = futures::executor::block_on(provider.create_inherent_data()).unwrap();
470
471		assert_eq!(inherent_data.get_data::<u32>(&TEST_INHERENT_0).unwrap().unwrap(), 42u32);
472	}
473
474	#[test]
475	fn check_inherents_result_encodes_and_decodes() {
476		let mut result = CheckInherentsResult::new();
477		assert!(result.ok());
478
479		result.put_error(TEST_INHERENT_0, &NoFatalError(2u32)).unwrap();
480		assert!(!result.ok());
481		assert!(!result.fatal_error());
482
483		let encoded = result.encode();
484
485		let decoded = CheckInherentsResult::decode(&mut &encoded[..]).unwrap();
486
487		assert_eq!(decoded.get_error::<u32>(&TEST_INHERENT_0).unwrap().unwrap(), 2);
488		assert!(!decoded.ok());
489		assert!(!decoded.fatal_error());
490	}
491
492	#[test]
493	fn check_inherents_result_removes_other_errors_on_fatal_error() {
494		let mut result = CheckInherentsResult::new();
495		assert!(result.ok());
496
497		result.put_error(TEST_INHERENT_0, &NoFatalError(2u32)).unwrap();
498		assert!(!result.ok());
499		assert!(!result.fatal_error());
500
501		result.put_error(TEST_INHERENT_1, &MakeFatalError(4u32)).unwrap();
502		assert!(!result.ok());
503		assert!(result.fatal_error());
504
505		assert!(result.put_error(TEST_INHERENT_0, &NoFatalError(5u32)).is_err());
506
507		result.into_errors().for_each(|(i, e)| match i {
508			TEST_INHERENT_1 => assert_eq!(u32::decode(&mut &e[..]).unwrap(), 4),
509			_ => panic!("There should be no other error!"),
510		});
511	}
512}