-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Bridge Hub preliminary docs * Add more info - DOT KSM bridge Ref - https://github.com/paritytech/polkadot-sdk/tree/master/bridges/docs * update DOT KSM bridge doc * Bridge Hub content update * DOT transfer to Kusama * Update docs/learn/learn-DOT-KSM-bridge.md Co-authored-by: Adrian Catangiu <[email protected]> * Update docs/learn/learn-guides-DOT-KSM-bridge.md Co-authored-by: Adrian Catangiu <[email protected]> * KSM transfer to Polkadot Asset Hub * augment KSM snapshot --------- Co-authored-by: Adrian Catangiu <[email protected]>
- Loading branch information
Showing
8 changed files
with
289 additions
and
0 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| --- | ||
| id: learn-dot-ksm-bridge | ||
| title: Polkadot <> Kusama Bridge | ||
| sidebar_label: DOT <> KSM Bridge | ||
| description: Overview of Polkadot and Kusama Bridge. | ||
| keywords: [Bridge, XCM, Bridge Hub] | ||
| slug: ../learn-dot-ksm-bridge | ||
| --- | ||
|
|
||
| Both Polkadot and Kusama blockchain networks achieve finality through GRANDPA consensus, which | ||
| enables trustless bridging of both the networks through their respective Bridge Hubs. Polkadot | ||
| Bridge Hub runs a [light client of Kusama network](https://polkadot.polkassembly.io/referenda/545) | ||
| and Kusama Bridge Hub runs a | ||
| [light client of Polkadot network](https://kusama.polkassembly.io/referenda/354), which were both | ||
| enabled through their respective OpenGov referenda. This trustless bridge allows Polkadot Asset Hub | ||
| to bridge in wrapped KSM tokens and Kusama Asset Hub to bridge in wrapped DOT tokens, thus making | ||
| DOT available to all Kusama parachains and KSM to all Polkadot parachains. | ||
|
|
||
| :::info Transferring Assets between Polkadot and Kusama | ||
|
|
||
| The user guides for transferring assets between Polkadot and Kusama are available | ||
| [here](./learn-guides-DOT-KSM-bridge.md). | ||
|
|
||
| ::: | ||
|
|
||
| ## Polkadot and Kusama Bridge Relayers | ||
|
|
||
| The job of the relayers is to relay Kusama/Polkadot GRANDPA justifications to the bridge hubs on one | ||
| side to the other. They also relay finalized Kusama Bridge Hub and Polkadot Bridge Hub block | ||
| headers. They operate only when messages are queued at the bridge hubs. When there are no messages | ||
| queued, the relayers stay idle. | ||
|
|
||
| ### Run a Polkadot and Kusama Bridge Relayer | ||
|
|
||
| Anyone can start running a relayer for the Polkadot < > Kusama Bridge. For instructions, check | ||
| [the relayer docs on Polkadot-SDK repository](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/docs/running-relayer.md). | ||
| Of course, running relayer has costs involved. Apart from paying for the CPU and network, the | ||
| relayer pays for transactions at both sides of the bridge. | ||
|
|
||
| ### Relayer Rewards | ||
|
|
||
| :::caution Relayer Incentive Mechanism - Work in Progress | ||
|
|
||
| The initial bridge design supports any number of relayers, but there's no guaranteed reward for each | ||
| and every relayer submitting valid bridge transactions. Also, these rewards are distributed from the | ||
| accounts controlled by the respective relay chain's governance. Hence, any delays in replenishing | ||
| the funds on these accounts will result in not receiving any rewards. | ||
|
|
||
| ::: | ||
|
|
||
| Rewards paid to relayer has two parts - static and dynamic. The static part of the reward is set | ||
| through the on-chain governance. It requires the relayer to deliver a preset number of valid | ||
| messages to earn a preset number of DOT or KSM. The other reward part is dynamic, which involves | ||
| delivering an XCM message from one BridgeHub to another. The relayer needs to submit transactions on | ||
| both the bridge hubs, where each transaction has its cost, which can be: | ||
|
|
||
| - dynamic, because message size can change and/or fee factor of the target chain may change. | ||
| - significant, because the bridge transactions can be of arbitrary size. | ||
|
|
||
| The relayers are compensated for the cost of submitting valid, minimal and useful bridge-related | ||
| transactions. Valid here means that the transaction doesn't fail. Minimal means that all data within | ||
| transaction call is actually required for the transaction to succeed. Useful means that all supplied | ||
| data in transaction is new and yet unknown to the target chain. | ||
|
|
||
| It is always the sending chain that will be paying for rewards for the relayers. The sending chain | ||
| will be paying at both ends of the bridge from its sovereign accounts on each Bridge Hub. For | ||
| example Polkadot Asset Hub (PAH) → Kusama Asset Hub (KAH) transfer will involve relayers getting | ||
| some rewards from PAH's sovereign account on Polkadot Bridge Hub (PBH) and some rewards from PAH's | ||
| sovereign account on Kusama Bridge Hub (KBH). It is the responsibility of Polkadot OpenGov to | ||
| replenish the funds of PAH's sovereign account on both the bridge hubs (PBH and KBH). Similarly, KAH | ||
| → PAH transfer is rewarded by KAH's sovereign accounts on PBH and KBH, which have to be replenished | ||
| through Kusama OpenGov. | ||
|
|
||
| For more information on relayer rewards, check the | ||
| [relayers compensation scheme section](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/docs/running-relayer.md#a-brief-introduction-into-relayers-and-our-compensations-scheme) | ||
| on the relayer docs on the Polkadot-SDK repository. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| --- | ||
| id: learn-bridge-hub | ||
| title: Bridge Hub | ||
| sidebar_label: Bridge Hub | ||
| description: Overview of Bridge Hub System Parachain. | ||
| keywords: [Bridge, XCM, Bridge Hub] | ||
| slug: ../learn-bridge-hub | ||
| --- | ||
|
|
||
| The primary functionality of {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay | ||
| chain is to secure the parachains and facilitate secure communication between them. All other | ||
| functionalities like asset transfers, governance, identities and especially bridging, which can be | ||
| resource intensive can benefit from operating seaparately on system parachains. That's why, the | ||
| Bridge Hub system parachain is operating on | ||
| {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} since 2023. The Bridge Hub has all | ||
| the required bridge pallets in its runtime, which enable trustless bridging with other blockchain | ||
| networks like {{ polkadot: Kusama :polkadot }}{{ kusama: Polkadot :kusama }}, Ethereum etc. The | ||
| Bridge Hub uses the native token of the relay chain, | ||
| {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. | ||
|
|
||
| ## Trustless Bridges on Bridge Hub | ||
|
|
||
| A two-way trustless bridge between chains A and B can be viewed as two one-way bridges (A → B and B | ||
| → A). Hence, the design of a two-way bridge can be explained in terms of a one-way bridge with a | ||
| source and a target chain. Any bridge operating on the Bridge Hub will have on-chain (pallets) and | ||
| offchain (relayers) components. | ||
|
|
||
| ### On-chain Bridge Components | ||
|
|
||
| On-chain bridge components are modules (pallets or smart contracts) that are deployed on the chain's | ||
| runtime. Modules that track the finality of the source chain are required to be deployed on the | ||
| target chain, while the modules that deal with cross-chain messaging need to be deployed on both, | ||
| source and target chains. | ||
|
|
||
| Operating a bridge between chains that finalize through GRANDPA consensus is straight-forward. A | ||
| GRANDPA light client of the source chain built into the target chain's runtime provides a "source of | ||
| truth" about the source chain's finality. For instance, Polkadot Bridge Hub runs an on-chain light | ||
| client of Kusama which uses GRANDPA consensus and infers the finality of all the transactions on | ||
| Kusama and its parachains. | ||
|
|
||
| Operating a bridge between chains with different consensus models can require a sophisticated | ||
| design. For instance, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Bridge Hub | ||
| needs to run an on-chain light client of Ethereum to infer the finality of transactions on Ethereum | ||
| chain. On the other hand, running a GRANDPA light client through smart contracts on Ethereum is | ||
| possible but can be very expensive. Hence, BEEFY (Bridge Efficiency Enabling Finality Yielder) | ||
| consensus layer has been added to {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} | ||
| which enables a cost effective solution for operating a trustless bridge with Ethereum. Trustless | ||
| bridges to chains like Solana, Cosmos, Avalanche, NEAR etc. would require custom pallets to be | ||
| deployed on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Bridge Hub. | ||
|
|
||
| There are also on-chain components that are responsible for queuing messages at the source chain and | ||
| for receiving the messages proofs at the target chain. The messages are sent through a particular | ||
| **lane**, where they are guaranteed to be received in the same order they are sent. On | ||
| {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Bridge Hub, the messages are in XCM | ||
| format and an XCM executor is used to dispatch them. | ||
|
|
||
| ### Offchain Bridge Components | ||
|
|
||
| Offchain bridge components are separate processes, called relayers. Relayers are connected both to | ||
| the source chain and target chain nodes. For instance, the task of relayer between chains that run | ||
| on GRANDPA consensus 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 relayer | ||
| subscribes to the source chain GRANDPA justifications stream and submits every new justification it | ||
| sees to the target chain GRANDPA light client. | ||
|
|
||
| Messages between chains are relayed through the relayers, which involve messages delivery relay and | ||
| delivery confirmation relay. For more information on relayers and the Bridge Hub design, read | ||
| through the | ||
| [high level documentation on bridges on the Polkadot-SDK repository](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/docs/high-level-overview.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| --- | ||
| id: learn-guides-dot-ksm-bridge | ||
| title: Polkadot and Kusama Bridge Guides | ||
| sidebar_label: DOT <> KSM Bridge | ||
| description: Polkadot-JS Guides about Polkadot and Kusama Bridge. | ||
| keywords: [Bridge, XCM, Bridge Hub, polkadot-js] | ||
| slug: ../learn-guides-dot-ksm-bridge | ||
| --- | ||
|
|
||
| <div className="sticky" style={{ zIndex: 1 }}> | ||
| <br /> | ||
|
|
||
| These guides are for developers and power users only. | ||
|
|
||
| </div> | ||
|
|
||
| The fully functional Polkadot < > Kusama bridge facilitates secure asset transfers between the | ||
| chains in both the ecosystems. The progress of Polkadot < > Kusama bridge implementation can be | ||
| tracked [here](https://forum.polkadot.network/t/polkadot-kusama-bridge/2971/1). | ||
|
|
||
| ## Transfer DOT to Kusama Asset Hub | ||
|
|
||
| This tutorial shows how to transfer DOT on Polkadot Asset Hub to Kusama Asset Hub. The first step is | ||
| to ensure that your account on Polkadot Asset Hub has enough DOT to cover the XCM transfer fee and | ||
| the bridge fee (which is around 2 DOT). The next step is to craft an XCM message to be sent from | ||
| Polkadot Asset Hub. | ||
|
|
||
| [BagPipes (formerly called xcmsend)](https://xcmsend.com/#/builder) is an opensource application | ||
| that lets you create workflows in a drag and drop style interface in order to build execution flows | ||
| of cross chain assets transfers using XCM. Check | ||
| [Bagpipes docs](https://xcmsend.github.io/workflows/dotksm.html) for more information on how to | ||
| create workflows for crafting XCM transfers. The snapshot below shows a workflow on BagPipes that is | ||
| designed to send 3 DOT from an account Polkadot Asset Hub to Kusama Asset Hub. | ||
|
|
||
|  | ||
|
|
||
| This workflow crafts an XCM transfer as shown below. | ||
|
|
||
| ``` | ||
| { | ||
| "isSigned": false, | ||
| "method": { | ||
| "args": { | ||
| "dest": { | ||
| "V3": { | ||
| "parents": "2", | ||
| "interior": { | ||
| "X2": [ | ||
| { | ||
| "GlobalConsensus": "Kusama" | ||
| }, | ||
| { | ||
| "Parachain": "1,000" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| }, | ||
| "beneficiary": { | ||
| "V3": { | ||
| "parents": "0", | ||
| "interior": { | ||
| "X1": { | ||
| "AccountId32": { | ||
| "network": null, | ||
| "id": "0x9e4e7009937c56d267338762a60ed004293afd40e7c2081847c12cb63c76a818" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "assets": { | ||
| "V3": [ | ||
| { | ||
| "id": { | ||
| "Concrete": { | ||
| "parents": "1", | ||
| "interior": "Here" | ||
| } | ||
| }, | ||
| "fun": { | ||
| "Fungible": "30,000,000,000" | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "fee_asset_item": "0", | ||
| "weight_limit": "Unlimited" | ||
| }, | ||
| "method": "limitedReserveTransferAssets", | ||
| "section": "polkadotXcm" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Once this [extrinsic](https://assethub-polkadot.subscan.io/extrinsic/6028374-2) is signed and | ||
| submitted, it is broadcast to Polkadot Asset Hub nodes. As this is a reserve asset transfer, the DOT | ||
| is transferred to the destination's sovereign account on Polkadot Asset Hub and | ||
| [the wrapped DOT is issued](https://assethub-kusama.subscan.io/extrinsic/6758392-0?event=6758392-1) | ||
| as a foreign asset and deposited onto the destination account on Kusama Asset Hub. The foreign asset | ||
| balances of any account on Kusama Asset Hub can be queried on-chain through the | ||
| `foreignAssets`pallet as shown below. | ||
|
|
||
|  | ||
|
|
||
| ## Transfer KSM to Polkadot Asset Hub | ||
|
|
||
| This tutorial shows how to transfer KSM on Kusama Asset Hub to Polkadot Asset Hub. The first step is | ||
| to ensure that your account on Kusama Asset Hub has enough KSM to cover the XCM transfer fee and the | ||
| bridge fee (which is around 0.4 KSM). The next step is to craft an XCM message to be sent from | ||
| Kusama Asset Hub. | ||
|
|
||
| The XCM transfer extrinsic shown below can be accessed | ||
| [here.](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-asset-hub-rpc.polkadot.io#/extrinsics/decode/0x1f08030202090200a10f03000101008479c8ea5480acca5a847133cd97a87801b6e698a98f2eab0e8e9d5c51b14a33030400010000070088526a740000000000) | ||
| If you plan on reusing this extrinsic, ensure that you change the Account ID and the transfer amount | ||
| highlighted in the snapshot below. | ||
|
|
||
|  | ||
|
|
||
| Once this [extrinsic](https://assethub-kusama.subscan.io/extrinsic/6761480-2) is signed and | ||
| submitted, it is broadcast to Kusama Asset Hub nodes. As this is a reserve asset transfer, the KSM | ||
| is transferred to the sovereign account on Kusama Asset Hub and | ||
| [the wrapped KSM is issued](https://assethub-polkadot.subscan.io/extrinsic/6031467-0?event=6031467-6) | ||
| as a foreign asset and deposited onto the destination account on Kusama Asset Hub. The foreign asset | ||
| balances of any account on Kusama Asset Hub can be queried on-chain through the | ||
| `foreignAssets`pallet as shown below. | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters