pallet_insecure_randomness_collective_flip/
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//! # DO NOT USE IN PRODUCTION
19//!
20//! The produced values do not fulfill the cryptographic requirements for random numbers.
21//! Should not be used for high-stake production use-cases.
22//!
23//! # Randomness Pallet
24//!
25//! The Randomness Collective Flip pallet provides a [`random`](./struct.Module.html#method.random)
26//! function that generates low-influence random values based on the block hashes from the previous
27//! `81` blocks. Low-influence randomness can be useful when defending against relatively weak
28//! adversaries. Using this pallet as a randomness source is advisable primarily in low-security
29//! situations like testing.
30//!
31//! ## Public Functions
32//!
33//! See the [`Module`] struct for details of publicly available functions.
34//!
35//! ## Usage
36//!
37//! ### Prerequisites
38//!
39//! Import the Randomness Collective Flip pallet and derive your pallet's configuration trait from
40//! the system trait.
41//!
42//! ### Example - Get random seed for the current block
43//!
44//! ```
45//! use frame::{prelude::*, traits::Randomness};
46//!
47//! #[frame::pallet]
48//! pub mod pallet {
49//!     use super::*;
50//!
51//!     #[pallet::pallet]
52//!     pub struct Pallet<T>(_);
53//!
54//!     #[pallet::config]
55//!     pub trait Config: frame_system::Config + pallet_insecure_randomness_collective_flip::Config {}
56//!
57//!     #[pallet::call]
58//!     impl<T: Config> Pallet<T> {
59//!         #[pallet::weight(0)]
60//!         pub fn random_module_example(origin: OriginFor<T>) -> DispatchResult {
61//!             let _random_value = pallet_insecure_randomness_collective_flip::Pallet::<T>::random(&b"my context"[..]);
62//!             Ok(())
63//!         }
64//!     }
65//! }
66//! # fn main() { }
67//! ```
68
69#![cfg_attr(not(feature = "std"), no_std)]
70
71use safe_mix::TripletMix;
72
73use codec::Encode;
74use frame::{prelude::*, traits::Randomness};
75
76const RANDOM_MATERIAL_LEN: u32 = 81;
77
78fn block_number_to_index<T: Config>(block_number: BlockNumberFor<T>) -> usize {
79	// on_initialize is called on the first block after genesis
80	let index = (block_number - 1u32.into()) % RANDOM_MATERIAL_LEN.into();
81	index.try_into().ok().expect("Something % 81 is always smaller than usize; qed")
82}
83
84pub use pallet::*;
85
86#[frame::pallet]
87pub mod pallet {
88	use super::*;
89
90	#[pallet::pallet]
91	pub struct Pallet<T>(_);
92
93	#[pallet::config]
94	pub trait Config: frame_system::Config {}
95
96	#[pallet::hooks]
97	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
98		fn on_initialize(block_number: BlockNumberFor<T>) -> Weight {
99			let parent_hash = frame_system::Pallet::<T>::parent_hash();
100
101			RandomMaterial::<T>::mutate(|ref mut values| {
102				if values.try_push(parent_hash).is_err() {
103					let index = block_number_to_index::<T>(block_number);
104					values[index] = parent_hash;
105				}
106			});
107
108			T::DbWeight::get().reads_writes(1, 1)
109		}
110	}
111
112	/// Series of block headers from the last 81 blocks that acts as random seed material. This
113	/// is arranged as a ring buffer with `block_number % 81` being the index into the `Vec` of
114	/// the oldest hash.
115	#[pallet::storage]
116	pub type RandomMaterial<T: Config> =
117		StorageValue<_, BoundedVec<T::Hash, ConstU32<RANDOM_MATERIAL_LEN>>, ValueQuery>;
118
119	impl<T: Config> Pallet<T> {
120		/// Gets the random material storage value
121		pub fn random_material() -> BoundedVec<T::Hash, ConstU32<RANDOM_MATERIAL_LEN>> {
122			RandomMaterial::<T>::get()
123		}
124	}
125}
126
127impl<T: Config> Randomness<T::Hash, BlockNumberFor<T>> for Pallet<T> {
128	/// This randomness uses a low-influence function, drawing upon the block hashes from the
129	/// previous 81 blocks. Its result for any given subject will be known far in advance by anyone
130	/// observing the chain. Any block producer has significant influence over their block hashes
131	/// bounded only by their computational resources. Our low-influence function reduces the actual
132	/// block producer's influence over the randomness, but increases the influence of small
133	/// colluding groups of recent block producers.
134	///
135	/// WARNING: Hashing the result of this function will remove any low-influence properties it has
136	/// and mean that all bits of the resulting value are entirely manipulatable by the author of
137	/// the parent block, who can determine the value of `parent_hash`.
138	fn random(subject: &[u8]) -> (T::Hash, BlockNumberFor<T>) {
139		let block_number = frame_system::Pallet::<T>::block_number();
140		let index = block_number_to_index::<T>(block_number);
141
142		let hash_series = RandomMaterial::<T>::get();
143		let seed = if !hash_series.is_empty() {
144			// Always the case after block 1 is initialized.
145			hash_series
146				.iter()
147				.cycle()
148				.skip(index)
149				.take(RANDOM_MATERIAL_LEN as usize)
150				.enumerate()
151				.map(|(i, h)| (i as i8, subject, h).using_encoded(T::Hashing::hash))
152				.triplet_mix()
153		} else {
154			T::Hash::default()
155		};
156
157		(seed, block_number.saturating_sub(RANDOM_MATERIAL_LEN.into()))
158	}
159}
160
161#[cfg(test)]
162mod tests {
163	use super::*;
164	use crate as pallet_insecure_randomness_collective_flip;
165	use frame::{
166		testing_prelude::{frame_system::limits, *},
167		traits::Header as _,
168	};
169
170	type Block = frame_system::mocking::MockBlock<Test>;
171
172	construct_runtime!(
173		pub enum Test
174		{
175			System: frame_system,
176			CollectiveFlip: pallet_insecure_randomness_collective_flip,
177		}
178	);
179
180	parameter_types! {
181		pub BlockLength: limits::BlockLength = limits::BlockLength
182			::max(2 * 1024);
183	}
184
185	#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
186	impl frame_system::Config for Test {
187		type Block = Block;
188	}
189
190	impl pallet_insecure_randomness_collective_flip::Config for Test {}
191
192	fn new_test_ext() -> TestExternalities {
193		let t = frame_system::GenesisConfig::<Test>::default().build_storage().unwrap();
194		t.into()
195	}
196
197	#[test]
198	fn test_block_number_to_index() {
199		for i in 1..1000 {
200			assert_eq!((i - 1) as usize % 81, block_number_to_index::<Test>(i));
201		}
202	}
203
204	fn setup_blocks(blocks: u64) {
205		let mut parent_hash = System::parent_hash();
206
207		for i in 1..(blocks + 1) {
208			System::reset_events();
209			System::initialize(&i, &parent_hash, &Default::default());
210			CollectiveFlip::on_initialize(i);
211
212			let header = System::finalize();
213			parent_hash = header.hash();
214			System::set_block_number(*header.number());
215		}
216	}
217
218	#[test]
219	fn test_random_material_partial() {
220		new_test_ext().execute_with(|| {
221			let genesis_hash = System::parent_hash();
222
223			setup_blocks(38);
224
225			let random_material = RandomMaterial::<Test>::get();
226
227			assert_eq!(random_material.len(), 38);
228			assert_eq!(random_material[0], genesis_hash);
229		});
230	}
231
232	#[test]
233	fn test_random_material_filled() {
234		new_test_ext().execute_with(|| {
235			let genesis_hash = System::parent_hash();
236
237			setup_blocks(81);
238
239			let random_material = RandomMaterial::<Test>::get();
240
241			assert_eq!(random_material.len(), 81);
242			assert_ne!(random_material[0], random_material[1]);
243			assert_eq!(random_material[0], genesis_hash);
244		});
245	}
246
247	#[test]
248	fn test_random_material_filled_twice() {
249		new_test_ext().execute_with(|| {
250			let genesis_hash = System::parent_hash();
251
252			setup_blocks(162);
253
254			let random_material = RandomMaterial::<Test>::get();
255
256			assert_eq!(random_material.len(), 81);
257			assert_ne!(random_material[0], random_material[1]);
258			assert_ne!(random_material[0], genesis_hash);
259		});
260	}
261
262	#[test]
263	fn test_random() {
264		new_test_ext().execute_with(|| {
265			setup_blocks(162);
266
267			assert_eq!(System::block_number(), 162);
268			assert_eq!(CollectiveFlip::random_seed(), CollectiveFlip::random_seed());
269			assert_ne!(CollectiveFlip::random(b"random_1"), CollectiveFlip::random(b"random_2"));
270
271			let (random, known_since) = CollectiveFlip::random_seed();
272
273			assert_eq!(known_since, 162 - RANDOM_MATERIAL_LEN as u64);
274			assert_ne!(random, H256::zero());
275			assert!(!RandomMaterial::<Test>::get().contains(&random));
276		});
277	}
278}
pallet_insecure_randomness_collective_flip/lib.rs

pallet_insecure_randomness_collective_flip/
lib.rs
