跳到主要内容

⛓ XCM Onboarding

Process Overview:​

  • Test XCM between Calamari and your runtime locally with polkadot-launch.

  • Become a parachain on Rococo.

  • Calculate and fund your parachain's sovereign account on Rococo.

  • Open HRMP channels with Calamari.

  • Assets registrations.

  • Complete XCM tests between parachains.

  • Next steps discussion.

  • Manta Team Contact:

    • Georgi (XCM Eng): @Ghz (Telegram)
    • Shumo (Co-founder, Tech.): @xstec (Telegram)

Local XCM Integration​

  • As a first step we insist that both teams first run all tests on a local network.
  • For that you can download the latest manta binary from the Releases page.
  • Then use polkadot-launch to launch a calamari-local or calamari-dev network for testing.
  • You will also need to launch a rococo-local relay chain using the latest release of Polkadot.
  • Here's a reference polkadot-launch config for calamari-dev.
  • Please let us know if there's a specific branch of your codebase that we should test with.

XCM Integration on Rococo​

  • The next step of the Calamari integration is to integrate with our parachain (Dolphin) on the official Rococo relay chain. As part of this integration, you’ll need to register an HRMP channel with Dolphin. On the Rococo ecosystem we can also test integration with a number of other parachains, as most Kusama chains have also deployed on Rococo.

Rococo Ecosystem Data​

Sync Node & Open Rococo Slot Request​

  • To sync your node, you can use the following relay chain spec (note: relay chain is Rococo based, and will probably take a few hours to sync)
  • Register your parachain on Rococo. For that you will need to open a Rococo Slot Request issue and follow the instructions.

Calculate and Fund your Parachain's Sovereign Account​

ts-node calculateSovereignAddress.ts --paraid 2084
  • The result will be:
Sovereign Account Address on Relay: 0x7061726124080000000000000000000000000000000000000000000000000000
Sovereign Account Address on other Parachains (Generic): 0x7369626c24080000000000000000000000000000000000000000000000000000
Sovereign Account Address on Dolphin: 0x7369626c24080000000000000000000000000000
  • Once you’ve got your Sovereign Account’s address, please fund it using the Rococo faucet. Otherwise you won’t be able to create the HRMP channel as the transaction will fail due to insufficient fees. Let us know if you need additional funds.

Create HRMP Channel with Dolphin​

Get the Relay Encoded Call Data to Open HRMP Channel.​

  • Once your parachain is onboard, you need to create the HRMP channel between your Parachain and Dolphin.
  • The first step is to get an encoded call data from the relay chain. The extrinsic contains the target parachain ID, max number of messages, and max message size, described in the next bullet.
  • In PolkadotJS app, switch to the Rococo network. Go to Developer -> Javascript section. Run the following code, note to replace the demo recipient para id with your own:
const tx = api.tx.hrmp.hrmpInitOpenChannel(2084, 8, 1024);
console.log(tx.toHex());
  • The result will be like:

0x3c040x1700240800000800000000040000, remove the leading hex 3c04, and so the encoded result is 0x1700240800000800000000040000.

Send XCM to Relay Chain​

  • The next step is to build and send an XCM message to the relay chain that will request a channel to be opened through the relay chain. This XCM message needs to be sent from the root account (either SUDO or via governance). The message can be broken down in the following elements:
    1. Withdraw asset: take funds out of the Sovereign Account of the origin parachain (in the relay chain) to a holding state
    2. Buy execution: buys execution time from the relay chain, to execute the XCM message
    3. Transact: provides the call data to be executed
    4. Deposit asset (optional): refunds the leftover funds after the execution. If this is not provided, no refunds will be carried out
  • Therefore, to build/send this XCM, you need to:

    1. Polkadot.js Apps in your parachain -> extrinsics

    2. Set the following parameters: polkadotXcm -> send

    3. The destination has to be the relay chain, for dest (V1) set: { parents:1, interior: Here }

    4. For the message (V2), you’ll be adding 4 items (described before):

      1. WithdrawAsset { id: Concrete { parents: 0, interior: Here}, Fungible: 1000000000000 }
      2. BuyExecution { id: Concrete: {parents: 0, interior: Here}, Fungible: 1000000000000, weightLimit: Unlimited }
      3. Transact { originType: Native, requireWeightAtMost: 1000000000, call: XcmDoubleEncoded: { encoded: RelayEncodedCallData } }
          Note: you need to provide the encoded call data obtained before
      4. RefundSurplus
      5. DepositAsset: { assets: Wild { Wild: All }, maxAssets: 1, beneficiary: { parents: 0, interior: X1 { X1: AccountId32 { network: Any, id: SovereignAccountonRelay } } } }

      Note: The values used above are for reference to be used in this testing environment, do not use these values in production!

  • Once this message is sent, the relay chain should execute the content and the request to open the channel with Dolphin
  • Please let us know once you’ve requested opening the channel because the request needs to be accepted by Dolphin.

Here's an example of the fully formed extrinsic:

