From d05dc090a84c10fcf54896d0b21b5f5930e9c07e Mon Sep 17 00:00:00 2001
From: Joshy Orndorff <JoshOrndorff@users.noreply.github.com>
Date: Sun, 19 Apr 2020 05:57:16 -0400
Subject: [PATCH] Revise docs on randomness (#5497)
* Initial attempt to revise docs.
* Remove incorrect warning from Babe pallet
* Add more hints that collective flip is for low security
---
substrate/frame/babe/src/lib.rs | 15 +++++++++
.../randomness-collective-flip/src/lib.rs | 32 ++-----------------
2 files changed, 18 insertions(+), 29 deletions(-)
diff --git a/substrate/frame/babe/src/lib.rs b/substrate/frame/babe/src/lib.rs
index ea2f97e7a95..5227dd94423 100644
--- a/substrate/frame/babe/src/lib.rs
+++ b/substrate/frame/babe/src/lib.rs
@@ -205,6 +205,21 @@ decl_module! {
}
impl<T: Trait> RandomnessT<<T as frame_system::Trait>::Hash> for Module<T> {
+ /// Some BABE blocks have VRF outputs where the block producer has exactly one bit of influence,
+ /// either they make the block or they do not make the block and thus someone else makes the
+ /// next block. Yet, this randomness is not fresh in all BABE blocks.
+ ///
+ /// If that is an insufficient security guarantee then two things can be used to improve this
+ /// randomness:
+ ///
+ /// - Name, in advance, the block number whose random value will be used; ensure your module
+ /// retains a buffer of previous random values for its subject and then index into these in
+ /// order to obviate the ability of your user to look up the parent hash and choose when to
+ /// transact based upon it.
+ /// - Require your user to first commit to an additional value by first posting its hash.
+ /// Require them to reveal the value to determine the final result, hashing it with the
+ /// output of this random function. This reduces the ability of a cabal of block producers
+ /// from conspiring against individuals.
fn random(subject: &[u8]) -> T::Hash {
let mut subject = subject.to_vec();
subject.reserve(VRF_OUTPUT_LENGTH);
diff --git a/substrate/frame/randomness-collective-flip/src/lib.rs b/substrate/frame/randomness-collective-flip/src/lib.rs
index 194879eb65b..cf6dadf7cb9 100644
--- a/substrate/frame/randomness-collective-flip/src/lib.rs
+++ b/substrate/frame/randomness-collective-flip/src/lib.rs
@@ -19,7 +19,8 @@
//! The Randomness Collective Flip module provides a [`random`](./struct.Module.html#method.random)
//! function that generates low-influence random values based on the block hashes from the previous
//! `81` blocks. Low-influence randomness can be useful when defending against relatively weak
-//! adversaries.
+//! adversaries. Using this pallet as a randomness source is advisable primarily in low-security
+//! situations like testing.
//!
//! ## Public Functions
//!
@@ -43,7 +44,7 @@
//! pub struct Module<T: Trait> for enum Call where origin: T::Origin {
//! #[weight = SimpleDispatchInfo::FixedNormal(MINIMUM_WEIGHT)]
//! pub fn random_module_example(origin) -> dispatch::DispatchResult {
-//! let _random_seed = <pallet_randomness_collective_flip::Module<T>>::random_seed();
+//! let _random_value = <pallet_randomness_collective_flip::Module<T>>::random(&b"my context"[..]);
//! Ok(())
//! }
//! }
@@ -98,17 +99,6 @@ decl_storage! {
}
impl<T: Trait> Randomness<T::Hash> for Module<T> {
- /// Get a low-influence "random" value.
- ///
- /// Being a deterministic block chain, real randomness is difficult to come by. This gives you
- /// something that approximates it. `subject` is a context identifier and allows you to get a
- /// different result to other callers of this function; use it like
- /// `random(&b"my context"[..])`. This is initially implemented through a low-influence
- /// "triplet mix" convolution of previous block hash values. In the future it will be generated
- /// from a secure verifiable random function (VRF).
- ///
- /// ### Security Notes
- ///
/// This randomness uses a low-influence function, drawing upon the block hashes from the
/// previous 81 blocks. Its result for any given subject will be known far in advance by anyone
/// observing the chain. Any block producer has significant influence over their block hashes
@@ -116,22 +106,6 @@ impl<T: Trait> Randomness<T::Hash> for Module<T> {
/// block producer's influence over the randomness, but increases the influence of small
/// colluding groups of recent block producers.
///
- /// Some BABE blocks have VRF outputs where the block producer has exactly one bit of influence,
- /// either they make the block or they do not make the block and thus someone else makes the
- /// next block. Yet, this randomness is not fresh in all BABE blocks.
- ///
- /// If that is an insufficient security guarantee then two things can be used to improve this
- /// randomness:
- ///
- /// - Name, in advance, the block number whose random value will be used; ensure your module
- /// retains a buffer of previous random values for its subject and then index into these in
- /// order to obviate the ability of your user to look up the parent hash and choose when to
- /// transact based upon it.
- /// - Require your user to first commit to an additional value by first posting its hash.
- /// Require them to reveal the value to determine the final result, hashing it with the
- /// output of this random function. This reduces the ability of a cabal of block producers
- /// from conspiring against individuals.
- ///
/// WARNING: Hashing the result of this function will remove any low-influence properties it has
/// and mean that all bits of the resulting value are entirely manipulatable by the author of
/// the parent block, who can determine the value of `parent_hash`.
--
GitLab