Skip to content

Moonbeam XCM SDK Reference: Types and Interfaces

The XCM SDK is based on defining an asset to transfer, then the source chain to send the asset from, and the destination chain to send the asset to, which, together, build the transfer data.

The following sections cover the types and interfaces you'll encounter when working with assets, chains, and transfer data.

Assets

The Asset Object

Defines an asset's key and symbol used on the asset's origin chain.

Attributes

  • key string - Identifies an asset
  • originSymbol string - The symbol of the asset on the asset's origin chain
Example
// The Asset object
// For GLMR on Moonbeam
{
  key: 'glmr',
  originSymbol: 'GLMR'
}

The Asset Amount Object

Defines properties related to an asset, including Asset properties, the decimals and symbol of the asset, and the amount an associated source or destination address has of the asset.

Note

A few utility methods are available for working with the AssetAmount class that converts the amount to various formats. Please refer to the Methods for Asset Conversions section.

Attributes

  • key string - Identifies an asset
  • originSymbol string - The symbol of the asset on the asset's origin chain
  • amount bigint - Identifies a particular amount of the asset (i.e., balance, minimum, maximum, etc.)
  • decimals number - The number of decimals the asset has
  • symbol string - The symbol of the asset
Example
// The Asset Amount object
// For GLMR on Moonbeam
{
  key: 'glmr',
  originSymbol: 'GLMR',
  amount: 0n,
  decimals: 18,
  symbol: 'GLMR'
}

Chains

The Ecosystem Type

Specifies the relay chain ecosystem a chain belongs to. Can be any of the following ecosystems as defined by the Ecosystem enum:

enum Ecosystem {
  Polkadot = 'polkadot',
  Kusama = 'kusama',
  AlphanetRelay = 'alphanet-relay',
}
Example
// The Ecosystem Type
{
  ecosystem: 'polkadot',
}

The Chain Type

Specifies what kind of parachain a chain is.

enum ChainType {
  'Parachain' = 'parachain',
  'EvmParachain' = 'evm-parachain',
}
Example
// The Chain Type
{
  type: 'evm-parachain',
}

The Chain Asset ID Type

A generic type used to specify the location of the asset on the chain, which is different on every chain.

type ChainAssetId = string | number | bigint | { [key: string]: ChainAssetId };
Example
// The Chain Asset ID Type
// To target DOT on Moonbeam
{
  id: '42259045809535163221576417993425387648',
}

The Chain Object

Defines properties related to a chain and is used to define the source and destination chains. If a chain is an EVM parachain, there are a couple of additional properties.

Attributes

  • ecosystem Ecosystem - Identifies the ecosystem the chain belongs to: polkadot, kusama, or alphanet-relay
  • isTestChain boolean - Whether the chain is a testnet
  • key string - Identifies a chain
  • name string - The name of the chain
  • type ChainType - The type of the chain: parachain or evm-parachain
  • assetsData Map<string, ChainAssetsData> - A list of the assets that the chain supports
  • genesisHash string - The hash of the genesis block
  • parachainId number - The ID of the parachain (not the EVM chain ID)
  • ss58Format number - The ss58 format for the chain
  • usesChainDecimals boolean - A flag indicating if the chain uses its own decimals in balance queries for all the assets. Defaults to false
  • checkSovereignAccountBalances boolean - Indicates whether a check of the sovereign account balances for the asset is required when transferring to this chain. Defaults to false
  • ws string - The WebSocket endpoint for the chain
  • id number - For EVM parachains only - The chain ID
  • rpc string - For EVM parachains only - The HTTP RPC endpoint for the chain
Example
// The Chain object
// Moonbeam's Chain Object
{
  ecosystem: 'polkadot',
  isTestChain: false,
  key: 'moonbeam',
  name: 'Moonbeam',
  type: 'evm-parachain',
  assetsData: [Map],
  genesisHash: '0xfe58ea77779b7abda7da4ec526d14db9b1e9cd40a217c34892af80a9b332b76d',
  parachainId: 2004,
  ss58Format: 1284,
  usesChainDecimals: false,
  weight: 1000000000,
  ws: 'wss://wss.api.moonbeam.network',
  id: 1284,
  rpc: 'https://rpc.api.moonbeam.network'
}

The Chain Assets Data Object

Defines the information needed to target the asset on the chain. This is mostly for internal usage to accommodate how chains store their assets. The SDK defaults to the asset ID if certain properties do not apply to the given chain.

