(equivalent doc for Polkadot<>Ethereum bridge here)
There are a few options available to parachains that want to make use of the Polkadot<>Kusama bridge.
This document lists and describes them starting from the easiest to integrate and most general-purpose, to more involved configurations that allow higher levels of customization on the bridge behavior.
Please note that there are components of the bridge not presented or covered by this document as they are already working live under the hood and are not exposed or meant to be used directly by ecosystem parachains.
One major such component is bridge consensus (Polkadot and Kusama tracking each other's consensus and finality - including tracking finality of the other side's parachains) currently running on Bridge Hub. This is useful to everyone but only directly exposed to parachain teams that deploy Option 3
listed further down in this document.
Also note that we decided to move builder-facing bridging components to Asset Hub for easier integrations. Bridge Hub is just "invisible infrastructure".
Let's first start with a list of capabilities/requirements; the exact subset of these requirements for your business use-case will also inform the best deployment option.
classic
: reserve-based transfer, meaning original assets are locked in the bridge while 1:1 derivatives are minted on the other side.Transact
support. Supports calling a function/smart-contract/etc on the other side while preserving the original origin (actual caller).A bridge lane is a dedicated XCM transport channel between two parachains on opposite sides of the bridge. Conceptually, it serves the same purpose as an HRMP channel between two sibling parachains.
Today, the P<>K bridge has such a lane deployed between PAH (Polkadot Asset Hub) and KAH (Kusama Asset Hub).
Making use of this existing lane is the easiest option for a parachain to expose the bridge to its users, while satisfying the vast majority of bridge usecases.
Example using XCMv5: Alice
on ParaP
can send any asset to ParaK
and even transact on ParaK
as ParaP/Alice
origin:
UserAgent (UI/wallet/etc) executes XCM1
on ParaP
using Alice
signed account:
Note: XCM programs described above do not contain the details of how to calculate and include exact fees, or how the program above actually works under the hood to make everything happen; that will be covered by separate documentation specific to this Option 1
.
Satisfies requirements 1, 2, 3, and 6.
Mostly supports 4 and can even be "massaged" to support 5, but with some gotchas (covered in next section Drawbacks).
Supports (1) "Bidirectional classic transfer" by allowing native XCM transfers for assets understood/registered-on AssetHub(s). These assets are held in reserve on the AssetHub of their native ecosystem, and 1:1 derivatives are used on the other side.
Supports (2) "Ecosystem recognizes/accepts the bridged assets" because (bridged) assets registered on Asset Hub are recognized and supported by the rest of the ecosystem.
Supports (3) "XCM Transact support" by being able to persist the original origin across hops to the final destination. Requires XCMv5.
Major advantage is property (6) "No (extra) offchain infrastructure required". By using the existing and already serviced AssetHub lane, parachains do not need to deploy or worry about incentivizing others to deploy offchain relayers.
Another potentially big advantage is that user agents (UIs, wallets, Phone apps, Web apps) that support this for one parachain pair, automatically support it for others too. Tooling will be more accessible.
Another advantage worth mentioning is that all hops along the way understand and explicitly process all assets, so if there is any error on any hop, that hop will successfully trap the assets, with an easy recovery mechanism.
Complicated XCM programs could be built to cover (4) "Full XCM support", but they would obviously be more complex having to go through multiple hops when compared to the same functional equivalent when going point to point.
(5) Custom tokenomics XCMs can be run on the final destination (e.g. ReceiveTeleportedAsset
to teleport over the bridge), but with the drawback that special care or error handling needs to be built for potential failures along the way.
The intermediate hops do not process the custom tokenomics logic meant for final destination, so for example, if you burn TOK on source then encapsulate a message to mint TOK on destination all is good as long as the final XCM reaches destination. If it errors out along the way, the inner TOK logic is "lost", TOKs are not automatically trapped on AssetHub(s).
Does not support (7) "control over bridge traffic flow, QoS, pricing, latency". All bridge traffic on the AssetHub lane is bulked together with no differentiation; pricing and latency are controlled by Asset Hub.
TODO: Cisco link doc with:
With upcoming polkadot-fellows/runtimes v1.4.x
(ETA EOY 2024) we are deploying a feature where parachains on Polkadot and Kusama can permissionlessly open dedicated bridge lanes between each other. As described in previous section, a "lane" is a direct logical XCM channel between two chains. Visualisation for it:
The dedicated lanes use AHs as XCM exporters, meaning that XCMs destined for the other parachain are intercepted by a local Bridge Router on source parachain, wrapped in an ExportXCM
and sent to local AssetHub for exporting to the other side. The other Asset Hub will unwrap the original XCM and dispatch it to the final destination while including some origin-altering instructions so that the original XCM executes with the original origin (e.g. ParaP/Alice
).
User agents (UIs/wallets/etc) can use the bridge as if there are no intermediary hops. The intermediary hops are abstracted away by the deployed Bridge Router
and by Asset Hub machienery.
To showcase a similar usecase as with first option:
Alice
on ParaP
reserve-transfers some asset to ParaK
and even transacts on ParaK
as ParaP/Alice
origin within same XCM (XCMv5):
Another important usecase showing custom tokenomics capability: ParaP
teleports (custom tokenomics) some asset to ParaK
(this time using only already available XCMv4 instructions):
Note: XCM programs described above do not contain the details of how to calculate and include exact fees, or how the program above actually works under the hood to make everything happen; that will be covered by separate documentation specific to this Option 2
.
As you can see from the examples, one advantage is that the two parachains have direct XCM communication. The indirect hops through the exporter are hidden away from the User Agent.
Satisfies requirements 1, 3, 4, 5.
The major advantage is easy support for (5) Custom tokenomics. The two parachains are free to impose any asset rules they want. E.g. they can treat their native tokens as fungible between each other, allow teleporting them from one side to the other, thus effectively merging them in a single unified asset.
Supports (1) "Bidirectional classic transfer" by allowing native XCM transfers between the two parachains. But any bridged assets are not recognized/accepted by the rest of the Ecosystem and do not integrate with Asset Hub. Note that teleported/translated/merged tokens (such as merged native tokens) do not suffer from this problem. E.g. KusamaTOK (native to ParaK) teleported to ParaP is minted on ParaP directly as PolkadotTOK (native to ParaP), it is not a bridged-asset really, each ecosystem on both sides of the bridge treats TOK as native (just that its total supply is split between the two ecosystems).
Supports (3) "XCM Transact support" and (4) "Full XCM support" as it allows direct XCM communication between chains.
Kind of a compromise between (6) "No (extra) offchain infrastructure required" and (7) "control over bridge traffic flow, QoS, pricing, latency" where you sort of get a bit of both.
Offchain infra is required, but it's standard software. E.g. parachain needs to deploy and run offchain relayer but doesn't need to maintain its code, can use the standard Parity relayer software.
By having a dedicated lane and dedicated offchain relayers, the parachain team can control the traffic flow and latency (maybe even pricing with some further enhancements).
Does not support (2) Ecosystem recognizes/accepts the bridged assets as described above. This option is useful for custom tokenomics for specific parachain-native assets but doesn't play well with general purpose ecosystem assets.
Another disadvantage worth mentioning is that if the parachain-bridge-router-generated-XCM fails to execute on the exporter (AssetHub), the inner/exported XCM is lost and any inner assets with it. They are not trapped on Asset Hub as it happens with Option 1
, because Asset Hub does not process or inspect the inner/exported XCM. However, in practice this should never happen once the parachain deploys a robust bridge-router that generates robust XCMs.
TODO: @bkontur link doc with:
This option is the most involved but also offers the highest amount of flexibility to parachain teams. It is similar to Option 2
, but on top of offering a direct logical XCM channel, it also offers a direct XCM transport channel between the two parachains. Visualisation:
The parachains directly deploy Bridge Message Pallets that create direct, point-to-point XCM communication between them.
User agents (UIs/wallets/etc) reference the other side as if it were a directly connected sibling chain.
Since the same direct logical XCM channel exists at the application/XCM level, the XCM capabilities are the same as with Option 2. The differences lie in XCM transport, as with this option, the parachain team controls and owns both the onchain and offchain transport mechanisms and components.
Other side's consensus information (progress, finality, etc) is still provided by Bridge Hub; pallet-bridge-messages
can subscribe to that directly so parachains don't need to build or maintain anything for that.
Same as Option 2
:
plus
Also since there are no other XCM hops involved, there are no failure points other than source and destination, with assets being automatically either returned, respectively trapped and easily recovered in any XCM use-case.
Far from (6) "No (extra) offchain infrastructure required". Parachain teams need to maintain significant amount of code both on-chain (pallet-messages) and off-chain (relayers). They also need to operate the offchain relayers.
This option is really only useful if the team needs (7) "control over bridge traffic flow, QoS, pricing, latency"; in which case it's obvious they actually want to operate their own messaging infrastructure and control
TODO: Serban link doc with: