From c77256e3d044795edd2c1ef80f3651bd7b6b4204 Mon Sep 17 00:00:00 2001 From: Mario J Maurello Date: Thu, 2 Jan 2025 16:33:56 +0100 Subject: [PATCH] -wip- use mrl pag4e --- mkdocs/docs/example-usage-mrl.md | 735 ++++++++++++++++++++++++++++++- mkdocs/docs/example-usage.md | 4 +- 2 files changed, 729 insertions(+), 10 deletions(-) diff --git a/mkdocs/docs/example-usage-mrl.md b/mkdocs/docs/example-usage-mrl.md index e83a83d4..9066c551 100644 --- a/mkdocs/docs/example-usage-mrl.md +++ b/mkdocs/docs/example-usage-mrl.md @@ -188,16 +188,735 @@ The chained methods will provide data on the assets and chains along the way, bu 5. Call the `setIsAutomatic` function and pass in the boolean value to define if the transfer should be automatic or not. ```js - const { setIsAutomatic } = setIsAutomatic(false); + const { setAddresses } = setIsAutomatic(false); ``` There are routes in which the automatic transfer is not supported. You can check it in the [chains configuration file](https://github.com/moonbeam-foundation/mrl-config/blob/main/src/chains/chains.ts). If you set automatic as `true` for a route that is not supported, the SDK will throw an error at the moment of fetching the transfer data. -6. Call the `setAddresses` function and pass in the source and destination addresses to define the addresses for the transfer +6. Finally call the `setAddresses` function and pass in the source and destination addresses to define the addresses for the ransfer. This will return the transfer data including the balances of the source and destination addresses. Take into account that depending on the source or the destination chain, the address format will be different. For example, from Ethereum to Hydration, you can pass as the source the address from the EVM signer, but as the destination the address from the Polkadot signer. - ```js - const { setAddresses } = setAddresses({ - sourceAddress: account.address, - destinationAddress: account.address, - }); - ``` +An example of the steps described above to build the transfer data to transfer USDC from Ethereym to Hydration is as follows: + +```js +import { Mrl } from '@moonbeam-network/mrl'; +import { hydration, usdc } from '@moonbeam-network/xcm-config'; +import { ethereum } from '@moonbeam-network/xcm-config'; +import { Ecosystem } from '@moonbeam-network/xcm-types'; + +const fromEvm = async () => { + const mrlInstance = Mrl({ ecosystem: Ecosystem.Polkadot }); + const { sources, setSource } = mrlInstance; + + console.log( + `The supported sources are: ${sources.map((asset) => asset.name)}`, + ); + + const { destinations, setDestination } = setSource(ethereum); + console.log( + `The supported destinations are: ${destinations.map((asset) => asset.name)}`, + ); + + const { assets, setAsset } = setDestination(hydration); + console.log( + `The supported assets are: ${assets.map((asset) => asset.originSymbol)}`, + ); + + const { setIsAutomatic } = setAsset(usdc); + + const { setAddresses } = setIsAutomatic(false); + + const transferData = await setAddresses({ + sourceAddress: account.address, + destinationAddress: pair.address, + }); + + console.log(transferData); + +}; + +fromEvm(); + +``` + +The same output will be generated regardless of which example you used to build the transfer data. + +??? code "Example response" + + ```js + // Send USDC from Ethereum to Hydration + // transfer data + { + destination: { + chain: _Parachain { + assets: Map(7) { + "hdx": [Object ...], + "glmr": [Object ...], + "dai": [Object ...], + "usdcwh": [Object ...], + "usdtwh": [Object ...], + "wbtc": [Object ...], + "weth": [Object ...], + }, + ecosystem: "polkadot", + explorer: "https://hydradx.subscan.io", + isTestChain: false, + key: "hydration", + name: "Hydration", + wh: undefined, + checkSovereignAccountBalances: false, + genesisHash: "0xafdc188f45c71dacbaa0b62e16a91f726c7b8699a9748cdf715459de6b7f366d", + isRelay: false, + parachainId: 2034, + ss58Format: 63, + usesChainDecimals: false, + weight: undefined, + ws: [ "wss://rpc.hydradx.cloud", "wss://rpc.helikon.io/hydradx", "wss://hydradx.paras.dotters.network", + "wss://hydradx-rpc.dwellir.com" + ], + nativeAsset: [Getter], + isEqual: [Function: isEqual], + getChainAsset: [Function: getChainAsset], + getWormholeName: [Function: getWormholeName], + }, + balance: _AssetAmount { + key: "usdcwh", + originSymbol: "USDC.Wh", + address: undefined, + decimals: 6, + ids: [Object ...], + min: undefined, + symbol: undefined, + amount: 8271697n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + existentialDeposit: _AssetAmount { + key: "hdx", + originSymbol: "HDX", + address: undefined, + decimals: 12, + ids: [Object ...], + min: undefined, + symbol: undefined, + amount: 1000000000000n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + fee: _AssetAmount { + key: "usdcwh", + originSymbol: "USDC.Wh", + address: undefined, + decimals: 6, + ids: [Object ...], + min: undefined, + symbol: undefined, + amount: 4000n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + min: _AssetAmount { + key: "usdcwh", + originSymbol: "USDC.Wh", + address: undefined, + decimals: 6, + ids: [Object ...], + min: undefined, + symbol: undefined, + amount: 0n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + sovereignAccountBalances: undefined, + }, + getEstimate: [Function: getEstimate], + isAutomaticPossible: false, + max: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 3328424n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + min: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 4000n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + moonChain: { + address: "0x98891e5FD24Ef33A488A47101F65D212Ff6E650E", + balance: _AssetAmount { + key: "usdcwh", + originSymbol: "USDC.Wh", + address: "0x931715FEE2d06333043d11F658C8CE934aC61D0c", + decimals: 6, + ids: [Object ...], + min: undefined, + symbol: undefined, + amount: 2081768n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + feeBalance: _AssetAmount { + key: "glmr", + originSymbol: "GLMR", + address: "0x0000000000000000000000000000000000000802", + decimals: 18, + ids: [Object ...], + min: 100000000000000000n, + symbol: undefined, + amount: 206735189943789999813n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + chain: _EvmParachain { + assets: Map(45) { + "aca": [Object ...], + "astr": [Object ...], + "aseed": [Object ...], + "axlusdc": [Object ...], + "bnc": [Object ...], + "bncs": [Object ...], + "cfg": [Object ...], + "dai": [Object ...], + "ded": [Object ...], + "dot": [Object ...], + "eq": [Object ...], + "eqd": [Object ...], + "fil": [Object ...], + "glmr": [Object ...], + "hdx": [Object ...], + "ibtc": [Object ...], + "intr": [Object ...], + "ldot": [Object ...], + "manta": [Object ...], + "nodl": [Object ...], + "neuro": [Object ...], + "peaq": [Object ...], + "pha": [Object ...], + "pen": [Object ...], + "ring": [Object ...], + "sub": [Object ...], + "usdc": [Object ...], + "usdcwh": [Object ...], + "usdtwh": [Object ...], + "usdt": [Object ...], + "vastr": [Object ...], + "vdot": [Object ...], + "vfil": [Object ...], + "vglmr": [Object ...], + "vmanta": [Object ...], + "wbtc": [Object ...], + "weth": [Object ...], + "ztg": [Object ...], + "pink": [Object ...], + "stink": [Object ...], + "apillon": [Object ...], + "wifd": [Object ...], + "wbtce": [Object ...], + "wethe": [Object ...], + "wstethe": [Object ...], + }, + ecosystem: "polkadot", + explorer: "https://moonbeam.moonscan.io", + isTestChain: false, + key: "moonbeam", + name: "Moonbeam", + wh: [Object ...], + checkSovereignAccountBalances: false, + genesisHash: "0xfe58ea77779b7abda7da4ec526d14db9b1e9cd40a217c34892af80a9b332b76d", + isRelay: false, + parachainId: 2004, + ss58Format: 1284, + usesChainDecimals: false, + weight: undefined, + ws: [ "wss://wss.api.moonbeam.network" ], + id: 1284, + rpc: "https://rpc.api.moonbeam.network", + isEvmSigner: true, + contracts: undefined, + getViemChain: [Function: getViemChain], + nativeAsset: [Getter], + isEqual: [Function: isEqual], + getChainAsset: [Function: getChainAsset], + getWormholeName: [Function: getWormholeName], + }, + fee: _AssetAmount { + key: "glmr", + originSymbol: "GLMR", + address: "0x0000000000000000000000000000000000000802", + decimals: 18, + ids: [Object ...], + min: 100000000000000000n, + symbol: undefined, + amount: 150000000000000000n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + }, + source: { + balance: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 3328424n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + chain: _EvmChain { + assets: Map(7) { + "eth": [Object ...], + "usdc": [Object ...], + "usdt": [Object ...], + "dai": [Object ...], + "wbtc": [Object ...], + "glmr": [Object ...], + "peaq": [Object ...], + }, + ecosystem: "polkadot", + explorer: "https://etherscan.io", + isTestChain: false, + key: "ethereum", + name: "Ethereum", + wh: [Object ...], + id: 1, + rpc: "https://ethereum-rpc.publicnode.com", + getViemChain: [Function: getViemChain], + nativeAsset: [Getter], + isEqual: [Function: isEqual], + getChainAsset: [Function: getChainAsset], + getWormholeName: [Function: getWormholeName], + }, + destinationFee: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 4000n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + destinationFeeBalance: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 3328424n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + moonChainFeeBalance: undefined, + existentialDeposit: undefined, + fee: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 0n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + feeBalance: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 3328424n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + max: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 3328424n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + min: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 0n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + relayerFee: _AssetAmount { + key: "usdc", + originSymbol: "USDC", + address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + decimals: 6, + ids: undefined, + min: undefined, + symbol: undefined, + amount: 0n, + isSame: [Function: isSame], + isEqual: [Function: isEqual], + copyWith: [Function: copyWith], + convertDecimals: [Function: convertDecimals], + toBig: [Function: toBig], + toBigDecimal: [Function: toBigDecimal], + toDecimal: [Function: toDecimal], + getSymbol: [Function: getSymbol], + getAssetId: [Function: getAssetId], + getBalanceAssetId: [Function: getBalanceAssetId], + getMinAssetId: [Function: getMinAssetId], + getAssetPalletInstance: [Function: getAssetPalletInstance], + getAssetMin: [Function: getAssetMin], + hasOnlyAddress: [Function: hasOnlyAddress], + }, + }, + transfer: [AsyncFunction: transfer], + } + + ``` + +As you may have noticed in the example response, the transfer data contains information on the asset, source, and destination chain, and also the moonChian. In addition, a couple of functions have been exposed: + + +- [`transfer`](./reference/methods.md#the-transfer-method) - transfers a given amount of the asset from the source chain to the destination chain + +- [`getEstimate`](./reference/methods.md#the-get-estimate-method) - returns an estimated amount of the asset that will be received on the destination chain, less any destination fees + +## Transfer an Asset {: #transfer-an-asset } + + +Now that you've built the transfer data, you can transfer the asset from the source chain to the destination chain. To do so, you can use the [`transfer`](./reference/methods.md#the-transfer-method) function, but first, you'll need to specify an amount to send. You can specify the amount in integer or decimal format. For example, if you wanted to send 0.1 USDC, you could use `100000n` or `'0.1'`. You can use [asset conversion methods](./reference/methods.md#asset-utilities){target=\_blank}, like [`toDecimal`](./reference/methods.md#the-to-decimal-method) to convert the asset to decimal format. +You'll also need to specify if the transfer is automatic or not and the signer you're using for the transfer. + + +For this example, you can transfer twice the minimum amount required of USDC: + +```js +... + +const amount = +transferData.min.toDecimal() * 1.5 + 0.000001; +console.log( + `\nSending ${amount} ${transferData.source.balance.getSymbol()} from ${transferData.source.chain.name} to ${transferData.destination.chain.name}`, +); +const result = await transferData.transfer(amount, false, { + evmSigner: walletClient, +}); +``` + +The `transfer` function returns an array of strings that represent the transaction hashes. It is an array because for some assets coming from EVM chains, two transactions are sent in the process: one Approve and the actual Transfer. Where applicable, the first transaction is the Approve and the second is the Transfer. Where an Approve is not needed, only one transaction is returned. + +!!! note + +The transfer function also admits other optional parameters, which are not needed for this example. For more information on the parameters and returned data for `transfer`, please refer to the [MRL SDK Reference](./reference/methods.md#the-transfer-method){target=\_blank}. + +## Redeem the Asset - Complete the Transfer {: #redeem-an-asset } + + + +As mentioned before, if the isAutomatic flag is set to false, a manual redeem is required to complete the transfer in the destination chain of the bridge (redeem chain). Take into account that, if the transfer is from EVM chains to a Parachain, the redeem chain is the MoonChain, which is where the GMP contract call is made to initiate the XCM transfer to the destination parachain. For other types of transfers, the redeem chain is the destination chain. + +This SDK also provides a function for redeeming, but the same way as with the transfer, you first have to build the redeem data. + +### Build the Redeem Data {: #build-the-redeem-data } + +Following the example above, you can build the redeem data by calling the [`getRedeemData`](./reference/methods.md#the-get-redeem-data-method) function, with the transfer hash that was returned from the transfer function. + +Remember that for this example (Ethereum to Hydration), the redeem chain is going to be Moonbeam, which can be extracted from the transfer data as moonChain. + +```js +... + +const hash = result.pop(); + +if (!isAutomatic && hash) { + const redeemData = await Mrl().getRedeemData({ + txId: hash, + chain: transferData.moonChain.chain, + }); +} +``` + +### Redeem the Asset {: #redeem-the-asset } + + +Once you have the redeem data, you can redeem the asset by calling the [`redeem`](./reference/methods.md#the-redeem-method) function. +You'll need to specify the signer you're using for the redeem chain. Note that the signer is different from the signer used for the transfer, as the chains are different. + +```js +... + +const redeemChainWalletClient = createWalletClient({ + account, + chain: transferData.moonChain.chain.getViemChain(), + transport: http(), +}); + + +const redeemResult = await redeemData.redeem(redeemChainWalletClient); +``` + +## Get an Estimate of the Asset to Be Received on the Destination Chain {: #get-estimate } + + +When you send an MRL message, you typically pay fees on the destination chain to execute the XCM instructions, if any, or to pay the relayer if the transfer is set as automatic. Before you transfer the asset, you can use the [`getEstimate`](./reference/methods.md#the-get-estimate-method) function to calculate an estimated amount of the asset that will be received on the destination chain minus any fees. + + +The `getEstimate` function is tied to a specific transfer request as it is based on the asset being transferred and the destination chain fees, so you'll need to create the [transfer data](#build-xcm-transfer-data) first. + +You must provide the amount to be transferred to the `getEstimate` function. In the following example, you'll get the estimated amount of DOT that will be received on Moonbeam when 0.1 DOT is transferred. You can specify the amount in integer (`1000000000n`) or decimal (`'0.1'`) format. + +```js +... + +const amount = '0.1'; +const estimatedAmount = transferData.getEstimate(amount); + +console.log( + `The estimated amount of ${ + transferData.source.balance.originSymbol + } to be received on ${ + transferData.destination.chain.name + } is: ${estimatedAmount.toDecimal()} ${transferData.destination.balance.getSymbol()}`, +); +``` + +## Get information about the MoonChain {: #get-moonchain-info } + + +The MoonChain (Moonbeam for Mainnet and Moonbase Alpha for Testnet) is the chain which serves as intermediary between the Polkadot Ecosystem and external chains. + +Depending on the type of transfer you're making, you may need to have balance in the MoonChain to pay for the fees. You can see the information about the balance by looking at the `moonChain` property in the transfer data. + +```js +... + +console.log( + `This transfer will need to pay ${transferData.moonChain.fee.amount} ${transferData.moonChain.fee.getSymbol()} in ${transferData.moonChain.chain.name}`, +); +console.log( + `The current balance in ${transferData.moonChain.chain.name} for the address ${transferData.moonChain.address} is ${transferData.moonChain.feeBalance.toDecimal()} ${transferData.moonChain.feeBalance.getSymbol()}`, +); +``` diff --git a/mkdocs/docs/example-usage.md b/mkdocs/docs/example-usage.md index 75cb8e5f..9523fcd5 100644 --- a/mkdocs/docs/example-usage.md +++ b/mkdocs/docs/example-usage.md @@ -378,7 +378,7 @@ The same output will be generated regardless of which example you used to build ```js // Send DOT from Polkadot to Moonbeam - // data + // transfer data { destination: { chain: _EvmParachain { @@ -871,7 +871,7 @@ const estimatedAmount = transferData.getEstimate(amount); console.log( `The estimated amount of ${ - transferData.source.balance.originSymbol + transferData.source.balance.getSymbol() } to be received on ${ transferData.destination.chain.name } is: ${estimatedAmount.toDecimal()} ${transferData.destination.balance.getSymbol()}`,