diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md new file mode 100644 index 000000000..58667b413 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md @@ -0,0 +1,24 @@ +
+ ts-node localParachainTx.ts +
+ Call data: + { + "origin": "moonbeam", + "dest": "moonbeam", + "direction": "local", + "xcmVersion": null, + "method": "balances::transferKeepAlive", + "format": "call", + "tx": "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600" + } + + Decoded tx: + { + "args": { + "dest": "0xF977814e90dA44bFA03b6295A0616a897441aceC", + "value": "1,000,000,000,000,000,000" + }, + "method": "transferKeepAlive", + "section": "balances" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts new file mode 100644 index 000000000..a2a6453b6 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts @@ -0,0 +1,37 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://wss.api.moonbeam.network" + ); + const assetApi = new AssetTransferApi(api, specName, safeXcmVersion); + + let callInfo; + try { + callInfo = await assetApi.createTransferTransaction( + "2004", + "0xF977814e90dA44bFA03b6295A0616a897441aceC", + [], + ["1000000000000000000"], + { + format: "call", + keepAlive: true, + } + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } + + const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call"); + console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`); +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md new file mode 100644 index 000000000..ff1535601 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md @@ -0,0 +1,87 @@ +
+ ts-node paraToPara.ts + +
+ Call data: + { + "origin": "moonriver", + "dest": "bifrost", + "direction": "ParaToPara", + "xcmVersion": 2, + "method": "transferMultiassets", + "format": "call", + "tx": "0x6a05010800010200451f06080101000700e40b540200010200451f0608010a0002093d000000000001010200451f0100c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300" + } + + Decoded tx: + { + "args": { + "assets": { + "V2": [ + { + "id": { + "Concrete": { + "parents": "1", + "interior": { + "X2": [ + { + "Parachain": "2,001" + }, + { + "GeneralKey": "0x0101" + } + ] + } + } + }, + "fun": { + "Fungible": "10,000,000,000" + } + }, + { + "id": { + "Concrete": { + "parents": "1", + "interior": { + "X2": [ + { + "Parachain": "2,001" + }, + { + "GeneralKey": "0x010a" + } + ] + } + } + }, + "fun": { + "Fungible": "1,000,000" + } + } + ] + }, + "fee_item": "0", + "dest": { + "V2": { + "parents": "1", + "interior": { + "X2": [ + { + "Parachain": "2,001" + }, + { + "AccountId32": { + "network": "Any", + "id": "0xc4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a063" + } + } + ] + } + } + }, + "dest_weight_limit": "Unlimited" + }, + "method": "transferMultiassets", + "section": "xTokens" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts new file mode 100644 index 000000000..c5dbd7809 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts @@ -0,0 +1,36 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://moonriver.public.blastapi.io" + ); + const assetApi = new AssetTransferApi(api, specName, safeXcmVersion); + let callInfo; + try { + callInfo = await assetApi.createTransferTransaction( + "2001", + "0xc4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a063", + ["vMOVR", "72145018963825376852137222787619937732"], + ["1000000", "10000000000"], + { + format: "call", + xcmVersion: safeXcmVersion, + } + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } + + const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call"); + console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`); +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md new file mode 100644 index 000000000..dea06e3b5 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md @@ -0,0 +1,62 @@ +
+ ts-node relayToSystem.ts +
+ Call data: + { + "origin": "westend", + "dest": "westmint", + "direction": "RelayToSystem", + "xcmVersion": 3, + "method": "transferAssets", + "format": "call", + "tx": "0x630b03000100a10f03000101006c0c32faf970eacb2d4d8e538ac0dab3642492561a1be6f241c645876c056c1d030400000000070010a5d4e80000000000" + } + + Decoded tx: + { + "args": { + "dest": { + "V3": { + "parents": "0", + "interior": { + "X1": { + "Parachain": "1,000" + } + } + } + }, + "beneficiary": { + "V3": { + "parents": "0", + "interior": { + "X1": { + "AccountId32": { + "network": null, + "id": "0x6c0c32faf970eacb2d4d8e538ac0dab3642492561a1be6f241c645876c056c1d" + } + } + } + } + }, + "assets": { + "V3": [ + { + "id": { + "Concrete": { + "parents": "0", + "interior": "Here" + } + }, + "fun": { + "Fungible": "1,000,000,000,000" + } + } + ] + }, + "fee_asset_item": "0", + "weight_limit": "Unlimited" + }, + "method": "transferAssets", + "section": "xcmPallet" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts new file mode 100644 index 000000000..ead3c4be5 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts @@ -0,0 +1,36 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://westend-rpc.polkadot.io" + ); + const assetApi = new AssetTransferApi(api, specName, safeXcmVersion); + let callInfo; + try { + callInfo = await assetApi.createTransferTransaction( + "1000", + "5EWNeodpcQ6iYibJ3jmWVe85nsok1EDG8Kk3aFg8ZzpfY1qX", + ["WND"], + ["1000000000000"], + { + format: "call", + xcmVersion: safeXcmVersion, + } + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } + + const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call"); + console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`); +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts new file mode 100644 index 000000000..24f32ef24 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts @@ -0,0 +1,16 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "INSERT_WEBSOCKET_URL" + ); + + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + // Your code using assetsApi goes here +} + +main(); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md new file mode 100644 index 000000000..b9029d958 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md @@ -0,0 +1,10 @@ +```ts +export type AssetTransferType = + | LocalReserve + | DestinationReserve + | Teleport + | RemoteReserve; +``` + +!!! note + To use the `assetTransferType` parameter, which is a string, you should use the `AssetTransferType` type as if each of its variants are strings. For example: `assetTransferType = 'LocalReserve'`. \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts new file mode 100644 index 000000000..d35427a2d --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts @@ -0,0 +1,35 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://westend-rpc.polkadot.io" + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + let callInfo; + try { + callInfo = await assetsApi.claimAssets( + [ + `{"parents":"0","interior":{"X2":[{"PalletInstance":"50"},{"GeneralIndex":"1984"}]}}`, + ], + ["1000000000000"], + "0xf5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b", + { + format: "call", + xcmVersion: 2, + } + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md new file mode 100644 index 000000000..cea34c61c --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md @@ -0,0 +1,12 @@ +
+ Call data: + { + "origin": "0", + "dest": "westend", + "direction": "local", + "xcmVersion": 2, + "method": "claimAssets", + "format": "call", + "tx": "0x630c0104000002043205011f00070010a5d4e80100010100f5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts new file mode 100644 index 000000000..4303c60d1 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts @@ -0,0 +1,6 @@ +public async claimAssets( + assetIds: string[], + amounts: string[], + beneficiary: string, + opts: TransferArgsOpts +): Promise>; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md new file mode 100644 index 000000000..7b610adf8 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md @@ -0,0 +1,15 @@ +```ts +export type ConstructedFormat = T extends 'payload' + ? GenericExtrinsicPayload + : T extends 'call' + ? `0x${string}` + : T extends 'submittable' + ? SubmittableExtrinsic<'promise', ISubmittableResult> + : never; +``` + +The `ConstructedFormat` type is a conditional type that returns a specific type based on the value of the TxResult `format` field. + +- Payload format - if the format field is set to `'payload'`, the `ConstructedFormat` type will return a [`GenericExtrinsicPayload`](https://github.com/polkadot-js/api/blob/3b7b44f048ff515579dd233ea6964acec39c0589/packages/types/src/extrinsic/ExtrinsicPayload.ts#L48){target=_blank} +- Call format - if the format field is set to `'call'`, the `ConstructedFormat` type will return a hexadecimal string (`0x${string}`). This is the encoded representation of the extrinsic call +- Submittable format - if the format field is set to `'submittable'`, the `ConstructedFormat` type will return a [`SubmittableExtrinsic`](https://github.com/polkadot-js/api/blob/3b7b44f048ff515579dd233ea6964acec39c0589/packages/api-base/src/types/submittable.ts#L56){target=_blank}. This is a Polkadot.js type that represents a transaction that can be submitted to the blockchain \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts new file mode 100644 index 000000000..4cfca7993 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts @@ -0,0 +1,34 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://wss.api.moonbeam.network" + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + let callInfo; + try { + callInfo = await assetsApi.createTransferTransaction( + "2004", + "0xF977814e90dA44bFA03b6295A0616a897441aceC", + [], + ["1000000000000000000"], + { + format: "call", + keepAlive: true, + } + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md new file mode 100644 index 000000000..a1bb01f6a --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md @@ -0,0 +1,12 @@ +
+ Call data: + { + "origin": "moonbeam", + "dest": "moonbeam", + "direction": "local", + "xcmVersion": null, + "method": "balances::transferKeepAlive", + "format": "call", + "tx": "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts new file mode 100644 index 000000000..0af1ef38c --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts @@ -0,0 +1,7 @@ +public async createTransferTransaction( + destChainId: string, + destAddr: string, + assetIds: string[], + amounts: string[], + opts: TransferArgsOpts = {} +): Promise>; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts new file mode 100644 index 000000000..903714021 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts @@ -0,0 +1,27 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://wss.api.moonbeam.network" + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + const encodedExt = "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600"; + + try { + const decodedExt = assetsApi.decodeExtrinsic(encodedExt, "call"); + console.log( + `Decoded tx:\n ${JSON.stringify(JSON.parse(decodedExt), null, 4)}` + ); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md new file mode 100644 index 000000000..3bc83e19d --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md @@ -0,0 +1,11 @@ +
+ Decoded tx: + { + "args": { + "dest": "0xF977814e90dA44bFA03b6295A0616a897441aceC", + "value": "100,000" + }, + "method": "transferKeepAlive", + "section": "balances" + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts new file mode 100644 index 000000000..197d817df --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts @@ -0,0 +1,4 @@ +public decodeExtrinsic( + encodedTransaction: string, + format: T +): string; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts new file mode 100644 index 000000000..6fc39c42e --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts @@ -0,0 +1,25 @@ +import { + AssetTransferApi, + constructApiPromise, +} from "@substrate/asset-transfer-api"; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + "wss://wss.api.moonbeam.network" + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + const encodedExt = "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600"; + + try { + const decodedExt = await assetsApi.fetchFeeInfo(encodedExt, "call"); + console.log(`Fee info:\n${JSON.stringify(decodedExt, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md new file mode 100644 index 000000000..3f90dea38 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md @@ -0,0 +1,11 @@ +
+ Fee info: + { + "weight": { + "refTime": 163777000, + "proofSize": 3581 + }, + "class": "Normal", + "partialFee": 0 + } +
\ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts new file mode 100644 index 000000000..7f87e9aa8 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts @@ -0,0 +1,4 @@ +public async fetchFeeInfo( + tx: ConstructedFormat, + format: T +): Promise; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts new file mode 100644 index 000000000..7e20a0012 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts @@ -0,0 +1 @@ +export type Format = "payload" | "call" | "submittable"; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md new file mode 100644 index 000000000..e244fecbc --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md @@ -0,0 +1,94 @@ +Options for customizing the claim assets transaction. These options allow you to specify the transaction format, fee payment details, weight limits, XCM versions, and more. + +??? child "Show more" + + `format` ++"T extends Format"++ + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + + --- + + `paysWithFeeOrigin` ++"string"++ + + The Asset ID to pay fees on the current common good parachain. The defaults are as follows: + + - Polkadot Asset Hub - `'DOT'` + - Kusama Asset Hub - `'KSM'` + + --- + + `paysWithFeeDest` ++"string"++ + + Asset ID to pay fees on the destination parachain. + + --- + + `weightLimit` ++"{ refTime?: string, proofSize?: string }"++ + + Custom weight limit option. If not provided, it will default to unlimited. + + --- + + `xcmVersion` ++"number"++ + + Sets the XCM version for message construction. If this is not present a supported version will be queried, and if there is no supported version a safe version will be queried. + + --- + + `keepAlive` ++"boolean"++ + + Enables `transferKeepAlive` for local asset transfers. For creating local asset transfers, if `true` this will allow for a `transferKeepAlive` as opposed to a `transfer`. + + --- + + `transferLiquidToken` ++"boolean"++ + + Declares if this will transfer liquidity tokens. Default is `false`. + + --- + + `assetTransferType` ++"string"++ + + The XCM transfer type used to transfer assets. The `AssetTransferType` type defines the possible values for this parameter. + + ??? child "Type `AssetTransferType`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md' + + --- + + `remoteReserveAssetTransferTypeLocation` ++"string"++ + + The remove reserve location for the XCM transfer. Should be provided when specifying an `assetTransferType` of `RemoteReserve`. + + --- + + `feesTransferType` ++"string"++ + + XCM TransferType used to pay fees for XCM transfer. The `AssetTransferType` type defines the possible values for this parameter. + + ??? child "Type `AssetTransferType`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md' + + --- + + `remoteReserveFeesTransferTypeLocation` ++"string"++ + + The remote reserve location for the XCM transfer fees. Should be provided when specifying a `feesTransferType` of `RemoteReserve`. + + --- + + `customXcmOnDest` ++"string"++ + + A custom XCM message to be executed on the destination chain. Should be provided if a custom XCM message is needed after transferring assets. Defaults to: + + ```bash + Xcm(vec![DepositAsset { assets: Wild(AllCounted(assets.len())), beneficiary }]) + ``` \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md new file mode 100644 index 000000000..389d58391 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md @@ -0,0 +1,148 @@ +A promise containing the result of constructing the transaction. + +??? child "Show more" + + `dest` ++"string"++ + + The destination `specName` of the transaction. + + --- + + `origin` ++"string"++ + + The origin `specName` of the transaction. + + --- + + `format` ++"Format | 'local'"++ + + The format type the transaction is outputted in. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + + --- + + `xcmVersion` ++"number | null"++ + + The XCM version that was used to construct the transaction. + + --- + + `direction` ++"Direction | 'local'"++ + + The direction of the cross-chain transfer. + + ??? child "Enum `Direction` values" + + `Local` + + Local transaction. + + --- + + `SystemToPara` + + System parachain to parachain. + + --- + + `SystemToRelay` + + System paracahin to system relay chain. + + --- + + `SystemToSystem` + + System parachain to System parachain chain. + + --- + + `SystemToBridge` + + System parachain to an external `GlobalConsensus` chain. + + --- + + `ParaToPara` + + Parachain to Parachain. + + --- + + `ParaToRelay` + + Parachain to Relay chain. + + --- + + `ParaToSystem` + + Parachain to System parachain. + + --- + + `RelayToSystem` + + Relay to System Parachain. + + --- + + `RelayToPara` + + Relay chain to Parachain. + + --- + + `RelayToBridge` + + Relay chain to an external `GlobalConsensus` chain. + + `method` ++"Methods"++ + + The method used in the transaction. + + ??? child "Type `Methods`" + + ```ts + type Methods = + | LocalTransferTypes + | 'transferAssets' + | 'transferAssetsUsingTypeAndThen' + | 'limitedReserveTransferAssets' + | 'limitedTeleportAssets' + | 'transferMultiasset' + | 'transferMultiassets' + | 'transferMultiassetWithFee' + | 'claimAssets'; + ``` + + ??? child "Type `LocalTransferTypes`" + + ```ts + type LocalTransferTypes = + | 'assets::transfer' + | 'assets::transferKeepAlive' + | 'foreignAssets::transfer' + | 'foreignAssets::transferKeepAlive' + | 'balances::transfer' + | 'balances::transferKeepAlive' + | 'poolAssets::transfer' + | 'poolAssets::transferKeepAlive' + | 'tokens::transfer' + | 'tokens::transferKeepAlive'; + ``` + + --- + + `tx` ++"ConstructedFormat"++ + + The constructed transaction. + + ??? child "Type `ConstructedFormat`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md' diff --git a/develop/application-devs/tooling/.pages b/develop/application-devs/tooling/.pages index 19e5de2ad..873708359 100644 --- a/develop/application-devs/tooling/.pages +++ b/develop/application-devs/tooling/.pages @@ -3,3 +3,4 @@ nav: - index.md - chopsticks - zombienet + - asset-transfer-api diff --git a/develop/application-devs/tooling/asset-transfer-api/.pages b/develop/application-devs/tooling/asset-transfer-api/.pages new file mode 100644 index 000000000..cb23f4fbd --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/.pages @@ -0,0 +1,6 @@ +title: Asset Transfer API +hide: false +nav: + - index.md + - 'Overview': 'overview.md' + - 'API Reference': 'reference.md' diff --git a/develop/application-devs/tooling/asset-transfer-api/index.md b/develop/application-devs/tooling/asset-transfer-api/index.md new file mode 100644 index 000000000..836f37f56 --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/index.md @@ -0,0 +1,7 @@ +--- +title: Asset Transfer API +description: Asset Transfer API is a library that simplifies the transfer of assets for Substrate based chains. It provides methods for cross-chain and local transfers. +template: subsection-index-page.html +hide: + - feedback +--- diff --git a/develop/application-devs/tooling/asset-transfer-api/overview.md b/develop/application-devs/tooling/asset-transfer-api/overview.md new file mode 100644 index 000000000..9f0d54667 --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/overview.md @@ -0,0 +1,130 @@ +--- +title: Asset Transfer API +description: Asset Transfer API is a library that simplifies the transfer of assets for Substrate-based chains. It provides methods for cross-chain and local transfers. +--- + +# Asset Transfer API + +## Introduction + +[Asset Transfer API](https://github.com/paritytech/asset-transfer-api){target=_blank}, a tool developed and maintained by [Parity](https://www.parity.io/){target=_blank}, is a specialized library designed to streamline asset transfers for Substrate-based blockchains. This API provides a simplified set of methods for users to: + +- Execute asset transfers to other parachains or locally within the same chain +- Facilitate transactions involving system parachains like Asset Hub (Polkadot and Kusama) + +Using this API, developers can manage asset transfers more efficiently, reducing the complexity of cross-chain transactions and enabling smoother operations within the ecosystem. + +For additional support and information, please reach out through [GitHub Issues](https://github.com/paritytech/asset-transfer-api/issues){target=_blank}. + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- [Node.js](https://nodejs.org/en/){target=_blank} (recommended version 21 or greater) +- Package manager - [npm](https://www.npmjs.com/){target=_blank} should be installed with Node.js by default. Alternatively, you can use other package managers like [Yarn](https://yarnpkg.com/){target=_blank} + +## Install Asset Transfer API + +To use `asset-transfer-api`, you need a TypeScript project. If you don't have one, you can create a new one: + +1. Create a new directory for your project: + + ```bash + mkdir my-asset-transfer-project \ + && cd my-asset-transfer-project + ``` + +2. Initialize a new TypeScript project: + + ```bash + npm init -y \ + && npm install typescript ts-node @types/node --save-dev \ + && npx tsc --init + ``` + +Once you have a project set up, you can install the `asset-transfer-api` package: + +```bash +npm install @substrate/asset-transfer-api@{{dependencies.asset_transfer_api.version}} +``` + +!!!note + This documentation covers version `{{dependencies.asset_transfer_api.version}}` of Asset Transfer API. + +## Set Up Asset Transfer API + +To initialize the Asset Transfer API, you need three key components: + +- A Polkadot.js API instance +- The `specName` of the chain +- The XCM version to use + + + +### Using Helper Function from Library + +For a simpler setup process, you can leverage the `constructApiPromise` helper function provided by the library. It not only constructs a Polkadot.js `ApiPromise` but also automatically retrieves the chain's `specName` and fetches a safe XCM version. By using this function, developers can significantly reduce boilerplate code and potential configuration errors, making the initial setup both quicker and more robust. + + + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts' +``` + +!!!note + The code examples are enclosed in an async main function to provide the necessary asynchronous context. However, you can use the code directly if you're already working within an async environment. The key is to ensure you're in an async context when working with these asynchronous operations, regardless of your specific setup. + +## Asset Transfer API Reference + +For detailed information on the Asset Transfer API, including available methods, data types, and functionalities, refer to the [Asset Transfer API Reference](/develop/application-devs/tooling/asset-transfer-api/reference) section. This resource provides in-depth explanations and technical specifications to help you integrate and utilize the API effectively. + +## Examples + +### Relay to System Parachain Transfer + +This example demonstrates how to initiate a cross-chain token transfer from a relay chain to a system parachain. Specifically, 1 WND will be transferred from a Westend (relay chain) account to a Westmint (system parachain) account. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts' +``` + +After running the script, you'll see the following output in the terminal, which shows the call data for the cross-chain transfer and its decoded extrinsic details: + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md' + +### Local Parachain Transfer + +The following example demonstrates a local GLMR transfer within Moonbeam, using the `balances` pallet. It transfers 1 GLMR token from one account to another account, where both the sender and recipient accounts are located on the same parachain. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts' +``` + +Upon executing this script, the terminal will display the following output, illustrating the encoded extrinsic for the cross-chain message and its corresponding decoded format: + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md' + +### Parachain to Parachain Transfer + +This example demonstrates creating a cross-chain asset transfer between two parachains. It shows how to send vMOVR and vBNC from a Moonriver account to a Bifrost Kusama account using the safe XCM version. It connects to Moonriver, initializes the API, and uses the `createTransferTransaction` method to prepare a transaction. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts' +``` + +After running this script, you'll see the following output in your terminal. This output presents the encoded extrinsic for the cross-chain message, along with its decoded format, providing a clear view of the transaction details. + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md' \ No newline at end of file diff --git a/develop/application-devs/tooling/asset-transfer-api/reference.md b/develop/application-devs/tooling/asset-transfer-api/reference.md new file mode 100644 index 000000000..5ba57557c --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/reference.md @@ -0,0 +1,266 @@ +--- +title: Asset Transfer API Reference +description: Explore the Asset Transfer API Reference for comprehensive details on methods, data types, and functionalities. Essential for cross-chain asset transfers. +--- + +# Asset Transfer API Reference + +
+
+- :octicons-download-16:{ .lg .middle } __Install the Asset Transfer API__ + + --- + + Learn how to install [`asset-transfer-api`](https://github.com/paritytech/asset-transfer-api){target=\_blank} into a new or existing project. + +
+ [:octicons-arrow-right-24: Get started](../asset-transfer-api/overview.md) + +- :octicons-code-16:{ .lg .middle } __Dive in with a tutorial__ + + --- + + Ready to start coding? Follow along with a step-by-step tutorial. + +
+ [:octicons-arrow-right-24: How to use the Asset Transfer API](../asset-transfer-api/overview.md/#examples) +
+
+ + +## Asset Transfer API Class + +Holds open an API connection to a specified chain within the `ApiPromise` to help construct transactions for assets and estimate fees. + +For a more in-depth explanation of the Asset Transfer API class structure, check the [source code](https://github.com/paritytech/asset-transfer-api/blob/f2aa50db83882f23492f975221dd5501c35a26d5/src/AssetTransferApi.ts#L106){target=_blank}. + +### Methods + +#### Create Transfer Transaction + +Generates an XCM transaction for transferring assets between chains. It simplifies the process by inferring what type of transaction is required given the inputs, ensuring that the assets are valid, and that the transaction details are correctly formatted. + +After obtaining the transaction, you must handle the signing and submission process separately. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts' +``` + +??? interface "Request parameters" + + `destChainId` ++"string"++ ++"required"++ + + ID of the destination chain (`'0'` for relay chain, other values for parachains). + + --- + + `destAddr` ++"string"++ ++"required"++ + + Address of the recipient account on the destination chain. + + --- + + `assetIds` ++"string[]"++ ++"required"++ + + Array of asset IDs to be transferred. + + When asset IDs are provided, the API dynamically selects the appropriate pallet for the current chain to handle these specific assets. If the array is empty, the API defaults to using the `balances` pallet. + + --- + + `amounts` ++"string[]"++ ++"required"++ + + Array of amounts corresponding to each asset in `assetIds`. + + --- + + `opts` ++"TransferArgsOpts"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md' + +??? interface "Response parameters" + + ++"Promise>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md' + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md' + +#### Claim Assets + +Creates a local XCM transaction to retrieve trapped assets. This function can be used to claim assets either locally on a system parachain, on the relay chain, or on any chain that supports the `claimAssets` runtime call. + + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts' +``` + +??? interface "Request parameters" + + `assetIds` ++"string[]"++ ++"required"++ + + Array of asset IDs to be claimed from the `AssetTrap`. + + --- + + `amounts` ++"string[]"++ ++"required"++ + + Array of amounts corresponding to each asset in `assetIds`. + + --- + + `beneficiary` ++"string"++ ++"required"++ + + Address of the account to receive the trapped assets. + + --- + + `opts` ++"TransferArgsOpts"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md' + +??? interface "Response parameters" + + ++"Promise>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md' + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md' + + +#### Decode Extrinsic + +Decodes the hex of an extrinsic into a string readable format. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts' +``` + +??? interface "Request parameters" + + `encodedTransaction` ++"string"++ ++"required"++ + + A hex encoded extrinsic. + + --- + + `format` ++"T extends Format"++ ++"required"++ + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + +??? interface "Response parameters" + + ++"string"++ + + Decoded extrinsic in string readable format. + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md' + +#### Fetch Fee Info + +Fetch estimated fee information for an extrinsic. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts' +``` + +??? interface "Request parameters" + + `tx` ++"ConstructedFormat"++ ++"required"++ + + The constructed transaction. + + ??? child "Type `ConstructedFormat`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md' + + --- + + `format` ++"T extends Format"++ ++"required"++ + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + +??? interface "Response parameters" + + ++"Promise"++ + + A promise containing the estimated fee information for the provided extrinsic. + + ??? child "Type `RuntimeDispatchInfo`" + + ```ts + export interface RuntimeDispatchInfo extends Struct { + readonly weight: Weight; + readonly class: DispatchClass; + readonly partialFee: Balance; + } + ``` + + For more information on the underlying types and fields of `RuntimeDispatchInfo`, check the [RuntimeDispatchInfo](https://github.com/polkadot-js/api/blob/2329af239eaf194696daeaa58ebf89f0080a5e0d/packages/types/src/interfaces/payment/types.ts#L21){target=_blank} source code. + + + ??? child "Type `RuntimeDispatchInfoV1`" + + ```ts + export interface RuntimeDispatchInfoV1 extends Struct { + readonly weight: WeightV1; + readonly class: DispatchClass; + readonly partialFee: Balance; + } + ``` + + For more information on the underlying types and fields of `RuntimeDispatchInfoV1`, check the [RuntimeDispatchInfoV1](https://github.com/polkadot-js/api/blob/2329af239eaf194696daeaa58ebf89f0080a5e0d/packages/types/src/interfaces/payment/types.ts#L28){target=_blank} source code. + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md' \ No newline at end of file