Asset Integration Guide

Why Integrating SubBridge

A TL;DR answer is that: SubBridge greatly reduces the efforts to transfer your assets to/from multiple blockchains.

Generally speaking, it takes two steps to bridge your asset to another chain:

1. To find an asset route to your target chain so you can transfer your token there, which may be consisted of one bridge or multiple bridges;
2. To ensure that your token can be recognized and handled in the target chain, this usually involves ad-hoc negotiation and program development;

And SubBridge can simplify both steps for you:

1. Instead of connecting your chain to others one-by-one, by integrating SubBridge you will be able to get the routes to any other chains that have already supported SubBridge (for now, this includes Polkadot parachains, Ethereum and Moonriver EVM);
2. SubBridge provides a unified interface (based on Polkadot XCM protocol) to abstract your asset and the corresponding asset-handling example, also our technical team is glad to provide support during your integration.

Overview

SubBridge supports both parachain assets and EVM assets, making it possible to transfer them between parachains and EVM chains. All supported assets are whitelisted, which means it would be failed if you transfer assets through SubBridge without registration. Refer to Supported Assets to check the asset list we have integrated.

• A parachain asset means the asset is reserved on a parachain. For example, GLMR is reserved on Moonbeam.
• An EVM asset means the asset is reserved on an EVM chain, in general, it’s an ERC-20 smart contract deployed on EVM. Note we currently only support assets deployed on Ethereum and Moonriver EVM.

You need to do the following steps to finish integration with SubBridge:

• Open an issue on subbridge-integration repo to provide asset registry information;
• Test registration locally or on Rococo;
• Register assets on Khala Network;
• [Optional] Integrate SubBridge into your app;

Provide Asset Registry Information

If you are interested in integrating your asset into SubBridge, please go to integration repo to open an issue with the template below:

### Who we are

*** Brief introduction of your project and team ***

### Asset registry information

- name
- symbol
- decimals
- location (represented as a MultiLocation in XCM)
- contract address(EVM assets only)
- is mintable (EVM assets only)

• location must be a MultiLocation. For example, the location of KAR is MultiLocation::new(1, X2(Parachain(2000), General(0x0080))). If your asset is an EVM asset, the location should be MultiLocation::new(1, X3(Parachain(2004), GeneralIndex(chain_id), GeneralKey(erc20_address))). chain_id should match the chain your asset deployed on. So far chain id of Ethereum is 0, and chain id of Moonriver EVM is 2.
• is mintable represents whether your ERC20 smart contract support mint and burn, if set as true, your users will need to give the mint authority to our contract when the first time they use SubBridge. Check Assets Registration find more details about what we have done on registration.

After the issue is opened, feel free to notify the team on our Discord channel if we haven’t replied immediately. Now you are ready to work with the team to finish the integration stuff when we approve the request on the issue.

Test Registration

Before onboarding your asset to the Khala network, we must make sure everything works properly on the Rhala network, which is our test parachain on Rococo. For parachain assets, you can choose to test the registration locally before running a test with the Phala team on Rococo. We have provided a config file which contains the information on how to run our test runtime Thala with polkadot-launch. Check here to find more about polkadot-launch.

For both parachain assets and EVM assets, the necessary step is to test the whole integration stuff on Rococo with the Phala team. The parachain registration on Rococo is maintained by Parity, if you are a parachain asset and you haven’t been a Rococo parachain, please notice the Parity team to onboard your chain on Rococo, also don’t forget to let them open HRMP channels between your parachain and Rhala network. If you are an EVM asset, please deploy an ERC20 asset on Kovan in advance, which will be used to config the EVM bridge. The architecture of the test net is as follow:

As shown, we have deployed a test ChainBridge that bridges the Rhala network and Kovan, contracts information is as below:

To start integration testing, please transfer some assets to our test account in advance

• For parachain asset, please transfer 10000 of your asset to account 0x7804e66ec9eea3d8daf6273ffbe0a8af25a8879cf43f14d0ebbb30941f578242 on your parachain
• For EVM asset, please transfer 10000 of your asset(ERC20) to account 0xA29D4E0F035cb50C0d78c8CeBb56Ca292616Ab20 on Kovan

Now it’s time to let us know that you have everything ready to do the test with the Phala team on Rococo. We will register your asset on the Rhala network and enable ChainBridge transfer if you are an EVM asset or you certainly want to bridge your parachain asset to EVM chains. Check Assets Registration to find more details.

Register assets on the Khala network

After we have confirmed all functions are working properly on Rococo, we will start integrating your asset on the Khala network. If your asset is a parachian asset, please refer to Parachain assets integration guide and if your assets is an EVM asset, please refer to EVM assets integration guide.

Parachain Assets Integration Guide

SubBridge contains an XCM-based bridge that can let assets transferred between parachains. If the parachian your asset reserved hasn’t opened HRMP channel with Khala network, the first thing we should do is follow these steps to open bi-direction HRMP channels:

💡 Steps 1 - 3 are the stuff to open HRMP channels between our two parachains. You can directly jump to Step 4 if it has been done. Information of PHA are as follows:

• Head to: https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama.api.onfinality.io%2Fpublic-ws#/extrinsics
• Choose extrinsic with parameters: hrmp -> hrmpInitOpenChannel { recipient: 2004 , proposedMaxCapacity: 1000, proposedMaxMessageSize: 102400}
• Copy the encoded call data, it should be 0x3c00d4070000e803000000900100

The XCM message you constructed should contain the following 5 instructions:

• WithdrawAsset
• BuyExecution
• Transact
• RefundSurplus
• DepositAsset

