update draft, add testing chapter and fix links

examples/README.md

@@ -1,2 +1,52 @@
 # xcm-examples
-This repository shows the xcm examples for the xcm docs
+This repository contains the xcm examples for the xcm docs. 
+The examples are set up using the [XCM-simulator](/~https://github.com/paritytech/polkadot/tree/master/xcm/xcm-simulator).
+The testnet can be found in `examples/src/simple_test_net`.
+
+#### How to run
+To run the examples, do the following:
+1. Clone the repository:
+`git clone /~https://github.com/paritytech/xcm-docs.git`
+
+2. cd to the examples folder:
+`cd examples/`
+
+3. Run all the tests: 
+`cargo test`
+or a single test:
+`cargo test -p xcm-examples trap_and_claim_assets -- --nocapture`
+
+#### events printing
+You can print out the events on a parachain or the relay chain using the `print_para_events` or `print_relay_events` functions. The functions are used in a parachain or relay chain `TestExternalities`:
+
+```rust
+ParaA::execute_with(|| {
+    print_para_events();
+});
+```
+
+#### Tests
+- `first_look`
+- `transfers/teleport_fungible`
+- `transfers/reserve_backed_transfer_para_to_para`
+- `transfers/reserve_backed_transfer_relay_to_para`
+- `transfers/reserve_backed_transfer_para_to_relay`
+- `transact/transact_set_balance`
+- `transact/transact_mint_nft`
+- `origins/descend_origin`
+- `holding_modifiers/burn_assets`
+- `holding_modifiers/exchange_asset_maximal_true`
+- `holding_modifiers/exchange_asset_maximal_false`
+- `trap_and_claim/trap_and_claim_assets`
+- `expects/expect_asset`
+- `expects/expect_origin`
+- `expects/expect_pallet`
+- `expects/expect_error`
+- `expects/expect_transact_status`
+- `queries/query_holding`
+- `queries/query_pallet`
+- `queries/report_error`
+- `queries/report_transact_status`
+- `version_subscription/subscribe_and_unsubscribe_version`
+- `locks/remote_locking_on_relay`
+- `locks/locking_overlap`

examples/src/first_look.rs → examples/src/0_first_look/mod.rs

@@ -44,7 +44,7 @@ mod tests {
 			// Check if the funds are subtracted from the account of Alice and added to the account of Bob.
 			assert_eq!(ParachainBalances::free_balance(ALICE), INITIAL_BALANCE - amount);
 			assert_eq!(parachain::Assets::balance(0, ALICE), INITIAL_BALANCE - fee);
-			assert_eq!(ParachainBalances::free_balance(BOB), amount);
+			assert_eq!(ParachainBalances::free_balance(BOB), INITIAL_BALANCE + amount);
 		});
 	}
 }

examples/src/2_fees/mod.rs

@@ -0,0 +1,52 @@
+#[cfg(test)]
+mod tests {
+	use crate::simple_test_net::{parachain::estimate_message_fee, *};
+	use frame_support::assert_ok;
+	use xcm::latest::prelude::*;
+	use xcm_simulator::TestExt;
+
+	/// Scenario:
+	/// Relay chain sends a XCM to Parachain A.
+	/// Enough execution is bought for the full message.
+	/// However, the message errors at the Trap(1) instruction (simulates error in other instructions).
+	/// The last three instructions are not executed
+	/// and the weight surplus of these instructions is refunded to the relay chain account.
+	#[test]
+	fn refund_surplus() {
+		MockNet::reset();
+		let message_fee = parachain::estimate_message_fee(9);
+		let message = Xcm(vec![
+			WithdrawAsset((Parent, message_fee).into()),
+			BuyExecution {
+				fees: (Parent, message_fee).into(),
+				weight_limit: WeightLimit::Unlimited,
+			},
+			SetErrorHandler(Xcm(vec![
+				RefundSurplus,
+				DepositAsset {
+					assets: All.into(),
+					beneficiary: AccountId32 {
+						network: Some(ByGenesis([0; 32])),
+						id: relay_sovereign_account_id().into(),
+					}
+					.into(),
+				},
+			])),
+			Trap(1),
+			ClearOrigin,
+			ClearOrigin,
+			ClearOrigin,
+		]);
+
+		Relay::execute_with(|| {
+			assert_ok!(RelaychainPalletXcm::send_xcm(Here, Parachain(1), message.clone(),));
+		});
+
+		ParaA::execute_with(|| {
+			assert_eq!(
+				ParachainAssets::balance(0, relay_sovereign_account_id()),
+				INITIAL_BALANCE - message_fee + estimate_message_fee(3)
+			);
+		})
+	}
+}

examples/src/holding_modifiers/mod.rs → examples/src/5_holding_modifiers/mod.rs

@@ -1,6 +1,6 @@
 #[cfg(test)]
 mod tests {
-	use crate::simple_test_net::{parachain::RelayNativeAsset, *};
+	use crate::simple_test_net::*;
 	use frame_support::{assert_ok, pallet_prelude::Weight};
 	use xcm::latest::prelude::*;
 	use xcm_simulator::TestExt;

examples/src/queries/mod.rs → examples/src/8_queries/mod.rs

@@ -105,7 +105,6 @@ mod tests {
 			]);
 
 			assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),));
