mdBook generated from gitorial

Author: shawntabrizi

src/0/source/README.md

@@ -1,33 +1,69 @@
-# polkadot-sdk-workshop-xcm
-
-This project is a workshop for learning about Polkadot SDK's XCM.
-
-## Overview
-
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
+# XCM Workshop
 
 Students will first go through, learn, and use all the fundamental building blocks for XCM:
 
-- Location / Topography
+1. [Location / Topography](location.md)
 	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
+2. Assets and Filters
 	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
 	- Constructing asset filters to target pools of assets.
-- Asset Holding
+3. Asset Holding
 	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
+4. Instructions
 	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
+5. The XCM Executor
 	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
+6. Pallet XCM
 	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
 
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
 
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
+## Prerequisite Knowledge
+
+Before we can even start teaching the low level concepts of XCM, we need to provide some high level knowledge about Polkadot, cross consensus messages, and tokens, and more...
+
+## Parachains
+
+Truthfully, we cannot in fine detail go over Polkadot and Parachains in this workshop. That would be its own educational endeavour.
+
+However, for the context of understanding common end to end scenarios that we will try to cover in this XCM Workshop, you will need to have a basic understanding of Parachains in the Polkadot Ecosystem.
+
+### System Parachains
+
+Polkadot uses parachains to scale itself through the creation of "system parachains".
+
+System parachains use the same parachain technology stack used to create and secure self-sovereign parachains. But in this case, rather than these parachains being their own sovereign entity,
+
+A very relevant example of this is the Asset Hub. This is a System Parachain for
+
+## Transfers
+
+We can argue that one of the native operations of any blockchain is to transfer assets and keep track of the ownership of those assets. Within a single consensus system, this is a solved problem.
+
+However, in a multi-chain, multi-token, multi-consensus ecosystem, this is a problem still being solved.
+
+Within the XCM world, we have established two different kinds of transfers which can be used across consensus systems, and based on their trust assumptions.
+
+### Teleport Transfers
+
+In high trust scenarios, we
+
+Teleport:
+
+	Destroying an asset (or amount of funds/token/currency) in one place and minting a corresponding amount in a second place. Imagine the teleporter from Star Trek. The two places need not be equivalent in nature (e.g. could be a UTXO chain that destroys assets and an account-based chain that mints them). Neither place acts as a reserve or derivative for the other. Though the nature of the tokens may be different, neither place is more canonical than the other. This is only possible if there is a bilateral trust relationship both of the STF and the validity/finality/availability between them.
+
+### Reserved Backed Transfers
+
+## XCM
+
+### Principles
+
+XCM is designed around four 'A's:
+
+- Asynchronous: XCM messages in no way assume that the sender will be blocking on its completion.
+- Absolute: XCM messages are guaranteed to be delivered and interpreted accurately, in order and in a timely fashion.
+- Asymmetric: XCM messages do not have results. Any results must be separately communicated to the sender with an additional message.
+- Agnostic: XCM makes no assumptions about the nature of the Consensus System between which messages are being passed.
 
-As a parachain:
+### Messages
 
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+### XCM Virtual Machine

src/1/solution/README.md

@@ -1,33 +1,3 @@
-# polkadot-sdk-workshop-xcm
+# XCM Workshop
 
-This project is a workshop for learning about Polkadot SDK's XCM.
-
-## Overview
-
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
-
-Students will first go through, learn, and use all the fundamental building blocks for XCM:
-
-- Location / Topography
-	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
-	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
-	- Constructing asset filters to target pools of assets.
-- Asset Holding
-	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
-	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
-	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
-	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
-
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
-
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
-
-As a parachain:
-
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+Solution to Fundamentals Location

src/1/template/README.md

@@ -1,33 +1,80 @@
-# polkadot-sdk-workshop-xcm
+# Locations
 
-This project is a workshop for learning about Polkadot SDK's XCM.
+In the world of XCM, the first fundamental primitive you need to learn about is Locations.
 
-## Overview
+As a software developer, Locations are most similar to filepaths in a filesystem.
 
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
+When writing a program, filepaths can help you locate folders, which contain many items, and the items themselves.
 
-Students will first go through, learn, and use all the fundamental building blocks for XCM:
+This is very similar to Locations in XCM, which can be used to locate consensus systems, like Relay Chains, Parachains, Smart Contracts, etc... and also specific users, assets, applications, and groups.
 
-- Location / Topography
-	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
-	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
-	- Constructing asset filters to target pools of assets.
-- Asset Holding
-	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
-	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
-	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
-	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
+Let's explore how Locations work inside of XCM.
 
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
+## Relative Locations
 
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
+By default, locations in XCM are always relative.
 