Attributes

  • asset Asset - The asset's key and origin symbol
  • balanceId ChainAssetId - The balance ID of the asset. Defaults to the asset ID
  • decimals number - The number of decimals the asset has
  • id ChainAssetId - The asset ID
  • metadataId ChainAssetId - The metadata ID of the asset
  • minId ChainAssetId - The minimum ID of the asset
  • palletInstance number - The number of the pallet instance the asset belongs to
  • min number - The minimum amount of the asset that is required to be left in the account for it to be active. Similar to the existential deposit, except it is for non-native assets
Example
// The Chain Assets Data object
// To target DOT on Moonbeam
{
  asset: dot,
  id: '42259045809535163221576417993425387648',
}

Transfer Data

The Transfer Data Object

Defines the complete transfer data for transferring an asset, including asset, source chain, and destination chain information, as well as a few helper functions for the transfer process.

Attributes

  • destination DestinationChainTransferData - The assembled destination chain and address information
  • getEstimate function - Gets the estimated amount of the asset that the destination address will receive
  • isSwapPossible boolean - Returns whether or not the swap is possible
  • max AssetAmount - The maximum amount of the asset that can be transferred
  • min AssetAmount - The minimum amount of the asset that can be transferred
  • source SourceChainTransferData - The assembled source chain and address information
  • swap function - Swaps the destination and the source chains and returns the swapped transfer data
  • transfer function - Transfers a given amount of the asset from the source chain to the destination chain
Example
// The Transfer Data object
// For sending DOT from Polkadot to Moonbeam
{
  destination: {
    balance: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    },
    chain: {
      ecosystem: 'polkadot',
      isTestChain: false,
      key: 'moonbeam',
      name: 'Moonbeam',
      type: 'evm-parachain',
      assetsData: [Map],
      genesisHash: '0xfe58ea77779b7abda7da4ec526d14db9b1e9cd40a217c34892af80a9b332b76d',
      parachainId: 2004,
      ss58Format: 1284,
      usesChainDecimals: false,
      weight: 1000000000,
      ws: 'wss://wss.api.moonbeam.network',
      id: 1284,
      rpc: 'https://rpc.api.moonbeam.network'
    },
    existentialDeposit: {
      key: 'glmr',
      originSymbol: 'GLMR',
      amount: 0n,
      decimals: 18,
      symbol: 'GLMR'
    },
    fee: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 33068783n,
      decimals: 10,
      symbol: 'DOT'
    },
    min: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    }
  },
  getEstimate: [Function: getEstimate],
  isSwapPossible: true,
  max: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  min: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 33068783n,
    decimals: 10,
    symbol: 'DOT'
  },
  source: {
    balance: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    },
    chain: {
      ecosystem: 'polkadot',
      isTestChain: false,
      key: 'polkadot',
      name: 'Polkadot',
      type: 'parachain',
      assetsData: Map(0) {},
      genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
      parachainId: 0,
      ss58Format: 0,
      usesChainDecimals: false,
      weight: 1000000000,
      ws: 'wss://rpc.polkadot.io'
    },
    destinationFeeBalance: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    },
    existentialDeposit: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 10000000000n,
      decimals: 10,
      symbol: 'DOT'
    },
    fee: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 169328990n,
      decimals: 10,
      symbol: 'DOT'
    },
    feeBalance: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    },
    max: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    },
    min: {
      key: 'dot',
      originSymbol: 'DOT',
      amount: 0n,
      decimals: 10,
      symbol: 'DOT'
    }
  },
  swap: [AsyncFunction: swap],
  transfer: [AsyncFunction: transfer]
}

The Destination Chain Transfer Data Object

Defines the destination chain data for the transfer.

Attributes

  • balance AssetAmount - The balance of the asset being transferred on the destination address
  • chain AnyChain - The destination chain information
  • existentialDeposit AssetAmount - The existential deposit for the asset being transferred on the destination chain
  • fee AssetAmount - The amount of fees for the asset being transferred on the destination chain
  • min AssetAmount - The minimum amount of the asset to transfer. This is different than TransferData.min, as this dictates the minimum amount that should be received on the destination chain
Example
// The Destination Chain Transfer Data object
// For sending DOT from Polkadot to Moonbeam
{
  balance: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  chain: {
    ecosystem: 'polkadot',
    isTestChain: false,
    key: 'moonbeam',
    name: 'Moonbeam',
    type: 'evm-parachain',
    assetsData: [Map],
    genesisHash: '0xfe58ea77779b7abda7da4ec526d14db9b1e9cd40a217c34892af80a9b332b76d',
    parachainId: 2004,
    ss58Format: 1284,
    usesChainDecimals: false,
    weight: 1000000000,
    ws: 'wss://wss.api.moonbeam.network',
    id: 1284,
    rpc: 'https://rpc.api.moonbeam.network'
  },
  existentialDeposit: {
    key: 'glmr',
    originSymbol: 'GLMR',
    amount: 0n,
    decimals: 18,
    symbol: 'GLMR'
  },
  fee: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 33068783n,
    decimals: 10,
    symbol: 'DOT'
  },
  min: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  }
}

