Skip to content

Interacting with the XCM Utilities Precompile

Introduction

The XCM Utilities Precompile contract gives developers XCM-related utility functions directly within the EVM. This allows for easier transactions and interactions with other XCM-related precompiles.

Similar to other precompile contracts, the XCM Utilities Precompile is located at the following addresses:

0x000000000000000000000000000000000000080C
0x000000000000000000000000000000000000080C
0x000000000000000000000000000000000000080C

Note

There can be some unintended consequences when using the precompiled contracts on Moonbeam. Please refer to the Security Considerations page for more information.

The XCM Utilities Solidity Interface

XcmUtils.sol is an interface to interact with the precompile.

Note

The precompile will be updated in the future to include additional features. Feel free to suggest additional utility functions in the Discord.

The interface includes the following functions:

  • multilocationToAddress(Multilocation memory multilocation) — read-only function that returns the Computed Origin account from a given multilocation
  • weightMessage(bytes memory message) — read-only function that returns the weight that an XCM message will consume on the chain. The message parameter must be a SCALE encoded XCM versioned XCM message
  • getUnitsPerSecond(Multilocation memory multilocation) — read-only function that gets the units per second for a given asset in the form of a Multilocation. The multilocation must describe an asset that can be supported as a fee payment, such as an external XC-20, or else this function will revert
  • xcmExecute(bytes memory message, uint64 maxWeight) - available on Moonbase Alpha only - executes a custom XCM message given the SCALE encoded versioned message to be executed and the maximum weight to be consumed. This function cannot be called from a smart contract due to the nature of the Transact instruction
  • xcmSend(Multilocation memory dest, bytes memory message) - available on Moonbase Alpha only - sends a custom XCM message given the multilocation of the destination chain to send the message to and the SCALE encoded versioned message to be sent

The Multilocation struct in the XCM Utilities Precompile is built the same as the XCM Transactor Precompile's Multilocation.

Using the XCM Utilities Precompile

The XCM Utilities precompile allows users to read data off of the Ethereum JSON-RPC instead of having to go through a Polkadot library. The functions are more for convenience, and less for smart contract use cases.

For multilocationToAddress, one example use case is being able to allow transactions that originate from other parachains by whitelisting their Computed Origin addresses. A user can whitelist a multilocation by calculating and storing an address. EVM transactions can originate from other parachains via remote EVM calls.

// SPDX-License-Identifier: GPL-3.0-only
pragma solidity >=0.8.3;

import "https://github.com/moonbeam-foundation/moonbeam/blob/master/precompiles/xcm-utils/XcmUtils.sol";

contract MultilocationWhitelistExample {
    XcmUtils xcmutils = XcmUtils(0x000000000000000000000000000000000000080C);
    mapping(address => bool) public whitelistedAddresses;

    modifier onlyWhitelisted(address addr) {
        _;
        require(whitelistedAddresses[addr], "Address not whitelisted!");
        _;
    }

    function addWhitelistedMultilocation(
        XcmUtils.Multilocation calldata externalMultilocation
    ) external onlyWhitelisted(msg.sender) {
        address derivedAddress = xcmutils.multilocationToAddress(
            externalMultilocation
        );
        whitelistedAddresses[derivedAddress] = true;
    }

    ...
}

To check out an example of how to use the xcmExecute function to execute a custom XCM message locally, please refer to the Create and Execute Custom XCM Messages guide.

Last update: May 10, 2024
| Created: November 16, 2022