Migration Guide v10 ➡ v11

This guide covers all breaking changes and new features introduced in version v11 of the ParaSpell XCM Tools.
These changes affect XCM SDK, XCM API, XCM Router, and XCM Analyser.

---

1. Removal of the multi Prefix

In v11, all functions and types previously using the multi prefix have been renamed to remove that prefix.
For example:

- multilocation()
+ location()

- getAssetMultilocation()
+ getAssetLocation()

This was done because the multi prefix is no longer used within Polkadot.

✅ Action Required:
Update all your function calls, type imports, and references to remove the multi prefix.

---

2. NODE ➡ CHAIN Renaming

The term NODE is now replaced by CHAIN across types and functions.

Example changes:

- TNode
+ TChain

- getTNode()
+ getTChain()

The term node is not as informative to new developers as the term chain.

✅ Action Required:
Search your code for any NODE references and replace them with CHAIN.

---

3. New Chain Division Types

New chain division types are introduced for more granular chain handling.
See documentation: Import Chains as Constant

Example usage:

// Export all Parachains
console.log(PARACHAINS)

// Export all Relay chains
console.log(RELAYCHAINS)

// Export all Substrate chains (Parachains + Relays)
console.log(SUBSTRATE_CHAINS)

// Export chains outside Polkadot ecosystem (Ethereum)
console.log(EXTERNAL_CHAINS)

// Export all chains implemented in ParaSpell
console.log(CHAINS)

Instead of the previous:

// Export all Parachains
console.log(CHAINS_WITH_RELAYS)

The previous type division was a little messy. The new type division also accounts for chains outside the Polkadot ecosystem, such as Ethereum.

✅ Action Required:
Update your imports if you plan to use these new chain types for improved type safety and consistency.

---

4. Decimal Abstraction Setting (abstractDecimals)

A new decimal abstraction setting has been added to the builder configuration.

Default Behavior

• v11 default: abstractDecimals: false
• Future versions: Will default to true

Purpose

When enabled in Builder config as {abstractDecimals: true}, the SDK automatically abstracts decimals for you.
For example, sending 1 DOT from the Relay chain to Asset Hub:

const builder = await Builder({
    abstractDecimals: true // Abstracts decimals from amount - so 1 in amount for DOT equals 10_000_000_000 
    })
      .from('Polkadot')
      .to('AssetHubPolkadot')
      .currency({symbol: 'DOT', amount: 1}) 
      .address(address)

const tx = await builder.build()

// Make sure to disconnect API after it is no longer used (eg. after transaction)
await builder.disconnect()

Instead of default {abstractDecimals: false}:

const builder = await Builder()
      .from('Polkadot')
      .to('AssetHubPolkadot')
      .currency({symbol: 'DOT', amount: 10000000000}) 
      .address(address)

const tx = await builder.build()

// Make sure to disconnect API after it is no longer used (eg. after transaction)
await builder.disconnect()

NOTE:

We advise everyone who does not wish to use the abstractDecimals setting to manually set it as false to prevent issues when bumping to new versions in the future.

Special Case: bigint

If you pass a bigint as the amount and decimal abstraction is enabled,
the SDK will automatically disable abstraction for that call because bigint does not support floating-point numbers.

//Decimal abstraction will be ignored
const builder = await Builder()
      .from('Polkadot')
      .to('AssetHubPolkadot')
      .currency({symbol: 'DOT', amount: 10000000000n}) 
      .address(address)

const tx = await builder.build()

// Make sure to disconnect API after it is no longer used (eg. after transaction)
await builder.disconnect()

✅ Action Required:

• If you want automatic decimal handling, set abstractDecimals: true in your Builder configuration.
• Be mindful of the future default change to true. Review your amount values to ensure they behave as expected.
• Make sure to use String or Number when entering a value, as Bigint will require decimal inputs.

---

5. Multiasset type is now an array:

Previously, we used the multiasset selector for multiple assets in one call. With the removal of the multi prefix, we decided to completely replace the selector with an array.

Previously:

.currency(Multiasset: {currencySelection /*for example symbol: symbol or id: id, or location: location*/, amount: amount}, {currencySelection}, ..
)

Now:

.currency([{currencySelection /*for example symbol: symbol or id: id, or location: location*/, amount: amount}, {currencySelection}, ..]
)

✅ Action Required:

• Replace Multiasset: with an array.

---

6. findAsset is now findAssetInfo

The function findAsset is not mentioned in the docs because it is mainly used internally, but this function allows you to see the support of an asset for a specific chain. It was renamed to findAssetInfo. It returns null if not found.

7. findAssetOrThrow is now findAssetInfoOrThrow

The function findAssetOrThrow is not mentioned in the docs because it is mainly used internally, but this function allows you to see the support of an asset for a specific chain. It was renamed to findAssetInfoOrThrow. It returns an error if not found.

8. convertSs58 now uses types for ecosystem param: TRelaychain | TExternalChain

The function previously took ecosystem names as lowercase strings such as 'polkadot', 'kusama', and so on. It has now migrated to using the new TRelaychain | TExternalChain chain types to improve the experience. Explore more about the types here.

9. Pull Request Reference

For a detailed technical overview of these changes, see:
🔗 PR #1064: Decimal abstraction & chain changes

---

Summary Table

Change	v10	v11	Action
multi prefix removed everywhere	Multilocation	Location	Rename functions & types
NODE renamed to CHAIN	TNode	TChain	Replace all occurrences in types and functions
Chain division constants	CHAINS_WITH_RELAYS	Available via more intuitive constants	Use new constants for imports
Decimal abstraction	Not available	abstractDecimals option	Set to true if you want abstraction - false by default, in the future true by default
BigInt handling	N/A	Abstraction auto-disabled	Be aware when passing bigint, use String or Number instead
Multiasset currency selector is now an array	.currency(Multiasset: {currency}, {currency})	.currency([{currency}, {currency}])	Multiasset currency selector is now completely replaced by array directly.
findAsset is now findAssetInfo	findAsset	findAssetInfo	Rename findAsset to findAssetInfo
findAssetOrThrow is now findAssetInfoOrThrow	findAssetOrThrow	findAssetInfoOrThrow	Rename findAssetOrThrow to findAssetInfoOrThrow
convertSs58 uses types in ecosystem parameter now	convertSs58(ecosystem: 'polkadot', ..)	convertSs58(ecosystem: TRelaychain | TExternalChain)	Use new types as function input instead of string

---

Recommended Migration Steps

1. Search & Replace

   • Remove multi prefix from all functions and types.
   • Replace NODE with CHAIN in constants and functions.

2. Adopt Chain Constants

   • Use the new chain division constants for cleaner imports.

3. Review Decimal Handling

   • Decide whether to enable abstractDecimals now or wait for it to become default in future versions.

4. Test BigInt Scenarios

   • Ensure bigint amounts work as expected without unwanted decimal abstraction.

5. Replace multiasset currency selectors with array

   • Make sure to replace multiasset currency selector directly with an array.

6. Rename findAsset to findAssetInfo

   • Make sure to rename the findAsset function to findAssetInfo.

7. Rename findAssetOrThrow to findAssetInfoOrThrow

   • Make sure to rename the findAssetOrThrow function to findAssetInfoOrThrow.

8. Replace ecosystem parameter from string to new type TRelaychain | TExternalChain in convertSs58

   • Make sure to replace old ecosystem parameter accepting string with TRelaychain | TExternalChain param.

---

This migration ensures compatibility with v11 and prepares your codebase for future defaults in decimal handling.