added/updated pallet level docs to grandpa and messages pallets (pari…

…tytech#1771)

docs/high-level-overview.md

@@ -115,7 +115,7 @@ the source chain GRANDPA justifications stream and submits every new justificati
 target chain GRANDPA light client. In addition, relay is searching for mandatory headers and
 submits their justifications - without that the pallet will be unable to move forward.
 
-More: [GRANDPA Finality Relay Sequence Diagram](./grandpa-finality-relay.html), [code](../relays/finality/).
+More: [GRANDPA Finality Relay Sequence Diagram](./grandpa-finality-relay.html), [pallet level documentation and code](../relays/finality/).
 
 ### Parachains Finality Relay
 
@@ -158,7 +158,7 @@ relay submits transactions to both source and target chains, it requires both _s
 _target-to-source_ finality relays. They can be GRANDPA finality relays or GRANDPA+parachains finality relays,
 depending on the type of connected chain.
 
-More: [Messages Relay Sequence Diagram](./messages-relay.html), [code](../relays/messages/).
+More: [Messages Relay Sequence Diagram](./messages-relay.html), [pallet level documentation and code](../relays/messages/).
 
 ### Complex Relay
 

modules/grandpa/README.md

@@ -0,0 +1,83 @@
+# Bridge GRANDPA Pallet
+
+The bridge GRANDPA pallet is a light client for the GRANDPA finality gadget, running at the bridged chain.
+It may import headers and their GRANDPA finality proofs (justifications) of the bridged chain. Imported
+headers then may be used to verify storage proofs by other pallets. This makes the bridge GRANDPA pallet
+a basic pallet of all bridges with Substrate-based chains. It is used by all bridge types (bridge between
+standalone chains, between parachains and any combination of those) and is used by other bridge pallets.
+It is used by the parachains light client (bridge parachains pallet) and by messages pallet.
+
+## A Brief Introduction into GRANDPA Finality
+
+You can find detailed information on GRANDPA, by exploring its [repository](https://github.com/paritytech/finality-grandpa).
+Here is the minimal reqiuired GRANDPA information to understand how pallet works.
+
+Any Substrate chain may use different block authorship algorithms (like BABE or Aura) to determine block producers and
+generate blocks. This has nothing common with finality, though - the task of block authorship is to coordinate
+blocks generation. Any block may be reverted (if there's a fork) if it is not finalized. The finality solution
+for (standalone) Substrate-based chains is the GRANDPA finality gadget. If some block is finalized by the gadget, it
+can't be reverted.
+
+In GRANDPA, there are validators, identified by their public keys. They select some generated block and produce
+signatures on this block hash. If there are enough (more than `2 / 3 * N`, where `N` is number of validators)
+signatures, then the block is considered finalized. The set of signatures for the block is called justification.
+Anyone who knows the public keys of validators is able to verify GRANDPA justification and that it is generated
+for provided header.
+
+There are two main things in GRANDPA that help building light clients:
+
+- there's no need to import all headers of the bridged chain. Light client may import finalized headers or just
+  some of finalized headders that it consider useful. While the validators set stays the same, the client may
+  import any header that is finalized by this set;
+- when validators set changes, the GRANDPA gadget adds next set to the header. So light client doesn't need to
+  verify storage proofs when this happens - it only needs to look at the header and see if it changes the set.
+  Once set is changed, all following justifications are generated by the new set. Header that is changing the
+  set is called "mandatory" in the pallet. As the name says, the light client need to import all such headers
+  to be able to operate properly.
+
+## Pallet Operations
+
+The main entrypoint of the pallet is the `submit_finality_proof` call. It has two arguments - the finalized
+headers and associated GRANDPA justification. The call simply verifies the justification using current
+validators set and checks if header is better than the previous best header. If both checks are passed, the
+header (only its useful fields) is inserted into the runtime storage and may be used by other pallets to verify
+storage proofs.
+
+The submitter pays regular fee for submitting all headers, except for the mandatory header. Since it is
+required for the pallet operations, submitting such header is free. So if you're ok with session-length
+lags (meaning that there's exactly 1 mandatory header per session), the cost of pallet calls is zero.
+
+When the pallet sees mandatory header, it updates the validators set with the set from the header. All
+following justifications (until next mandatory header) must be generated by this new set.
+
+## Pallet Initialization
+
+As the previous section states, there are two things that are mandatory for pallet operations: best finalized
+header and the current validators set. Without it the pallet can't import any headers. But how to provide
+initial values for these fields? There are two options.
+
+First option, while it is easier, doesn't work in all cases. It is to start chain with initial header and
+validators set specified in the chain specification. This won't work, however, if we want to add bridge
+to already started chain.
+
+For the latter case we have the `initialize` call. It accepts the initial header and initial validators set.
+The call may be called by the governance, root or by the pallet owner (if it is set).
+
+## Non-Essential Functionality
+
+There may be a special account in every runtime where the bridge GRANDPA module is deployed. This
+account, named 'module owner', is like a module-level sudo account - he's able to halt and
+resume all module operations without requiring runtime upgrade. Calls that are related to this
+account are:
+- `fn set_owner()`: current module owner may call it to transfer "ownership" to another account;
+- `fn set_operating_mode()`: the module owner (or sudo account) may call this function to stop all
+  module operations. After this call, all finality proofs will be rejected until further `set_operating_mode` call'.
+  This call may be used when something extraordinary happens with the bridge;
+- `fn initialize()`: module owner may call this function to initialize the bridge.
+
+If pallet owner is not defined, the governance may be used to make those calls.
+
+## GRANDPA Finality Relay
+
+We have an offchain actor, who is watching for GRANDPA justifications and submits them to the bridged chain.
+It is the finality relay - you may look at the [crate level documentation and the code](../../relays/finality/).