Here is an example to send the request to Moonriver from Khala 0x03000821040101009d1f02000000210001010002140004000000000700e876481713000000000700e876481700060002286bee383c00e7070000e803000000900100140d0100040001010070617261d4070000000000000000000000000000000000000000000000000000, you can decode the call at page https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkhala.api.onfinality.io%2Fpublic-ws#/extrinsics/decode

• Make sure the XCM message is sent from the root account (either SUDO or via governance)
• Make sure your parachian sovereign account has enough KSM on the Kusama network
• The destination should be (1, Here)
• Asset id(MultiLocation) should be set to (0, Here)
• Recipient of DepositAsset should be an AccountId32 and put your parachain sovereign account public key to id field.

💡 Please let us know when the XCM message is executed successfully on Kusama, then we will propose to send an XCM message to receive the request and send open the request to your parachain at the same time.

HRMP channel is a one-way channel, which means you also need to receive our open request on your side or your parachain will not be able to receive messages from our parachain. The steps to receive the request from the Khala network are similar to the open request we did before. When the Khala network successfully sends the open request, you should do as follow:

• Head to https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama.api.onfinality.io%2Fpublic-ws#/extrinsics
• Choose extrinsic with parameters: hrmp -> hrmpAcceptOpenChannel { sender: 2004 }
• Copy the encoded call data, it should be 0x3c01d4070000

Since the HRMP channel already opened between our two parachains, the last thing we need to do is to register your asset into our parachain and register our asset(PHA) into your parachain. You can refer to Assets Registration to see what we have done to register an asset. Please note that the location of PHA is MultiLocation::new(1, X1(Parachain(2004)). You may want to add it to your runtime XCM trader config according to your implementation.

EVM Assets Integration Guide

If the smart contract of your asset is ERC20 compatible, we can easily integrate it into SubBridge. Currently, we have integrated ChainBridge as our EVM bridge. It already deployed on both Ethereum mainnet and Moonriver EVM, here is the deployed ChainBridge contracts information:

• SygmaBridge smart contract info

Head to Sygma shared repo for the contract deployment information and more.

• ChainBridge smart contract info

Compare with the registration of parachain assets, registration of EVM assets is more convenient. You should be relaxed because we will do everything need with the registration information provided by you. If you are aware of things we did when registering an asset, please refer to Assets Registration for more information.

💡 You should receive the update when we finish the registration.

Integrate SubBridge into Your App

It’s better to integrate SubBridge into your App if you’d like to let your users use it easily. Integrating SubBridge into your app is super easy, the only thing you need to do is follow the dest specification we defined previously on your client. The difference between doing crosschain transfer on a parachain and an EVM chain is that in the former case you will need to interact with the XCM implementation pallet on that parachain, while in the latter you will need to interact with the smart contract deployed by Phala.

• Issuing crosschain transfer on other parachains or Khala network

For example, when issuing a crosschain transfer to the Khala network or EVM chains from Karura, you should use the xtoken»transfer, while issuing a crosschain transfer to other parachains or EVM chains from Khala, you should use the xtransfer»transfer. So interfaces may be different between different parachains depends on its implementation.

• Issuing crosschain transfer on EVM chains with SygmaBridge

So far we have already supported SygmaBridge and ChainBridge as EVM bridge, and we will integrate more EVM bridges in the future. The following is based on interaction with SygmaBridge, with less fee being paied compared with ChainBridge. According to the mechanism of the ERC20 protocol, before calling Bridge.deposit which is the interface to issue crosschain transfer we need to call ERC20 approve method to let user approve the specific amount of assets to ERC20Handler contract of SygmaBridge. This operation will allow ERC20Handler to spend up to the specific number of assets from the user account. After approval done, we can deposit asset through SygmaBridge contract. Luckily, Sygma has provided SDK to handle all of these stuffs, head to their SDK repo for more details.

We prepared the following 5 examples that almost covered all of the scenarios. If the transaction is issued on parachain, we have provided an encoded call you can decode on https://polkadot.js.app, and if the transaction is issued on EVM chains, we have provided a code snippet.

An example of transferring 100 PHA from the Phala network to Moonbeam, the recipient address is 0xA29D4E0F035cb50C0d78c8CeBb56Ca292616Ab20:

0x5200000000000b00407a10f35a010200511f0300a29d4e0f035cb50c0d78c8cebb56ca292616ab20010700f2052a0102127a00

An example of transferring 100 PHA from Khala network to Ethereum with Sygma bridge, recipient is 0xA29D4E0F035cb50C0d78c8CeBb56Ca292616Ab20. Note small amount of PHA will be deducted as the fee of SygmaBridge:

0x5200000000000b00407a10f35a000306057379676d6100000000000000000000000000000000000000000000000000000005000614a29d4e0f035cb50c0d78c8cebb56ca292616ab2000000000000000000000000000

An example of transferring 100 PHA from Karura to Khala network, the recipient is Alice. Karura XCM transfer based on the implementation of [xtoken pallet]https://github.com/open-web3-stack/open-runtime-module-library/tree/master/xtokens):

0x6a010300010100cd1f000b00407a10f35a03010200511f01007804e66ec9eea3d8daf6273ffbe0a8af25a8879cf43f14d0ebbb30941f578242010700f2052a0102127a00

An example of transferring 100 PHA from Moonbeam to Ethereum with SygmaBridge, recipient is 0xA29D4E0F035cb50C0d78c8CeBb56Ca292616Ab20. Note small amount of PHA will be deducted as the fee of SygmaBridge:

0x6a010300010100cd1f000b00407a10f35a03010400cd1f06057379676d6100000000000000000000000000000000000000000000000000000005000614a29d4e0f035cb50c0d78c8cebb56ca292616ab20000000000000000000000000010700f2052a0102127a00

Sygma SDK provided us example code of transfer fungible token from Goerli testnet to Substrate chain, head to here for the details.