-			print_para_events();
 		});
 
 		ParaA::execute_with(|| {

examples/src/lib.rs

@@ -1,11 +1,23 @@
+#[path = "7_expects/mod.rs"]
 mod expects;
+#[path = "2_fees/mod.rs"]
+mod fees;
+#[path = "0_first_look/mod.rs"]
 mod first_look;
+#[path = "5_holding_modifiers/mod.rs"]
 mod holding_modifiers;
+#[path = "10_locks/mod.rs"]
 mod locks;
+#[path = "4_origins/mod.rs"]
 mod origins;
+#[path = "8_queries/mod.rs"]
 mod queries;
 mod simple_test_net;
+#[path = "3_transact/mod.rs"]
 mod transact;
+#[path = "1_transfers/mod.rs"]
 mod transfers;
+#[path = "6_trap_and_claim/mod.rs"]
 mod trap_and_claim;
+#[path = "9_version_subscription/mod.rs"]
 mod version_subscription;

examples/src/simple_test_net/mod.rs

@@ -13,7 +13,7 @@
 
 // You should have received a copy of the GNU General Public License
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
-
+#![allow(dead_code)]
 pub mod parachain;
 pub mod relay_chain;
 
@@ -130,7 +130,6 @@ pub fn para_ext(para_id: u32) -> sp_io::TestExternalities {
 	use parachain::{MsgQueue, Runtime, System};
 
 	let mut t = frame_system::GenesisConfig::default().build_storage::<Runtime>().unwrap();
-
 	let other_para_ids = match para_id {
 		1 => [2, 3],
 		2 => [1, 3],
@@ -139,7 +138,7 @@ pub fn para_ext(para_id: u32) -> sp_io::TestExternalities {
 	};
 
 	pallet_balances::GenesisConfig::<Runtime> {
-		balances: vec![(ALICE, INITIAL_BALANCE), (relay_sovereign_account_id(), INITIAL_BALANCE)]
+		balances: vec![(ALICE, INITIAL_BALANCE), (relay_sovereign_account_id(), INITIAL_BALANCE), (BOB, INITIAL_BALANCE)]
 			.into_iter()
 			.chain(other_para_ids.iter().map(
 				// Initial balance of native token for ALICE on all sibling sovereign accounts
@@ -181,6 +180,7 @@ pub fn para_ext(para_id: u32) -> sp_io::TestExternalities {
 	.assimilate_storage(&mut t)
 	.unwrap();
 
+
 	let mut ext = sp_io::TestExternalities::new(t);
 	ext.execute_with(|| {
 		sp_tracing::try_init_simple();

src/SUMMARY.md

@@ -21,8 +21,8 @@
   - [Transfers](journey/transfers/README.md)
     - [Asset teleportation](journey/transfers/teleports.md)
     - [Reserve-backed transfers](journey/transfers/reserve.md)
-  - [Transact: A general solution](journey/transact.md)
   - [Fee handling](journey/fees/README.md)
+  - [Transact: A general solution](journey/transact.md)
   - [Origin manipulation](journey/origins.md)
   - [More register modifiers](journey/register-modifiers.md)
   - [More Holding Modifiers](./journey/holding-modifiers.md)
@@ -32,22 +32,12 @@
   - [XCM Version](journey/version.md)
   - [Locks](journey/locks/locks.md)
   - [Channels and Bridges](journey/channels-and-bridges.md)
-  - [Misc]()
 - [Config Deep Dive](executor_config/README.md)
 - [Testing](testing/README.md)
-  - [Separation of concerns]()
-  - [Simulating message execution]()
-  - [How to test my own configuration]()
-  - [Testing the full XCM Journey]()
-- [Transport Protocols](transport_protocols/README.md)
-  - [VMP]()
-  - [HRMP]()
-  - [XCMP]()
 
 # Reference
 
-- [Cookbook]()
-- [All Instructions]()
+<!---- [Cookbook]()
+- [All Instructions]()--->
 - [All XCVM Registers](reference/xcvm-registers.md)
 
-[Next Steps]()

src/executor_config/README.md

@@ -79,7 +79,7 @@ The `RuntimeCall` type is equal to the RuntimeCall created in the `construct_run
 
 ### XcmSender
 The `XcmSender` type implements the `SendXcm` trait, and defines how the xcm_executor can send XCMs (which transport layer it can use for the XCMs).
-This type normally implements a tuple for one or more [transport layer(s)](Todo Transport Layer Link).
+This type normally implements a tuple for one or more [transport layer(s)](https://wiki.polkadot.network/docs/learn-xcm-transport).
 For example a parachain can implement the XcmSender as: 
 ```rust,noplayground
  (
@@ -170,7 +170,7 @@ The most used is the `FixedWeightBounds`:
 // BaseXcmWeight is a const weight.
 FixedWeightBounds<BaseXcmWeight, RuntimeCall, MaxInstructions>;
 ```
-Note: [More information](Todo) about weight.
+Note: [More information](../fundamentals/weight_and_fees.md) about weight.
 
 ### Trader
 The `Trader` type is responsible for buying weight in the `BuyExecution` instruction using assets in the holding register and to refund unspend weight.

src/fundamentals/multilocation/junction.md

@@ -1,5 +1,5 @@
 # Junction(s)
-In the section on [MultiLocations](README.md), we looked at the MultiLocation struct.
+In the section on [MultiLocations](index.html), we looked at the MultiLocation struct.
 We talked about the Multilocation being a way to describe moving from one place in the system hierarchy to another.
 The `parents` parameter expresses the number of steps up in the hierarchy.
 In this section, we dive further into the MultiLocation struct and explain how we can use the Junctions type to describe steps in the system hierarchy.

src/fundamentals/weight_and_fees.md

@@ -15,16 +15,16 @@ Weight, however, is static, defined beforehand, which makes XCM execution lighte
 The principle behind weight payment is to pay for what you use, so the two stages of XCM where fees are paid are *sending* the message and actually *executing* it.
 The fees for sending are paid on the local system, usually by the origin of the message, because we are using the message delivery mechanism maintained by the origin.
 Similarly, the execution fees are paid on the destination system, via the `BuyExecution` instruction. In other words, XCMs are paid for via their own instructions.
-We'll talk more about `BuyExecution` in the [fee handling chapter](TODO:add_link).
+We'll talk more about `BuyExecution` in the [fee handling chapter](../journey/fees/index.html).
 
 XCM is agnostic, which means it doesn't assume fees need to be paid.
 It's entirely possible to not pay for the effects of an XCM on the destination system.
 Even in systems where fees have to be paid, special cases of free execution can be made.
-There are security measures systems can put in place (see [barrier](TODO:add_link)) to not execute XCMs that do not pay for their fees.
+There are security measures systems can put in place (see [barrier](../executor_config/index.html#barrier)) to not execute XCMs that do not pay for their fees.
 
 ## Executor config
 
-The executor has a `Weigher` [configuration item](TODO:add_link) that specifies the weight of each instruction.
+The executor has a `Weigher` [configuration item](../executor_config/index.html#weigher) that specifies the weight of each instruction.
 It weighs the whole message by adding the weight of each instruction.
 A simple way of weighing instructions is to assign them a base weight value to all of them.
 This works, but it is not very accurate, as different instructions use more resources when being executed.

src/journey/expects.md

@@ -18,7 +18,7 @@ ExpectAsset(MultiAssets)
 
 ### Example
 
-For the full example, check [here](/~https://github.com/paritytech/xcm-docs).
+For the full example, check [here](/~https://github.com/paritytech/xcm-docs/tree/main/examples).
 
 ```rust, noplayground 
 WithdrawAsset((Here, AMOUNT).into()),
@@ -45,7 +45,7 @@ ExpectOrigin(Option<MultiLocation>)
 
 ### Example
 
-For the full example, check [here](/~https://github.com/paritytech/xcm-docs).
+For the full example, check [here](/~https://github.com/paritytech/xcm-docs/tree/main/examples).
 The `ExpectOrigin` instruction errors because the `ClearOrigin` clears the origin register and we expect it to be equal to `Parachain(1)`.
 ```rust,noplayground
 // Set the instructions that are executed when ExpectOrigin does not pass.
@@ -81,7 +81,7 @@ ExpectPallet {
 ```
 
 ### Example
-For the full example, check [here](/~https://github.com/paritytech/xcm-docs).
+For the full example, check [here](/~https://github.com/paritytech/xcm-docs/tree/main/examples).
 ```rust, noplayground
 // Set the instructions that are executed when ExpectPallet does not pass.
 // In this case, reporting back an error to the Parachain.
@@ -112,7 +112,7 @@ The `ExpectError` instruction allows to only execute the instructions in the err
 
 ### Example
 
-For the full example, check [here](/~https://github.com/paritytech/xcm-docs).
+For the full example, check [here](/~https://github.com/paritytech/xcm-docs/tree/main/examples).
 
 ```rust,noplayground
 SetErrorHandler(Xcm(vec![
@@ -135,21 +135,10 @@ ExpectPallet {
 
 ## ExpectTransactStatus
 The `ExpectTransactStatus` instruction throws an `ExpectationFalse` error if the transact status register does not equal the expected transact status.
-The status is described by the `MaybeErrorCode` enum, and can either be a Success, Error or TruncatedError if the length of the error exceeds the MaxDispatchErrorLen. 
-For pallet-based calls, the Error is represented as the scale encoded `Error` enum of the called pallet. 
-```rust,noplayground
-ExpectTransactStatus(MaybeErrorCode)
-
-pub enum MaybeErrorCode {
-	Success,
-	Error(BoundedVec<u8, MaxDispatchErrorLen>),
-	TruncatedError(BoundedVec<u8, MaxDispatchErrorLen>),
-}
-```
 
 ### Example
 
-For the full example, check [here](/~https://github.com/paritytech/xcm-docs).
+For the full example, check [here](/~https://github.com/paritytech/xcm-docs/tree/main/examples).
 The transact status is reported to `Parachain(1)` if the call in the `Transact` errors. 
 
 ```rust,noplayground