Added crate-level docs for the parachains pallet

modules/grandpa/README.md

@@ -29,6 +29,7 @@ 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
@@ -69,14 +70,31 @@ There may be a special account in every runtime where the bridge GRANDPA module
 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.
 
+## Signed Extension to Reject Obsolete Headers
+
+It'd be better for anyone (for chain and for submitters) to reject all transactions that are submitting
+already known headers to the pallet. This way, we leave block space to other useful transactions and
+we don't charge concurrent submitters for their honest actions.
+
+To deal with that, we have a [signed extension](./src/extension.rs) that may be added to the runtime.
+It does exactly what is required - rejects all transactions with already known headers. The submitter
+pays nothing for such transactions - they're simply removed from the transaction pool, when the block
+is built.
+
+You may also take a look at the [`generate_bridge_reject_obsolete_headers_and_messages`](../../bin/runtime-common/src/lib.rs)
+macro that bundles several similar signed extensions in a single one.
+
 ## GRANDPA Finality Relay
 
 We have an offchain actor, who is watching for GRANDPA justifications and submits them to the bridged chain.

modules/parachains/README.md

@@ -0,0 +1,90 @@
+# Bridge Parachains Pallet
+
+The bridge parachains pallet is a light client for one or several parachains of the bridged relay chain.
+It serves as a source of finalized parachain headers and is used when you need to build a bridge with
+a parachain.
+
+The pallet requires [bridge GRANDPA pallet](../grandpa/) to be deployed at the same chain - it is used
+to verify storage proofs, generated at the bridged relay chain.
+
+## A Brief Introduction into Parachains Finality
+
+You can find detailed information on parachains finality in the [Polkadot](https://github.com/paritytech/polkadot)
+and [Cumulus](https://github.com/paritytech/cumulus) repositories. This section gives a brief overview of how
+the parachain finality works and how to build a light client for a parachain.
+
+The main thing there is that the parachain generates blocks on its own, but it can't achieve finality without
+help of its relay chain. Instead, the parachain collators create a block and hand it over to the relay chain
+validators. Validators validate the block and register the new parachain head in the
+[`Heads` map](https://github.com/paritytech/polkadot/blob/88013730166ba90745ae7c9eb3e0c1be1513c7cc/runtime/parachains/src/paras/mod.rs#L645)
+of the [`paras`](https://github.com/paritytech/polkadot/tree/master/runtime/parachains/src/paras) pallet,
+deployed at the relay chain. Keep in mind that this pallet, deployed at a relay chain, is **NOT** a bridge pallet,
+even though the names are similar. 
+
+And what the bridge parachains pallet does, is simply verifying storage proofs of parachain heads within that
+`Heads` map. It does that using relay chain header, that has been previously imported by the
+[bridge GRANDPA pallet](../grandpa/). Once the proof is verified, the pallet knows that the given parachain
+header has been finalized by the relay chain. The parachain header fields may then be used to verify storage
+proofs, coming from the parachain. This allows the pallet to be used e.g. as a source of finality for the messages
+pallet.
+
+## Pallet Operations
+
+The main entrypoint of the pallet is the `submit_parachain_heads` call. It has three arguments:
+
+- storage proof of parachain heads from the `Heads` map;
+
+- parachain identifiers and hashes of their heads from the storage proof;
+
+- the relay block, at which the storage proof has been generated.
+
+The pallet may track multiple parachains. And the parachains may use different primitives - one may use 128-bit block
+numbers, other - 32-bit. To avoid extra decode operations, the pallet is using relay chain block number to order
+parachain headers. Any finalized descendant of finalized relay block `RB`, which has parachain block `PB` in
+its `Heads` map, is guaranteed to have either `PB`, or its descendant. So parachain block number grows with relay
+block number.
+
+The pallet may reject parachain head if it already knows better (or the same) head. In addition, pallet rejects
+heads of untracked parachains.
+
+The pallet doesn't track anything behind parachain heads. So it requires no initialization - it is ready to accept
+headers right after deployment.
+
+## Non-Essential Functionality
+
+There may be a special account in every runtime where the bridge parachains 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.
+
+If pallet owner is not defined, the governance may be used to make those calls.
+
+## Signed Extension to Reject Obsolete Headers
+
+It'd be better for anyone (for chain and for submitters) to reject all transactions that are submitting
+already known parachain heads to the pallet. This way, we leave block space to other useful transactions and
+we don't charge concurrent submitters for their honest actions.
+
+To deal with that, we have a [signed extension](./src/extension.rs) that may be added to the runtime.
+It does exactly what is required - rejects all transactions with already known heads. The submitter
+pays nothing for such transactions - they're simply removed from the transaction pool, when the block
+is built.
+
+The signed extension, however, is a bit limited - it only works with transactions that provide single
+parachain head. So it won't work with multiple parachain heads transactions. This fits our needs
+for [Kusama <> Polkadot bridge](../../docs/polkadot-kusama-bridge-overview.md). If you need to deal
+with other transaction formats, you may implement similar extension for your runtime.
+
+You may also take a look at the [`generate_bridge_reject_obsolete_headers_and_messages`](../../bin/runtime-common/src/lib.rs)
+macro that bundles several similar signed extensions in a single one.
+
+## Parachains Finality Relay
+
+We have an offchain actor, who is watching for new parachain heads and submits them to the bridged chain.
+It is the parachains relay - you may look at the [crate level documentation and the code](../../relays/parachains/).