# Polkadot parachains options for using Polkadot<>Ethereum bridge (Snowbridge)
*(equivalent doc for P<>K bridge [here](https://hackmd.io/@acatangiu/B1oGPAQkkg))*
There are a few options available to parachains that want to make use of Snowbridge.
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 Ethereum tracking each other's consensus and finality - including Ethereum tracking finality of Polkadot parachains) currently running on Bridge Hub. While this is a major part of the bridge infrastructure, it is not exposed to parachain teams or builders, so not covered in this doc.
Also note that we decided to [expose builder-facing bridging components on Asset Hub](https://hackmd.io/@acatangiu/S1HfkItaA) for easier integrations. Bridge Hub has become "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 Ethereum assets.
Where "classic" means: reserve-based transfer, where _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**. Support for calling a function/smart-contract/etc on the other side while preserving the _original origin_ (actual caller).
4. **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).
5. **No (extra) offchain infrastructure** required. Once the parachain is configured on-chain, bridge "just works".
6. Parachain has **control over bridge traffic flow, QoS, pricing, latency**, etc.
## Option 1: Use AssetHub bridge lane
A **bridge lane** is a dedicated XCM transport channel between two chains on opposite sides of the bridge. Conceptually, it serves the same purpose as an HRMP channel between two sibling parachains.
Today, Snowbridge has such a lane deployed between AssetHub and Ethereum.
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 `Ethereum` and even transact on `Ethereum` as `ParaP/Alice` origin:
UserAgent (UI/wallet/etc) executes `XCM1` on `ParaP` using `Alice` signed account:
```rust
// 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 AH including custom logic
InitiateTransfer(
// send to AH
dest: AssetHub,
// 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 AH
remote_xcm: XCM(
// exchange TOK for some WETH for bridge fees
ExchangeAsset(TOK, WETH),
// initiate transfer to Ethereum including custom logic
InitiateTransfer(
// send to Ethereum
dest: Ethereum,
// send WETH to pay remote fees (on Ethereum)
remote_fee: ReserveWithdraw(WETH),
// include the other assets
assets: WhateverYouWant,
// executes on Ethereum
remote_xcm: XCM(
// transact on Ethereum as ParaP/Alice
Transact(Whatever),
// deposit all transferred assets to Bob on Ethereum
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 linked to in lower section [Parachain-integration-steps](#Parachain-integration-steps).*
### Properties
Satisfies [requirements 1, 2, 3, and 5](#Bridge-CapabilitiesRequirements). Can be "massaged" to support 4, but with some gotchas (covered in next section [Drawbacks](#Drawbacks)).
Supports **(1) "Bidirectional classic transfer"** by allowing native XCM transfers for assets understood/registered-on AssetHub and Ethereum. These assets are held in reserve on their native ecosystem on AssetHub, respectively Ethereum, and 1:1 derivatives are used on the other side.
Supports **(2) "Ecosystem recognizes/accepts the bridged assets"** because (bridged) assets registered on AssetHub are recognized and supported by the rest of the ecosystem.
Supports **(3) "XCM Transact support"** by being able to [persist the original origin](https://github.com/polkadot-fellows/RFCs/pull/122) across hops to the final destination. **Requires XCMv5**.
The _MAJOR_ advantage of this option is property **(5) "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 **big advantage** is that user agents (UIs, wallets, Phone apps, Web apps) that support this lane, automatically or very easily support all parachains using it. **Tooling will be more accessible**.
### Drawbacks
**(4) 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 AssetHub intermediate hop does 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 on AH, the inner TOK logic is "lost", TOKs are not automatically trapped on AssetHub.
Does **NOT** support **(6) "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 AssetHub (and existing relayers).
### Parachain integration steps
Detailed description of an example flow including fees calculation can be found in the [Snowbridge V2 design doc](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/docs/v2.md).
**TODO:** We will follow up with more details on:
- Relevant required parachain runtime configs.
## Option 2: Use dedicated bridge lane with AH as exporter
Snowfork team plans to support a feature where parachains on Polkadot can permissionlessly open dedicated bridge lanes with Ethereum. This would be deployed on AssetHub and it would be the functional equivalent of the [same feature on the P<>K bridge](https://hackmd.io/3ei1CQhnTBKHBXF3yi2IIg?view).
This feature/option **does not yet have** an estimated delivery date, but I expect it to be live by end of 2025.
A "dedicated bridge lane" is a **direct** *logical* XCM channel between the parachain and Ethereum, while using "AH as exporter" means the actual message transport still goes through AssetHub to make use of existing bridging logic there. Visualisation for it:
The dedicated lane uses AH as XCM exporter, meaning that XCMs destined for Ethereum are intercepted by a local [Bridge Router](https://github.com/paritytech/polkadot-sdk/tree/master/bridges/modules/xcm-bridge-hub-router) on source parachain, wrapped in an `ExportXCM` and sent to AssetHub for exporting to Ethereum. The Ethereum exporter on AssetHub will unwrap the original XCM and dispatch it to Ethereum 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 AssetHub hop is abstracted away by the deployed `Bridge Router` and by AssetHub machienery.
This is an example for an important usecase where **custom tokenomics** are supported between Polkadot parachain `ParaP` and Ethereum smart contract `ESC`, where the TOK token is fungible on both networks:
```rust
// following bridge-teleport only allowed for certain origins,
// e.g. TOK owner
XCM(
// withdraw native asset for fees and pay for transport and remote fees
WithdrawAsset(TOK),
PayFees(TOK),
// initiate a transfer directly to Ethereum including custom logic
InitiateTransfer(
// send to Ethereum
dest: Ethereum,
// teleport TOK over the bridge
remote_fee: Teleport(TOK, fee),
assets: Teleport(TOK, rest),
// executes on Ethereum
remote_xcm: XCM(
// deposit `rest` TOK to ESC on Ethereum
Deposit(All, ESC)
)
)
)
```
*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 example, one advantage is that the parachain has _direct_ XCM communication with Ethereum. The indirect hop through the exporter (AssetHub) is hidden away from the User Agent.
Satisfies [requirements 1, 3, 4](#Bridge-CapabilitiesRequirements).
The **major advantage** is easy support for **(4) Custom tokenomics**. The parachain team is free to impose any asset rules it wants. E.g. they can treat their native tokens as fungible between their Polkadot parachain and their Ethereum Smart Contract, allow teleporting them from one side to the other, thus effectively _merging_ them in a single unified asset, and **economically consolidate their multi-chain tokenomics and business**.
Supports **(1) "Bidirectional classic transfer"** by allowing native XCM transfers between the two chains. 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. ETOK (native to Ethereum) teleported to ParaP is minted on ParaP directly as PTOK (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"** as it allows direct XCM communication between chains.
### Drawbacks
Kind of a compromise between **(5) "No (extra) offchain infrastructure required"** and **(6) "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 *Snowfork 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 AssetHub as it happens with `Option 1`, because AssetHub 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:** @snowfork-team to publish these when design is complete.
Sign in with Wallet
Connect another wallet