https://i.imgur.com/GUN8qJd.png

https://i.imgur.com/3ONY21d.png

Accepting HRMP Channel with Calamari​

  • Channels are one way. This means that if you open a channel with Dolphin, it will allow you only to send tokens from your parachain to Dolphin. There needs to be a channel that Dolphin will request to send back tokens, and you need to accept.
  • The process of accepting the channel is similar to the one for opening, meaning that you have to construct an encoded call data in the relay chain, and then get it executed via an XCM from your parachain.

Get the Relay Encoded Call Data to Accept HRMP Channel​

  • To get an encoded call data from the relay chain, to accept a channel request with a target parachain, take the following steps:
  • In PolkadotJS app, switch to the live Polkadot/Kusama network. Go to Developer -> Javascript section. Run the following code, note to replace the demo recipient para id with your own:
const tx = api.tx.hrmp.hrmpAcceptOpenChannel(2084);
console.log(tx.toHex());
  • The result will be like:

0x1c04170124080000, remove the leading hex 1c04, and the encoded result is 0x170124080000.

Send XCM to Relay Chain​

  • The steps are the same as before (when making the request to open a channel). The main difference is in the Transact item, where you need to provide the encoded call data calculated above. This XCM message needs to be sent from the root account (either SUDO or via governance):
Transact { originType: Native, requireWeightAtMost: 1000000000, call: XcmDoubleEncoded: { encoded: RelayEncodedCallData } }

Note: The values used above are for reference to be used in this testing environment, do not use these values in production!

Assets Registrations​

Registering your Asset on Dolphin​

  • Once the channel is opened, we need to register the asset that will be transferred to Dolphin. For that, we need the following information:
    1. MultiLocation of your asset (as seen by Dolphin). Please indicate parachain ID and the interior (if you use any pallet index, general index, etc)
    2. Asset Name
    3. Asset symbol
    4. Number of decimals
  • Please write this information as a comment in this issue.
  • We will confirm once the asset is registered. We will also set an arbitrary UnitsPerSecond, which is the number of tokens charged per second of execution of the XCM message.
  • After the asset is successfully registered, you can try transferring tokens from your parachain to Dolphin.
  • For testing, please also provide your Parachain WS Endpoint so we can connect to it. Lastly, we would need some funds to the following account: 5CacAW3K4gq3Ufv2dAqUFYWKoqJcQaFu346ahesmt4sua7Xx
  • If you need DOL tokens (the native token for Dolphin) to use your parachain's asset, you can get some from our Discord Bot - We can also provide you with some if you give us your address

Registering Calamari’s Token on your Parachain​

  • To register our DOL token on your parachain, you can use the following MultiLocation:

{ "parents": 1, "interior": {"X1": { "Parachain": 2084 }}

  • And the following metadata:
Name: Dolphin
Symbol: DOL
Decimals: 18
  • Note: Calamari MultiLocation is different!

Example Polkadot Launch Config​

{
    "relaychain": {
        "bin": "./polkadot",
        "chain": "rococo-local",
        "nodes": [
            {
                "name": "alice",
                "wsPort": 9944,
                "port": 30444,
                "flags": [
                    "--rpc-cors=all",
                    "--execution=wasm",
                    "--wasm-execution=compiled",
                ]
            },
            {
                "name": "bob",
                "wsPort": 9955,
                "port": 30555,
                "flags": [
                    "--rpc-cors=all",
                    "--execution=wasm",
                    "--wasm-execution=compiled",
                ]
            },
            {
                "name": "charlie",
                "wsPort": 9966,
                "port": 30666,
                "flags": [
                    "--rpc-cors=all",
                    "--execution=wasm",
                    "--wasm-execution=compiled",
                ]
            }
        ],
        "genesis": {
            "runtime": {
                "runtime_genesis_config": {
                    "configuration": {
                        "config": {
                            "validation_upgrade_frequency": 10,
                            "validation_upgrade_delay": 10
                        }
                    }
                }
            }
        }
    },
    "parachains": [
        {
            "bin": "./manta",
            "chain": "calamari-dev",
            "nodes": [
                {
                    "wsPort": 9801,
                    "port": 31201,
                    "name": "alice",
                    "flags": [
                        "--rpc-cors=all",
                        "--rpc-port=9971",
                        "--execution=wasm",
                        "--wasm-execution=compiled"
                    ]
                }
            ]
        }
    ],
    "hrmpChannels": [
    ],
    "types": {},
    "finalization": false
}

Next Steps - Calamari & Manta​

  • The following items must have been completed and fully tested in the Rococo Ecosystem with Dolphin before proceeding with an XCM integration on Calamari (and Manta in the future):

    1. Bi-directional HRMP channels between Dolphin and your parachain
    2. Bi-directional asset registration (DOL token and the token of your parachain)
    3. Both teams must have successfully tested asset transfers through Polkadot.js Apps

  • Once everything is successful we can plan governance proposals to open HRMP channels and asset registrations on the Kusama parachains, as well as additional marketing initiatives if relevant.