External XC-20s¶
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:
- ERC-20 Interface — as described in the XC-20 overview page
- Permit Interface (EIP-712 compliant) — as described in the XC-20 overview page
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 |
| Astar | xcASTR | 0xFfFFFfffA893AD19e540E172C10d78D4d479B5Cf |
| Darwinia | xcRING | 0xFfffFfff5e90e365eDcA87fB4c8306Df1E91464f |
| Interlay | xcIBTC | 0xFFFFFfFf5AC1f9A51A93F5C527385edF7Fe98A52 |
| Interlay | xcINTR | 0xFffFFFFF4C1cbCd97597339702436d4F18a375Ab |
| Parallel | xcPARA | 0xFfFffFFF18898CB5Fe1E88E668152B4f4052A947 |
| Phala | xcPHA | 0xFFFfFfFf63d24eCc8eB8a7b5D0803e900F7b6cED |
| Statemint | xcUSDT | 0xFFFFFFfFea09FB06d082fd1275CD48b191cbCD1d |
*You can check each Asset ID on Polkadot.js Apps
| Origin | Symbol | XC-20 Address |
|---|---|---|
| Kusama | xcKSM | 0xFfFFfFff1FcaCBd218EDc0EbA20Fc2308C778080 |
| Bifrost | xcBNC | 0xFFfFFfFFF075423be54811EcB478e911F22dDe7D |
| Calamari | xcKMA | 0xffffffffA083189F870640B141AE1E882C2B5BAD |
| Crab | xcCRAB | 0xFFFffFfF8283448b3cB519Ca4732F2ddDC6A6165 |
| Crust-Shadow | xcCSM | 0xffFfFFFf519811215E05eFA24830Eebe9c43aCD7 |
| Heiko | xcHKO | 0xffffffFF394054BCDa1902B6A6436840435655a3 |
| Integritee | xcTEER | 0xFfFfffFf4F0CD46769550E5938F6beE2F5d4ef1e |
| Karura | xcKAR | 0xFfFFFFfF08220AD2E6e157f26eD8bD22A336A0A5 |
| Karura | xcaUSD | 0xFfFffFFfa1B026a00FbAA67c86D5d1d5BF8D8228 |
| Khala | xcPHA | 0xffFfFFff8E6b63d9e447B6d4C45BDA8AF9dc9603 |
| Kintsugi | xcKINT | 0xfffFFFFF83F4f317d3cbF6EC6250AeC3697b3fF2 |
| Kintsugi | xckBTC | 0xFFFfFfFfF6E528AD57184579beeE00c5d5e646F0 |
| Litmus | xcLIT | 0xfffFFfFF31103d490325BB0a8E40eF62e2F614C0 |
| Shiden | xcSDN | 0xFFFfffFF0Ca324C842330521525E7De111F38972 |
| Statemine | xcRMRK | 0xffffffFF893264794d9d57E1E0E21E0042aF5A0A |
| Statemine | xcUSDT | 0xFFFFFFfFea09FB06d082fd1275CD48b191cbCD1d |
*You can check each Asset ID on Polkadot.js Apps
| 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:
- From the selected state query dropdown, choose assets
- Select the asset extrinsic
- Disable the include option slider
- Send the query by clicking on the + button
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:
- From the selected state query dropdown, choose assets
- Select the metadata extrinsic
- Enable the include option slider
- 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
- Send the query by clicking on the + button
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.