referrerpolicy=no-referrer-when-downgrade

bp_runtime/
lib.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Parity Bridges Common.
3
4// Parity Bridges Common is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Parity Bridges Common is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
16
17//! Primitives that may be used at (bridges) runtime level.
18
19#![warn(missing_docs)]
20#![cfg_attr(not(feature = "std"), no_std)]
21
22use codec::{Decode, DecodeWithMemTracking, Encode, FullCodec, MaxEncodedLen};
23use frame_support::{
24	pallet_prelude::DispatchResult, weights::Weight, PalletError, StorageHasher, StorageValue,
25};
26use frame_system::RawOrigin;
27use scale_info::TypeInfo;
28use serde::{Deserialize, Serialize};
29use sp_core::storage::StorageKey;
30use sp_runtime::{
31	traits::{BadOrigin, Header as HeaderT, UniqueSaturatedInto},
32	RuntimeDebug,
33};
34use sp_std::{fmt::Debug, ops::RangeInclusive, vec, vec::Vec};
35
36pub use chain::{
37	AccountIdOf, AccountPublicOf, BalanceOf, BlockNumberOf, Chain, EncodedOrDecodedCall, HashOf,
38	HasherOf, HeaderOf, NonceOf, Parachain, ParachainIdOf, SignatureOf, TransactionEraOf,
39	UnderlyingChainOf, UnderlyingChainProvider, __private,
40};
41pub use frame_support::storage::storage_prefix as storage_value_final_key;
42use num_traits::{CheckedAdd, CheckedSub, One, SaturatingAdd, Zero};
43#[cfg(feature = "std")]
44pub use storage_proof::craft_valid_storage_proof;
45#[cfg(feature = "test-helpers")]
46pub use storage_proof::{
47	grow_storage_proof, grow_storage_value, record_all_keys as record_all_trie_keys,
48	UnverifiedStorageProofParams,
49};
50pub use storage_proof::{
51	raw_storage_proof_size, RawStorageProof, StorageProofChecker, StorageProofError,
52};
53pub use storage_types::BoundedStorageValue;
54
55extern crate alloc;
56
57pub mod extensions;
58pub mod messages;
59
60mod chain;
61mod storage_proof;
62mod storage_types;
63
64// Re-export macro to avoid include paste dependency everywhere
65pub use sp_runtime::paste;
66
67// Re-export for usage in macro.
68#[doc(hidden)]
69pub mod private {
70	#[doc(hidden)]
71	pub use alloc::vec::Vec;
72}
73
74/// Use this when something must be shared among all instances.
75pub const NO_INSTANCE_ID: ChainId = [0, 0, 0, 0];
76
77/// Generic header Id.
78#[derive(
79	RuntimeDebug,
80	Default,
81	Clone,
82	Encode,
83	Decode,
84	Copy,
85	Eq,
86	Hash,
87	MaxEncodedLen,
88	PartialEq,
89	PartialOrd,
90	Ord,
91	TypeInfo,
92)]
93pub struct HeaderId<Hash, Number>(pub Number, pub Hash);
94
95impl<Hash: Copy, Number: Copy> HeaderId<Hash, Number> {
96	/// Return header number.
97	pub fn number(&self) -> Number {
98		self.0
99	}
100
101	/// Return header hash.
102	pub fn hash(&self) -> Hash {
103		self.1
104	}
105}
106
107/// Header id used by the chain.
108pub type HeaderIdOf<C> = HeaderId<HashOf<C>, BlockNumberOf<C>>;
109
110/// Generic header id provider.
111pub trait HeaderIdProvider<Header: HeaderT> {
112	/// Get the header id.
113	fn id(&self) -> HeaderId<Header::Hash, Header::Number>;
114
115	/// Get the header id for the parent block.
116	fn parent_id(&self) -> Option<HeaderId<Header::Hash, Header::Number>>;
117}
118
119impl<Header: HeaderT> HeaderIdProvider<Header> for Header {
120	fn id(&self) -> HeaderId<Header::Hash, Header::Number> {
121		HeaderId(*self.number(), self.hash())
122	}
123
124	fn parent_id(&self) -> Option<HeaderId<Header::Hash, Header::Number>> {
125		self.number()
126			.checked_sub(&One::one())
127			.map(|parent_number| HeaderId(parent_number, *self.parent_hash()))
128	}
129}
130
131/// Unique identifier of the chain.
132///
133/// In addition to its main function (identifying the chain), this type may also be used to
134/// identify module instance. We have a bunch of pallets that may be used in different bridges. E.g.
135/// messages pallet may be deployed twice in the same runtime to bridge ThisChain with Chain1 and
136/// Chain2. Sometimes we need to be able to identify deployed instance dynamically. This type may be
137/// used for that.
138pub type ChainId = [u8; 4];
139
140/// Anything that has size.
141pub trait Size {
142	/// Return size of this object (in bytes).
143	fn size(&self) -> u32;
144}
145
146impl Size for () {
147	fn size(&self) -> u32 {
148		0
149	}
150}
151
152impl Size for Vec<u8> {
153	fn size(&self) -> u32 {
154		self.len() as _
155	}
156}
157
158/// Pre-computed size.
159pub struct PreComputedSize(pub usize);
160
161impl Size for PreComputedSize {
162	fn size(&self) -> u32 {
163		u32::try_from(self.0).unwrap_or(u32::MAX)
164	}
165}
166
167/// Era of specific transaction.
168#[derive(RuntimeDebug, Clone, Copy, PartialEq)]
169pub enum TransactionEra<BlockNumber, BlockHash> {
170	/// Transaction is immortal.
171	Immortal,
172	/// Transaction is valid for a given number of blocks, starting from given block.
173	Mortal(HeaderId<BlockHash, BlockNumber>, u32),
174}
175
176impl<BlockNumber: Copy + UniqueSaturatedInto<u64>, BlockHash: Copy>
177	TransactionEra<BlockNumber, BlockHash>
178{
179	/// Prepare transaction era, based on mortality period and current best block number.
180	pub fn new(
181		best_block_id: HeaderId<BlockHash, BlockNumber>,
182		mortality_period: Option<u32>,
183	) -> Self {
184		mortality_period
185			.map(|mortality_period| TransactionEra::Mortal(best_block_id, mortality_period))
186			.unwrap_or(TransactionEra::Immortal)
187	}
188
189	/// Create new immortal transaction era.
190	pub fn immortal() -> Self {
191		TransactionEra::Immortal
192	}
193
194	/// Returns mortality period if transaction is mortal.
195	pub fn mortality_period(&self) -> Option<u32> {
196		match *self {
197			TransactionEra::Immortal => None,
198			TransactionEra::Mortal(_, period) => Some(period),
199		}
200	}
201
202	/// Returns era that is used by FRAME-based runtimes.
203	pub fn frame_era(&self) -> sp_runtime::generic::Era {
204		match *self {
205			TransactionEra::Immortal => sp_runtime::generic::Era::immortal(),
206			// `unique_saturated_into` is fine here - mortality `u64::MAX` is not something we
207			// expect to see on any chain
208			TransactionEra::Mortal(header_id, period) =>
209				sp_runtime::generic::Era::mortal(period as _, header_id.0.unique_saturated_into()),
210		}
211	}
212
213	/// Returns header hash that needs to be included in the signature payload.
214	pub fn signed_payload(&self, genesis_hash: BlockHash) -> BlockHash {
215		match *self {
216			TransactionEra::Immortal => genesis_hash,
217			TransactionEra::Mortal(header_id, _) => header_id.1,
218		}
219	}
220}
221
222/// This is a copy of the
223/// `frame_support::storage::generator::StorageMap::storage_map_final_key` for maps based
224/// on selected hasher.
225///
226/// We're using it because to call `storage_map_final_key` directly, we need access to the runtime
227/// and pallet instance, which (sometimes) is impossible.
228pub fn storage_map_final_key<H: StorageHasher>(
229	pallet_prefix: &str,
230	map_name: &str,
231	key: &[u8],
232) -> StorageKey {
233	let key_hashed = H::hash(key);
234	let pallet_prefix_hashed = frame_support::Twox128::hash(pallet_prefix.as_bytes());
235	let storage_prefix_hashed = frame_support::Twox128::hash(map_name.as_bytes());
236
237	let mut final_key = Vec::with_capacity(
238		pallet_prefix_hashed.len() + storage_prefix_hashed.len() + key_hashed.as_ref().len(),
239	);
240
241	final_key.extend_from_slice(&pallet_prefix_hashed[..]);
242	final_key.extend_from_slice(&storage_prefix_hashed[..]);
243	final_key.extend_from_slice(key_hashed.as_ref());
244
245	StorageKey(final_key)
246}
247
248/// This is how a storage key of storage value is computed.
249///
250/// Copied from `frame_support::storage::storage_prefix`.
251pub fn storage_value_key(pallet_prefix: &str, value_name: &str) -> StorageKey {
252	let pallet_hash = sp_io::hashing::twox_128(pallet_prefix.as_bytes());
253	let storage_hash = sp_io::hashing::twox_128(value_name.as_bytes());
254
255	let mut final_key = vec![0u8; 32];
256	final_key[..16].copy_from_slice(&pallet_hash);
257	final_key[16..].copy_from_slice(&storage_hash);
258
259	StorageKey(final_key)
260}
261
262/// Can be use to access the runtime storage key of a `StorageMap`.
263pub trait StorageMapKeyProvider {
264	/// The name of the variable that holds the `StorageMap`.
265	const MAP_NAME: &'static str;
266
267	/// The same as `StorageMap::Hasher1`.
268	type Hasher: StorageHasher;
269	/// The same as `StorageMap::Key1`.
270	type Key: FullCodec + Send + Sync;
271	/// The same as `StorageMap::Value`.
272	type Value: 'static + FullCodec;
273
274	/// This is a copy of the
275	/// `frame_support::storage::generator::StorageMap::storage_map_final_key`.
276	///
277	/// We're using it because to call `storage_map_final_key` directly, we need access
278	/// to the runtime and pallet instance, which (sometimes) is impossible.
279	fn final_key(pallet_prefix: &str, key: &Self::Key) -> StorageKey {
280		storage_map_final_key::<Self::Hasher>(pallet_prefix, Self::MAP_NAME, &key.encode())
281	}
282}
283
284/// Can be used to access the runtime storage key of a `StorageDoubleMap`.
285pub trait StorageDoubleMapKeyProvider {
286	/// The name of the variable that holds the `StorageDoubleMap`.
287	const MAP_NAME: &'static str;
288
289	/// The same as `StorageDoubleMap::Hasher1`.
290	type Hasher1: StorageHasher;
291	/// The same as `StorageDoubleMap::Key1`.
292	type Key1: FullCodec + Send + Sync;
293	/// The same as `StorageDoubleMap::Hasher2`.
294	type Hasher2: StorageHasher;
295	/// The same as `StorageDoubleMap::Key2`.
296	type Key2: FullCodec + Send + Sync;
297	/// The same as `StorageDoubleMap::Value`.
298	type Value: 'static + FullCodec;
299
300	/// This is a copy of the
301	/// `frame_support::storage::generator::StorageDoubleMap::storage_double_map_final_key`.
302	///
303	/// We're using it because to call `storage_double_map_final_key` directly, we need access
304	/// to the runtime and pallet instance, which (sometimes) is impossible.
305	fn final_key(pallet_prefix: &str, key1: &Self::Key1, key2: &Self::Key2) -> StorageKey {
306		let key1_hashed = Self::Hasher1::hash(&key1.encode());
307		let key2_hashed = Self::Hasher2::hash(&key2.encode());
308		let pallet_prefix_hashed = frame_support::Twox128::hash(pallet_prefix.as_bytes());
309		let storage_prefix_hashed = frame_support::Twox128::hash(Self::MAP_NAME.as_bytes());
310
311		let mut final_key = Vec::with_capacity(
312			pallet_prefix_hashed.len() +
313				storage_prefix_hashed.len() +
314				key1_hashed.as_ref().len() +
315				key2_hashed.as_ref().len(),
316		);
317
318		final_key.extend_from_slice(&pallet_prefix_hashed[..]);
319		final_key.extend_from_slice(&storage_prefix_hashed[..]);
320		final_key.extend_from_slice(key1_hashed.as_ref());
321		final_key.extend_from_slice(key2_hashed.as_ref());
322
323		StorageKey(final_key)
324	}
325}
326
327/// Error generated by the `OwnedBridgeModule` trait.
328#[derive(Encode, Decode, DecodeWithMemTracking, PartialEq, Eq, TypeInfo, PalletError)]
329pub enum OwnedBridgeModuleError {
330	/// All pallet operations are halted.
331	Halted,
332}
333
334/// Operating mode for a bridge module.
335pub trait OperatingMode: Send + Copy + Debug + FullCodec {
336	/// Returns true if the bridge module is halted.
337	fn is_halted(&self) -> bool;
338}
339
340/// Basic operating modes for a bridges module (Normal/Halted).
341#[derive(
342	Encode,
343	Decode,
344	DecodeWithMemTracking,
345	Clone,
346	Copy,
347	PartialEq,
348	Eq,
349	RuntimeDebug,
350	TypeInfo,
351	MaxEncodedLen,
352	Serialize,
353	Deserialize,
354)]
355pub enum BasicOperatingMode {
356	/// Normal mode, when all operations are allowed.
357	Normal,
358	/// The pallet is halted. All operations (except operating mode change) are prohibited.
359	Halted,
360}
361
362impl Default for BasicOperatingMode {
363	fn default() -> Self {
364		Self::Normal
365	}
366}
367
368impl OperatingMode for BasicOperatingMode {
369	fn is_halted(&self) -> bool {
370		*self == BasicOperatingMode::Halted
371	}
372}
373
374/// Bridge module that has owner and operating mode
375pub trait OwnedBridgeModule<T: frame_system::Config> {
376	/// The target that will be used when publishing logs related to this module.
377	const LOG_TARGET: &'static str;
378
379	/// A storage entry that holds the module `Owner` account.
380	type OwnerStorage: StorageValue<T::AccountId, Query = Option<T::AccountId>>;
381	/// Operating mode type of the pallet.
382	type OperatingMode: OperatingMode;
383	/// A storage value that holds the pallet operating mode.
384	type OperatingModeStorage: StorageValue<Self::OperatingMode, Query = Self::OperatingMode>;
385
386	/// Check if the module is halted.
387	fn is_halted() -> bool {
388		Self::OperatingModeStorage::get().is_halted()
389	}
390
391	/// Ensure that the origin is either root, or `PalletOwner`.
392	fn ensure_owner_or_root(origin: T::RuntimeOrigin) -> Result<(), BadOrigin> {
393		match origin.into() {
394			Ok(RawOrigin::Root) => Ok(()),
395			Ok(RawOrigin::Signed(ref signer))
396				if Self::OwnerStorage::get().as_ref() == Some(signer) =>
397				Ok(()),
398			_ => Err(BadOrigin),
399		}
400	}
401
402	/// Ensure that the module is not halted.
403	fn ensure_not_halted() -> Result<(), OwnedBridgeModuleError> {
404		match Self::is_halted() {
405			true => Err(OwnedBridgeModuleError::Halted),
406			false => Ok(()),
407		}
408	}
409
410	/// Change the owner of the module.
411	fn set_owner(origin: T::RuntimeOrigin, maybe_owner: Option<T::AccountId>) -> DispatchResult {
412		Self::ensure_owner_or_root(origin)?;
413		match maybe_owner {
414			Some(owner) => {
415				Self::OwnerStorage::put(&owner);
416				log::info!(target: Self::LOG_TARGET, "Setting pallet Owner to: {:?}", owner);
417			},
418			None => {
419				Self::OwnerStorage::kill();
420				log::info!(target: Self::LOG_TARGET, "Removed Owner of pallet.");
421			},
422		}
423
424		Ok(())
425	}
426
427	/// Halt or resume all/some module operations.
428	fn set_operating_mode(
429		origin: T::RuntimeOrigin,
430		operating_mode: Self::OperatingMode,
431	) -> DispatchResult {
432		Self::ensure_owner_or_root(origin)?;
433		Self::OperatingModeStorage::put(operating_mode);
434		log::info!(target: Self::LOG_TARGET, "Setting operating mode to {:?}.", operating_mode);
435		Ok(())
436	}
437
438	/// Pallet owner has a right to halt all module operations and then resume it. If it is `None`,
439	/// then there are no direct ways to halt/resume module operations, but other runtime methods
440	/// may still be used to do that (i.e. democracy::referendum to update halt flag directly
441	/// or call the `set_operating_mode`).
442	fn module_owner() -> Option<T::AccountId> {
443		Self::OwnerStorage::get()
444	}
445
446	/// The current operating mode of the module.
447	/// Depending on the mode either all, some, or no transactions will be allowed.
448	fn operating_mode() -> Self::OperatingMode {
449		Self::OperatingModeStorage::get()
450	}
451}
452
453/// All extra operations with weights that we need in bridges.
454pub trait WeightExtraOps {
455	/// Checked division of individual components of two weights.
456	///
457	/// Divides components and returns minimal division result. Returns `None` if one
458	/// of `other` weight components is zero.
459	fn min_components_checked_div(&self, other: Weight) -> Option<u64>;
460}
461
462impl WeightExtraOps for Weight {
463	fn min_components_checked_div(&self, other: Weight) -> Option<u64> {
464		Some(sp_std::cmp::min(
465			self.ref_time().checked_div(other.ref_time())?,
466			self.proof_size().checked_div(other.proof_size())?,
467		))
468	}
469}
470
471/// Trait that provides a static `str`.
472pub trait StaticStrProvider {
473	/// Static string.
474	const STR: &'static str;
475}
476
477/// A macro that generates `StaticStrProvider` with the string set to its stringified argument.
478#[macro_export]
479macro_rules! generate_static_str_provider {
480	($str:expr) => {
481		$crate::paste::item! {
482			pub struct [<Str $str>];
483
484			impl $crate::StaticStrProvider for [<Str $str>] {
485				const STR: &'static str = stringify!($str);
486			}
487		}
488	};
489}
490
491/// A trait defining helper methods for `RangeInclusive` (start..=end)
492pub trait RangeInclusiveExt<Idx> {
493	/// Computes the length of the `RangeInclusive`, checking for underflow and overflow.
494	fn checked_len(&self) -> Option<Idx>;
495	/// Computes the length of the `RangeInclusive`, saturating in case of underflow or overflow.
496	fn saturating_len(&self) -> Idx;
497}
498
499impl<Idx> RangeInclusiveExt<Idx> for RangeInclusive<Idx>
500where
501	Idx: CheckedSub + CheckedAdd + SaturatingAdd + One + Zero,
502{
503	fn checked_len(&self) -> Option<Idx> {
504		self.end()
505			.checked_sub(self.start())
506			.and_then(|len| len.checked_add(&Idx::one()))
507	}
508
509	fn saturating_len(&self) -> Idx {
510		let len = match self.end().checked_sub(self.start()) {
511			Some(len) => len,
512			None => return Idx::zero(),
513		};
514		len.saturating_add(&Idx::one())
515	}
516}
517
518#[cfg(test)]
519mod tests {
520	use super::*;
521
522	#[test]
523	fn storage_value_key_works() {
524		assert_eq!(
525			storage_value_key("PalletTransactionPayment", "NextFeeMultiplier"),
526			StorageKey(
527				hex_literal::hex!(
528					"f0e954dfcca51a255ab12c60c789256a3f2edf3bdf381debe331ab7446addfdc"
529				)
530				.to_vec()
531			),
532		);
533	}
534
535	#[test]
536	fn generate_static_str_provider_works() {
537		generate_static_str_provider!(Test);
538		assert_eq!(StrTest::STR, "Test");
539	}
540}