From 2ed4b0113a3fd405f8502c9c471651fc1cd1449c Mon Sep 17 00:00:00 2001 From: Just van Stam Date: Thu, 13 Apr 2023 14:21:00 +0200 Subject: [PATCH 1/3] quickstart draft --- src/SUMMARY.md | 6 +++--- src/quickstart/README.md | 31 +++++++++++++++++++++++++++++ src/quickstart/first-look.md | 36 ++++++++++++++++++++++++++++++++++ src/quickstart/xcm-emulator.md | 9 +++++++++ 4 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 src/quickstart/README.md create mode 100644 src/quickstart/first-look.md create mode 100644 src/quickstart/xcm-emulator.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index a5fc430..e82cfa6 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -6,9 +6,9 @@ - [The Promise of Interoperability]() - [A Format, not a Protocol]() - [Architecture]() -- [Quickstart]() - - [XCM Simulator]() - - [First Look at an XCM]() +- [Quickstart](quickstart/README.md) + - [XCM Emulator](quickstart/xcm-emulator.md) + - [First Look at an XCM](quickstart/first-look.md) - [Fundamentals]() - [MultiLocation]() - [MultiAsset]() diff --git a/src/quickstart/README.md b/src/quickstart/README.md new file mode 100644 index 0000000..3f3d2a9 --- /dev/null +++ b/src/quickstart/README.md @@ -0,0 +1,31 @@ +# Quickstart + +The XCM code can be found in [polkadot repository](https://github.com/paritytech/polkadot/tree/master/xcm). + +### Rust & Cargo +A pre-requisite for using XCM is to have a stable Rust version and Cargo installed. Here's an [installation guide](https://docs.substrate.io/install/) on how to install rust and cargo. + +### Running the Examples + +All examples in the documentation are located in the [examples repository](). Follow the following steps to run the `first-look` example. First clone the repository: + +```shell +git clone git@github.com:vstam1/xcm-examples.git +cd xcm-examples +``` + +To run the first-look example, run the following line: + +```shell +cargo test -p xcm-examples parachain_a_simple_transfer -- --nocapture +``` + +It should show you the following output: + +```shell +running 1 test +test first_look::tests::parachain_a_simple_transfer ... ok + +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.01s +``` + diff --git a/src/quickstart/first-look.md b/src/quickstart/first-look.md new file mode 100644 index 0000000..be5ee9f --- /dev/null +++ b/src/quickstart/first-look.md @@ -0,0 +1,36 @@ +## First Look +In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`SimpleParachain`). Find here the [code example](). + +### Message +The message consists of three instructions: WithdrawAsset, BuyExecution, and DepositAsset. + +##### WithdrawAsset +```rust +WithdrawAsset((Here, amount).into()) +``` + +The first instruction takes as an input the [MultiAsset]() that should be withdrawn. The MultiAsset describes the native parachain token with the `Here` keyword. The `amount` parameter is the number of tokens that are transferred. The withdrawal account depends on the Origin of the message. In this example the Origin of the message is Alice. +The WithdrawAsset instruction moves `amount` number of native tokens from Alice's account into the `Holding register`. + +##### BuyExecution +```rust +BuyExecution{fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited} +``` +To execute XCM instructions, execution time (weight) has to be bought. The amount of execution time depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying execution time. See [fees]() for more information about the fee payments. + +##### DepositAsset +```rust +DepositAsset { + assets: All.into(), + beneficiary: MultiLocation { + parents: 0, + interior: X1(Junction::AccountId32 { + network: Some(NetworkId::Kusama), + id: BOB.clone().into() + }), + }.into() +} +``` +The DepositAsset instruction is used to deposit funds from the holding register into the account of the `beneficiary`. We don’t actually know how much is remaining in the Holding Register after the BuyExecution instruction, but that doesn’t matter since we specify a wildcard for the asset(s) which should be deposited. In this case, the wildcard is `All`, meaning that all assets in the Holding register should be deposited. The `beneficiary` in this case is the account of Bob in the current consensus system. + +When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of the instructions, and deposit the remaining tokens in the account of Bob. \ No newline at end of file diff --git a/src/quickstart/xcm-emulator.md b/src/quickstart/xcm-emulator.md new file mode 100644 index 0000000..482689e --- /dev/null +++ b/src/quickstart/xcm-emulator.md @@ -0,0 +1,9 @@ +### xcm-emulator +Setting up a live network with multiple connected parachains for testing XCM is not straight forward. The XCM-emulator was created as a solution to this problem. The XCM-emulator is a network emulator specifically designed for testing and playing around with XCM. It emulates the sending, delivery and execution of XCM instructions, with the assumption that the message can always be delivered to and executed in the destination. + +The xcm-emulator can use production relay chain and parachain runtimes. Users can plug in Kusama, Statemine, or their custom runtime etc. With up-to-date chain specs, it's able to verify if specific XCM messages work in live networks. + +The emulator makes it possible to quickly set up a custom emulated network. [This example](TODO) shows how to setup a network of one relaychain and three parachains. + + + From 486d4b060bce03fba4e1f3be591e961cdc99be07 Mon Sep 17 00:00:00 2001 From: Just van Stam Date: Mon, 17 Apr 2023 14:06:09 +0200 Subject: [PATCH 2/3] edit quickstart --- src/SUMMARY.md | 2 +- src/quickstart/README.md | 4 ++-- src/quickstart/first-look.md | 31 +++++++++++++++++++++++++++---- src/quickstart/xcm-emulator.md | 9 --------- src/quickstart/xcm-simulator.md | 13 +++++++++++++ 5 files changed, 43 insertions(+), 16 deletions(-) delete mode 100644 src/quickstart/xcm-emulator.md create mode 100644 src/quickstart/xcm-simulator.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e82cfa6..cd9718d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -7,7 +7,7 @@ - [A Format, not a Protocol]() - [Architecture]() - [Quickstart](quickstart/README.md) - - [XCM Emulator](quickstart/xcm-emulator.md) + - [XCM Simulator](quickstart/xcm-simulator.md) - [First Look at an XCM](quickstart/first-look.md) - [Fundamentals]() - [MultiLocation]() diff --git a/src/quickstart/README.md b/src/quickstart/README.md index 3f3d2a9..0bad600 100644 --- a/src/quickstart/README.md +++ b/src/quickstart/README.md @@ -17,14 +17,14 @@ cd xcm-examples To run the first-look example, run the following line: ```shell -cargo test -p xcm-examples parachain_a_simple_transfer -- --nocapture +cargo test -p xcm-examples para_a_simple_transfer -- --nocapture ``` It should show you the following output: ```shell running 1 test -test first_look::tests::parachain_a_simple_transfer ... ok +test first_look::tests::para_a_simple_transfer ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.01s ``` diff --git a/src/quickstart/first-look.md b/src/quickstart/first-look.md index be5ee9f..21435c0 100644 --- a/src/quickstart/first-look.md +++ b/src/quickstart/first-look.md @@ -1,8 +1,24 @@ ## First Look -In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`SimpleParachain`). Find here the [code example](). +In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`ParaA`). Find here the [code example](). ### Message -The message consists of three instructions: WithdrawAsset, BuyExecution, and DepositAsset. +```rust + let message = Xcm(vec![ + WithdrawAsset((Here, amount).into()), + BuyExecution{fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited}, + DepositAsset { + assets: All.into(), + beneficiary: MultiLocation { + parents: 0, + interior: X1(Junction::AccountId32 { + network: Some(NetworkId::Kusama), + id: BOB.clone().into() + }), + }.into() + } +]); +``` +The message consists of three instructions: WithdrawAsset, BuyExecution, and DepositAsset. In the following sections we will go over each of these instructions. ##### WithdrawAsset ```rust @@ -16,7 +32,7 @@ The WithdrawAsset instruction moves `amount` number of native tokens from Alice' ```rust BuyExecution{fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited} ``` -To execute XCM instructions, execution time (weight) has to be bought. The amount of execution time depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying execution time. See [fees]() for more information about the fee payments. +To execute XCM instructions, weight has to be bought. The amount of weight depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying weight. See [fees]() for more information about the fees in XCM. ##### DepositAsset ```rust @@ -33,4 +49,11 @@ DepositAsset { ``` The DepositAsset instruction is used to deposit funds from the holding register into the account of the `beneficiary`. We don’t actually know how much is remaining in the Holding Register after the BuyExecution instruction, but that doesn’t matter since we specify a wildcard for the asset(s) which should be deposited. In this case, the wildcard is `All`, meaning that all assets in the Holding register should be deposited. The `beneficiary` in this case is the account of Bob in the current consensus system. -When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of the instructions, and deposit the remaining tokens in the account of Bob. \ No newline at end of file +When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of the instructions, and deposit the remaining tokens in the account of Bob. + + +##### What next? +Now that we have taken a first look at an XCM, we can dive deeper into all the XCM instructions. +For an overview of the instructions check out the [xcm-format](https://github.com/paritytech/xcm-format#5-the-xcvm-instruction-set). +Or check out examples for each of the instruction in [A Journey through XCM](). +To get a better understanding about MultiLocations, MultiAssets, and other fundamental concepts in XCM, check out the [fundamentals chapter](fundamentals/README.md). diff --git a/src/quickstart/xcm-emulator.md b/src/quickstart/xcm-emulator.md deleted file mode 100644 index 482689e..0000000 --- a/src/quickstart/xcm-emulator.md +++ /dev/null @@ -1,9 +0,0 @@ -### xcm-emulator -Setting up a live network with multiple connected parachains for testing XCM is not straight forward. The XCM-emulator was created as a solution to this problem. The XCM-emulator is a network emulator specifically designed for testing and playing around with XCM. It emulates the sending, delivery and execution of XCM instructions, with the assumption that the message can always be delivered to and executed in the destination. - -The xcm-emulator can use production relay chain and parachain runtimes. Users can plug in Kusama, Statemine, or their custom runtime etc. With up-to-date chain specs, it's able to verify if specific XCM messages work in live networks. - -The emulator makes it possible to quickly set up a custom emulated network. [This example](TODO) shows how to setup a network of one relaychain and three parachains. - - - diff --git a/src/quickstart/xcm-simulator.md b/src/quickstart/xcm-simulator.md new file mode 100644 index 0000000..1620384 --- /dev/null +++ b/src/quickstart/xcm-simulator.md @@ -0,0 +1,13 @@ +### xcm-simulator +Setting up a live network with multiple connected parachains for testing XCM is not straight forward. The `XCM-simulator` was created as a solution to this problem. The XCM-simulator is a network simulator specifically designed for testing and playing around with XCM. It uses mock relay chain and parachain runtime. + +For testing xcm configurations for live runtime environments we use the `XCM-emulator`. The XCM-emulator can use production relay chain and parachain runtimes. Users can plug in Kusama, Statemine, or their custom runtime etc. With up-to-date chain specs, it's able to verify if specific XCM messages work in live networks. The specific use cases will be further explained in the chapter on [testing](testing/README.md). + +In the next section we will take a first look at an XCM. The XCM-simulator is used for the example code. + +[Next: First Look at an XCM](first-look.md) + + + + + From 932882e575c2dc2cdb9aaa1d51b3f2b53ffdf8b3 Mon Sep 17 00:00:00 2001 From: Just van Stam Date: Wed, 19 Apr 2023 17:23:33 +0200 Subject: [PATCH 3/3] address feedback --- src/quickstart/README.md | 6 +++--- src/quickstart/first-look.md | 27 +++++++++++++-------------- src/quickstart/xcm-simulator.md | 2 +- 3 files changed, 17 insertions(+), 18 deletions(-) diff --git a/src/quickstart/README.md b/src/quickstart/README.md index 0bad600..259fe46 100644 --- a/src/quickstart/README.md +++ b/src/quickstart/README.md @@ -2,12 +2,12 @@ The XCM code can be found in [polkadot repository](https://github.com/paritytech/polkadot/tree/master/xcm). -### Rust & Cargo +## Rust & Cargo A pre-requisite for using XCM is to have a stable Rust version and Cargo installed. Here's an [installation guide](https://docs.substrate.io/install/) on how to install rust and cargo. -### Running the Examples +## Running the Examples -All examples in the documentation are located in the [examples repository](). Follow the following steps to run the `first-look` example. First clone the repository: +All examples in the documentation are located in the [examples repository](). Follow these steps to run the `first-look` example. First clone the repository: ```shell git clone git@github.com:vstam1/xcm-examples.git diff --git a/src/quickstart/first-look.md b/src/quickstart/first-look.md index 21435c0..38c1ea6 100644 --- a/src/quickstart/first-look.md +++ b/src/quickstart/first-look.md @@ -1,7 +1,6 @@ -## First Look +# First Look In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`ParaA`). Find here the [code example](). - -### Message +## Message ```rust let message = Xcm(vec![ WithdrawAsset((Here, amount).into()), @@ -10,17 +9,17 @@ In this section, we take you through a simple example of an XCM. In this example assets: All.into(), beneficiary: MultiLocation { parents: 0, - interior: X1(Junction::AccountId32 { - network: Some(NetworkId::Kusama), + interior: Junction::AccountId32 { + network: None, id: BOB.clone().into() - }), + }.into(), }.into() } ]); ``` The message consists of three instructions: WithdrawAsset, BuyExecution, and DepositAsset. In the following sections we will go over each of these instructions. -##### WithdrawAsset +### WithdrawAsset ```rust WithdrawAsset((Here, amount).into()) ``` @@ -28,22 +27,22 @@ WithdrawAsset((Here, amount).into()) The first instruction takes as an input the [MultiAsset]() that should be withdrawn. The MultiAsset describes the native parachain token with the `Here` keyword. The `amount` parameter is the number of tokens that are transferred. The withdrawal account depends on the Origin of the message. In this example the Origin of the message is Alice. The WithdrawAsset instruction moves `amount` number of native tokens from Alice's account into the `Holding register`. -##### BuyExecution +### BuyExecution ```rust BuyExecution{fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited} ``` -To execute XCM instructions, weight has to be bought. The amount of weight depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying weight. See [fees]() for more information about the fees in XCM. +To execute XCM instructions, weight (some kind of resources) has to be bought. The amount of weight depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying weight. There are special occasions where it is not necessary to buy weight. See [fees]() for more information about the fees in XCM. -##### DepositAsset +### DepositAsset ```rust DepositAsset { assets: All.into(), beneficiary: MultiLocation { parents: 0, - interior: X1(Junction::AccountId32 { - network: Some(NetworkId::Kusama), + interior: Junction::AccountId32 { + network: None, id: BOB.clone().into() - }), + }.into(), }.into() } ``` @@ -52,7 +51,7 @@ The DepositAsset instruction is used to deposit funds from the holding register When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of the instructions, and deposit the remaining tokens in the account of Bob. -##### What next? +## What next? Now that we have taken a first look at an XCM, we can dive deeper into all the XCM instructions. For an overview of the instructions check out the [xcm-format](https://github.com/paritytech/xcm-format#5-the-xcvm-instruction-set). Or check out examples for each of the instruction in [A Journey through XCM](). diff --git a/src/quickstart/xcm-simulator.md b/src/quickstart/xcm-simulator.md index 1620384..178bb77 100644 --- a/src/quickstart/xcm-simulator.md +++ b/src/quickstart/xcm-simulator.md @@ -1,4 +1,4 @@ -### xcm-simulator +# XCM Simulator Setting up a live network with multiple connected parachains for testing XCM is not straight forward. The `XCM-simulator` was created as a solution to this problem. The XCM-simulator is a network simulator specifically designed for testing and playing around with XCM. It uses mock relay chain and parachain runtime. For testing xcm configurations for live runtime environments we use the `XCM-emulator`. The XCM-emulator can use production relay chain and parachain runtimes. Users can plug in Kusama, Statemine, or their custom runtime etc. With up-to-date chain specs, it's able to verify if specific XCM messages work in live networks. The specific use cases will be further explained in the chapter on [testing](testing/README.md).