diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 26ade73..c826b5c 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -7,9 +7,9 @@ - [A Format, not a Protocol](overview/format.md) - [The XCVM](overview/xcvm.md) - [Architecture](overview/architecture.md) -- [Quickstart]() - - [XCM Simulator]() - - [First Look at an XCM]() +- [Quickstart](quickstart/README.md) + - [XCM Simulator](quickstart/xcm-simulator.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..259fe46 --- /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 these 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 para_a_simple_transfer -- --nocapture +``` + +It should show you the following output: + +```shell +running 1 test +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 new file mode 100644 index 0000000..38c1ea6 --- /dev/null +++ b/src/quickstart/first-look.md @@ -0,0 +1,58 @@ +# 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 +```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: 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 +```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, 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 +```rust +DepositAsset { + assets: All.into(), + beneficiary: MultiLocation { + parents: 0, + interior: Junction::AccountId32 { + network: None, + id: BOB.clone().into() + }.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. + + +## 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-simulator.md b/src/quickstart/xcm-simulator.md new file mode 100644 index 0000000..178bb77 --- /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) + + + + +