Skip to content

Commit e43c999

Browse files
svyatonikacatangiu
svyatonik
and
acatangiu
authored
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 <[email protected]> * removed obsolete section * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * typo * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/high-level-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/polkadot-kusama-bridge-overview.md Co-authored-by: Adrian Catangiu <[email protected]> Co-authored-by: Adrian Catangiu <[email protected]>
1 parent bfa0a3f commit e43c999

8 files changed

+637
-151
lines changed

‎README.md

Lines changed: 37 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,6 @@ Substrate chains.
1010

1111
🚧 The bridges are currently under construction - a hardhat is recommended beyond this point 🚧
1212

13-
**IMPORTANT**: this documentation is outdated and it is mostly related to the previous version of our
14-
bridge. Right there's an ongoing work to make our bridge work with XCM messages. Old bridge is still
15-
available at [encoded-calls-messaging](https://github.com/paritytech/parity-bridges-common/releases/tag/encoded-calls-messaging)
16-
tag.
17-
1813
## Contents
1914

2015
- [Installation](#installation)
@@ -97,7 +92,7 @@ description of the bridge interaction.
9792

9893
## Project Layout
9994

100-
Here's an overview of how the project is laid out. The main bits are the `node`, which is the actual
95+
Here's an overview of how the project is laid out. The main bits are the `bin`, which is the actual
10196
"blockchain", the `modules` which are used to build the blockchain's logic (a.k.a the runtime) and
10297
the `relays` which are used to pass messages between chains.
10398

@@ -106,16 +101,16 @@ the `relays` which are used to pass messages between chains.
106101
│ └── ...
107102
├── deployments // Useful tools for deploying test networks
108103
│ └── ...
109-
├── diagrams // Pretty pictures of the project architecture
110-
│ └── ...
111104
├── modules // Substrate Runtime Modules (a.k.a Pallets)
105+
│ ├── beefy // On-Chain BEEFY Light Client (in progress)
112106
│ ├── grandpa // On-Chain GRANDPA Light Client
113107
│ ├── messages // Cross Chain Message Passing
114-
│ ├── dispatch // Target Chain Message Execution
108+
│ ├── parachains // On-Chain Parachains Light Client
109+
│ ├── relayers // Relayer rewards registry
115110
│ └── ...
116111
├── primitives // Code shared between modules, runtimes, and relays
117112
│ └── ...
118-
├── relays // Application for sending headers and messages between chains
113+
├── relays // Application for sending finality proofs and messages between chains
119114
│ └── ...
120115
└── scripts // Useful development and maintenance scripts
121116
```
@@ -127,8 +122,11 @@ on each side of the bridge (source and target chain).
127122

128123
There are 2 ways to run the bridge, described below:
129124

130-
- building & running from source
131-
- running a Docker Compose setup (recommended).
125+
- building & running from source: with this option, you'll be able to run the bridge between two standalone
126+
chains that are running GRANDPA finality gadget to achieve finality;
127+
128+
- running a Docker Compose setup: this is a recommended option, where you'll see bridges with parachains,
129+
complex relays and more.
132130

133131
### Using the Source
134132

@@ -204,7 +202,33 @@ You will also see the message lane relayers listening for new messages.
204202

205203
To send a message see the ["How to send a message" section](#how-to-send-a-message).
206204

207-
### Full Network Docker Compose Setup
205+
### How to send a message
206+
207+
In this section we'll show you how to quickly send a bridge message. The message is just an encoded XCM
208+
`Trap(43)` message.
209+
210+
```bash
211+
# In `parity-bridges-common` folder
212+
./scripts/send-message-from-millau-rialto.sh
213+
```
214+
215+
After sending a message you will see the following logs showing a message was successfully sent:
216+
217+
```
218+
INFO bridge Sending message to Rialto. Size: 5.
219+
TRACE bridge Sent transaction to Millau node: 0x5e68...
220+
```
221+
222+
And at the Rialto node logs you'll something like this:
223+
224+
```
225+
... runtime::bridge-dispatch: Going to execute message ([0, 0, 0, 0], 1) (...), Trap(43)])
226+
... runtime::bridge-dispatch: Incoming message ([0, 0, 0, 0], 1) dispatched with result: Incomplete(2000000000, Trap(43))
227+
```
228+
229+
It means that the message has been delivered and successfully dispatched.
230+
231+
## Full Network Docker Compose Setup
208232

209233
For a more sophisticated deployment which includes bidirectional header sync, message passing,
210234
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 \
220244
--rpc-cors=all --unsafe-rpc-external --unsafe-ws-external
221245
```
222246

223-
### How to send a message
224-
225-
In this section we'll show you how to quickly send a bridge message, if you want to
226-
interact with and test the bridge see more details in [send message](./docs/send-message.md)
227-
228-
```bash
229-
# In `parity-bridges-common` folder
230-
./scripts/send-message-from-millau-rialto.sh remark
231-
```
232-
233-
After sending a message you will see the following logs showing a message was successfully sent:
234-
235-
```
236-
INFO bridge Sending message to Rialto. Size: 286. Dispatch weight: 1038000. Fee: 275,002,568
237-
INFO bridge Signed Millau Call: 0x7904...
238-
TRACE bridge Sent transaction to Millau node: 0x5e68...
239-
```
240-
241247
## Community
242248

243249
Main hangout for the community is [Element](https://element.io/) (formerly Riot). Element is a chat

‎docs/complex-relay.html

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width">
6+
<title>Complex Relay</title>
7+
</head>
8+
<body>
9+
<h1>Complex Relay</h1>
10+
<p>
11+
Both Source Chain and Target Chains have Bridge Messages pallets deployed. They also have required
12+
finality pallets deployed - we don't care about finality type here - they can be either Bridge GRANDPA,
13+
or Bridge Parachains finality pallets, or any combination of those.<br/>
14+
</p>
15+
<p>
16+
There are 4-6 relayer subprocesses inside the Complex Relayer. They include two message relayers,
17+
serving the lane in both directions and 2-4 Complex Relayers (depending on the finality type of Source
18+
and Target Chains).<br/>
19+
</p>
20+
<p>
21+
The following diagram shows the way the complex relayer serves the lane in single direction. Everything
22+
below may be applied to the opposite direction if you'll swap the Source and Target Chains.
23+
</p>
24+
<div class="mermaid">
25+
sequenceDiagram
26+
participant Source Chain
27+
participant Complex Relayer
28+
participant Target Chain
29+
30+
Note right of Source Chain: Finalized: 480, Target Finalized: 50, Sent Messages: 42, Confirmed Messages: 42
31+
Note left of Target Chain: Finalized: 60, Source Finalized: 420, Received Messages: 42
32+
33+
Source Chain ->> Source Chain: someone Sends Message 43
34+
Source Chain ->> Source Chain: Import and Finalize Block 481
35+
36+
Source Chain ->> Complex Relayer: notes new outbound message 43 at Source Chain Block 481
37+
Note right of Complex Relayer: can't deliver message 43, Source Chain Block 481 is not relayed
38+
Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Source Chain Block 481
39+
40+
Source Chain ->> Complex Relayer: Read Finality Proof of Block 481
41+
Complex Relayer ->> Target Chain: Submit Finality Proof of Block 481
42+
Target Chain ->> Target Chain: Import and Finalize Block 61
43+
Note left of Target Chain: Finalized: 61, Source Finalized: 481, Received Messages: 42
44+
45+
Source Chain ->> Complex Relayer: Read Proof of Message 43 at Block 481
46+
Complex Relayer ->> Target Chain: Submit Proof of Message 43 at Block 481
47+
Target Chain ->> Target Chain: Import and Finalize Block 62
48+
Note left of Target Chain: Finalized: 62, Source Finalized: 481, Received Messages: { rewarded: 42, messages-relayer-account: [43] }
49+
50+
Target Chain ->> Complex Relayer: notes new unrewarded relayer at Target Chain Block 62
51+
Note right of Complex Relayer: can't relay delivery confirmations because Target Chain Block 62 is not relayed
52+
Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Target Chain Block 62
53+
54+
Target Chain ->> Complex Relayer: Read Finality Proof of Block 62
55+
Complex Relayer ->> Source Chain: Submit Finality Proof of Block 62
56+
Source Chain ->> Source Chain: Import and Finalize Block 482
57+
Note right of Source Chain: Finalized: 482, Target Finalized: 62, Confirmed Messages: 42
58+
59+
Target Chain ->> Complex Relayer: Read Proof of Message 43 Delivery at Block 62
60+
Complex Relayer ->> Source Chain: Submit Proof of Message 43 Delivery at Block 612
61+
Source Chain ->> Source Chain: rewards messages-relayer-account for delivering message [43]
62+
Source Chain ->> Source Chain: prune delivered message 43 from runtime storage
63+
Note right of Source Chain: Finalized: 482, Target Finalized: 61, Confirmed Messages: 43
64+
65+
Source Chain ->> Source Chain: someone Sends Message 44
66+
Source Chain ->> Source Chain: Import and Finalize Block 483
67+
68+
Source Chain ->> Complex Relayer: notes new outbound message 44 at Source Chain Block 483 and new confirmed message 43
69+
Note right of Complex Relayer: can't deliver message 44, Source Chain Block 483 is not relayed
70+
Complex Relayer ->> Complex Relayer: asks on-demand Finality Relayer to relay Source Chain Block 483
71+
72+
Source Chain ->> Complex Relayer: Read Finality Proof of Block 483
73+
Complex Relayer ->> Target Chain: Submit Finality Proof of Block 483
74+
Target Chain ->> Target Chain: Import and Finalize Block 63
75+
Note left of Target Chain: Finalized: 63, Source Finalized: 483, Received Messages: { rewarded: 42, messages-relayer-account: [43] }
76+
77+
Source Chain ->> Complex Relayer: Read Proof of Message 44 and Proof of Message 43 reward at Block 483
78+
Complex Relayer ->> Target Chain: Submit Proof of Message 44 and Proof of Message 43 reward at Block 483
79+
Target Chain ->> Target Chain: Import and Finalize Block 64
80+
Note left of Target Chain: Finalized: 64, Source Finalized: 483, Received Messages: { rewarded: 43, messages-relayer-account: [44] }-->
81+
</div>
82+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
83+
<script>mermaid.initialize({startOnLoad: true})</script>
84+
</body>
85+
</html>

‎docs/grandpa-finality-relay.html

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width">
6+
<title>GRANDPA Finality Relay</title>
7+
</head>
8+
<body>
9+
<h1>GRANDPA Finality Relay</h1>
10+
<p>
11+
Source Chain is running GRANDPA Finality Gadget. Bridge GRANDPA finality pallet is deployed at
12+
Target Chain runtime. Relayer is configured to relay Source Chain finality to Target Chain.
13+
</p>
14+
<div class="mermaid">
15+
sequenceDiagram
16+
participant Source Chain
17+
participant Relayer
18+
participant Target Chain
19+
Note left of Source Chain: Best: 500, Finalized: 480, Authorities Set Index: 42
20+
Note right of Target Chain: Uninitialized
21+
22+
Source Chain ->> Relayer: Read Initialization Data
23+
Relayer ->> Target Chain: Initialize Bridge GRANDPA Finality Pallet
24+
Note right of Target Chain: Finalized: 480, Authorities Set Index: 42
25+
26+
Source Chain ->> Source Chain: Import Block 501
27+
Source Chain ->> Source Chain: Import Block 502
28+
Source Chain ->> Source Chain: Finalize Block 495
29+
Source Chain ->> Relayer: Read Finality Proof of Block 495
30+
Relayer ->> Target Chain: Finality Proof of Block 495
31+
Note right of Target Chain: Finalized: 495, Authorities Set Index: 42
32+
33+
Source Chain ->> Source Chain: Import Block 503 that changes Authorities Set to 43
34+
Source Chain ->> Source Chain: Finalize Block 500
35+
Note left of Relayer: Relayer Misses Finality Notification for Block 500
36+
37+
Source Chain ->> Source Chain: Import Block 504
38+
Source Chain ->> Source Chain: Finalize Mandatory Block 503
39+
Source Chain ->> Source Chain: Finalize Block 504
40+
Source Chain ->> Relayer: Read Finality Proof of Mandatory Block 503
41+
Relayer ->> Target Chain: Finality Proof of Block 503
42+
Note right of Target Chain: Finalized: 503, Authorities Set Index: 43
43+
</div>
44+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
45+
<script>mermaid.initialize({startOnLoad: true})</script>
46+
</body>
47+
</html>

0 commit comments

Comments
 (0)