High-Level Documentation (#565)

* High level docs - start.

* Clean up README

* Start adding details to high level docs

* More docs on the header sync pallet

* Testing scenarios document.

* Add some scenarios.

* Add multi-sig scenario.

* Start writing about message dispatch pallet

* Move content from old README into PoA specific doc

* Apply suggestions from code review

Co-authored-by: Andreas Doerr <adoerr@users.noreply.github.com>

* GRANDPA for consistency.

* Describe scenario steps.

* WiP

* Add notes about block production and forks

* Update.

* Add sequence diagram for Millau to Rialto transfer

* Clean up header sync pallet overview

* Remove leftover example code

* Clean up testing scenarios and amend sequence diagram.

* Linking docs.

* Add some more docs.

* Do a bit of cleanup on the high-level docs

* Clean up the testing scenario

* Fix typos in flow charts

* Fix small typo

* Fix indentation of Rust block

* Another attempt at rendering block correctly

* TIL about lazy list numbering in Markdown

* Add list numbers across sections

* Start counting from correct number

* Update README to use correct path to local scripts

* Wrap ASCII art in code block

Co-authored-by: Tomasz Drwięga <tomasz@parity.io>
Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>
Co-authored-by: Andreas Doerr <adoerr@users.noreply.github.com>

bridges/modules/substrate/src/fork_tests.rs

@@ -134,7 +134,7 @@ fn fork_does_not_allow_competing_finality_proofs() {
 //
 // Not allowed to import 3 until we get F2
 //
-// Note: Grandpa would technically allow 3 to be imported as long as it didn't try and enact an
+// Note: GRANDPA would technically allow 3 to be imported as long as it didn't try and enact an
 // authority set change. However, since we expect finality proofs to be imported quickly we've
 // decided to simplify our import process and disallow header imports until we get a finality proof.
 #[test]
@@ -161,9 +161,9 @@ fn fork_waits_for_finality_proof_before_importing_header_past_one_which_enacts_a
 //
 // [1] <- [2: S|1] <- [3: S|0]
 //
-// Grandpa can have multiple authority set changes pending on the same fork. However, we've decided
+// GRANDPA can have multiple authority set changes pending on the same fork. However, we've decided
 // to introduce a limit of _one_ pending authority set change per fork in order to simplify pallet
-// logic and to prevent DoS attacks if Grandpa finality were to temporarily stall for a long time
+// logic and to prevent DoS attacks if GRANDPA finality were to temporarily stall for a long time
 // (we'd have to perform a lot of expensive ancestry checks to catch back up).
 #[test]
 fn fork_does_not_allow_multiple_scheduled_changes_on_the_same_fork() {

bridges/modules/substrate/src/justification.rs

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Module for checking Grandpa Finality Proofs.
+//! Module for checking GRANDPA Finality Proofs.
 //!
 //! Adapted copy of substrate/client/finality-grandpa/src/justification.rs. If origin
 //! will ever be moved to the sp_finality_grandpa, we should reuse that implementation.
@@ -123,7 +123,7 @@ where
 	Ok(())
 }
 
-/// A Grandpa Justification is a proof that a given header was finalized
+/// A GRANDPA Justification is a proof that a given header was finalized
 /// at a certain height and with a certain set of authorities.
 ///
 /// This particular proof is used to prove that headers on a bridged chain

bridges/modules/substrate/src/lib.rs

@@ -21,7 +21,7 @@
 //! It has a simple interface for achieving this. First it can import headers to the runtime
 //! storage. During this it will check the validity of the headers and ensure they don't conflict
 //! with any existing headers (e.g they're on a different finalized chain). Secondly it can finalize
-//! an already imported header (and its ancestors) given a valid Grandpa justification.
+//! an already imported header (and its ancestors) given a valid GRANDPA justification.
 //!
 //! With these two functions the pallet is able to form a "source of truth" for what headers have
 //! been finalized on a given Substrate chain. This can be a useful source of info for other
@@ -94,17 +94,17 @@ decl_storage! {
 		/// Hash of the best finalized header.
 		BestFinalized: BridgedBlockHash<T>;
 		/// The set of header IDs (number, hash) which enact an authority set change and therefore
-		/// require a Grandpa justification.
+		/// require a GRANDPA justification.
 		RequiresJustification: map hasher(identity) BridgedBlockHash<T> => BridgedBlockNumber<T>;
 		/// Headers which have been imported into the pallet.
 		ImportedHeaders: map hasher(identity) BridgedBlockHash<T> => Option<ImportedHeader<BridgedHeader<T>>>;
-		/// The current Grandpa Authority set.
+		/// The current GRANDPA Authority set.
 		CurrentAuthoritySet: AuthoritySet;
 		/// The next scheduled authority set change for a given fork.
 		///
 		/// The fork is indicated by the header which _signals_ the change (key in the mapping).
 		/// Note that this is different than a header which _enacts_ a change.
-		// Grandpa doesn't require there to always be a pending change. In fact, most of the time
+		// GRANDPA doesn't require there to always be a pending change. In fact, most of the time
 		// there will be no pending change available.
 		NextScheduledChange: map hasher(identity) BridgedBlockHash<T> => Option<ScheduledChange<BridgedBlockNumber<T>>>;
 		/// Optional pallet owner.
@@ -448,10 +448,10 @@ pub trait BridgeStorage {
 	/// Returns None if it is not known to the pallet.
 	fn header_by_hash(&self, hash: <Self::Header as HeaderT>::Hash) -> Option<ImportedHeader<Self::Header>>;
 
-	/// Get the current Grandpa authority set.
+	/// Get the current GRANDPA authority set.
 	fn current_authority_set(&self) -> AuthoritySet;
 
-	/// Update the current Grandpa authority set.
+	/// Update the current GRANDPA authority set.
 	///
 	/// Should only be updated when a scheduled change has been triggered.
 	fn update_current_authority_set(&self, new_set: AuthoritySet);
@@ -462,13 +462,13 @@ pub trait BridgeStorage {
 	#[allow(clippy::result_unit_err)]
 	fn enact_authority_set(&mut self, signal_hash: <Self::Header as HeaderT>::Hash) -> Result<(), ()>;
 
-	/// Get the next scheduled Grandpa authority set change.
+	/// Get the next scheduled GRANDPA authority set change.
 	fn scheduled_set_change(
 		&self,
 		signal_hash: <Self::Header as HeaderT>::Hash,
 	) -> Option<ScheduledChange<<Self::Header as HeaderT>::Number>>;
 
-	/// Schedule a Grandpa authority set change in the future.
+	/// Schedule a GRANDPA authority set change in the future.
 	///
 	/// Takes the hash of the header which scheduled this particular change.
 	fn schedule_next_set_change(

bridges/modules/substrate/src/storage.rs

@@ -42,24 +42,24 @@ pub struct InitializationData<H: HeaderT> {
 	pub is_halted: bool,
 }
 
-/// A Grandpa Authority List and ID.
+/// A GRANDPA Authority List and ID.
 #[derive(Default, Encode, Decode, RuntimeDebug, PartialEq, Clone)]
 #[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
 pub struct AuthoritySet {
-	/// List of Grandpa authorities for the current round.
+	/// List of GRANDPA authorities for the current round.
 	pub authorities: AuthorityList,
-	/// Monotonic identifier of the current Grandpa authority set.
+	/// Monotonic identifier of the current GRANDPA authority set.
 	pub set_id: SetId,
 }
 
 impl AuthoritySet {
-	/// Create a new Grandpa Authority Set.
+	/// Create a new GRANDPA Authority Set.
 	pub fn new(authorities: AuthorityList, set_id: SetId) -> Self {
 		Self { authorities, set_id }
 	}
 }
 
-/// Keeps track of when the next Grandpa authority set change will occur.
+/// Keeps track of when the next GRANDPA authority set change will occur.
 #[derive(Default, Encode, Decode, RuntimeDebug, PartialEq, Clone)]
 #[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
 pub struct ScheduledChange<N> {

bridges/modules/substrate/src/verifier.rs

@@ -19,7 +19,7 @@
 //!
 //! When importing headers it performs checks to ensure that no invariants are broken (like
 //! importing the same header twice). When it imports finality proofs it will ensure that the proof
-//! has been signed off by the correct Grandpa authorities, and also enact any authority set changes
+//! has been signed off by the correct GRANDPA authorities, and also enact any authority set changes
 //! if required.
 
 use crate::justification::verify_justification;
@@ -34,8 +34,8 @@ use sp_std::{prelude::Vec, vec};
 
 /// The finality proof used by the pallet.
 ///
-/// For a Substrate based chain using Grandpa this will
-/// be an encoded Grandpa Justification.
+/// For a Substrate based chain using GRANDPA this will
+/// be an encoded GRANDPA Justification.
 #[derive(RuntimeDebug)]
 pub struct FinalityProof(Vec<u8>);
 
@@ -139,7 +139,7 @@ where
 		// we need to make a note of it.
 		//
 		// Note: This assumes that we can only have one authority set change pending per fork at a
-		// time. While this is not strictly true of Grandpa (it can have multiple pending changes,
+		// time. While this is not strictly true of GRANDPA (it can have multiple pending changes,
 		// even across forks), this assumption simplifies our tracking of authority set changes.
 		let mut signal_hash = parent_header.signal_hash;
 		let scheduled_change = find_scheduled_change(&header);
@@ -213,7 +213,7 @@ where
 		Ok(())
 	}
 
-	/// Verify that a previously imported header can be finalized with the given Grandpa finality
+	/// Verify that a previously imported header can be finalized with the given GRANDPA finality
 	/// proof. If the header enacts an authority set change the change will be applied once the
 	/// header has been finalized.
 	pub fn import_finality_proof(&mut self, hash: H::Hash, proof: FinalityProof) -> Result<(), FinalizationError> {
@@ -680,7 +680,7 @@ mod tests {
 			let mut storage = PalletStorage::<TestRuntime>::new();
 			let _imported_headers = write_default_headers(&mut storage, vec![1]);
 
-			// Nothing special about this header, yet Grandpa may have created a justification
+			// Nothing special about this header, yet GRANDPA may have created a justification
 			// for it since it does that periodically
 			let header = test_header(2);