The Source Chain Transfer Data Object

Defines the source chain data for the transfer.

Attributes

  • balance AssetAmount - The balance of the asset being transferred for the source address
  • chain AnyChain - The source chain information
  • destinationFeeBalance AssetAmount - The balance of the asset used to pay for fees in the destination chain
  • existentialDeposit AssetAmount - The existential deposit for the asset being transferred on the source chain
  • fee AssetAmount - The amount of fees for the asset being transferred on the source chain
  • feeBalance AssetAmount - The balance of the asset being transferred on the source chain
  • min AssetAmount - The minimum amount of the asset that should be kept on the source chain, taking into consideration the existentialDeposit and fee for the transfer
  • max AssetAmount - The maximum amount of the asset that can be transferred
Example
// The Source Chain Transfer Data object
// For sending DOT from Polkadot to Moonbeam
{
  balance: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  chain: {
    ecosystem: 'polkadot',
    isTestChain: false,
    key: 'polkadot',
    name: 'Polkadot',
    type: 'parachain',
    assetsData: Map(0) {},
    genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
    parachainId: 0,
    ss58Format: 0,
    usesChainDecimals: false,
    weight: 1000000000,
    ws: 'wss://rpc.polkadot.io'
  },
  destinationFeeBalance: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  existentialDeposit: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 10000000000n,
    decimals: 10,
    symbol: 'DOT'
  },
  fee: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 169328990n,
    decimals: 10,
    symbol: 'DOT'
  },
  feeBalance: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  max: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  },
  min: {
    key: 'dot',
    originSymbol: 'DOT',
    amount: 0n,
    decimals: 10,
    symbol: 'DOT'
  }
}

SDK Options

The SDK Options Object

Defines options to initialize the SDK, including EVM and Polkadot signers and a custom configuration service.

Attributes

  • evmSigner EvmSigner - The signer for transfers involving EVM chains
  • polkadotSigner Signer | IKeyringPair - The signer for transfers involving non-EVM chains
  • configService IConfigService - The custom configuration service
Example
// The Sdk Options object
{
  evmSigner: INSERT_EVM_SIGNER,
  polkadotSigner: INSERT_POLKADOT_SIGNER,
  configService: {
    assets: INSERT_ASSETS_MAPPING,
    chains: INSERT_CHAINS_MAPPING,
    chainsConfig: INSERT_CHAIN_CONFIG_MAPPING,
  }
}

Signers

The EVM Signer Type

Defines the EVM signer for transfers involving EVM chains. Can be an Ethers signer or viem Wallet Client.

Example
import { ethers } from 'ethers';

const provider = new ethers.WebSocketProvider(
  'wss://wss.api.moonbeam.network',
  {
    chainId: 1284,
    name: 'moonbeam',
  },
);
const evmSigner = new ethers.Wallet('INSERT_PRIVATE_KEY', provider);

The Polkadot Signer Type

Defines the signer for transfers involving non-EVM chains. Can be a signer or a Keyring pair.

Example
import { Keyring } from '@polkadot/api';
import { cryptoWaitReady } from '@polkadot/util-crypto';

await cryptoWaitReady();
const keyring = new Keyring({ type: 'sr25519' });
const pair = keyring.addFromUri('INSERT_MNEMONIC');

Configurations

The interfaces in this section are primarily used for defining your own custom configuration source and adding or updating new asset and chain configurations to the XCM SDK. To learn how to add new configurations, please refer to the Contribute to the XCM SDK guide.

The Config Service Object

Defines a custom configuration service. This overrides the asset and chain configurations in the xcm-config package, which is exposed by default by the SDK.

Attributes

  • assets Map<string, Asset> - A list of the supported assets mapping each asset key to its corresponding Asset object
  • chains Map<string, AnyChain> - A list of the supported assets mapping each chain key to its corresponding Chain object
  • chainsConfig Map<string, ChainConfig> - A list of the supported chain configurations mapping each chain key to its corresponding ChainConfig object
Example
import { Keyring } from '@polkadot/api';
import { cryptoWaitReady } from '@polkadot/util-crypto';

await cryptoWaitReady();
const keyring = new Keyring({ type: 'sr25519' });
const pair = keyring.addFromUri('INSERT_MNEMONIC');

The Chain Config Object

Defines a chain's configurations, including information for each chain's supported assets.

