DotSama parachains options for using Polkadot<>Kusama bridge

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 Expose builder-facing bridging components on 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 (parachains’) business use-case will also inform the best deployment option.

Bridge Capabilities/Requirements

  1. Bidirectional “classic” transfer for any Polkadot or Kusama assets.
    classic: reserve-based transfer, meaning original assets are locked in the bridge while 1:1 derivatives are minted on the other side.
  2. The rest of the Ecosystem recognizes/accepts the bridged assets.
  3. XCM Transact support. Supports calling a function/smart-contract/etc on the other side while preserving the original origin (actual caller).
  4. Full XCM support. Any operation that works between two sibling parachains, also works over the bridge (although this sounds easy, fees handling makes this hard in practice).
  5. Custom tokenomics for particular assets. E.g. effectively merge two assets on separate sides by treating them as fungible, or teleporting them over the bridge (burn & mint mechanism, nothing locked in the bridge).
  6. No (extra) offchain infrastructure required. Once the parachain is configured on-chain, bridge “just works”.
  7. Parachain has control over bridge traffic flow, QoS, pricing, latency, etc.
4 Likes

Option 1: Use AssetHub(s) bridge lane

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:

// executes on ParaP with Alice local origin
XCM(
    // withdraw assets for transfer
    WithdrawAsset(WhateverYouWant),
    // withdraw native asset for fees and pay for transport
    WithdrawAsset(TOK),
    PayFees(TOK),
    // initiate a transfer to PAH including custom logic
    InitiateTransfer(
        // send to PAH
        dest: PolkadotAssetHub,
        // teleport TOK if registered as foreign asset,
        // reserve-transfer otherwise, to pay fees (on PAH)
        remote_fee: ReserveDeposit/Teleport(TOK),
        // include the other assets
        assets: WhateverYouWant,
        // executes on PAH
        remote_xcm: XCM(
            // exchange TOK for some DOT for fees
            ExchangeAsset(TOK, DOT),
            // initiate transfer to KAH including custom logic
            InitiateTransfer(
                // send to KAH
                dest: KusamaAssetHub,
                // send DOT to pay remote fees (on KAH)
                remote_fee: ReserveDeposit(DOT),
                // include the other assets
                assets: WhateverYouWant,
                // executes on KAH
                remote_xcm: XCM(
                    // exchange DOT for some KSM for fees
                    ExchangeAsset(DOT, KSM),
                    // initiate transfer to ParaK including custom logic
                    InitiateTransfer(
                        // send KSM to pay remote fees (on ParaP)
                        remote_fee: ReserveDeposit(KSM),
                        // include any other assets
                        assets: WhateverYouWant,
                        // executes on ParaK
                        remote_xcm: XCM(
                            // transact on ParaK as ParaP/Alice
                            Transact(Whatever),
                            // refund any fees not spent
                            RefundSurplus,
                            // deposit all remaining assets to Bob on ParaK
                            Deposit(All, Bob)
                        )
                    )
                )
            )
        )
    )
)

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.

Properties

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.

Drawbacks

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.

Parachain integration steps

TODO: We will follow up with documentation detailing:

  • Relevant runtime configs required,
  • Example flow including fees calculation,
    • from the point of view of the User Agent (how to build program, how to calculate fees),
    • from the point of view of the involved chains once it executes.
1 Like

Option 2: Use dedicated bridge lane with AH as exporter

With upcoming polkadot-fellows/runtimes v1.4.x (ETA Q1 2025) 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):

// executes on ParaP with Alice local origin
XCM(
    // withdraw assets for transfer
    WithdrawAsset(WhateverYouWant),
    // withdraw native asset for fees and pay for transport
    WithdrawAsset(TOK),
    PayFees(TOK),
    // initiate a transfer directly to ParaK including custom logic
    InitiateTransfer(
        // send to Kusama/ParaK
        dest: Kusama/ParaK,
        // teleport TOK over the bridge
        remote_fee: Teleport(TOK),
        // include the other assets
        assets: WhateverYouWant,
        // executes on Kusama/ParaK
        remote_xcm: XCM(
            // transact on ParaK as ParaP/Alice
            Transact(Whatever),
            // refund any fees not spent
            RefundSurplus,
            // deposit all remaining assets to Bob on ParaK
            Deposit(All, Bob)
        )
    )
)

Another important usecase showing custom tokenomics capability: ParaP teleports (custom tokenomics) some asset to ParaK (this time using only already available XCMv4 instructions):

// executes on ParaP
XCM(
    // withdraw native asset for transferring
    WithdrawAsset(TOK),
    // initiate teleport to Kusama/ParaK
    InitiateTeleport(
        dest: Kusama/ParaK,
        assets: TOK,
        // executes on Kusama/ParaK
        remote_xcm: XCM(
            // buy execution on ParaK
            BuyExecution(TOK)
            // deposit all remaining assets to Bob on ParaK
            Deposit(All, Bob)
        )
    )
)

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.

Properties

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.

Drawbacks

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.

Parachain integration steps

TODO: We will follow up with documentation detailing:

  • Relevant components required by parachains to add to their runtimes,
  • Relevant parachain runtime configs required,
  • Example flow including fees calculation,
    • from the point of view of the User Agent (how to build program, how to calculate fees),
    • from the point of view of the involved chains once it executes,
  • Documentation on how to run a messages relayer for a dedicated lane.

Option 3: Use dedicated bridge lane with local custom exporter

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.

Properties

Same as Option 2:

  • (1) “Bidirectional classic transfer”,
  • (3) “XCM Transact support”,
  • (4) “Full XCM support”,
  • (5) Custom tokenomics,

plus

  • (7) “control over bridge traffic flow, QoS, pricing, latency”.

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.

Drawbacks

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 and control their own messaging infrastructure.

Parachain integration steps

TODO: We will follow up with documentation detailing:

  • Relevant components required by parachains to add to their runtimes,
  • Relevant parachain runtime configs required,
  • Example flow including fees calculation,
    • from the point of view of the User Agent (how to build program, how to calculate fees),
    • from the point of view of the involved chains once it executes,
  • Documentation on how to run the Parity messages relayer for their lane, with explanation that they probably want to run their own relayer implementation if they chose this option - to be able to control QoS, pricing, latency, etc.
2 Likes

There is also an equivalent guide/thread covering the Polkadot<>Ethereum Snowbridge: Polkadot parachains options for using Polkadot<>Ethereum bridge (Snowbridge)