Skip to content

Latest commit

 

History

History
356 lines (274 loc) · 13 KB

v2.md

File metadata and controls

356 lines (274 loc) · 13 KB
Raw

Snowbridge V2

This design lowers fees, improves UX, improves relayer decentralization and allows "transacting" over the bridge, making it a general-purpose bridge rather than just a token bridge.

We're grateful to Adrian Catangiu, Francisco Aguirre, and others from the Parity XCM/Bridges team for their help and collaboration on this design.

Summary

  • Unordered messaging
  • All messages routed through AH
  • Off-chain fee estimation
  • P→E Fee Asset: WETH
  • E→P Fee Asset: ETH
  • Relayer rewards for both directions paid out on AH in WETH

Polkadot→Ethereum

Given source parachain $S$, with native token $S^{'}$ and the initial xcm $x_0$ to be executed on $S$.

Step 1: User agent constructs initial XCM

The user agent constructs an initial XCM message $x_0$ that will be executed on S.

The fee amounts in this message should be high enough to enable dry-running, after which they will be lowered.

Step 2: User agent estimates fees

  • Given source parachain $S$, with native token $S^{'}$ and the initial xcm $x_0$ to be executed on $S$.
  • The native currency $P^{'}$ (DOT) of the Polkadot relay chain, and $E^{'}$ (ETH) of Ethereum.
  • Suppose that the user agent chooses relayer reward $r$ in $E^{'}$.
  • Suppose that the exchange rates are $K_{P^{'}/S^{'}}$ and $K_{E^{'}/S^{'}}$. The user agent chooses a multiplier to $\beta$ to cover volatility in these rates.

Apply the following sequence operations:

  1. Dry-run $x_0$ on $S$ to receive xcm $x_1$ and cost $a$ in $S^{'}$
  2. Dry-run $x_1$ on AH to receive xcm $x_2$ and cost $b$ in $P^{'}$ (DOT)
  3. Dry-run $x_2$ on BH to receive command $m$ and cost $c$ in $P^{'}$ (DOT)
  4. Dry-run $m$ on Ethereum to receive cost $d$ in $E^{'}$ (ETH)

The final cost to the user in $S^{'}$ is given by

$$ \beta \left(a + \frac{b + c}{K_{P^{'}/S^{'}}} + \frac{d + r}{K_{E^{'}/S^{'}}}\right) $$

The user agent should perform a final update to xcm $x_0$, substituting the calculated fee amounts.

Step 3: User agent initiates bridging operation

The user agent calls pallet_xcm::execute with the initial xcm $x_0$

WithdrawAsset (KLT, 100)
PayFees (KLT, 20)
InitiateAssetsTransfer asset=(KLT, 60) remoteFee=(KLT, 20) dest=AH
  ExchangeAsset give=(KLT, 20) want=(WETH, 1)
  InitiateAssetsTransfer asset=(KLT, 40) remoteFee=(WETH, 1) dest=Ethereum
    DepositAsset (KLT, 40) beneficiary=Bob

Step 4: AH executes message x1

The message $x_1$ is application-specific:

ReserveAssetDeposited (KLT, 80)
PayFees (KLT, 20)
SetAssetClaimer Kilt/Alice
AliasOrigin Kilt/Alice
ExchangeAsset give=(KLT, 20) want=(WETH, 1)
InitiateAssetsTransfer asset=(KLT, 60) remoteFee=(WETH, 1) dest=Ethereum
  DepositAsset (KLT, 60) beneficiary=Bob

or

*ReserveAssetDeposited (KLT, 80)
*PayFees (KLT, 20)
*SetAssetClaimer Kilt/Alice
*AliasOrigin Kilt/Alice
ExchangeAsset give=(KLT, 20) want=(WETH, 1)
InitiateAssetsTransfer asset=(KLT, 60) remoteFee=(WETH, 1) dest=Ethereum
  DepositAsset (KLT, 60) beneficiary=Bob
  Transact Bob.hello()

Note that the SetAssetClaimer instruction is placed before AliasOrigin in case AH fails to interpret the latter instruction.

In all cases, $x_1$ should contain the necessary instructions to:

  1. Pay fees for local execution using PaysFees
  2. Obtain WETH for remote delivery fees.

The XCM bridge-router on AH will charge a small fee to prevent spamming BH with bridge messages. This is necessary since the ExportMessage instruction in message $x_2$ will have no execution fee on BH. For a similar reason, we should also impose a minimum relayer reward of at least the existential deposit 0.1 DOT, which acts as a deposit to stop spamming messages with 0 rewards.

Step 5: BH executes message x2

Message $x_2$ is parsed by the SnowbridgeMessageExporter in block $n$ with the following effects:

  • A bridge command $m$ is committed to binary merkle tree $M_n$.
    • The transferred asset is parsed from ReserveAssetDeposited , WithdrawAsset or TeleportedAssetReceived instructions for the local, destination and teleport asset transfer types respectively.
    • The original origin is preserved through the AliasOrigin instruction. This will allow us to resolve agents for the case of Transact.
    • The message exporter must be able to support multiple assets and reserve types in the same message and potentially multiple Transacts.
    • The Message Exporter must be able to support multiple Deposited Assets.
    • The Message Exporter must be able to parse SetAssetClaimer and allow the provided location to claim the assets on BH in case of errors.
  • Given relayer reward $r$ in WETH, set storage $P(\mathrm{hash}(m)) = r$. This is parsed from the WithdrawAsset and PayFees instruction within ExportMessage.

Note that WETH on AH & BH is a wrapped derivative of the WETH ERC20 contract on Ethereum, which is itself a wrapper over ETH, the native currency of Ethereum. For the purposes of this document you can consider them all to be of equivalent value.

!WithdrawAsset(DOT, 10)
!PayFees (DOT, 10)
!ExportMessage dest=Ethereum
  *ReserveAssetDeposited (KLT, 60)
  *WithdrawAsset (WETH, 1)
  *PayFees (WETH, 1)
  *SetAssetClaimer Kilt/Alice
  *AliasOrigin Kilt/Alice
  DepositAsset (KLT, 60) beneficiary=Bob

or

!WithdrawAsset(DOT, 10)
!PayFees (DOT, 10)
!ExportMessage dest=Ethereum
  *ReserveAssetDeposited (KLT, 80)
  *PayFees (KLT, 20)
  *SetAssetClaimer Kilt/Alice
  *AliasOrigin Kilt/Alice
  DepositAsset (KLT, 60) beneficiary=Bob
  Transact Bob.hello()

Step 6: Relayer relays message to Gateway

  1. A relayer Charlie inspects storage $P$ to look for new messages to relay. Suppose it finds $\mathrm{hash}(m)$ giving reward $r$.
  2. The relayer queries $m$ from $M$ and constructs the necessary proofs.
  3. The relayer dry-runs m on Ethereum to decide whether the message is profitable to deliver.
  4. The relayer finally delivers the message together with a relayer-controlled address $u$ on AH where the relayer can claim their reward after proof of delivery.

Step 7: Relayer delivers proof of delivery to BH

The proof of delivery is essentially a merkle proof for the InboundMessageAccepted event log.

When BH processes the proof of delivery:

  1. The command $m$ is removed from storage items $M$ and $P$.
  2. The relayer reward is tracked in storage $R$, where $R(u)$ is the accumulated rewards that can be claimed by account $u$.

Ethereum→Polkadot

Step 1: Submit send on Gateway

The interface that the Gateway will use to initiate transfers will be similar to the interface from transfer_assets_using_type_and_then extrinsic that we currently use to initiate transfers from the Polkadot to Ethereum direction.

  1. It must allow multiple assets to be transferred and specify the transfer type: Local, Destination or Teleport asset transfer types. It is the job of the User Agent/UX layer to fill in this information correctly.
  2. It must allow specifying a destination which is Address32, Address20 or a custom scale-encoded XCM payload that is executed on the destination. This is how we will support Transact , the User Agent/UX layer can build a scale-encoded payload with an encoded transact call.
  3. The same interface is used for both PNA (Polkadot Assets) and ERC20 tokens. Internally we will still look up whether the token is registered as a PNA or ERC20 for the purpose of minting/locking burning/unlocking logic. The asset transfer type chosen by the UX layer will inform the XCM that is built from the message on BH.
enum Kind {
    Index,
    Address32,
    Address20,
    XCMPayload,
}

struct Beneficiary {
    Kind kind;
    bytes data;
}

enum AssetTransferType {
    ReserveDeposit, ReserveWithdraw, Teleport
}

struct Token {
    AssetTransferType type;
    address token;
    uint128 amount;
}

function send(
  ParaID destinationChain,
  Beneficiary calldata beneficiary,
  Token[] tokens,
  uint128 reward
) external payable;

Message enqueued $m_0$:

send(
    3022, // KILT Para Id
    Address32(0x0000....),
    [(ReserveWithdraw, KLT, 100)],
    10, // WETH
)
send { value: 3 }( // Send 3 Eth for fees and reward
    3022, // KILT Para Id
    XCMPayload(
        DepositAsset (KLT, 100) dest=Bob
        Transact Bob.hello()
    ),
    [(ReserveWithdraw, KLT, 100)],
    1, // 1 ETH of 3 needs to be for the reward, the rest is for fees
)

The User Agent/UX layer will need to estimate the fee required to be passed into the send method. This may be an issue as we cannot Dry-Run something on Polkadot that has not even been submitted on Ethereum yet. We may need to make RPC API to DryRun and get back the xcm that would be submitted to asset hub.

Step 2: Relayer relays message to Bridge Hub

On-chain exchange rate is eliminated. Users pay remote delivery costs in ETH, and this amount is sent with the message as WETH. The delivery fee can be claimed by the relayer on BH.

The user agent applies a similar dry-running process as with Step 2: User agent estimates fees.

The message is converted from $m_0$ to $x_0$ during message submission on BH. Dry-running submission will return $x_0$ to the relayer so that it can verify it is profitable.

Step 3: AH receives $x_0$ from BH

Submitting the message $m_0$ will cause the following XCM, $x_0$, to be built on BH and dispatched to AH.

WithdrawAsset (KLT, 100)
ReserveAssetDeposited(WETH, 2)
PayFees (WETH, 1)
SetAssetClaimer Kilt/Bob       // derived from beneficiary on final destination
AliasOrigin Ethereum/Alice     // derived from msg.sender
InitiateAssetsTransfer asset=(KLT, 100) remoteFee=(WETH, 1) dest=KLT
  DepositAsset (KLT, 100) beneficiary=Bob

WithdrawAsset (KLT, 100)
ReserveAssetDeposited(WETH, 2)
PayFees (WETH, 1)
SetAssetClaimer Kilt/Bob         // derived from beneficiary on final destination
AliasOrigin Ethereum/Alice       // derived from msg.sender
InitiateAssetsTransfer asset=(KLT, 100) remoteFee=(WETH, 1) dest=KLT
    DepositAsset (KLT, 100) beneficiary=Bob
    Transact Bob.hello()

Step 4: KILT Receives XCM from AH

The following XCM $x_1$ is received from AH on KILT.

*WithdrawAsset (KLT, 100)
*ReserveAssetDeposited (WETH, 1)
*PayFees (WETH, 1)
*SetAssetClaimer Ethereum/Alice
*AliasOrigin Ethereum/Alice   // origin preserved from AH
SetAssetClaimer Bob
DepositAsset (KLT, 100) beneficiary=Bob

*WithdrawAsset (KLT, 100)
*ReserveAssetDeposited (WETH, 1)
*PayFees (WETH, 1)
*SetAssetClaimer Ethereum/Alice
*AliasOrigin Ethereum/Alice   // origin preserved from AH
SetAssetClaimer Bob
DepositAsset (KLT, 100) beneficiary=Bob
Transact Bob.hello()          // executes with the origin from AH

Relayer Rewards

The tracking and disbursement of relayer rewards for both directions has been unified. Rewards are accumulated on BH in WETH and must be manually claimed. As part of the claims flow, an XCM instruction is sent to AH to mint the WETH into the deposit account chosen by the relayer.

To claim, call following extrinsic, where $o$ is rewards account (origin), and $w$ is account on AH where the WETH will be minted.

$$ \mathrm{claim}(o,w) $$

For tax accounting purposes it might be desirable that $o \neq w$.

Top-Up

Top-up of the relayer reward is viable to implement for either direction as extrinsics on Bridge Hub and Ethereum respectively.

Origin Preservation

Origins for transact will be preserved by use of the AliasOrigin instruction. This instruction will have the following rules that parachain runtimes will need to allow:

  1. AliasOrigin can behave like DescendOrigin. This is safe because it respects the hierarchy of multi-locations and does not allow jumping up. Meaning no escalation of privileges.
    1. Example location Ethereum can alias into Ethereum/Alice because we are descending in origin and this essentially is how the DescendOrigin instruction works.
  2. AliasOrigin must allow AH to alias into bridged locations such as { parents: 2, interior: GlobalConsensus(Ethereum) } and all of its internal locations so that AH can act as a proxy for the bridge on parachains.

AliasOrigin will be inserted by every InitiateAssetTransfer instruction on the source parachain, populated with the contents of the origin register, essentially forwarding the origin of the source to the destination.

RFCS:

polkadot-fellows/RFCs#122

https://github.com/polkadot-fellows/RFCs/blob/main/text/0100-xcm-multi-type-asset-transfer.md

Parachain Requirements

  1. Pallet-xcm.execute enabled.
  2. XCM payment and dry run apis implemented.
  3. Must accept WETH needed for fees. Though in future user agents can inject ExchangeAsset instructions to obtain WETH.
  4. Trust AH as a reserve for bridged assets.
  5. Origin Preservation rules configured which allow asset hub to impersonate bridged addresses.