Attributes

  • assets AssetConfig[] - The supported asset configurations
  • chain AnyChain - The chain's properties
Example
// The Chain Config object
// For configuring the Polkadot Asset Hub
{
  assets: [
    ...new AssetConfig({
      asset: usdt,
      balance: BalanceBuilder().substrate().assets().account(),
      destination: moonbeam,
      destinationFee: {
        amount: FeeBuilder()
          .xcmPaymentApi()
          .xcmPaymentFee({ isAssetReserveChain: false }),
        asset: usdt,
        balance: BalanceBuilder().substrate().assets().account(),
      },
      extrinsic: ExtrinsicBuilder()
        .polkadotXcm()
        .limitedReserveTransferAssets()
        .X2(),
      fee: {
        asset: dot,
        balance: BalanceBuilder().substrate().system().account(),
        xcmDeliveryFeeAmount,
      },
      min: AssetMinBuilder().assets().asset(),
    }),
    ...
  ],
  chain: new Parachain({
    assetsData: [
      {
        asset: usdt,
        id: 1984,
        palletInstance: 50,
      },
      ...
    ],
    ecosystem: Ecosystem.Polkadot,
    genesisHash:
      '0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f',
    key: 'Polkadot-asset-hub',
    name: 'Polkadot Asset Hub',
    parachainId: 1000,
    ss58Format: 42,
    ws: 'wss://polkadot-asset-hub-rpc.polkadot.io',
  })
}

The Asset Config Object

Defines an asset's configurations for a source chain and includes information about the destination chain, associated fees for transferring the asset from the source chain to the destination chain, and builder functions that define how to transfer the asset.

Attributes

  • asset Asset - The asset's key and origin symbol
  • balance BalanceConfigBuilder - The query builder for retrieving the balance of an asset for a given account
  • contract ContractConfigBuilder - The contract call builder for a cross-chain transfer. This is specific to EVM chains that use contracts to interact with Substrate pallets for cross-chain transfers, such as Moonbeam's X-Tokens precompiled contract
  • destination AnyChain - The destination chain information
  • destinationFee DestinationFeeConfig - The destination chain fees
  • extrinsic ExtrinsicConfigBuilder - The extrinsic builder for a cross-chain transfer
  • fee FeeAssetConfig - The source chain fees
  • min AssetMinConfigBuilder - The query builder for retrieving the minimum amount of an asset required to be left in an account
Example
// The Asset Config object
// For configuring USDT to be sent from
// the Polkadot Asset Hub to Moonbeam
{
  asset: usdt,
  balance: BalanceBuilder().substrate().assets().account(),
  destination: moonbeam,
  destinationFee: {
    amount: FeeBuilder()
          .xcmPaymentApi()
          .xcmPaymentFee({ isAssetReserveChain: false }),
    asset: usdt,
    balance: BalanceBuilder().substrate().assets().account(),
  },
  extrinsic: ExtrinsicBuilder()
    .polkadotXcm()
    .limitedReserveTransferAssets()
    .X2(),
  fee: {
    asset: dot,
    balance: BalanceBuilder().substrate().system().account(),
    xcmDeliveryFeeAmount,
  },
  min: AssetMinBuilder().assets().asset(),
}

The Fee Asset Config

Defines the fees for a particular asset on the source chain.

Attributes

  • asset Asset - The asset's key and origin symbol
  • balance BalanceConfigBuilder - The query builder for retrieving the balance of an asset for a given account
  • xcmDeliveryFeeAmount number - The delivery fee amount for the cross-chain transfer
Example
// The Fee Asset Config object
// For configuring USDT to be sent from
// the Polkadot Asset Hub to Moonbeam
{
  asset: dot,
  balance: BalanceBuilder().substrate().system().account(),
  xcmDeliveryFeeAmount: 0.036,
}

The Destination Fee Asset Config

Defines the fees for a particular asset on the destination chain.

Attributes

  • asset Asset - The asset's key and origin symbol
  • balance BalanceConfigBuilder - The query builder for retrieving the balance of an asset for a given account
  • xcmDeliveryFeeAmount number - The delivery fee amount for the cross-chain transfer
  • amount number | FeeConfigBuilder - The fee amount or the query builder for retrieving the fee amount for the execution of the cross-chain transfer
Example
// The Desintation Fee Asset Config object
// For configuring USDT to be sent from
// the Polkadot Asset Hub to Moonbeam
{
  asset: dot,
  balance: BalanceBuilder().substrate().system().account(),
  amount: amount: FeeBuilder()
          .xcmPaymentApi()
          .xcmPaymentFee({ isAssetReserveChain: false }),
}