Skip to content

External XC-20s

Cross-Chain Assets Precompiled Contracts Banner

Introduction

As covered in the XC-20 Overview, there are two types of XC-20s: external and mintable. The key distinction between external and mintable XC-20s, is that external XC-20s represent assets that are locked in Moonbeam's sovereign account in either the relay chain or other parachains. In contrast, mintable XC-20s represent assets that are minted/burned in Moonbeam directly, but have native XCM interoperability features. This guide will cover external XC-20s.

Although XC-20s are Substrate assets, Moonbeam has abstracted away low-level interactions with the Substrate API via an easy to use ERC-20 interface via a precompile contract. This allows developers to interact with XC-20s as they would with any other ERC-20. Please note that XC-20 precompiles do not support cross-chain transfers, and this is intentionally done to stay as close as possible to the standard ERC-20 interface.

External XC-20 assets will all have xc prepended to their name. For example, Kusama's KSM representation on Moonriver will be known as xcKSM. They will need to be registered and linked to another asset in the ecosystem before being used. This is done through a whitelisting process via a democracy proposal.

If you are interested in testing XCM features in the Moonbase Alpha TestNet, please contact us through our Discord Server. For more information on XCM, you can check out the XCM Overview page of our documentation.

This guide will show you how to retrieve the available external XC-20s and calculate their precompile addresses for the Moonbase Alpha TestNet using Polkadot.js Apps.

The External XC-20 Solidity Interface

The Solidity interface for External XC-20 tokens is a combination of the following two interfaces:

Current External XC-20 Assets

The current list of available external XC-20 assets per network is as follows:

Origin Symbol XC-20 Address
Polkadot xcDOT 0xFfFFfFff1FcaCBd218EDc0EbA20Fc2308C778080
Acala xcaUSD 0xfFfFFFFF52C56A9257bB97f4B2b6F7B2D624ecda
Acala xcACA 0xffffFFffa922Fef94566104a6e5A35a4fCDDAA9f

*You can check each Asset ID on Polkadot.js Apps

Origin Symbol XC-20 Address
Relay Chain Alphanet xcUNIT 0xFfFFfFff1FcaCBd218EDc0EbA20Fc2308C778080
Basilisk Alphanet xcBSX 0xFFfFfFfF4d0Ff56d0097BBd14920eaC488540BFA
Bifrost Alphanet xcBNC 0xFffFFFfF1FAE104Dc4C134306bCA8e2E1990aCfd
Calamari Alphanet xcKMA 0xFFffFffFA083189f870640b141ae1E882c2b5bad
Crust/Shadow Alphanet xcCSM 0xffFfFFFf519811215E05eFA24830Eebe9c43aCD7
Karura Alphanet xcKAR 0xFfFFFFfF08220AD2E6e157f26eD8bD22A336A0A5
Karura Alphanet xckUSD 0xFfFffFFfa1B026a00FbAA67c86D5d1d5BF8D8228
Khala Alphanet xcPHA 0xffFfFFff8E6b63d9e447B6d4C45BDA8AF9dc9603
Kintsugi Alphanet xcKINT 0xFFFfffff27C019790DFBEE7cB70F5996671B2882
Kintsugi Alphanet xckBTC 0xFffFfFff5C2Ec77818D0863088929C1106635d26
Litentry Alphanet xcLIT 0xfffFFfFF31103d490325BB0a8E40eF62e2F614C0
Parallel Heiko Alphanet xcHKO 0xffffffFF394054BCDa1902B6A6436840435655a3
Statemine Alphanet xcMRMRK 0xFFffffFfd2aaD7f60626608Fa4a5d34768F7892d

*You can check each Asset ID on Polkadot.js Apps

Retrieve List of External XC-20s

To fetch a list of the external XC-20s currently available on the Moonbase Alpha TestNet, head to Polkadot.js Apps and make sure you're connected to Moonbase Alpha. Then click on the Developer tab and select Chain State from the dropdown. To query the available external XC-20s, you can follow these steps:

  1. From the selected state query dropdown, choose assets
  2. Select the asset extrinsic
  3. Disable the include option slider
  4. Send the query by clicking on the + button

Fetch list of cross-chain assets

The result will display the asset ID along with some additional information for all of the registered external XC-20s on Moonbase Alpha.

Retrieve Metadata for External XC-20s

To quickly get more information about a specific external XC-20 such as the name, symbol, and decimals of the asset, you can use the metadata extrinsic to return metadata. For this example, you can feel free to use asset ID 42259045809535163221576417993425387648, and take the following steps:

  1. From the selected state query dropdown, choose assets
  2. Select the metadata extrinsic
  3. Enable the include option slider
  4. Enter in the asset ID that was returned from calling the asset extrinsic. Please note that if you copy and paste the asset ID with the commas, the commas will automatically be removed and the number might be cut off. Make sure it's the exact same number as the ID
  5. Send the query by clicking on the + button

Get asset metadata

With the results from the metadata, you can see that the asset ID corresponds to the VUNIT external XC-20.

Calculate External XC-20 Precompile Addresses

Now that you have retrieved a list of the available external XC-20s, before you can interact with them via the precompile, you need to derive the precompile address from the asset ID.

The external XC-20 precompile address is calculated using the following:

address = "0xFFFFFFFF..." + DecimalToHex(AssetId)

Given the above calculation, the first step is to take the u128 representation of the asset ID and convert it to a hex value. You can use your search engine of choice to look up a simple tool for converting decimals to hex values. For asset ID 42259045809535163221576417993425387648, the hex value is 1FCACBD218EDC0EBA20FC2308C778080.

External XC-20 precompiles can only fall between 0xFFFFFFFF00000000000000000000000000000000 and 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.

Since Ethereum addresses are 40 characters long, you will need to start with the initial 8 Fs, and then prepend 0s to the hex value until the address has 40 characters.

The hex value that was already calculated is 32 characters long, so prepending 8 Fs to the hex value will give you the 40 character address you need to interact with the XC-20 precompile. For this example, the full address is 0xFFFFFFFF1FCACBD218EDC0EBA20FC2308C778080.

Now that you've calculated the external XC-20 precompile address, you can use the address to interact with the XC-20 like you would with any other ERC-20 in Remix. To learn how to interact with XC-20s, please refer to Interact with the Precompile Using Remix section of the XC-20 overview page.