pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-06-14 08:41:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial version of bridging pallets as git subtree (#2458)

Browse Source 
* Initial version of bridges pallet as subtree of https://github.com/paritytech/parity-bridges-common
Added `Bridges subtree files` pr review rule

* Squashed 'bridges/' content from commit d30927c08

git-subtree-dir: bridges
git-subtree-split: d30927c089bd9e73092d1ec1a62895603cb277a3

* Updated REAMDE.md and BRIDGES.md (inspired by original https://github.com/paritytech/polkadot/blob/d22eb62fe40e55e15eb91d375f48cc540d83a47e/BRIDGES.md)

* Squashed 'bridges/' changes from d30927c08..d3970944b

d3970944b Small simplifications (#2050)

git-subtree-dir: bridges
git-subtree-split: d3970944b0cfc4ea5226225e1ca07dab234c3556

* Squashed 'bridges/' changes from d3970944b..2180797fb

2180797fb Removed CODEOWNERS (#2051)

git-subtree-dir: bridges
git-subtree-split: 2180797fbf8a990490c67853dcffd81bc8dd083c

* Squashed 'bridges/' changes from 2180797fbf..4850aac8ce

4850aac8ce Removed relayer_account: &AccountId from MessageDispatch  (#2080)
8c8adafd54 Revert "Fix max-size messages at test chains (#2064)" (#2077)
c01a63efd8 Fixed off-by-one when confirming rewards in messages pallet (#2075)
a298be96aa Update subxt dependencies (#2072)
c0eef51eab Fix max-size messages at test chains (#2064)
3a658e3697 Messages relay fixes (#2073)
0022b5ab22 Slash relayers for invalid transactions (#2025)
198104007f Bump enumflags2 from 0.7.5 to 0.7.7
9229b257e5 [ci] Fix rules for docker build (#2069)
660d791390 [ci] Update buildah command and version (#2058)
e4535c0ca4 fix the way latest_confirmed_nonce_at_source is "calculated" (#2067)
dbc2d37590 select nothing if we have already selected nonces to submit or have submitted something (#2065)
a7eedd21fe [relay-substrate-client] Bump jsonrpsee (#2066)
8875d5aeae Bump clap from 4.2.2 to 4.2.4
25f9cf55e2 Another use of RangeInclusiveExt::checked_len() (#2060)
4942c12a5f submit lane unblock transactions from relay (#2030)
c0325d3c9c Test deployments fixes (#2057)
fc7b9b7ed7 Use the new matrix server (#2056)
63bcb5c10b Fixed delivery alert rule (#2052)

git-subtree-dir: bridges
git-subtree-split: 4850aac8ce6c34e5ca6246b88cd14c873a879cba

* Squashed 'bridges/' changes from 4850aac8ce..66aaf0dd23

66aaf0dd23 Nits (#2083)

git-subtree-dir: bridges
git-subtree-split: 66aaf0dd239dde40b64264061a77c921e2c82568

* Squashed 'bridges/' changes from 66aaf0dd23..557ecbcecc

557ecbcecc Fix sized messages (Follow-up on #2064) (#2103)
54f587a066 Add weight of refund extension post_dispatch to the weights of messages pallet (#2089)
5b1626f8c4 fix pallet param for nightly benchmarks check (#2099)
ae44c6b7a1 Add millau specific messages weights (#2097)
6ad0bd1f1e Add integrity tests to rialto parachain runtiime (#2096)
6919556de5 Bump tokio from 1.27.0 to 1.28.0
58795fcb75 Bump clap from 4.2.4 to 4.2.5
01bf31085b Bump scale-info from 2.5.0 to 2.6.0
8fe383240d Bump anyhow from 1.0.70 to 1.0.71
8d94e82ad5 deployments: add new BEEFY metrics and alarms (#2090)
e9a4749e7e Bump wasmtime from 6.0.1 to 6.0.2
9d9936c0d9 Bump wasmtime from 6.0.1 to 6.0.2 in /tools/runtime-codegen
5d77cd7bee Add more logs to relayer and message pallets (#2082)
75fbb9d3ef Update comment (#2081)
9904d09cf6 Benchmarks for new relayers pallet calls (#2040)

git-subtree-dir: bridges
git-subtree-split: 557ecbcecc585547b744a5ac9fb8d7f3b9de4521

* fmt

* Squashed 'bridges/' changes from 557ecbcecc..04b3dda6aa

04b3dda6aa Remove from subtree (#2111)
f8ff15e7e7 Add `MessagesPalletInstance` for integrity tests (#2107)
92ccef58e6 Use generated runtimes for BHR/BHW (#2106)
b33e0a585b Fix comment (#2105)

git-subtree-dir: bridges
git-subtree-split: 04b3dda6aa38599e612ff637710b6d2cff275ef3

* ".git/.scripts/commands/fmt/fmt.sh"

---------

Co-authored-by: parity-processbot <>
This commit is contained in:
Branislav Kontur
2023-05-04 08:36:58 +02:00
committed by GitHub
parent ee82e3f55b
commit 9e1afcafb5
114 changed files with 26856 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bridges/docs/complex-relay.html
+85
View File
@@ -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>
bridges/docs/grandpa-finality-relay.html
+47
View File
@@ -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>
bridges/docs/high-level-overview.md
+181
View File
@@ -0,0 +1,181 @@
# High-Level Bridge Documentation
This document gives a brief, abstract description of main components that may be found in this repository.
If you want to see how we're using them to build Rococo <> Wococo (Kusama <> Polkadot) bridge, please
refer to the [Polkadot <> Kusama Bridge](./polkadot-kusama-bridge-overview.md).
## Purpose
This repo contains all components required to build a trustless connection between standalone Substrate chains,
that are using GRANDPA finality, their parachains or any combination of those. On top of this connection, we
offer a messaging pallet that provides means to organize messages exchange.
On top of that layered infrastructure, anyone may build their own bridge applications - e.g. [XCM messaging](./polkadot-kusama-bridge-overview.md),
[encoded calls messaging](https://github.com/paritytech/parity-bridges-common/releases/tag/encoded-calls-messaging) and so on.
## Terminology
Even though we support (and require) two-way bridging, the documentation will generally talk about
a one-sided interaction. That's to say, we will only talk about syncing finality proofs and messages
from a _source_ chain to a _target_ chain. This is because the two-sided interaction is really just the
one-sided interaction with the source and target chains switched.
The bridge has both on-chain (pallets) and offchain (relayers) components.
## On-chain components
On-chain bridge components are pallets that are deployed at the chain runtime. Finality pallets require
deployment at the target chain, while messages pallet needs to be deployed at both, source
and target chains.
### Bridge GRANDPA Finality Pallet
A GRANDPA light client of the source chain built into the target chain's runtime. It provides a "source of truth"
about the source chain headers which have been finalized. This is useful for higher level applications.
The pallet tracks current GRANDPA authorities set and only accepts finality proofs (GRANDPA justifications),
generated by the current authorities set. The GRANDPA protocol itself requires current authorities set to
generate explicit justification for the header that enacts next authorities set. Such headers and their finality
proofs are called mandatory in the pallet and relayer pays no fee for such headers submission.
The pallet does not require all headers to be imported or provided. The relayer itself chooses which headers
he wants to submit (with the exception of mandatory headers).
More: [pallet level documentation and code](../modules/grandpa/).
### Bridge Parachains Finality Pallet
Parachains are not supposed to have their own finality, so we can't use bridge GRANDPA pallet to verify their
finality proofs. Instead, they rely on their relay chain finality. The parachain header is considered final,
when it is accepted by the [`paras` pallet](https://github.com/paritytech/polkadot/tree/1a034bd6de0e76721d19aed02a538bcef0787260/runtime/parachains/src/paras)
at its relay chain. Obviously, the relay chain block, where it is accepted, must also be finalized by the relay
chain GRANDPA gadget.
That said, the bridge parachains pallet accepts storage proof of one or several parachain heads, inserted to the
[`Heads`](https://github.com/paritytech/polkadot/blob/1a034bd6de0e76721d19aed02a538bcef0787260/runtime/parachains/src/paras/mod.rs#L642)
map of the [`paras` pallet](https://github.com/paritytech/polkadot/tree/1a034bd6de0e76721d19aed02a538bcef0787260/runtime/parachains/src/paras).
To verify this storage proof, the pallet uses relay chain header, imported earlier by the bridge GRANDPA pallet.
The pallet may track multiple parachains at once and those parachains may use different primitives. So the
parachain header decoding never happens at the pallet level. For maintaining the headers order, the pallet
uses relay chain header number.
More: [pallet level documentation and code](../modules/parachains/).
### Bridge Messages Pallet
The pallet is responsible for queuing messages at the source chain and receiving the messages proofs at the
target chain. The messages are sent to the particular _lane_, where they are guaranteed to be received in the
same order they are sent. The pallet supports many lanes.
The lane has two ends. Outbound lane end is storing number of messages that have been sent and the number of
messages that have been received. Inbound lane end stores the number of messages that have been received and
also a map that maps messages to relayers that have delivered those messages to the target chain.
The pallet has three main entrypoints:
- the `send_message` may be used by the other runtime pallets to send the messages;
- the `receive_messages_proof` is responsible for parsing the messages proof and handing messages over to the
dispatch code;
- the `receive_messages_delivery_proof` is responsible for parsing the messages delivery proof and rewarding
relayers that have delivered the message.
Many things are abstracted by the pallet:
- the message itself may mean anything, the pallet doesn't care about its content;
- the message dispatch happens during delivery, but it is decoupled from the pallet code;
- the messages proof and messages delivery proof are verified outside of the pallet;
- the relayers incentivization scheme is defined outside of the pallet.
Outside of the messaging pallet, we have a set of adapters, where messages and delivery proofs are regular
storage proofs. The proofs are generated at the bridged chain and require bridged chain finality. So messages
pallet, in this case, depends on one of the finality pallets. The messages are XCM messages and we are using
XCM executor to dispatch them on receival. You may find more info in [Polkadot <> Kusama Bridge](./polkadot-kusama-bridge-overview.md)
document.
More: [pallet level documentation and code](../modules/messages/).
### Bridge Relayers Pallet
The pallet is quite simple. It just registers relayer rewards and has an entrypoint to collect them. When
the rewards are registered and the reward amount is configured outside of the pallet.
More: [pallet level documentation and code](../modules/relayers/).
## Offchain Components
Offchain bridge components are separate processes, called relayers. Relayers are connected both to the
source chain and target chain nodes. Relayers are reading state of the source chain, compare it to the
state of the target chain and, if state at target chain needs to be updated, submits target chain
transaction.
### GRANDPA Finality Relay
The task of relay is to submit source chain GRANDPA justifications and their corresponding headers to
the Bridge GRANDPA Finality Pallet, deployed at the target chain. For that, the relay subscribes to
the source chain GRANDPA justifications stream and submits every new justification it sees to the
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), [pallet level documentation and code](../relays/finality/).
### Parachains Finality Relay
The relay connects to the source _relay_ chain and the target chain nodes. It doesn't need to connect to the
tracked parachain nodes. The relay looks at the [`Heads`](https://github.com/paritytech/polkadot/blob/1a034bd6de0e76721d19aed02a538bcef0787260/runtime/parachains/src/paras/mod.rs#L642)
map of the [`paras` pallet](https://github.com/paritytech/polkadot/tree/1a034bd6de0e76721d19aed02a538bcef0787260/runtime/parachains/src/paras)
in source chain, and compares the value with the best parachain head, stored in the bridge parachains pallet at
the target chain. If new parachain head appears at the relay chain block `B`, the relay process **waits**
until header `B` or one of its ancestors appears at the target chain. Once it is available, the storage
proof of the map entry is generated and is submitted to the target chain.
As its on-chain component (which requires bridge GRANDPA pallet to be deployed nearby), the parachains
finality relay requires GRANDPA finality relay to be running in parallel. Without it, the header `B` or
any of its children's finality at source won't be relayed at target, and target chain
won't be able to verify generated storage proof.
More: [Parachains Finality Relay Sequence Diagram](./parachains-finality-relay.html), [code](../relays/parachains/).
### Messages Relay
Messages relay is actually two relays that are running in a single process: messages delivery relay and
delivery confirmation relay. Even though they are more complex and have many caveats, the overall algorithm
is the same as in other relays.
Message delivery relay connects to the source chain and looks at the outbound lane end, waiting until new
messages are queued there. Once they appear at the source block `B`, the relay start waiting for the block
`B` or its descendant appear at the target chain. Then the messages storage proof is generated and submitted
to the bridge messages pallet at the target chain. In addition, the transaction may include the storage proof
of the outbound lane state - that proves that relayer rewards have been paid and this data (map of relay
accounts to the delivered messages) may be pruned from the inbound lane state at the target chain.
Delivery confirmation relay connects to the target chain and starts watching the inbound lane end. When new
messages are delivered to the target chain, the corresponding _source chain account_ is inserted to the
map in the inbound lane data. Relay detects that, say, at the target chain block `B` and waits until that
block or its descendant appears at the source chain. Once that happens, the relay crafts a storage proof of
that data and sends it to the messages pallet, deployed at the source chain.
As you can see, the messages relay also requires finality relay to be operating in parallel. Since messages
relay submits transactions to both source and target chains, it requires both _source-to-target_ and
_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), [pallet level documentation and code](../relays/messages/).
### Complex Relay
Every relay transaction has its cost. The only transaction, that is "free" to relayer is when the mandatory
GRANDPA header is submitted. The relay that feeds the bridge with every relay chain and/or parachain head it
sees, will have to pay a (quite large) cost. And if no messages are sent through the bridge, that is just
waste of money.
We have a special relay mode, called _complex relay_, where relay mostly sleeps and only submits transactions
that are required for the messages/confirmations delivery. This mode starts two message relays (in both
directions). All required finality relays are also started in a special _on-demand_ mode. In this mode they
do not submit any headers without special request. As always, the only exception is when GRANDPA finality
relay sees the mandatory header - it is submitted without such request.
The message relays are watching their lanes and when, at some block `B`, they see new messages/confirmations
to be delivered, they are asking on-demand relays to relay this block `B`. On-demand relays does that and
then message relay may perform its job. If on-demand relay is a parachain finality relay, it also runs its
own on-demand GRANDPA relay, which is used to relay required relay chain headers.
More: [Complex Relay Sequence Diagram](./complex-relay.html), [code](../relays/bin-substrate/src/cli/relay_headers_and_messages/).
bridges/docs/messages-relay.html
+78
View File
@@ -0,0 +1,78 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Messages Relay</title>
</head>
<body>
<h1>Messages 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.
</p>
<p>
Finality Relayer represents two actual relayers - one relays Source Chain Finality to Target Chain.
And another one relays Target Chain Finality to Source Chain.
</p>
<div class="mermaid">
sequenceDiagram
participant Source Chain
participant Finality Relayer
participant Messages 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 ->> Messages Relayer: notes new outbound message 43 at Source Chain Block 481
Note right of Messages Relayer: can't deliver message 43, Source Chain Block 481 is not relayed
Source Chain ->> Finality Relayer: Read Finality Proof of Block 481
Finality 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 ->> Messages Relayer: Read Proof of Message 43 at Block 481
Messages 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 ->> Messages Relayer: notes new unrewarded relayer at Target Chain Block 62
Note right of Messages Relayer: can't relay delivery confirmations because Target Chain Block 62 is not relayed
Target Chain ->> Finality Relayer: Read Finality Proof of Block 62
Finality 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 ->> Messages Relayer: Read Proof of Message 43 Delivery at Block 62
Messages 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 ->> Messages Relayer: notes new outbound message 44 at Source Chain Block 483 and new confirmed message 43
Note right of Messages Relayer: can't deliver message 44, Source Chain Block 483 is not relayed
Source Chain ->> Finality Relayer: Read Finality Proof of Block 483
Finality 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 ->> Messages Relayer: Read Proof of Message 44 and Proof of Message 43 reward at Block 483
Messages 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>
bridges/docs/parachains-finality-relay.html
+55
View File
@@ -0,0 +1,55 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Parachains Finality Relay</title>
</head>
<body>
<h1>Parachains Finality Relay</h1>
<p>
Source Relay Chain is running GRANDPA Finality Gadget. Source Parachain is a parachain of the Source
Relay Chain. Bridge GRANDPA finality pallet is deployed at Target Chain runtime and is "connected"
to the Source Relay Chain. Bridge Parachains finality pallet is deployed at Target Chain and is
configured to track the Source Parachain. GRANDPA Relayer is configured to relay Source Relay Chain
finality to Target Chain. Parachains Relayer is configured to relay Source Parachain headers finality
to Target Chain.
</p>
<div class="mermaid">
sequenceDiagram
participant Source Parachain
participant Source Relay Chain
participant GRANDPA Relayer
participant Parachains Relayer
participant Target Chain
Note left of Source Parachain: Best: 125
Note left of Source Relay Chain: Finalized: 500, Best Parachain at Finalized: 120
Note right of Target Chain: Best Relay: 480, Best Parachain: 110
Source Parachain ->> Source Parachain: Import Block 126
Source Parachain ->> Source Relay Chain: Receives the Parachain block 126
Source Relay Chain ->> Source Relay Chain: Import block 501
Source Relay Chain ->> Source Relay Chain: Finalize block 501
Note left of Source Relay Chain: Finalized: 501, Best Parachain at Finalized: 126
Source Relay Chain ->> Parachains Relayer: notes new Source Parachain Block 126
Note left of Parachains Relayer: can't relay Source Parachain Block 126, because it requires at least Source Relay Block 501 at Target Chain
Source Relay Chain ->> Source Relay Chain: Import block 502
Source Relay Chain ->> Source Relay Chain: Finalize block 502
Source Relay Chain ->> GRANDPA Relayer: read GRANDPA Finality Proof of Block 502
GRANDPA Relayer ->> Target Chain: submit GRANDPA Finality Proof of Block 502
Note right of Target Chain: Best Relay: 502, Best Parachain: 110
Target Chain ->> Parachains Relayer: notes finalized Source Relay Block 502 at Target Chain
Source Relay Chain ->> Parachains Relayer: read Parachain Finality Proof at Relay Block 502
Parachains Relayer ->> Target Chain: submit Parachain Finality Proof at Relay Block 502
Note right of Target Chain: Best Relay: 502, Best Parachain: 126
</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>
bridges/docs/polkadot-kusama-bridge-overview.md
+132
View File
@@ -0,0 +1,132 @@
# Polkadot <> Kusama Bridge Overview
This document describes how we use all components, described in the [High-Level Bridge Documentation](./high-level-overview.md),
to build the XCM bridge between Kusama and Polkadot. In this case, our components merely work as a XCM transport
(like XCMP/UMP/HRMP), between chains that are not a part of the same consensus system.
The overall architecture may be seen in [this diagram](./polkadot-kusama-bridge.html).
## Bridge Hubs
All operations at relay chain are expensive. Ideally all non-mandatory transactions must happen on parachains.
That's why we are planning to have two parachains - Polkadot Bridge Hub under Polkadot consensus and Kusama
Bridge Hub under Kusama consensus.
The Bridge Hub will have all required bridge pallets in its runtime. We hope that later, other teams will be able to
use our bridge hubs too and have their pallets there.
The Bridge Hub will use the base token of the ecosystem - KSM at Kusama Bridge Hub and DOT at Polkadot Bridge Hub.
The runtime will have minimal set of non-bridge pallets, so there's not much you can do directly on bridge hubs.
## Connecting Parachains
You won't be able to directly use bridge hub transactions to send XCM messages over the bridge. Instead, you'll need
to use other parachains transactions, which will use HRMP to deliver messages to the Bridge Hub. The Bridge Hub will
just queue these messages in its outbound lane, which is dedicated to deliver messages between two parachains.
Our first planned bridge will connect the Polkadot' Statemint and Kusama' Statemine. Bridge between those two
parachains would allow Statemint accounts to hold wrapped KSM tokens and Statemine accounts to hold wrapped DOT
tokens.
For that bridge (pair of parachains under different consensus systems) we'll be using the lane 00000000. Later,
when other parachains will join the bridge, they will be using other lanes for their messages.
## Running Relayers
We are planning to run our own complex relayer for the lane 00000000. The relayer will relay Kusama/Polkadot GRANDPA
justifications to the bridge hubs at the other side. It'll also relay finalized Kusama Bridge Hub and Polkadot Bridge
Hub heads. This will only happen when messages will be queued at hubs. So most of time relayer will be idle.
There's no any active relayer sets, or something like that. Anyone may start its own relayer and relay queued messages.
We are not against that and, as always, appreciate any community efforts. Of course, running relayer has the cost.
Apart from paying for the CPU and network, the relayer pays for transactions at both sides of the bridge. We have
a mechanism for rewarding relayers.
### Compensating the Cost of Message Delivery Transactions
One part of our rewarding scheme is that the cost of message delivery, for honest relayer, is zero. The honest relayer
is the relayer, which is following our rules:
- we do not reward relayers for submitting GRANDPA finality transactions. The only exception is submitting mandatory
headers (headers which are changing the GRANDPA authorities set) - the cost of such transaction is zero. The relayer
will pay the full cost for submitting all other headers;
- we do not reward relayers for submitting parachain finality transactions. The relayer will pay the full cost for
submitting parachain finality transactions;
- we compensate the cost of message delivery transactions that have actually delivered the messages. So if your
transaction has claimed to deliver messages `[42, 43, 44]`, but, because of some reasons, has actually delivered
messages `[42, 43]`, the transaction will be free for relayer. If it has not delivered any messages, then
the relayer pays the full cost of the transaction;
- we compensate the cost of message delivery and all required finality calls, if they are part of the same
[`frame_utility::batch_all`](https://github.com/paritytech/substrate/blob/891d6a5c870ab88521183facafc811a203bb6541/frame/utility/src/lib.rs#L326)
transaction. Of course, the calls inside the batch must be linked - e.g. the submitted parachain head must be used
to prove messages. Relay header must be used to prove parachain head finality. If one of calls fails, or if they
are not linked together, the relayer pays the full transaction cost.
Please keep in mind that the fee of "zero-cost" transactions is still withdrawn from the relayer account. But the
compensation is registered in the `pallet_bridge_relayers::RelayerRewards` map at the target bridge hub. The relayer
may later claim all its rewards later, using the `pallet_bridge_relayers::claim_rewards` call.
*A side note*: why we don't simply set the cost of useful transactions to zero? That's because the bridge has its cost.
If we won't take any fees, it would mean that the sender is not obliged to pay for its messages. And Bridge Hub
collators (and, maybe, "treasury") are not receiving any payment for including transactions. More about this later,
in the [Who is Rewarding Relayers](#who-is-rewarding-relayers) section.
### Message Delivery Confirmation Rewards
In addition to the "zero-cost" message delivery transactions, the relayer is also rewarded for:
- delivering every message. The reward is registered during delivery confirmation transaction at the Source Bridge
Hub.;
- submitting delivery confirmation transaction. The relayer may submit delivery confirmation that e.g. confirms
delivery of four messages, of which the only one (or zero) messages is actually delivered by this relayer. It
receives some fee for confirming messages, delivered by other relayers.
Both rewards may be claimed using the `pallet_bridge_relayers::claim_rewards` call at the Source Bridge Hub.
### Who is Rewarding Relayers
Obviously, there should be someone who is paying relayer rewards. We want bridge transactions to have a cost, so we
can't use fees for rewards. Instead, the parachains using the bridge, use sovereign accounts on both sides
of the bridge to cover relayer rewards.
Bridged Parachains will have sovereign accounts at bridge hubs. For example, the Statemine (Kusama Parachain) will
have an account at the Polkadot Bridge Hub. The Statemint (Polkadot Parachain) will have an account at the Kusama
Bridge Hub. The sovereign accounts are used as a source of funds when the relayer is calling the
`pallet_bridge_relayers::claim_rewards`.
Since messages lane is only used by the pair of parachains, there's no collision between different bridges. E.g.
Statemine will only reward relayers that are delivering messages from Statemine. The Statemine sovereign account
is not used to cover rewards of bridging with some other Polkadot Parachain.
### Multiple Relayers and Rewards
Our goal is to incentivize running honest relayers. But we have no relayers sets, so at any time anyone may submit
message delivery transaction, hoping that the cost of this transaction will be compensated. So what if some message is
currently queued and two relayers are submitting two identical message delivery transactions at once? Without any
special means, the cost of first included transaction will be compensated and the cost of the other one won't. A honest,
but unlucky relayer will lose some money. In addition, we'll waste some portion of block size and weight, which
may be used by other useful transactions.
To solve the problem, we have two signed extensions ([generate_bridge_reject_obsolete_headers_and_messages! {}](../bin/runtime-common/src/lib.rs)
and [RefundRelayerForMessagesFromParachain](../bin/runtime-common/src/refund_relayer_extension.rs)), that are
preventing bridge transactions with obsolete data from including into the block. We are rejecting following
transactions:
- transactions, that are submitting the GRANDPA justification for the best finalized header, or one of its ancestors;
- transactions, that are submitting the proof of the current best parachain head, or one of its ancestors;
- transactions, that are delivering already delivered messages. If at least one of messages is not yet delivered,
the transaction is not rejected;
- transactions, that are confirming delivery of already confirmed messages. If at least one of confirmations is new,
the transaction is not rejected;
- [`frame_utility::batch_all`](https://github.com/paritytech/substrate/blob/891d6a5c870ab88521183facafc811a203bb6541/frame/utility/src/lib.rs#L326)
transactions, that have both finality and message delivery calls. All restrictions from the
[Compensating the Cost of Message Delivery Transactions](#compensating-the-cost-of-message-delivery-transactions)
are applied.
bridges/docs/polkadot-kusama-bridge.html
+67
View File
@@ -0,0 +1,67 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Polkadot &lt;&gt; Kusama Bridge</title>
</head>
<body>
<h1>Polkadot &lt;&gt; Kusama Bridge</h1>
<p>
Our bridge connects two parachains - Kusama Bridge Hub and Polkadot Bridge Hub. Messages that
are sent over bridge have XCM format and we are using existing architecture to dispatch them.
Since both Polkadot, Kusama and their parachains already have means to exchange XCM messages
within the same consensus system (HRMP, VMP, ...), it means that we are able to connect all those
chains with our bridge.
</p>
<p>
In our architecture, the lane that is used to relay messages over the bridge is determined by
the XCM source and destinations. So e.g. bridge between Statemint and Statemine (and opposite direction)
will use the lane 00000000, bridge between some other Polkadot Parachain and some other Kusama Parachain
will use the lane 00000001 and so on.
</p>
<div class="mermaid">
flowchart LR
subgraph Polkadot Consensus
polkadot(((Polkadot)))
statemint(((Statemint)))
polkadot_bh(((Polkadot Bridge Hub)))
polkadot---statemint
polkadot---polkadot_bh
statemint-->|Send Message Using HRMP|polkadot_bh
polkadot_bh-->|Send Message Using HRMP|statemint
statemint-->|Dispatch the Message|statemint
end
subgraph Kusama Consensus
kusama_bh(((Kusama Bridge Hub)))
statemine(((Statemine)))
kusama(((Kusama)))
kusama---statemine
kusama---kusama_bh
kusama_bh-->|Send Message Using HRMP|statemine
statemine-->|Dispatch the Message|statemine
statemine-->|Send Message Using HRMP|kusama_bh
end
polkadot_bh&lt;===&gt;|Message is relayed to the Bridged Chain using lane 00000000|kusama_bh
linkStyle 2 stroke:red
linkStyle 7 stroke:red
linkStyle 8 stroke:red
linkStyle 3 stroke:green
linkStyle 4 stroke:green
linkStyle 9 stroke:green
</div>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>
</html>