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
Relay Chain Alphanet xcUNIT 0xFfFFfFff1FcaCBd218EDc0EbA20Fc2308C778080
Basilisk Alphanet xcBSX 0xFFfFfFfF4d0Ff56d0097BBd14920eaC488540BFA
Clover Alphanet xcCLV 0xFfFfFffFD3ba399d7D9d684D94b22767a5FA1cCA
Crust/Shadow Alphanet xcCSM 0xffFfFFFf519811215E05eFA24830Eebe9c43aCD7
Integritee Alphanet xcTEER 0xFfFfffFf4F0CD46769550E5938F6beE2F5d4ef1e
Kintsugi Alphanet xckBTC 0xFffFfFff5C2Ec77818D0863088929C1106635d26
Kintsugi Alphanet xcKINT 0xFFFfffff27C019790DFBEE7cB70F5996671B2882
Litentry Alphanet xcLIT 0xfffFFfFF31103d490325BB0a8E40eF62e2F614C0
Pangolin Alphanet xcPARING 0xFFFffFfF8283448b3cB519Ca4732F2ddDC6A6165
Statemine Alphanet xcTT1 0xfFffFfFf75976211C786fe4d73d2477e222786Ac

*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.