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:

diff

- multilocation()
+ location()

- getAssetMultilocation()
+ getAssetLocation()

This was done, because 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:

diff

- TNode
+ TChain

- getTNode()
+ getTChain()

Term node is not as informative to new developers as 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(TParachain)

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

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

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

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

Instead of previous

// Export all Parachains
console.log(CHAINS_WITH_RELAYS)

Previous type division was a little messy, new type division counts with chains outside Polkadot ecosystem such as Ethereum as well.

✅ 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 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 do not wish to use 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 value as Bigint will require decimal inputs.

5. Multiasset type is now an array:

Previously we used multiasset selector for multiple assets in one call with the removal of multi prefix we decided to completely replace selector by 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. 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 types	CHAINS_WITH_RELAYS	Available via more intuitive types	Use new types 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.

Recommended Migration Steps

Search & Replace
- Remove multi prefix from all functions and types.
- Replace NODE with CHAIN in constants and functions.
Adopt Chain Types
- Use the new chain division types for cleaner imports.
Review Decimal Handling
- Decide whether to enable abstractDecimals now or wait for it to become default in future versions.
Test BigInt Scenarios
- Ensure bigint amounts work as expected without unwanted decimal abstraction.
Replace multiasset currency selectors with array
- Make sure to replace multiasset currency selector directly with an array.

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

Migration Guide — v10 ➡ v11 ​

1. Removal of the multi Prefix ​

2. NODE ➡ CHAIN Renaming ​

3. New Chain Division Types ​

4. Decimal Abstraction Setting (abstractDecimals) ​

Default Behavior ​

Purpose ​

Special Case: bigint ​

5. Multiasset type is now an array: ​

6. Pull Request Reference ​

Summary Table ​

Recommended Migration Steps ​