Update project level docs (paritytech#1734)

* updated project level document * updated high level overview document * GRANDPA finality relay sequence diagram * Parachains Finality Relay Sequence Diagram * Messages Relay Sequence Diagram * Complex Relayer Sequence Diagram * small fix * Polkadot <> Kusama bridge flowchart * remove obsolete files * started polkadot-kusama-bridge-overview.md * continue polkadot-kusama-bridge-overview.md * couple more sections in polkadot-kusama-bridge-overview.md * continue polkadot-kusama-bridge-overview.md * renew deployments readme * fixed review suggestions * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * removed obsolete section * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * typo * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <adrian@parity.io> Co-authored-by: Adrian Catangiu <adrian@parity.io>
serban300 · Jan 9, 2023 · e43c999 · e43c999
1 parent bfa0a3f
commit e43c999
Show file tree

Hide file tree

Showing 8 changed files with 637 additions and 151 deletions.
diff --git a/README.md b/README.md
@@ -10,11 +10,6 @@ Substrate chains.
 
 🚧 The bridges are currently under construction - a hardhat is recommended beyond this point 🚧
 
-**IMPORTANT**: this documentation is outdated and it is mostly related to the previous version of our
-bridge. Right there's an ongoing work to make our bridge work with XCM messages. Old bridge is still
-available at [encoded-calls-messaging](https://github.com/paritytech/parity-bridges-common/releases/tag/encoded-calls-messaging)
-tag.
-
 ## Contents
 
 - [Installation](#installation)
@@ -97,7 +92,7 @@ description of the bridge interaction.
 
 ## Project Layout
 
-Here's an overview of how the project is laid out. The main bits are the `node`, which is the actual
+Here's an overview of how the project is laid out. The main bits are the `bin`, which is the actual
 "blockchain", the `modules` which are used to build the blockchain's logic (a.k.a the runtime) and
 the `relays` which are used to pass messages between chains.
 
@@ -106,16 +101,16 @@ the `relays` which are used to pass messages between chains.
 │  └── ...
 ├── deployments     // Useful tools for deploying test networks
 │  └──  ...
-├── diagrams        // Pretty pictures of the project architecture
-│  └──  ...
 ├── modules         // Substrate Runtime Modules (a.k.a Pallets)
+│  ├── beefy        // On-Chain BEEFY Light Client (in progress)
 │  ├── grandpa      // On-Chain GRANDPA Light Client
 │  ├── messages     // Cross Chain Message Passing
-│  ├── dispatch     // Target Chain Message Execution
+│  ├── parachains   // On-Chain Parachains Light Client
+│  ├── relayers     // Relayer rewards registry
 │  └──  ...
 ├── primitives      // Code shared between modules, runtimes, and relays
 │  └──  ...
-├── relays          // Application for sending headers and messages between chains
+├── relays          // Application for sending finality proofs and messages between chains
 │  └──  ...
 └── scripts         // Useful development and maintenance scripts
 ```
@@ -127,8 +122,11 @@ on each side of the bridge (source and target chain).
 
 There are 2 ways to run the bridge, described below:
 
-- building & running from source
-- running a Docker Compose setup (recommended).
+- building & running from source: with this option, you'll be able to run the bridge between two standalone
+chains that are running GRANDPA finality gadget to achieve finality;
+
+- running a Docker Compose setup: this is a recommended option, where you'll see bridges with parachains,
+complex relays and more.
 
 ### Using the Source
 
@@ -204,7 +202,33 @@ You will also see the message lane relayers listening for new messages.
 
 To send a message see the ["How to send a message" section](#how-to-send-a-message).
 
-### Full Network Docker Compose Setup
+### How to send a message
+
+In this section we'll show you how to quickly send a bridge message. The message is just an encoded XCM
+`Trap(43)` message.
+
+```bash
+# In `parity-bridges-common` folder
+./scripts/send-message-from-millau-rialto.sh
+```
+
+After sending a message you will see the following logs showing a message was successfully sent:
+
+```
+INFO bridge Sending message to Rialto. Size: 5.
+TRACE bridge Sent transaction to Millau node: 0x5e68...
+```
+
+And at the Rialto node logs you'll something like this:
+
+```
+... runtime::bridge-dispatch: Going to execute message ([0, 0, 0, 0], 1) (...), Trap(43)])    
+... runtime::bridge-dispatch: Incoming message ([0, 0, 0, 0], 1) dispatched with result: Incomplete(2000000000, Trap(43))    
+``` 
+
+It means that the message has been delivered and successfully dispatched.
+
+## Full Network Docker Compose Setup
 
 For a more sophisticated deployment which includes bidirectional header sync, message passing,
 monitoring dashboards, etc. see the [Deployments README](./deployments/README.md).
@@ -220,24 +244,6 @@ docker run -p 30333:30333 -p 9933:9933 -p 9944:9944 \
   --rpc-cors=all --unsafe-rpc-external --unsafe-ws-external
 ```
 
-### How to send a message
-
-In this section we'll show you how to quickly send a bridge message, if you want to
-interact with and test the bridge see more details in [send message](./docs/send-message.md)
-
-```bash
-# In `parity-bridges-common` folder
-./scripts/send-message-from-millau-rialto.sh remark
-```
-
-After sending a message you will see the following logs showing a message was successfully sent:
-
-```
-INFO bridge Sending message to Rialto. Size: 286. Dispatch weight: 1038000. Fee: 275,002,568
-INFO bridge Signed Millau Call: 0x7904...
-TRACE bridge Sent transaction to Millau node: 0x5e68...
-```
-
 ## Community
 
 Main hangout for the community is [Element](https://element.io/) (formerly Riot). Element is a chat

diff --git a/docs/complex-relay.html b/docs/complex-relay.html
@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width">
+		<title>Complex Relay</title>
+	</head>
+	<body>
+		<h1>Complex Relay</h1>
+		<p>
+			Both Source Chain and Target Chains have Bridge Messages pallets deployed. They also have required
+			finality pallets deployed - we don't care about finality type here - they can be either Bridge GRANDPA,
+			or Bridge Parachains finality pallets, or any combination of those.<br/>
+		</p>
+		<p>
+			There are 4-6 relayer subprocesses inside the Complex Relayer. They include two message relayers,
+			serving the lane in both directions and 2-4 Complex Relayers (depending on the finality type of Source
+			and Target Chains).<br/>
+		</p>
+		<p>
+			The following diagram shows the way the complex relayer serves the lane in single direction. Everything
+			below may be applied to the opposite direction if you'll swap the Source and Target Chains.
+		</p>
+		<div class="mermaid">
+			sequenceDiagram
+			participant Source Chain
+			participant Complex Relayer
+			participant Target Chain
+
+			Note right of Source Chain: Finalized: 480, Target Finalized: 50, Sent Messages: 42, Confirmed Messages: 42
+			Note left of Target Chain: Finalized: 60, Source Finalized: 420, Received Messages: 42
+
+			Source Chain ->> Source Chain: someone Sends Message 43
+			Source Chain ->> Source Chain: Import and Finalize Block 481
+
+			Source Chain ->> Complex Relayer: notes new outbound message 43 at Source Chain Block 481
+			Note right of Complex Relayer: can't deliver message 43, Source Chain Block 481 is not relayed
+			Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Source Chain Block 481
+
+			Source Chain ->> Complex Relayer: Read Finality Proof of Block 481
+			Complex Relayer ->> Target Chain: Submit Finality Proof of Block 481
+			Target Chain ->> Target Chain: Import and Finalize Block 61
+			Note left of Target Chain: Finalized: 61, Source Finalized: 481, Received Messages: 42
+
+			Source Chain ->> Complex Relayer: Read Proof of Message 43 at Block 481
+			Complex Relayer ->> Target Chain: Submit Proof of Message 43 at Block 481
+			Target Chain ->> Target Chain: Import and Finalize Block 62
+			Note left of Target Chain: Finalized: 62, Source Finalized: 481, Received Messages: { rewarded: 42, messages-relayer-account: [43] }
+
+			Target Chain ->> Complex Relayer: notes new unrewarded relayer at Target Chain Block 62
+			Note right of Complex Relayer: can't relay delivery confirmations because Target Chain Block 62 is not relayed
+			Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Target Chain Block 62
+
+			Target Chain ->> Complex Relayer: Read Finality Proof of Block 62
+			Complex Relayer ->> Source Chain: Submit Finality Proof of Block 62
+			Source Chain ->> Source Chain: Import and Finalize Block 482
+			Note right of Source Chain: Finalized: 482, Target Finalized: 62, Confirmed Messages: 42
+
+			Target Chain ->> Complex Relayer: Read Proof of Message 43 Delivery at Block 62
+			Complex Relayer ->> Source Chain: Submit Proof of Message 43 Delivery at Block 612
+			Source Chain ->> Source Chain: rewards messages-relayer-account for delivering message [43]
+			Source Chain ->> Source Chain: prune delivered message 43 from runtime storage
+			Note right of Source Chain: Finalized: 482, Target Finalized: 61, Confirmed Messages: 43
+
+			Source Chain ->> Source Chain: someone Sends Message 44
+			Source Chain ->> Source Chain: Import and Finalize Block 483
+
+			Source Chain ->> Complex Relayer: notes new outbound message 44 at Source Chain Block 483 and new confirmed message 43
+			Note right of Complex Relayer: can't deliver message 44, Source Chain Block 483 is not relayed
+			Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Source Chain Block 483
+
+			Source Chain ->> Complex Relayer: Read Finality Proof of Block 483
+			Complex Relayer ->> Target Chain: Submit Finality Proof of Block 483
+			Target Chain ->> Target Chain: Import and Finalize Block 63
+			Note left of Target Chain: Finalized: 63, Source Finalized: 483, Received Messages: { rewarded: 42, messages-relayer-account: [43] }
+
+			Source Chain ->> Complex Relayer: Read Proof of Message 44 and Proof of Message 43 reward at Block 483
+			Complex Relayer ->> Target Chain: Submit Proof of Message 44 and Proof of Message 43 reward at Block 483
+			Target Chain ->> Target Chain: Import and Finalize Block 64
+			Note left of Target Chain: Finalized: 64, Source Finalized: 483, Received Messages: { rewarded: 43, messages-relayer-account: [44] }-->
+		</div>
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@8.8.4/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({startOnLoad: true})</script>
+	</body>
+</html>
diff --git a/docs/grandpa-finality-relay.html b/docs/grandpa-finality-relay.html
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width">
+		<title>GRANDPA Finality Relay</title>
+	</head>
+	<body>
+		<h1>GRANDPA Finality Relay</h1>
+		<p>
+			Source Chain is running GRANDPA Finality Gadget. Bridge GRANDPA finality pallet is deployed at
+			Target Chain runtime. Relayer is configured to relay Source Chain finality to Target Chain.
+		</p>
+		<div class="mermaid">
+			sequenceDiagram
+			participant Source Chain
+			participant Relayer
+			participant Target Chain
+			Note left of Source Chain: Best: 500, Finalized: 480, Authorities Set Index: 42
+			Note right of Target Chain: Uninitialized
+
+			Source Chain ->> Relayer: Read Initialization Data
+			Relayer ->> Target Chain: Initialize Bridge GRANDPA Finality Pallet
+			Note right of Target Chain: Finalized: 480, Authorities Set Index: 42
+
+			Source Chain ->> Source Chain: Import Block 501
+			Source Chain ->> Source Chain: Import Block 502
+			Source Chain ->> Source Chain: Finalize Block 495
+			Source Chain ->> Relayer: Read Finality Proof of Block 495
+			Relayer ->> Target Chain: Finality Proof of Block 495
+			Note right of Target Chain: Finalized: 495, Authorities Set Index: 42
+
+			Source Chain ->> Source Chain: Import Block 503 that changes Authorities Set to 43
+			Source Chain ->> Source Chain: Finalize Block 500
+			Note left of Relayer: Relayer Misses Finality Notification for Block 500
+
+			Source Chain ->> Source Chain: Import Block 504
+			Source Chain ->> Source Chain: Finalize Mandatory Block 503
+			Source Chain ->> Source Chain: Finalize Block 504
+			Source Chain ->> Relayer: Read Finality Proof of Mandatory Block 503
+			Relayer ->> Target Chain: Finality Proof of Block 503
+			Note right of Target Chain: Finalized: 503, Authorities Set Index: 43
+		</div>
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@8.8.4/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({startOnLoad: true})</script>
+	</body>
+</html>