-As a parachain:
+This means, when considering how to construct a location, you must first establish your relative perspective.
 
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+For example, take the following topography:
+
+```text
+                  ┌───────────┐
+                  │  Relay A  │
+                  │  Polkadot │
+                  └─────┬─────┘
+                        │
+             ┌──────────┴──────────┐
+             │                     │
+       ┌─────┴─────┐         ┌─────┴─────┐
+       │  Para A   │         │  Para B   │
+       │  Id 1000  │         │  Id 1337  │
+       └─────┬─────┘         └─────┬─────┘
+             │                     │
+      ┌──────┴──────┐              ├───────────┐
+      │             │              │           │
+┌─────┴─────┐ ┌─────┴─────┐ ┌──────┴────┐ ┌────┴──────┐
+│   Alice   │ │  Pallet   │ │    Bob    │ │  Pallet   │
+│ AcctKey32 │ │  Assets   │ │ AcctKey20 │ │   EVM     │
+│           │ │           │ │           │ │           │
+│ 0x11111...│ │ Pallet #2 │ │ 0x22222...│ │ Pallet #5 │
+└───────────┘ └─────┬─────┘ └───────────┘ └─────┬─────┘
+                    │                           │
+              ┌─────┴─────┐               ┌─────┴─────┐
+              │   Asset   │               │   Smart   │
+              │   wBTC    │               │ Contract  │
+              │           │               │           │
+              │   Id 21   │               │ 0x55555...│
+              └───────────┘               └───────────┘
+```
+
+Let's treat this like a file system, and say we want to locate `Asset wBTC - ID 21`.
+
+From the perspective of the Polkadot relay chain:
+
+```text
+./{Para A}/{Pallet Assets}/{Asset wBTC}
+```
+
+But from the perspective of Smart Contract `0x555...`, which might be a DEX used to trade `wBTC`:
+
+```text
+../../../{Para A}/{Pallet Assets}/{Asset wBTC}
+```
+
+## The Location Format
+
+So nothing new to learn about with locations, we just need to break down how they are represented in the XCM system.
+
+### Junction
+
+The building blocks of a location are Junctions.
+
+```rust
+pub enum Junction {
+	Parachain(#[codec(compact)] u32),
+	PalletInstance(u8),
+	GeneralIndex(#[codec(compact)] u128),
+	// ... there are more junctions
+}
+```

src/2/solution/README.md

@@ -1,33 +1,3 @@
-# polkadot-sdk-workshop-xcm
+# XCM Workshop
 
-This project is a workshop for learning about Polkadot SDK's XCM.
-
-## Overview
-
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
-
-Students will first go through, learn, and use all the fundamental building blocks for XCM:
-
-- Location / Topography
-	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
-	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
-	- Constructing asset filters to target pools of assets.
-- Asset Holding
-	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
-	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
-	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
-	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
-
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
-
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
-
-As a parachain:
-
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+Solution to Assets

src/2/template/README.md

@@ -1,33 +1,9 @@
-# polkadot-sdk-workshop-xcm
+# Assets
 
-This project is a workshop for learning about Polkadot SDK's XCM.
+Now that you are familiar with XCM Locations, we can take a look at how we use these locations to identify particular Assets within a consensus system.
 
-## Overview
+## Fungible Tokens
 
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
+## Non-Fungible Tokens
 
-Students will first go through, learn, and use all the fundamental building blocks for XCM:
-
-- Location / Topography
-	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
-	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
-	- Constructing asset filters to target pools of assets.
-- Asset Holding
-	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
-	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
-	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
-	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
-
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
-
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
-
-As a parachain:
-
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+## Asset Filters

src/3/solution/README.md

@@ -1,33 +1,3 @@
-# polkadot-sdk-workshop-xcm
+# XCM Workshop
 
-This project is a workshop for learning about Polkadot SDK's XCM.
-
-## Overview
-
-This workshop aims to teach students about XCM following the philosophy of "discovery through experience".
-
-Students will first go through, learn, and use all the fundamental building blocks for XCM:
-
-- Location / Topography
-	- Learn how to construct relative and absolute locations for common objects and types used in XCM.
-- Assets and Filters
-	- Learn how to represent various types of assets like fungible tokens and non-fungible tokens.
-	- Constructing asset filters to target pools of assets.
-- Asset Holding
-	- Learn how we can manage multiple assets in memory using the `AssetsInHolding` abstraction.
-- Instructions
-	- Construct common XCM messages through individual XCM instructions.
-- The XCM Executor
-	- Learn how the XCM Executor actually functions, and loosely implement a few common instructions needed to complete end to end scenarios.
-- Pallet XCM
-	- Learn how Pallet XCM provides a simple to access wrapper to the underlying XCM Executor to perform common tasks like send, execute, and teleport transfers.
-
-After learning the fundamentals, students should feel confident they have strong understanding of how these underlying XCM primitives function and are constructed. With this knowledge, they will be able to investigate the real implementations of XCM to learn more deeply if needed.
-
-The next step after fundamentals is using the XCM Simulator an investigating the different ways we can configure XCM for various common scenarios. This workshop will not be comprehensive to all possible interactions, but will focus on a few key scenarios that we commonly expect to see in the Polkadot Ecosystem.
-
-As a parachain:
-
-1. Accepting and using the native asset of your relay chain.
-2. Accepting and using the native asset of other parachains.
-3. Accessing pallets of the relay chain or other parachains.
+Solution to Holding