@paraspell/xcm-router
v1.5.0
Published
Tool for XCM cross-chain asset exchanging across Polkadot and Kusama ecosystems
Downloads
2,274
Readme
Introduction
XCM Router (Codenamed SpellRouter) is ParaSpell's latest innovation, that allows for seamless XCM Exchanges. Send one token type and receive a different one you choose on the destination chain cross-chain. All within one call and three signatures. This seamless operation allows for a better user experience, limiting the possibility of user errors. The router currently implements the 8 largest Parachain DEXes and is easy to extend as the number of DEXes with public SDKs increases. Together, there are 524 asset pools to choose from, making XCM Router the largest liquidity bridging tool in the ecosystem.
Exchanges implemented:
- Acala / 36 Pools available
- Basilisk / 15 Pools available
- BifrostKusama / 66 Pools available / Requires native token for swaps
- BifrostPolkadot / 45 Pools available / Requires native token for swaps
- HydraDX / 210 Pools available
- Interlay / 10 Pools available / Requires native token for swaps
- Karura / 136 Pools available
- Kintsugi / 6 Pools available / Requires native token for swaps
NOTE: Some exchanges require native tokens in order to proceed with swaps.
Installation
Install dependencies
//PNPM temporarily unsupported
npm install || yarn add @polkadot/api @polkadot/types @polkadot/api-base @polkadot/apps-config @polkadot/util
Install XCM Router
//PNPM temporarily unsupported
npm install || yarn add @paraspell/xcm-router
Importing package to your project
Builder pattern:
import { RouterBuilder } from '@paraspell/xcm-router'
Other patterns:
// ESM
import * as xcmRouter from '@paraspell/xcm-router'
//Multiple import options
import { transfer,
TransactionType,
TTransferOptions,
TTxProgressInfo } from '@paraspell/xcm-router'
//As Polkadot moves to ESM only, our Router also moves to ESM only. CJS is not supported anymore.
Implementation
Builder pattern with automatic exchange selection (Based on best price)
If you wish to have an exchange chain selection based on the best price outcome, you can opt for an automatic exchange selection method. This method can be selected by not using the .exchange()
parameter in the call. The router will then automatically select the best exchange chain for you based on the best price outcome.
await RouterBuilder
.from('Polkadot') //Origin Parachain/Relay chain
.to('Astar') //Destination Parachain/Relay chain
.currencyFrom({symbol: 'DOT'}) // Currency to send {id: currencyID} | {symbol: currencySymbol}
.currencyTo({symbol: 'ASTR'}) // Currency to receive {id: currencyID} | {symbol: currencySymbol}
.amount('1000000') // Amount to send
.slippagePct('1') // Max slipppage percentage
.injectorAddress(injectorAddress) //Injector address
.recipientAddress(recipientAddress) //Recipient address
.signer(injector.signer) //Signer
//.evmInjectorAddress(evmInjector address) //Optional parameters when origin node is EVM based (Required with evmSigner)
//.evmSigner(EVM signer) //Optional parameters when origin node is EVM based (Required with evmInjectorAddress)
.onStatusChange((status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
})
.buildAndSend()
Builder pattern with manual exchange selection
If you wish to select your exchange chain manually, you can provide the additional .exchange()
parameter to the call. The router will then use the exchange chain of your choice.
await RouterBuilder
.from('Polkadot') //Origin Parachain/Relay chain
.exchange('HydraDDex') //Exchange Parachain
.to('Astar') //Destination Parachain/Relay chain
.currencyFrom({symbol: 'DOT'}) // Currency to send {id: currencyID} | {symbol: currencySymbol}
.currencyTo({symbol: 'ASTR'}) // Currency to receive {id: currencyID} | {symbol: currencySymbol}
.amount('1000000') // Amount to send
.slippagePct('1') // Max slipppage percentage
.injectorAddress(selectedAccount.address) //Injector address
.recipientAddress(recipientAddress) //Recipient address
.signer(injector.signer) //Signer
//.evmInjectorAddress(evmInjector address) //Optional parameters when origin node is EVM based (Required with evmSigner)
//.evmSigner(EVM signer) //Optional parameters when origin node is EVM based (Required with evmInjectorAddress)
.onStatusChange((status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
})
.buildAndSend()
Function pattern with automatic exchange selection (Based on best price)
If you wish to have an exchange chain selection based on the best price outcome, you can opt for an automatic exchange selection method. This method can be selected by not using exchange:
parameter in the call. The router will then automatically select the best exchange chain for you based on the best price outcome.
await transfer({
from: 'Polkadot', //Origin Parachain/Relay chain
to: 'Interlay', //Destination Parachain/Relay chain
currencyFrom: {symbol: 'DOT'}, // Currency to send {id: currencyID} | {symbol: currencySymbol}
currencyTo: {symbol: 'INTR'}, // Currency to receive {id: currencyID} | {symbol: currencySymbol}
amount: '100000', // Amount to send
slippagePct: '1', // Max slipppage percentage
injectorAddress: selectedAccount.address, //Injector address
address: recipientAddress, //Recipient address
signer: injector.signer, //Signer
//evmInjectorAddress: evmInjector address, //Optional parameters when origin node is EVM based (Required with evmSigner)
//evmSigner: EVM signer, //Optional parameters when origin node is EVM based (Required with evmInjectorAddress)
onStatusChange: (status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
},
});
Function pattern with manual exchange selection
If you wish to select your exchange chain manually, you can provide the additional exchange:
parameter to the call. The router will then use the exchange chain of your choice.
await transfer({
from: 'Polkadot', //Origin Parachain/Relay chain
exchange: 'AcalaDex', //Exchange Parachain
to: 'Interlay', //Destination Parachain/Relay chain
currencyFrom: {symbol: 'DOT'}, // Currency to send
currencyTo: {symbol: 'INTR'}, // Currency to receive
amount: '100000', // Amount to send
slippagePct: '1', // Max slipppage percentage
injectorAddress: selectedAccount.address, //Injector address
address: recipientAddress, //Recipient address
signer: injector.signer, //Signer
//evmInjectorAddress: evmInjector address, //Optional parameters when origin node is EVM based (Required with evmSigner)
//evmSigner: EVM signer, //Optional parameters when origin node is EVM based (Required with evmInjectorAddress)
onStatusChange: (status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
},
});
Snowbridge
You can now use Ethereum <> Polkadot bridge in the XCM Router. There are two scenarios to this transfer.
Polkadot -> Ethereum
Following scenario works just like normal transfer, you just select Ethereum as destination chain. See example below.
await RouterBuilder
.from('Origin') //Origin Parachain/Relay chain
.to('Ethereum')
.currencyFrom({symbol: 'DOT'}) // Currency to send {id: currencyID} | {symbol: currencySymbol}
.currencyTo({symbol: 'WETH'}) // Any currency supported by Ethereum bridge (WETH, WBTC and more) - {id: currencyID} | {symbol: currencySymbol}
.amount('1000000') // Amount to send
.slippagePct('1') // Max slipppage percentage
.injectorAddress(selectedAccount.address) //Injector address
.recipientAddress(recipientAddress) //Recipient address
.signer(injector.signer) //Signer
//.evmInjectorAddress(evmInjector address) //Optional parameters when origin node is EVM based (Required with evmSigner)
//.evmSigner(EVM signer) //Optional parameters when origin node is EVM based (Required with evmInjectorAddress)
.onStatusChange((status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
})
.buildAndSend()
Ethereum -> Polkadot
The other scenario is a little different as it requires other parameters because Ethereum has different wallets and signers.
await RouterBuilder()
.from('Ethereum')
.to('Destination') //Destination Chain
.currencyTo({symbol: 'WETH'}) // Any currency supported by Ethereum bridge (WETH, WBTC and more) - {id: currencyID} | {symbol: currencySymbol}
.currencyTo({symbol: 'GLMR'}) // Currency to receive {id: currencyID} | {symbol: currencySymbol}
.amount('1000000') // Amount to send
.injectorAddress(selectedAccount.address) //Injector address
.recipientAddress(recipientAddress) //Recipient address
.signer(injector.signer) //Signer
.slippagePct('1') // Max slipppage percentage
.onStatusChange(onStatusChange)
.assetHubAddress(address) //Asset Hub address where currency from Ethereum will be sent
.ethSigner(ethSigner) // Ethereum signer
.build();
.onStatusChange((status: TTxProgressInfo) => { //This is how we subscribe to calls that need signing
console.log(status.hashes); //Transaction hashes
console.log(status.status); //Transaction statuses
console.log(status.type); //Transaction types
})
.buildAndSend()
List of DEX chains, assets, and Parachains supported by XCM Router
| DEX | Can send to/receive from | Supported assets | Notes | | ------------- | ------------- | ------------- |------------- | | Acala DEX |Polkadot Relay, Astar, HydraDX, Interlay, Moonbeam, Parallel, AssetHubPolkadot, Unique network|ACA, DOT, aSEED, USDCet, UNQ, IBTC, INTR, lcDOT, LDOT| Fees are paid by either ACA or DOT| |Karura DEX| Kusama Relay, Altair, Basilisk, BifrostKusama, Calamari, Crab, Parallel Heiko, Kintsugi, Moonriver, Quartz, Crust Shadow, Shiden, AssetHubKusama| BNC, USDCet, RMRK, ARIS, AIR, QTZ, CSM, USDT, KAR, KBTC, KINT, KSM, aSEED, LKSM, PHA, tKSM, TAI | Fees are paid by either KAR or KSM| |Hydration DEX| Polkadot Relay, Acala, Interlay, AssetHubPolkadot, Zeitgeist, Astar, Centrifuge, BifrostPolkadot, Mythos | USDT, MYTH, HDX, WETH, GLMR, IBTC, BNC, WBTC, vDOT, DAI, CFG, DOT, DAI, ZTG, WBTC, INTR, ASTR, LRNA, USDC| Chain automatically gives you native asset to pay for fees.| | Basilisk DEX | Kusama Relay, Karura, AssetHubKusama, Tinkernet, Robonomics| BSX, USDT, aSEED, XRT, KSM, TNKR| Chain automatically gives you native asset to pay for fees.| |Bifrost Kusama DEX| Kusama Relay, AssetHubKusama, Karura, Moonriver, Kintsugi| BNC, vBNC, vsKSM, vKSM, USDT, aSEED, KAR, ZLK, RMRK, KBTC, MOVR, vMOVR| Chain requires native BNC asset for fees.| |Bifrost Polkadot DEX| Polkadot Relay, AssetHubPolkadot, Moonbeam, Astar, Interlay| BNC, vDOT, vsDOT, USDT, FIL, vFIL, ASTR, vASTR, GLMR, vGLMR, MANTA, vMANTA|Chain requires native BNC asset for fees.| |Interlay DEX| Polkadot Relay, Acala, Astar, Parallel, PolkadotAssetHub, HydraDX, BifrostPolkadot |INTR, DOT, IBTC, USDT, VDOT| Chain requires native INTR asset for fees.| |Kintsugi DEX| Kusama Relay, Karura, KusamaAssetHub, Parallel Heiko, BifrostKusama|KINT,KSM,KBTC,USDT|Chain requires native KINT asset for fees.|
💻 Testing
Run compilation using
yarn compile
Run linting test using
yarn lint
Run unit tests using
yarn test
Run integration tests using
yarn test:integration
XCM Router can be tested in Playground.
License
Made with 💛 by ParaSpell✨
Published under MIT License.