feat(web): add network subpages and subdomains listing page

- Add /subdomains page listing all 20 PezkuwiChain subdomains - Add Back to Home button to Subdomains page - Create NetworkPage reusable component for network details - Add 7 network subpages: /mainnet, /staging, /testnet, /beta, /alfa, /development, /local - Update ChainSpecs network cards to navigate to network subpages - Add i18n translations for chainSpecs section in en.ts - Add SDK docs with rebranding support (rebrand-rustdoc.cjs) - Add generate-docs-structure.cjs for automatic docs generation - Update shared libs: endpoints, polkadot, wallet, xcm-bridge - Add new token logos: TYR, ZGR, pezkuwi_icon - Add new pages: Explorer, Docs, Wallet, Api, Faucet, Developers, Grants, Wiki, Forum, Telemetry
2026-04-22 17:07:57 +00:00 · 2025-12-11 00:33:47 +03:00
parent 2c6c4f5606
commit 11678fe7cd
976 changed files with 60601 additions and 168 deletions
@@ -0,0 +1,12 @@
+flowchart TD
+    dot[pezkuwichain.io] --> devhub[pezkuwi_sdk_docs]
+
+    devhub --> pezkuwi_sdk
+    devhub --> reference_docs
+    devhub --> guides
+	devhub --> external_resources
+
+    pezkuwi_sdk --> substrate
+    pezkuwi_sdk --> frame
+    pezkuwi_sdk --> xcm
+	pezkuwi_sdk --> templates
@@ -0,0 +1,5 @@
+flowchart TD
+    E(Extrinsic) ---> I(Inherent);
+    E --> T(Transaction)
+    T --> ST("Signed (aka. Transaction)")
+    T --> UT(Unsigned)
@@ -0,0 +1,3 @@
+flowchart LR
+    RuntimeCall --"TryInto"--> PalletCall
+    PalletCall --"Into"--> RuntimeCall
@@ -0,0 +1,10 @@
+flowchart LR
+
+	subgraph Pezkuwi[The Pezkuwi Relay Chain]
+		PezkuwiNode[Pezkuwi Node]
+		PezkuwiRuntime[Pezkuwi Runtime]
+	end
+
+    FRAME -.-> PezkuwiRuntime
+    PezkuwiSDK[Pezkuwi SDK Node Libraries] -.-> PezkuwiNode
+
@@ -0,0 +1,8 @@
+flowchart LR
+	subgraph PezkuwiSDKChain[A Pezkuwi SDK-based blockchain]
+		Node
+		Runtime
+	end
+
+    FRAME -.-> Runtime
+    PezkuwiSDK[Pezkuwi SDK Node Libraries] -.-> Node
@@ -0,0 +1,11 @@
+flowchart LR
+	subgraph TeyrChain[A Pezkuwi TeyrChain]
+		TeyrChainNode[TeyrChain Node]
+		TeyrChainRuntime[TeyrChain Runtime]
+	end
+
+    FRAME -.-> TeyrChainRuntime
+    PezkuwiSDK[Pezkuwi SDK Node Libraries] -.-> TeyrChainNode
+
+    CumulusC[Cumulus Node Libraries] -.-> TeyrChainNode
+    CumulusR[Cumulus Runtime Libraries] -.-> TeyrChainRuntime
@@ -0,0 +1,16 @@
+flowchart TB
+    subgraph Node[Node's View Of The State 🙈]
+        direction LR
+        0x1234 --> 0x2345
+        0x3456 --> 0x4567
+        0x5678 --> 0x6789
+        :code --> code[wasm code]
+    end
+
+    subgraph Runtime[Runtime's View Of The State 🙉]
+        direction LR
+        ab[alice's balance] --> abv[known value]
+        bb[bob's balance] --> bbv[known value]
+        cb[charlie's balance] --> cbv[known value]
+        c2[:code] --> c22[wasm code]
+    end
@@ -0,0 +1,21 @@
+flowchart LR
+    %%{init: {'flowchart' : {'curve' : 'linear'}}}%%
+    subgraph BData[Blockchain Database]
+        direction LR
+        BN[Block N] -.-> BN1[Block N+1]
+    end
+
+    subgraph SData[State Database]
+        direction LR
+        SN[State N] -.-> SN1[State N+1] -.-> SN2[State N+2]
+    end
+
+    BN --> STFN[STF]
+    SN --> STFN[STF]
+    STFN[STF] --> SN1
+
+    BN1 --> STFN1[STF]
+    SN1 --> STFN1[STF]
+    STFN1[STF] --> SN2
+
+
@@ -0,0 +1,4 @@
+flowchart LR
+	B[Block] --> STF
+    S[State] --> STF
+    STF --> NS[New State]
@@ -0,0 +1,12 @@
+graph TB
+subgraph Substrate
+	direction LR
+	subgraph Node
+	end
+
+	subgraph Runtime
+	end
+
+	Node --runtime-api--> Runtime
+	Runtime --host-functions--> Node
+end
@@ -0,0 +1,2 @@
+flowchart LR
+	T[Using a Template] --> P[Writing Your Own FRAME-Based Pallet] --> C[Custom Node]
@@ -0,0 +1,8 @@
+graph TB
+subgraph Substrate
+	direction LR
+	subgraph Node
+	end
+	subgraph Runtime
+	end
+end
@@ -0,0 +1,20 @@
+graph TB
+subgraph Substrate
+	direction LR
+	subgraph Node
+		Database
+		Networking
+		Consensus
+	end
+	subgraph Runtime
+		subgraph FRAME
+			direction LR
+			Governance
+			Currency
+			Staking
+			Identity
+		end
+	end
+	Node --runtime-api--> Runtime
+	Runtime --host-functions--> Node
+end
@@ -0,0 +1,213 @@
+[package]
+name = "pezkuwi-sdk-docs"
+description = "The one stop shop for developers of the pezkuwi-sdk"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+homepage = "https://docs.pezkuwichain.io/sdk/"
+repository.workspace = true
+authors.workspace = true
+edition.workspace = true
+# This crate is not publish-able to crates.io for now because of docify.
+publish = false
+version = "0.0.1"
+
+[lints]
+workspace = true
+
+[dependencies]
+# Needed for all FRAME-based code
+codec = { workspace = true }
+frame = { features = [
+	"experimental",
+	"runtime",
+], workspace = true, default-features = true }
+pallet-contracts = { workspace = true }
+pallet-default-config-example = { workspace = true, default-features = true }
+pallet-example-offchain-worker = { workspace = true, default-features = true }
+pallet-examples = { workspace = true }
+scale-info = { workspace = true }
+
+# How we build docs in rust-docs
+docify = { workspace = true }
+serde_json = { workspace = true }
+simple-mermaid = { workspace = true }
+
+# Pezkuwi SDK deps, typically all should only be in scope such that we can link to their doc item.
+chain-spec-builder = { workspace = true, default-features = true }
+frame-benchmarking = { workspace = true }
+frame-executive = { workspace = true }
+frame-metadata-hash-extension = { workspace = true, default-features = true }
+frame-support = { workspace = true }
+frame-system = { workspace = true }
+kitchensink-runtime = { workspace = true }
+log = { workspace = true, default-features = true }
+node-cli = { workspace = true }
+pallet-example-authorization-tx-extension = { workspace = true, default-features = true }
+pallet-example-single-block-migrations = { workspace = true, default-features = true }
+pezkuwi-sdk = { features = [
+	"runtime-full",
+], workspace = true, default-features = true }
+subkey = { workspace = true, default-features = true }
+
+# Substrate Client
+sc-chain-spec = { workspace = true, default-features = true }
+sc-cli = { workspace = true, default-features = true }
+sc-client-db = { workspace = true, default-features = true }
+sc-consensus-aura = { workspace = true, default-features = true }
+sc-consensus-babe = { workspace = true, default-features = true }
+sc-consensus-beefy = { workspace = true, default-features = true }
+sc-consensus-grandpa = { workspace = true, default-features = true }
+sc-consensus-manual-seal = { workspace = true, default-features = true }
+sc-consensus-pow = { workspace = true, default-features = true }
+sc-executor = { workspace = true, default-features = true }
+sc-network = { workspace = true, default-features = true }
+sc-rpc = { workspace = true, default-features = true }
+sc-rpc-api = { workspace = true, default-features = true }
+sc-service = { workspace = true, default-features = true }
+
+substrate-wasm-builder = { workspace = true, default-features = true }
+
+# Cumulus
+cumulus-client-service = { workspace = true, default-features = true }
+cumulus-pallet-aura-ext = { workspace = true, default-features = true }
+cumulus-pallet-teyrchain-system = { workspace = true, default-features = true }
+cumulus-pallet-weight-reclaim = { workspace = true, default-features = true }
+cumulus-primitives-proof-size-hostfunction = { workspace = true, default-features = true }
+teyrchain-info = { workspace = true, default-features = true }
+
+# Omni Node
+pezkuwi-omni-node-lib = { workspace = true, default-features = true }
+
+# Pallets and FRAME internals
+pallet-asset-conversion-tx-payment = { workspace = true, default-features = true }
+pallet-asset-tx-payment = { workspace = true, default-features = true }
+pallet-assets = { workspace = true, default-features = true }
+pallet-aura = { workspace = true, default-features = true }
+pallet-babe = { workspace = true, default-features = true }
+pallet-balances = { workspace = true, default-features = true }
+pallet-collective = { workspace = true, default-features = true }
+pallet-democracy = { workspace = true, default-features = true }
+pallet-grandpa = { workspace = true, default-features = true }
+pallet-nfts = { workspace = true, default-features = true }
+pallet-preimage = { workspace = true, default-features = true }
+pallet-scheduler = { workspace = true, default-features = true }
+pallet-skip-feeless-payment = { workspace = true, default-features = true }
+pallet-timestamp = { workspace = true, default-features = true }
+pallet-transaction-payment = { workspace = true, default-features = true }
+pallet-uniques = { workspace = true, default-features = true }
+
+# Primitives
+sp-api = { workspace = true, default-features = true }
+sp-arithmetic = { workspace = true, default-features = true }
+sp-core = { workspace = true, default-features = true }
+sp-genesis-builder = { workspace = true, default-features = true }
+sp-io = { workspace = true, default-features = true }
+sp-keyring = { workspace = true, default-features = true }
+sp-offchain = { workspace = true, default-features = true }
+sp-runtime = { workspace = true, default-features = true }
+sp-runtime-interface = { workspace = true, default-features = true }
+sp-std = { workspace = true, default-features = true }
+sp-storage = { workspace = true, default-features = true }
+sp-tracing = { workspace = true, default-features = true }
+sp-version = { workspace = true, default-features = true }
+sp-weights = { workspace = true, default-features = true }
+
+# XCM
+pallet-xcm = { workspace = true }
+xcm = { workspace = true, default-features = true }
+xcm-builder = { workspace = true }
+xcm-docs = { workspace = true }
+xcm-executor = { workspace = true }
+xcm-simulator = { workspace = true }
+
+# Runtime guides
+chain-spec-guide-runtime = { workspace = true, default-features = true }
+
+# Templates
+minimal-template-runtime = { workspace = true, default-features = true }
+solochain-template-runtime = { workspace = true, default-features = true }
+
+# local packages
+first-runtime = { workspace = true, default-features = true }
+
+[dev-dependencies]
+assert_cmd = { workspace = true }
+cmd_lib = { workspace = true }
+rand = { workspace = true, default-features = true }
+tokio = { workspace = true }
+
+[features]
+runtime-benchmarks = [
+	"chain-spec-builder/runtime-benchmarks",
+	"chain-spec-guide-runtime/runtime-benchmarks",
+	"cumulus-client-service/runtime-benchmarks",
+	"cumulus-pallet-aura-ext/runtime-benchmarks",
+	"cumulus-pallet-teyrchain-system/runtime-benchmarks",
+	"cumulus-pallet-weight-reclaim/runtime-benchmarks",
+	"cumulus-primitives-proof-size-hostfunction/runtime-benchmarks",
+	"first-runtime/runtime-benchmarks",
+	"frame-benchmarking/runtime-benchmarks",
+	"frame-executive/runtime-benchmarks",
+	"frame-metadata-hash-extension/runtime-benchmarks",
+	"frame-support/runtime-benchmarks",
+	"frame-system/runtime-benchmarks",
+	"frame/runtime-benchmarks",
+	"kitchensink-runtime/runtime-benchmarks",
+	"minimal-template-runtime/runtime-benchmarks",
+	"node-cli/runtime-benchmarks",
+	"pallet-asset-conversion-tx-payment/runtime-benchmarks",
+	"pallet-asset-tx-payment/runtime-benchmarks",
+	"pallet-assets/runtime-benchmarks",
+	"pallet-aura/runtime-benchmarks",
+	"pallet-babe/runtime-benchmarks",
+	"pallet-balances/runtime-benchmarks",
+	"pallet-collective/runtime-benchmarks",
+	"pallet-contracts/runtime-benchmarks",
+	"pallet-default-config-example/runtime-benchmarks",
+	"pallet-democracy/runtime-benchmarks",
+	"pallet-example-authorization-tx-extension/runtime-benchmarks",
+	"pallet-example-offchain-worker/runtime-benchmarks",
+	"pallet-example-single-block-migrations/runtime-benchmarks",
+	"pallet-examples/runtime-benchmarks",
+	"pallet-grandpa/runtime-benchmarks",
+	"pallet-nfts/runtime-benchmarks",
+	"pallet-preimage/runtime-benchmarks",
+	"pallet-scheduler/runtime-benchmarks",
+	"pallet-skip-feeless-payment/runtime-benchmarks",
+	"pallet-timestamp/runtime-benchmarks",
+	"pallet-transaction-payment/runtime-benchmarks",
+	"pallet-uniques/runtime-benchmarks",
+	"pallet-xcm/runtime-benchmarks",
+	"pezkuwi-omni-node-lib/runtime-benchmarks",
+	"pezkuwi-sdk/runtime-benchmarks",
+	"sc-chain-spec/runtime-benchmarks",
+	"sc-cli/runtime-benchmarks",
+	"sc-client-db/runtime-benchmarks",
+	"sc-consensus-aura/runtime-benchmarks",
+	"sc-consensus-babe/runtime-benchmarks",
+	"sc-consensus-beefy/runtime-benchmarks",
+	"sc-consensus-grandpa/runtime-benchmarks",
+	"sc-consensus-manual-seal/runtime-benchmarks",
+	"sc-consensus-pow/runtime-benchmarks",
+	"sc-executor/runtime-benchmarks",
+	"sc-network/runtime-benchmarks",
+	"sc-rpc-api/runtime-benchmarks",
+	"sc-rpc/runtime-benchmarks",
+	"sc-service/runtime-benchmarks",
+	"solochain-template-runtime/runtime-benchmarks",
+	"sp-api/runtime-benchmarks",
+	"sp-genesis-builder/runtime-benchmarks",
+	"sp-io/runtime-benchmarks",
+	"sp-keyring/runtime-benchmarks",
+	"sp-offchain/runtime-benchmarks",
+	"sp-runtime-interface/runtime-benchmarks",
+	"sp-runtime/runtime-benchmarks",
+	"sp-version/runtime-benchmarks",
+	"subkey/runtime-benchmarks",
+	"substrate-wasm-builder/runtime-benchmarks",
+	"teyrchain-info/runtime-benchmarks",
+	"xcm-builder/runtime-benchmarks",
+	"xcm-docs/runtime-benchmarks",
+	"xcm-executor/runtime-benchmarks",
+	"xcm-simulator/runtime-benchmarks",
+	"xcm/runtime-benchmarks",
+]
@@ -0,0 +1,2 @@
+<script> mermaid.init({ startOnLoad: true, theme: "dark" }, "pre.language-mermaid > code");</script>
+
@@ -0,0 +1,147 @@
+<script>
+	function createToC() {
+		let sidebar = document.querySelector(".sidebar");
+		let headers = document.querySelectorAll("#main-content h2, #main-content h3, #main-content h4");
+		console.log(`detected polkadot_sdk_docs: headers: ${headers.length}`);
+
+		let toc = document.createElement("div");
+		toc.classList.add("sidebar-table-of-contents");
+		toc.appendChild(document.createElement("h2").appendChild(document.createTextNode("Table of Contents")).parentNode);
+
+		let modules = document.querySelectorAll("main .item-table a.mod");
+
+		// the first two headers are always junk
+		headers.forEach(header => {
+			let link = document.createElement("a");
+			link.href = "#" + header.id;
+			const headerTextContent = header.textContent.replace("§", "")
+			link.textContent = headerTextContent;
+			link.className = header.tagName.toLowerCase();
+
+			toc.appendChild(link);
+
+			if (header.id == "modules" && headerTextContent == "Modules") {
+				modules.forEach(module => {
+					let link = document.createElement("a");
+					link.href = module.href;
+					link.textContent = module.textContent;
+					link.className = "h3";
+
+					toc.appendChild(link);
+				});
+			}
+		});
+
+		// insert toc as the second child in sidebar
+		let sidebar_children = sidebar.children;
+		if (sidebar_children.length > 1) {
+			sidebar.insertBefore(toc, sidebar_children[1]);
+		} else {
+			sidebar.appendChild(toc);
+		}
+	}
+
+	function hideSidebarElements() {
+		// Create the 'Expand for More' button
+		var expandButton = document.createElement('button');
+		expandButton.innerText = 'Expand More Items';
+		expandButton.classList.add('expand-button');
+
+		// Insert the button at the top of the sidebar or before the '.sidebar-elems'
+		var sidebarElems = document.querySelector('.sidebar-elems');
+		sidebarElems.parentNode.insertBefore(expandButton, sidebarElems);
+
+		// Initially hide the '.sidebar-elems'
+		sidebarElems.style.display = 'none';
+
+		// Add click event listener to the button
+		expandButton.addEventListener('click', function () {
+			// Toggle the display of the '.sidebar-elems'
+			if (sidebarElems.style.display === 'none') {
+				sidebarElems.style.display = 'block';
+				expandButton.innerText = 'Collapse';
+			} else {
+				sidebarElems.style.display = 'none';
+				expandButton.innerText = 'Expand for More';
+			}
+		});
+	}
+
+	window.addEventListener("DOMContentLoaded", (event) => {
+		// if the crate is one that starts with `polkadot_sdk_docs`
+		let crate_name = document.querySelector("#main-content > div > h1 > a:nth-child(1)");
+		if (!crate_name.textContent.startsWith("polkadot_sdk_docs")) {
+			console.log("skipping -- not `polkadot_sdk_docs`");
+			return;
+		} else {
+			// insert class 'sdk-docs' to the body, so it enables the custom css rules.
+			document.body.classList.add("sdk-docs");
+		}
+
+		createToC();
+		hideSidebarElements();
+
+		console.log("updating page based on being `polkadot_sdk_docs` crate");
+	});
+</script>
+
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+
+<style>
+	body.sdk-docs {
+		nav.side-bar {
+			width: 300px;
+		}
+
+		.sidebar-table-of-contents {
+			margin-bottom: 1em;
+			padding: 0.5em;
+		}
+
+		.sidebar-table-of-contents a {
+			display: block;
+			margin: 0.2em 0;
+		}
+
+		.sidebar-table-of-contents .h2 {
+			font-weight: bold;
+			margin-left: 0;
+		}
+
+		.sidebar-table-of-contents .h3 {
+			margin-left: 1em;
+		}
+
+		.sidebar-table-of-contents .h4 {
+			margin-left: 2em;
+		}
+
+		.sidebar h2.location {
+			display: none;
+		}
+
+		.sidebar-elems {
+			display: none;
+		}
+
+		/* Center the 'Expand for More' button */
+		.expand-button {
+			display: inline-block;
+			/* Use inline-block for sizing */
+			margin: 10px auto;
+			/* Auto margins for horizontal centering */
+			padding: 5px 10px;
+			background-color: #007bff;
+			color: white;
+			text-align: center;
+			cursor: pointer;
+			border: none;
+			border-radius: 5px;
+			width: auto;
+			/* Centering the button within its parent container */
+			position: relative;
+			left: 50%;
+			transform: translateX(-50%);
+		}
+	}
+</style>
@@ -0,0 +1,57 @@
+:root {
+	--polkadot-pink: #E6007A;
+	--polkadot-green: #56F39A;
+	--polkadot-lime: #D3FF33;
+	--polkadot-cyan: #00B2FF;
+	--polkadot-purple: #552BBF;
+}
+
+/* Light theme */
+html[data-theme="light"] {
+    --quote-background: #f9f9f9;
+    --quote-border: #ccc;
+    --quote-text: #333;
+}
+
+/* Dark theme */
+html[data-theme="dark"] {
+    --quote-background: #333;
+    --quote-border: #555;
+    --quote-text: #f9f9f9;
+}
+
+/* Ayu theme */
+html[data-theme="ayu"] {
+    --quote-background: #272822;
+    --quote-border: #383830;
+    --quote-text: #f8f8f2;
+}
+
+body.sdk-docs {
+	nav.sidebar>div.sidebar-crate>a>img {
+		width: 190px;
+		height: 52px;
+	}
+
+	nav.sidebar {
+		flex: 0 0 250px;
+	}
+}
+
+html[data-theme="light"] .sidebar-crate > .logo-container > img {
+  content: url("https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/docs/images/Polkadot_Logo_Horizontal_Pink_Black.png");
+}
+
+/* Custom styles for blockquotes */
+blockquote {
+    background-color: var(--quote-background);
+    border-left: 5px solid var(--quote-border);
+    color: var(--quote-text);
+    margin: 1em 0;
+    padding: 1em 1.5em;
+    /* font-style: italic; */
+}
+
+blockquote p {
+    margin: 0;
+}
@@ -0,0 +1,27 @@
+[package]
+name = "pezkuwi-sdk-docs-first-pallet"
+description = "A simple pallet created for the pezkuwi-sdk-docs guides"
+version = "0.0.0"
+license = "MIT-0"
+authors.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { workspace = true }
+docify = { workspace = true }
+frame = { workspace = true, features = ["runtime"] }
+scale-info = { workspace = true }
+
+[features]
+default = ["std"]
+std = ["codec/std", "frame/std", "scale-info/std"]
+runtime-benchmarks = ["frame/runtime-benchmarks"]
@@ -0,0 +1,481 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Pallets used in the `your_first_pallet` guide.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod shell_pallet {
+	use frame::prelude::*;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+}
+
+#[frame::pallet(dev_mode)]
+pub mod pallet {
+	use frame::prelude::*;
+
+	#[docify::export]
+	pub type Balance = u128;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[docify::export]
+	/// Single storage item, of type `Balance`.
+	#[pallet::storage]
+	pub type TotalIssuance<T: Config> = StorageValue<_, Balance>;
+
+	#[docify::export]
+	/// A mapping from `T::AccountId` to `Balance`
+	#[pallet::storage]
+	pub type Balances<T: Config> = StorageMap<_, _, T::AccountId, Balance>;
+
+	#[docify::export(impl_pallet)]
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		/// An unsafe mint that can be called by anyone. Not a great idea.
+		pub fn mint_unsafe(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			// ensure that this is a signed account, but we don't really check `_anyone`.
+			let _anyone = ensure_signed(origin)?;
+
+			// update the balances map. Notice how all `<T: Config>` remains as `<T>`.
+			Balances::<T>::mutate(dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			// update total issuance.
+			TotalIssuance::<T>::mutate(|t| *t = Some(t.unwrap_or(0) + amount));
+
+			Ok(())
+		}
+
+		/// Transfer `amount` from `origin` to `dest`.
+		pub fn transfer(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			// ensure sender has enough balance, and if so, calculate what is left after `amount`.
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			if sender_balance < amount {
+				return Err("InsufficientBalance".into());
+			}
+			let remainder = sender_balance - amount;
+
+			// update sender and dest balances.
+			Balances::<T>::mutate(dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			Balances::<T>::insert(&sender, remainder);
+
+			Ok(())
+		}
+	}
+
+	#[allow(unused)]
+	impl<T: Config> Pallet<T> {
+		#[docify::export]
+		pub fn transfer_better(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			ensure!(sender_balance >= amount, "InsufficientBalance");
+			let remainder = sender_balance - amount;
+
+			// .. snip
+			Ok(())
+		}
+
+		#[docify::export]
+		/// Transfer `amount` from `origin` to `dest`.
+		pub fn transfer_better_checked(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			let remainder = sender_balance.checked_sub(amount).ok_or("InsufficientBalance")?;
+
+			// .. snip
+			Ok(())
+		}
+	}
+
+	#[cfg(any(test, doc))]
+	pub(crate) mod tests {
+		use crate::pallet::*;
+
+		#[docify::export(testing_prelude)]
+		use frame::testing_prelude::*;
+
+		pub(crate) const ALICE: u64 = 1;
+		pub(crate) const BOB: u64 = 2;
+		pub(crate) const CHARLIE: u64 = 3;
+
+		#[docify::export]
+		// This runtime is only used for testing, so it should be somewhere like `#[cfg(test)] mod
+		// tests { .. }`
+		mod runtime {
+			use super::*;
+			// we need to reference our `mod pallet` as an identifier to pass to
+			// `construct_runtime`.
+			// YOU HAVE TO CHANGE THIS LINE BASED ON YOUR TEMPLATE
+			use crate::pallet as pallet_currency;
+
+			construct_runtime!(
+				pub enum Runtime {
+					// ---^^^^^^ This is where `enum Runtime` is defined.
+					System: frame_system,
+					Currency: pallet_currency,
+				}
+			);
+
+			#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+			impl frame_system::Config for Runtime {
+				type Block = MockBlock<Runtime>;
+				// within pallet we just said `<T as frame_system::Config>::AccountId`, now we
+				// finally specified it.
+				type AccountId = u64;
+			}
+
+			// our simple pallet has nothing to be configured.
+			impl pallet_currency::Config for Runtime {}
+		}
+
+		pub(crate) use runtime::*;
+
+		#[allow(unused)]
+		#[docify::export]
+		fn new_test_state_basic() -> TestState {
+			let mut state = TestState::new_empty();
+			let accounts = vec![(ALICE, 100), (BOB, 100)];
+			state.execute_with(|| {
+				for (who, amount) in &accounts {
+					Balances::<Runtime>::insert(who, amount);
+					TotalIssuance::<Runtime>::mutate(|b| *b = Some(b.unwrap_or(0) + amount));
+				}
+			});
+
+			state
+		}
+
+		#[docify::export]
+		pub(crate) struct StateBuilder {
+			balances: Vec<(<Runtime as frame_system::Config>::AccountId, Balance)>,
+		}
+
+		#[docify::export(default_state_builder)]
+		impl Default for StateBuilder {
+			fn default() -> Self {
+				Self { balances: vec![(ALICE, 100), (BOB, 100)] }
+			}
+		}
+
+		#[docify::export(impl_state_builder_add)]
+		impl StateBuilder {
+			fn add_balance(
+				mut self,
+				who: <Runtime as frame_system::Config>::AccountId,
+				amount: Balance,
+			) -> Self {
+				self.balances.push((who, amount));
+				self
+			}
+		}
+
+		#[docify::export(impl_state_builder_build)]
+		impl StateBuilder {
+			pub(crate) fn build_and_execute(self, test: impl FnOnce() -> ()) {
+				let mut ext = TestState::new_empty();
+				ext.execute_with(|| {
+					for (who, amount) in &self.balances {
+						Balances::<Runtime>::insert(who, amount);
+						TotalIssuance::<Runtime>::mutate(|b| *b = Some(b.unwrap_or(0) + amount));
+					}
+				});
+
+				ext.execute_with(test);
+
+				// assertions that must always hold
+				ext.execute_with(|| {
+					assert_eq!(
+						Balances::<Runtime>::iter().map(|(_, x)| x).sum::<u128>(),
+						TotalIssuance::<Runtime>::get().unwrap_or_default()
+					);
+				})
+			}
+		}
+
+		#[docify::export]
+		#[test]
+		fn first_test() {
+			TestState::new_empty().execute_with(|| {
+				// We expect Alice's account to have no funds.
+				assert_eq!(Balances::<Runtime>::get(&ALICE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), None);
+
+				// mint some funds into Alice's account.
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(
+					RuntimeOrigin::signed(ALICE),
+					ALICE,
+					100
+				));
+
+				// re-check the above
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(100));
+			})
+		}
+
+		#[docify::export]
+		#[test]
+		fn state_builder_works() {
+			StateBuilder::default().build_and_execute(|| {
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn state_builder_add_balance() {
+			StateBuilder::default().add_balance(CHARLIE, 42).build_and_execute(|| {
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), Some(42));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(242));
+			})
+		}
+
+		#[test]
+		#[should_panic]
+		fn state_builder_duplicate_genesis_fails() {
+			StateBuilder::default()
+				.add_balance(CHARLIE, 42)
+				.add_balance(CHARLIE, 43)
+				.build_and_execute(|| {
+					assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+					assert_eq!(TotalIssuance::<Runtime>::get(), Some(242));
+				})
+		}
+
+		#[docify::export]
+		#[test]
+		fn mint_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(RuntimeOrigin::signed(ALICE), BOB, 100));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(200));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(300));
+
+				// given:
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(
+					RuntimeOrigin::signed(ALICE),
+					CHARLIE,
+					100
+				));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(400));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn transfer_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(ALICE), BOB, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(50));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(150));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+
+				// when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(BOB), ALICE, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn transfer_from_non_existent_fails() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_err!(
+					Pallet::<Runtime>::transfer(RuntimeOrigin::signed(CHARLIE), ALICE, 10),
+					"NonExistentAccount"
+				);
+
+				// then nothing has changed.
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+	}
+}
+
+#[frame::pallet(dev_mode)]
+pub mod pallet_v2 {
+	use super::pallet::Balance;
+	use frame::prelude::*;
+
+	#[docify::export(config_v2)]
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		/// The overarching event type of the runtime.
+		#[allow(deprecated)]
+		type RuntimeEvent: From<Event<Self>>
+			+ IsType<<Self as frame_system::Config>::RuntimeEvent>
+			+ TryInto<Event<Self>>;
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[pallet::storage]
+	pub type Balances<T: Config> = StorageMap<_, _, T::AccountId, Balance>;
+
+	#[pallet::storage]
+	pub type TotalIssuance<T: Config> = StorageValue<_, Balance>;
+
+	#[docify::export]
+	#[pallet::error]
+	pub enum Error<T> {
+		/// Account does not exist.
+		NonExistentAccount,
+		/// Account does not have enough balance.
+		InsufficientBalance,
+	}
+
+	#[docify::export]
+	#[pallet::event]
+	#[pallet::generate_deposit(pub(super) fn deposit_event)]
+	pub enum Event<T: Config> {
+		/// A transfer succeeded.
+		Transferred { from: T::AccountId, to: T::AccountId, amount: Balance },
+	}
+
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		#[docify::export(transfer_v2)]
+		pub fn transfer(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			// ensure sender has enough balance, and if so, calculate what is left after `amount`.
+			let sender_balance =
+				Balances::<T>::get(&sender).ok_or(Error::<T>::NonExistentAccount)?;
+			let remainder =
+				sender_balance.checked_sub(amount).ok_or(Error::<T>::InsufficientBalance)?;
+
+			Balances::<T>::mutate(&dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			Balances::<T>::insert(&sender, remainder);
+
+			Self::deposit_event(Event::<T>::Transferred { from: sender, to: dest, amount });
+
+			Ok(())
+		}
+	}
+
+	#[cfg(any(test, doc))]
+	pub mod tests {
+		use super::{super::pallet::tests::StateBuilder, *};
+		use frame::testing_prelude::*;
+		const ALICE: u64 = 1;
+		const BOB: u64 = 2;
+
+		#[docify::export]
+		pub mod runtime_v2 {
+			use super::*;
+			use crate::pallet_v2 as pallet_currency;
+
+			construct_runtime!(
+				pub enum Runtime {
+					System: frame_system,
+					Currency: pallet_currency,
+				}
+			);
+
+			#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+			impl frame_system::Config for Runtime {
+				type Block = MockBlock<Runtime>;
+				type AccountId = u64;
+			}
+
+			impl pallet_currency::Config for Runtime {
+				type RuntimeEvent = RuntimeEvent;
+			}
+		}
+
+		pub(crate) use runtime_v2::*;
+
+		#[docify::export(transfer_works_v2)]
+		#[test]
+		fn transfer_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// skip the genesis block, as events are not deposited there and we need them for
+				// the final assertion.
+				System::set_block_number(ALICE);
+
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(ALICE), BOB, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(50));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(150));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+
+				// now we can also check that an event has been deposited:
+				assert_eq!(
+					System::read_events_for_pallet::<Event<Runtime>>(),
+					vec![Event::Transferred { from: ALICE, to: BOB, amount: 50 }]
+				);
+			});
+		}
+	}
+}
@@ -0,0 +1,71 @@
+[package]
+name = "pezkuwi-sdk-docs-first-runtime"
+description = "A simple runtime created for the pezkuwi-sdk-docs guides"
+version = "0.0.0"
+license = "MIT-0"
+authors.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[dependencies]
+codec = { workspace = true }
+scale-info = { workspace = true }
+serde_json = { workspace = true }
+
+# this is a frame-based runtime, thus importing `frame` with runtime feature enabled.
+frame = { workspace = true, features = ["runtime"] }
+
+# pallets that we want to use
+pallet-balances = { workspace = true }
+pallet-sudo = { workspace = true }
+pallet-timestamp = { workspace = true }
+pallet-transaction-payment = { workspace = true }
+pallet-transaction-payment-rpc-runtime-api = { workspace = true }
+
+# other pezkuwi-sdk-deps
+sp-keyring = { workspace = true }
+
+# local pallet templates
+first-pallet = { workspace = true }
+
+docify = { workspace = true }
+
+[build-dependencies]
+substrate-wasm-builder = { workspace = true, optional = true }
+
+[features]
+default = ["std"]
+std = [
+	"codec/std",
+	"scale-info/std",
+	"serde_json/std",
+
+	"frame/std",
+
+	"pallet-balances/std",
+	"pallet-sudo/std",
+	"pallet-timestamp/std",
+	"pallet-transaction-payment-rpc-runtime-api/std",
+	"pallet-transaction-payment/std",
+
+	"first-pallet/std",
+	"sp-keyring/std",
+
+	"substrate-wasm-builder",
+]
+runtime-benchmarks = [
+	"first-pallet/runtime-benchmarks",
+	"frame/runtime-benchmarks",
+	"pallet-balances/runtime-benchmarks",
+	"pallet-sudo/runtime-benchmarks",
+	"pallet-timestamp/runtime-benchmarks",
+	"pallet-transaction-payment-rpc-runtime-api/runtime-benchmarks",
+	"pallet-transaction-payment/runtime-benchmarks",
+	"sp-keyring/runtime-benchmarks",
+	"substrate-wasm-builder?/runtime-benchmarks",
+]
@@ -0,0 +1,27 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+fn main() {
+	#[cfg(feature = "std")]
+	{
+		substrate_wasm_builder::WasmBuilder::new()
+			.with_current_project()
+			.export_heap_base()
+			.import_memory()
+			.build();
+	}
+}
@@ -0,0 +1,299 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Runtime used in `your_first_runtime`.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+extern crate alloc;
+use alloc::{vec, vec::Vec};
+use first_pallet::pallet_v2 as our_first_pallet;
+use frame::{
+	prelude::*,
+	runtime::{apis, prelude::*},
+};
+use pallet_transaction_payment_rpc_runtime_api::{FeeDetails, RuntimeDispatchInfo};
+
+#[docify::export]
+#[runtime_version]
+pub const VERSION: RuntimeVersion = RuntimeVersion {
+	spec_name: alloc::borrow::Cow::Borrowed("first-runtime"),
+	impl_name: alloc::borrow::Cow::Borrowed("first-runtime"),
+	authoring_version: 1,
+	spec_version: 0,
+	impl_version: 1,
+	apis: RUNTIME_API_VERSIONS,
+	transaction_version: 1,
+	system_version: 1,
+};
+
+#[docify::export(cr)]
+construct_runtime!(
+	pub struct Runtime {
+		// Mandatory for all runtimes
+		System: frame_system,
+
+		// A number of other pallets from FRAME.
+		Timestamp: pallet_timestamp,
+		Balances: pallet_balances,
+		Sudo: pallet_sudo,
+		TransactionPayment: pallet_transaction_payment,
+
+		// Our local pallet
+		FirstPallet: our_first_pallet,
+	}
+);
+
+#[docify::export_content]
+mod runtime_types {
+	use super::*;
+	pub(super) type SignedExtra = (
+		// `frame` already provides all the signed extensions from `frame-system`. We just add the
+		// one related to tx-payment here.
+		frame::runtime::types_common::SystemTransactionExtensionsOf<Runtime>,
+		pallet_transaction_payment::ChargeTransactionPayment<Runtime>,
+	);
+
+	pub(super) type Block = frame::runtime::types_common::BlockOf<Runtime, SignedExtra>;
+	pub(super) type Header = HeaderFor<Runtime>;
+
+	pub(super) type RuntimeExecutive = Executive<
+		Runtime,
+		Block,
+		frame_system::ChainContext<Runtime>,
+		Runtime,
+		AllPalletsWithSystem,
+	>;
+}
+use runtime_types::*;
+
+#[docify::export_content]
+mod config_impls {
+	use super::*;
+
+	parameter_types! {
+		pub const Version: RuntimeVersion = VERSION;
+	}
+
+	#[derive_impl(frame_system::config_preludes::SolochainDefaultConfig)]
+	impl frame_system::Config for Runtime {
+		type Block = Block;
+		type Version = Version;
+		type AccountData =
+			pallet_balances::AccountData<<Runtime as pallet_balances::Config>::Balance>;
+	}
+
+	#[derive_impl(pallet_balances::config_preludes::TestDefaultConfig)]
+	impl pallet_balances::Config for Runtime {
+		type AccountStore = System;
+	}
+
+	#[derive_impl(pallet_sudo::config_preludes::TestDefaultConfig)]
+	impl pallet_sudo::Config for Runtime {}
+
+	#[derive_impl(pallet_timestamp::config_preludes::TestDefaultConfig)]
+	impl pallet_timestamp::Config for Runtime {}
+
+	#[derive_impl(pallet_transaction_payment::config_preludes::TestDefaultConfig)]
+	impl pallet_transaction_payment::Config for Runtime {
+		type OnChargeTransaction = pallet_transaction_payment::FungibleAdapter<Balances, ()>;
+		// We specify a fixed length to fee here, which essentially means all transactions charge
+		// exactly 1 unit of fee.
+		type LengthToFee = FixedFee<1, <Self as pallet_balances::Config>::Balance>;
+		type WeightToFee = NoFee<<Self as pallet_balances::Config>::Balance>;
+	}
+}
+
+#[docify::export(our_config_impl)]
+impl our_first_pallet::Config for Runtime {
+	type RuntimeEvent = RuntimeEvent;
+}
+
+/// Provides getters for genesis configuration presets.
+pub mod genesis_config_presets {
+	use super::*;
+	use crate::{
+		interface::{Balance, MinimumBalance},
+		BalancesConfig, RuntimeGenesisConfig, SudoConfig,
+	};
+	use frame::deps::frame_support::build_struct_json_patch;
+	use serde_json::Value;
+
+	/// Returns a development genesis config preset.
+	#[docify::export]
+	pub fn development_config_genesis() -> Value {
+		let endowment = <MinimumBalance as Get<Balance>>::get().max(1) * 1000;
+		build_struct_json_patch!(RuntimeGenesisConfig {
+			balances: BalancesConfig {
+				balances: Sr25519Keyring::iter()
+					.map(|a| (a.to_account_id(), endowment))
+					.collect::<Vec<_>>(),
+			},
+			sudo: SudoConfig { key: Some(Sr25519Keyring::Alice.to_account_id()) },
+		})
+	}
+
+	/// Get the set of the available genesis config presets.
+	#[docify::export]
+	pub fn get_preset(id: &PresetId) -> Option<Vec<u8>> {
+		let patch = match id.as_ref() {
+			DEV_RUNTIME_PRESET => development_config_genesis(),
+			_ => return None,
+		};
+		Some(
+			serde_json::to_string(&patch)
+				.expect("serialization to json is expected to work. qed.")
+				.into_bytes(),
+		)
+	}
+
+	/// List of supported presets.
+	#[docify::export]
+	pub fn preset_names() -> Vec<PresetId> {
+		vec![PresetId::from(DEV_RUNTIME_PRESET)]
+	}
+}
+
+impl_runtime_apis! {
+	impl apis::Core<Block> for Runtime {
+		fn version() -> RuntimeVersion {
+			VERSION
+		}
+
+		fn execute_block(block: <Block as frame::traits::Block>::LazyBlock) {
+			RuntimeExecutive::execute_block(block)
+		}
+
+		fn initialize_block(header: &Header) -> ExtrinsicInclusionMode {
+			RuntimeExecutive::initialize_block(header)
+		}
+	}
+
+	impl apis::Metadata<Block> for Runtime {
+		fn metadata() -> OpaqueMetadata {
+			OpaqueMetadata::new(Runtime::metadata().into())
+		}
+
+		fn metadata_at_version(version: u32) -> Option<OpaqueMetadata> {
+			Runtime::metadata_at_version(version)
+		}
+
+		fn metadata_versions() -> Vec<u32> {
+			Runtime::metadata_versions()
+		}
+	}
+
+	impl apis::BlockBuilder<Block> for Runtime {
+		fn apply_extrinsic(extrinsic: ExtrinsicFor<Runtime>) -> ApplyExtrinsicResult {
+			RuntimeExecutive::apply_extrinsic(extrinsic)
+		}
+
+		fn finalize_block() -> HeaderFor<Runtime> {
+			RuntimeExecutive::finalize_block()
+		}
+
+		fn inherent_extrinsics(data: InherentData) -> Vec<ExtrinsicFor<Runtime>> {
+			data.create_extrinsics()
+		}
+
+		fn check_inherents(
+			block: <Block as frame::traits::Block>::LazyBlock,
+			data: InherentData,
+		) -> CheckInherentsResult {
+			data.check_extrinsics(&block)
+		}
+	}
+
+	impl apis::TaggedTransactionQueue<Block> for Runtime {
+		fn validate_transaction(
+			source: TransactionSource,
+			tx: ExtrinsicFor<Runtime>,
+			block_hash: <Runtime as frame_system::Config>::Hash,
+		) -> TransactionValidity {
+			RuntimeExecutive::validate_transaction(source, tx, block_hash)
+		}
+	}
+
+	impl apis::OffchainWorkerApi<Block> for Runtime {
+		fn offchain_worker(header: &HeaderFor<Runtime>) {
+			RuntimeExecutive::offchain_worker(header)
+		}
+	}
+
+	impl apis::SessionKeys<Block> for Runtime {
+		fn generate_session_keys(_seed: Option<Vec<u8>>) -> Vec<u8> {
+			Default::default()
+		}
+
+		fn decode_session_keys(
+			_encoded: Vec<u8>,
+		) -> Option<Vec<(Vec<u8>, apis::KeyTypeId)>> {
+			Default::default()
+		}
+	}
+
+	impl apis::AccountNonceApi<Block, interface::AccountId, interface::Nonce> for Runtime {
+		fn account_nonce(account: interface::AccountId) -> interface::Nonce {
+			System::account_nonce(account)
+		}
+	}
+
+	impl apis::GenesisBuilder<Block> for Runtime {
+		fn build_state(config: Vec<u8>) -> GenesisBuilderResult {
+			build_state::<RuntimeGenesisConfig>(config)
+		}
+
+		fn get_preset(id: &Option<PresetId>) -> Option<Vec<u8>> {
+			get_preset::<RuntimeGenesisConfig>(id, self::genesis_config_presets::get_preset)
+		}
+
+		fn preset_names() -> Vec<PresetId> {
+			crate::genesis_config_presets::preset_names()
+		}
+	}
+
+	impl pallet_transaction_payment_rpc_runtime_api::TransactionPaymentApi<
+		Block,
+		interface::Balance,
+	> for Runtime {
+		fn query_info(uxt: ExtrinsicFor<Runtime>, len: u32) -> RuntimeDispatchInfo<interface::Balance> {
+			TransactionPayment::query_info(uxt, len)
+		}
+		fn query_fee_details(uxt: ExtrinsicFor<Runtime>, len: u32) -> FeeDetails<interface::Balance> {
+			TransactionPayment::query_fee_details(uxt, len)
+		}
+		fn query_weight_to_fee(weight: Weight) -> interface::Balance {
+			TransactionPayment::weight_to_fee(weight)
+		}
+		fn query_length_to_fee(length: u32) -> interface::Balance {
+			TransactionPayment::length_to_fee(length)
+		}
+	}
+}
+
+/// Just a handy re-definition of some types based on what is already provided to the pallet
+/// configs.
+pub mod interface {
+	use super::Runtime;
+	use frame::prelude::frame_system;
+
+	pub type AccountId = <Runtime as frame_system::Config>::AccountId;
+	pub type Nonce = <Runtime as frame_system::Config>::Nonce;
+	pub type Hash = <Runtime as frame_system::Config>::Hash;
+	pub type Balance = <Runtime as pallet_balances::Config>::Balance;
+	pub type MinimumBalance = <Runtime as pallet_balances::Config>::ExistentialDeposit;
+}
@@ -0,0 +1,14 @@
+//! # External Resources
+//!
+//! A non-exhaustive, un-opinionated list of external resources about Pezkuwi SDK.
+//!
+//! Unlike [`crate::guides`], or [`crate::pezkuwi_sdk::templates`] that contain material directly
+//! maintained in the `pezkuwi-sdk` repository, the list of resources here are maintained by
+//! third-parties, and are therefore subject to more variability. Any further resources may be added
+//! by opening a pull request to the `pezkuwi-sdk` repository.
+//!
+//! - [Pezkuwi NFT Marketplace Tutorial by Pezkuwi Fellow Shawn Tabrizi](https://www.shawntabrizi.com/substrate-collectables-workshop/)
+//! - [HEZ Code School](https://dotcodeschool.com/)
+//! - [Pezkuwi Developers Github Organization](https://github.com/polkadot-developers/)
+//! - [Pezkuwi Blockchain Academy](https://github.com/pezkuwichain/kurdistan_blockchain-akademy)
+//! - [Pezkuwi Wiki](https://wiki.network.pezkuwichain.io/)
@@ -0,0 +1,254 @@
+//! # Upgrade Teyrchain for Asynchronous Backing Compatibility
+//!
+//! This guide is relevant for cumulus based teyrchain projects started in 2023 or before, whose
+//! backing process is synchronous where parablocks can only be built on the latest Relay Chain
+//! block. Async Backing allows collators to build parablocks on older Relay Chain blocks and create
+//! pipelines of multiple pending parablocks. This parallel block generation increases efficiency
+//! and throughput. For more information on Async backing and its terminology, refer to the document
+//! on [the Pezkuwi SDK docs.](https://docs.pezkuwichain.io/sdk/master/polkadot_sdk_docs/guides/async_backing_guide/index.html)
+//!
+//! > If starting a new teyrchain project, please use an async backing compatible template such as
+//! > the
+//! > [teyrchain template](https://github.com/pezkuwichain/pezkuwi-sdk/tree/master/templates/teyrchain).
+//! The rollout process for Async Backing has three phases. Phases 1 and 2 below put new
+//! infrastructure in place. Then we can simply turn on async backing in phase 3.
+//!
+//! ## Prerequisite
+//!
+//! The relay chain needs to have async backing enabled so double-check that the relay-chain
+//! configuration contains the following three parameters (especially when testing locally e.g. with
+//! zombienet):
+//!
+//! ```json
+//! "async_backing_params": {
+//!     "max_candidate_depth": 3,
+//!     "allowed_ancestry_len": 2
+//! },
+//! "scheduling_lookahead": 2
+//! ```
+//!
+//! <div class="warning"><code>scheduling_lookahead</code> must be set to 2, otherwise teyrchain
+//! block times will degrade to worse than with sync backing!</div>
+//!
+//! ## Phase 1 - Update Teyrchain Runtime
+//!
+//! This phase involves configuring your teyrchain’s runtime `/runtime/src/lib.rs` to make use of
+//! async backing system.
+//!
+//! 1. Establish and ensure constants for `capacity` and `velocity` are both set to 1 in the
+//!    runtime.
+//! 2. Establish and ensure the constant relay chain slot duration measured in milliseconds equal to
+//!    `6000` in the runtime.
+//! ```rust
+//! // Maximum number of blocks simultaneously accepted by the Runtime, not yet included into the
+//! // relay chain.
+//! pub const UNINCLUDED_SEGMENT_CAPACITY: u32 = 1;
+//! // How many teyrchain blocks are processed by the relay chain per parent. Limits the number of
+//! // blocks authored per slot.
+//! pub const BLOCK_PROCESSING_VELOCITY: u32 = 1;
+//! // Relay chain slot duration, in milliseconds.
+//! pub const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000;
+//! ```
+//!
+//! 3. Establish constants `MILLISECS_PER_BLOCK` and `SLOT_DURATION` if not already present in the
+//!    runtime.
+//! ```ignore
+//! // `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked
+//! // up by `pallet_aura` to implement `fn slot_duration()`.
+//! //
+//! // Change this to adjust the block time.
+//! pub const MILLISECS_PER_BLOCK: u64 = 12000;
+//! pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK;
+//! ```
+//!
+//! 4. Configure `cumulus_pallet_teyrchain_system` in the runtime.
+//!
+//! - Define a `FixedVelocityConsensusHook` using our capacity, velocity, and relay slot duration
+//! constants. Use this to set the teyrchain system `ConsensusHook` property.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", ConsensusHook)]
+//! ```ignore
+//! impl cumulus_pallet_teyrchain_system::Config for Runtime {
+//!     ..
+//!     type ConsensusHook = ConsensusHook;
+//!     ..
+//! }
+//! ```
+//! - Set the teyrchain system property `CheckAssociatedRelayNumber` to
+//! `RelayNumberMonotonicallyIncreases`
+//! ```ignore
+//! impl cumulus_pallet_teyrchain_system::Config for Runtime {
+//! 	..
+//! 	type CheckAssociatedRelayNumber = RelayNumberMonotonicallyIncreases;
+//! 	..
+//! }
+//! ```
+//!
+//! 5. Configure `pallet_aura` in the runtime.
+//!
+//! - Set `AllowMultipleBlocksPerSlot` to `false` (don't worry, we will set it to `true` when we
+//! activate async backing in phase 3).
+//!
+//! - Define `pallet_aura::SlotDuration` using our constant `SLOT_DURATION`
+//! ```ignore
+//! impl pallet_aura::Config for Runtime {
+//! 	..
+//! 	type AllowMultipleBlocksPerSlot = ConstBool<false>;
+//! 	#[cfg(feature = "experimental")]
+//! 	type SlotDuration = ConstU64<SLOT_DURATION>;
+//! 	..
+//! }
+//! ```
+//!
+//! 6. Update `sp_consensus_aura::AuraApi::slot_duration` in `sp_api::impl_runtime_apis` to match
+//!    the constant `SLOT_DURATION`
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/apis.rs", impl_slot_duration)]
+//!
+//! 7. Implement the `AuraUnincludedSegmentApi`, which allows the collator client to query its
+//!    runtime to determine whether it should author a block.
+//!
+//!    - Add the dependency `cumulus-primitives-aura` to the `runtime/Cargo.toml` file for your
+//!      runtime
+//! ```ignore
+//! ..
+//! cumulus-primitives-aura = { path = "../../../../primitives/aura", default-features = false }
+//! ..
+//! ```
+//!
+//! - In the same file, add `"cumulus-primitives-aura/std",` to the `std` feature.
+//!
+//! - Inside the `impl_runtime_apis!` block for your runtime, implement the
+//!   `cumulus_primitives_aura::AuraUnincludedSegmentApi` as shown below.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/apis.rs", impl_can_build_upon)]
+//!
+//! **Note:** With a capacity of 1 we have an effective velocity of ½ even when velocity is
+//! configured to some larger value. This is because capacity will be filled after a single block is
+//! produced and will only be freed up after that block is included on the relay chain, which takes
+//! 2 relay blocks to accomplish. Thus with capacity 1 and velocity 1 we get the customary 12 second
+//! teyrchain block time.
+//!
+//! 8. If your `runtime/src/lib.rs` provides a `CheckInherents` type to `register_validate_block`,
+//!    remove it. `FixedVelocityConsensusHook` makes it unnecessary. The following example shows how
+//!    `register_validate_block` should look after removing `CheckInherents`.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", register_validate_block)]
+//!
+//!
+//! ## Phase 2 - Update Teyrchain Nodes
+//!
+//! This phase consists of plugging in the new lookahead collator node.
+//!
+//! 1. Import `cumulus_primitives_core::ValidationCode` to `node/src/service.rs`.
+#![doc = docify::embed!("../../templates/teyrchain/node/src/service.rs", cumulus_primitives)]
+//!
+//! 2. In `node/src/service.rs`, modify `sc_service::spawn_tasks` to use a clone of `Backend` rather
+//!    than the original
+//! ```ignore
+//! sc_service::spawn_tasks(sc_service::SpawnTasksParams {
+//!     ..
+//!     backend: backend.clone(),
+//!     ..
+//! })?;
+//! ```
+//!
+//! 3. Add `backend` as a parameter to `start_consensus()` in `node/src/service.rs`
+//! ```text
+//! fn start_consensus(
+//!     ..
+//!     backend: Arc<TeyrchainBackend>,
+//!     ..
+//! ```
+//! ```ignore
+//! if validator {
+//!   start_consensus(
+//!     ..
+//!     backend.clone(),
+//!     ..
+//!    )?;
+//! }
+//! ```
+//!
+//! 4. In `node/src/service.rs` import the lookahead collator rather than the basic collator
+#![doc = docify::embed!("../../templates/teyrchain/node/src/service.rs", lookahead_collator)]
+//!
+//! 5. In `start_consensus()` replace the `BasicAuraParams` struct with `AuraParams`
+//!    - Change the struct type from `BasicAuraParams` to `AuraParams`
+//!    - In the `para_client` field, pass in a cloned para client rather than the original
+//!    - Add a `para_backend` parameter after `para_client`, passing in our para backend
+//!    - Provide a `code_hash_provider` closure like that shown below
+//!    - Increase `authoring_duration` from 500 milliseconds to 2000
+//! ```ignore
+//! let params = AuraParams {
+//!     ..
+//!     para_client: client.clone(),
+//!     para_backend: backend.clone(),
+//!     ..
+//!     code_hash_provider: move |block_hash| {
+//!         client.code_at(block_hash).ok().map(|c| ValidationCode::from(c).hash())
+//!     },
+//!     ..
+//!     authoring_duration: Duration::from_millis(2000),
+//!     ..
+//! };
+//! ```
+//!
+//! **Note:** Set `authoring_duration` to whatever you want, taking your own hardware into account.
+//! But if the backer who should be slower than you due to reading from disk, times out at two
+//! seconds your candidates will be rejected.
+//!
+//! 6. In `start_consensus()` replace `basic_aura::run` with `aura::run`
+//! ```ignore
+//! let fut =
+//! aura::run::<Block, sp_consensus_aura::sr25519::AuthorityPair, _, _, _, _, _, _, _, _, _>(
+//!    params,
+//! );
+//! task_manager.spawn_essential_handle().spawn("aura", None, fut);
+//! ```
+//!
+//! ## Phase 3 - Activate Async Backing
+//!
+//! This phase consists of changes to your teyrchain’s runtime that activate async backing feature.
+//!
+//! 1. Configure `pallet_aura`, setting `AllowMultipleBlocksPerSlot` to true in
+//!    `runtime/src/lib.rs`.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/configs/mod.rs", aura_config)]
+//!
+//! 2. Increase the maximum `UNINCLUDED_SEGMENT_CAPACITY` in `runtime/src/lib.rs`.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", async_backing_params)]
+//!
+//! 3. Decrease `MILLISECS_PER_BLOCK` to 6000.
+//!
+//! - Note: For a teyrchain which measures time in terms of its own block number rather than by
+//!   relay block number it may be preferable to increase velocity. Changing block time may cause
+//!   complications, requiring additional changes. See the section “Timing by Block Number”.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", block_times)]
+//!
+//! 4. Update `MAXIMUM_BLOCK_WEIGHT` to reflect the increased time available for block production.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", max_block_weight)]
+//!
+//! 5. Add a feature flagged alternative for `MinimumPeriod` in `pallet_timestamp`. The type should
+//!    be `ConstU64<0>` with the feature flag experimental, and `ConstU64<{SLOT_DURATION / 2}>`
+//!    without.
+//! ```ignore
+//! impl pallet_timestamp::Config for Runtime {
+//!     ..
+//!     #[cfg(feature = "experimental")]
+//!     type MinimumPeriod = ConstU64<0>;
+//!     #[cfg(not(feature = "experimental"))]
+//!     type MinimumPeriod = ConstU64<{ SLOT_DURATION / 2 }>;
+//!     ..
+//! }
+//! ```
+//!
+//! ## Timing by Block Number
+//!
+//! With asynchronous backing it will be possible for teyrchains to opt for a block time of 6
+//! seconds rather than 12 seconds. But modifying block duration isn’t so simple for a teyrchain
+//! which was measuring time in terms of its own block number. It could result in expected and
+//! actual time not matching up, stalling the teyrchain.
+//!
+//! One strategy to deal with this issue is to instead rely on relay chain block numbers for timing.
+//! Relay block number is kept track of by each teyrchain in `pallet-teyrchain-system` with the
+//! storage value `LastRelayChainBlockNumber`. This value can be obtained and used wherever timing
+//! based on block number is needed.
+
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::private_intra_doc_links)]
@@ -0,0 +1 @@
+//! # Changing Consensus
@@ -0,0 +1 @@
+//! # Cumulus Enabled Teyrchain
@@ -0,0 +1,182 @@
+//! # Enable elastic scaling for a teyrchain
+//!
+//! <div class="warning">This guide assumes full familiarity with Asynchronous Backing and its
+//! terminology, as defined in <a href="https://docs.pezkuwichain.io/sdk/master/polkadot_sdk_docs/guides/async_backing_guide/index.html">the Pezkuwi SDK Docs</a>.
+//! </div>
+//!
+//! ## Quick introduction to Elastic Scaling
+//!
+//! [Elastic scaling](https://www.parity.io/blog/polkadot-web3-cloud) is a feature that enables teyrchains (rollups) to use multiple cores.
+//! Teyrchains can adjust their usage of core resources on the fly to increase TPS and decrease
+//! latency.
+//!
+//! ### When do you need Elastic Scaling?
+//!
+//! Depending on their use case, applications might have an increased need for the following:
+//! - compute (CPU weight)
+//! - bandwidth (proof size)
+//! - lower latency (block time)
+//!
+//! ### High throughput (TPS) and lower latency
+//!
+//! If the main bottleneck is the CPU, then your teyrchain needs to maximize the compute usage of
+//! each core while also achieving a lower latency.
+//! 3 cores provide the best balance between CPU, bandwidth and latency: up to 6s of execution,
+//! 5MB/s of DA bandwidth and fast block time of just 2 seconds.
+//!
+//! ### High bandwidth
+//!
+//! Useful for applications that are bottlenecked by bandwidth.
+//! By using 6 cores, applications can make use of up to 6s of compute, 10MB/s of bandwidth
+//! while also achieving 1 second block times.
+//!
+//! ### Ultra low latency
+//!
+//! When latency is the primary requirement, Elastic scaling is currently the only solution. The
+//! caveat is the efficiency of core time usage decreases as more cores are used.
+//!
+//! For example, using 12 cores enables fast transaction confirmations with 500ms blocks and up to
+//! 20 MB/s of DA bandwidth.
+//!
+//! ## Dependencies
+//!
+//! Prerequisites: Pezkuwi-SDK `2509` or newer.
+//!
+//! To ensure the security and reliability of your chain when using this feature you need the
+//! following:
+//! - An omni-node based collator. This has already become the default choice for collators.
+//! - UMP signal support.
+//! [RFC103](https://github.com/polkadot-fellows/RFCs/blob/main/text/0103-introduce-core-index-commitment.md).
+//!   This is mandatory protection against PoV replay attacks.
+//! - Enabling the relay parent offset feature. This is required to ensure the teyrchain block times
+//!   and transaction in-block confidence are not negatively affected by relay chain forks. Read
+//!   [`crate::guides::handling_teyrchain_forks`] for more information.
+//! - Block production configuration adjustments.
+//!
+//! ### Upgrade to Pezkuwi Omni node
+//!
+//! Your collators need to run `pezkuwi-teyrchain` or `pezkuwi-omni-node` with the `--authoring
+//! slot-based` CLI argument.
+//! To avoid potential issues and get best performance it is recommeneded to always run the  
+//! latest release on all of the collators.
+//!
+//! Further information about omni-node and how to upgrade is available:
+//! - [high level docs](https://docs.pezkuwichain.io/develop/toolkit/parachains/polkadot-omni-node/)
+//! - [`crate::reference_docs::omni_node`]
+//!
+//! ### UMP signals
+//!
+//! UMP signals are now enabled by default in the `teyrchain-system` pallet and are used for
+//! elastic scaling. You can find more technical details about UMP signals and their usage for
+//! elastic scaling
+//! [here](https://github.com/polkadot-fellows/RFCs/blob/main/text/0103-introduce-core-index-commitment.md).
+//!
+//! ### Enable the relay parent offset feature
+//!
+//! It is recommended to use an offset of `1`, which is sufficient to eliminate any issues
+//! with relay chain forks.
+//!
+//! Configure the relay parent offset like this:
+//! ```ignore
+//!     /// Build with an offset of 1 behind the relay chain best block.
+//!     const RELAY_PARENT_OFFSET: u32 = 1;
+//!
+//!     impl cumulus_pallet_teyrchain_system::Config for Runtime {
+//!         // ...
+//!         type RelayParentOffset = ConstU32<RELAY_PARENT_OFFSET>;
+//!     }
+//! ```
+//!
+//! Implement the runtime API to retrieve the offset on the client side.
+//! ```ignore
+//!     impl cumulus_primitives_core::RelayParentOffsetApi<Block> for Runtime {
+//!         fn relay_parent_offset() -> u32 {
+//!             RELAY_PARENT_OFFSET
+//!         }
+//!     }
+//! ```
+//!
+//! ### Block production configuration
+//!
+//! This configuration directly controls the minimum block time and maximum number of cores
+//! the teyrchain can use.
+//!
+//! Example configuration for a 3 core teyrchain:
+//!  ```ignore
+//!     /// The upper limit of how many teyrchain blocks are processed by the relay chain per
+//!     /// parent. Limits the number of blocks authored per slot. This determines the minimum
+//!     /// block time of the teyrchain:
+//!     /// `RELAY_CHAIN_SLOT_DURATION_MILLIS/BLOCK_PROCESSING_VELOCITY`
+//!     const BLOCK_PROCESSING_VELOCITY: u32 = 3;
+//!
+//!     /// Maximum number of blocks simultaneously accepted by the Runtime, not yet included
+//!     /// into the relay chain.
+//!     const UNINCLUDED_SEGMENT_CAPACITY: u32 = (2 + RELAY_PARENT_OFFSET) *
+//! BLOCK_PROCESSING_VELOCITY + 1;
+//!
+//!     /// Relay chain slot duration, in milliseconds.
+//!     const RELAY_CHAIN_SLOT_DURATION_MILLIS: u32 = 6000;
+//!
+//!     type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook<
+//!         Runtime,
+//!         RELAY_CHAIN_SLOT_DURATION_MILLIS,
+//!         BLOCK_PROCESSING_VELOCITY,
+//!         UNINCLUDED_SEGMENT_CAPACITY,
+//!     >;
+//!
+//!  ```
+//!
+//! ### Teyrchain Slot Duration
+//!
+//! A common source of confusion is the correct configuration of the `SlotDuration` that is passed
+//! to `pallet-aura`.
+//! ```ignore
+//! impl pallet_aura::Config for Runtime {
+//!     // ...
+//!     type SlotDuration = ConstU64<SLOT_DURATION>;
+//! }
+//! ```
+//!
+//! The slot duration determines the length of each author's turn and is decoupled from the block
+//! production interval. During their slot, authors are allowed to produce multiple blocks. **The
+//! slot duration is required to be at least 6s (same as on the relay chain).**
+//!
+//! **Configuration recommendations:**
+//! - For new teyrchains starting from genesis: use a slot duration of 24 seconds
+//! - For existing live teyrchains: leave the slot duration unchanged
+//!
+//!
+//! ## Current limitations
+//!
+//! ### Maximum execution time per relay chain block.
+//!
+//! Since teyrchain block authoring is sequential, the next block can only be built after
+//! the previous one has been imported.
+//! At present, a core allows up to 2 seconds of execution per relay chain block.
+//!
+//! If we assume a 6s teyrchain slot, and each block takes the full 2 seconds to execute,
+//! the teyrchain will not be able to fully utilize the compute resources of all 3 cores.
+//!    
+//! If the collator hardware is faster, it can author and import full blocks more quickly,
+//! making it possible to utilize even more than 3 cores efficiently.
+//!
+//! #### Why?
+//!
+//! Within a 6-second teyrchain slot, collators can author multiple teyrchain blocks.
+//! Before building the first block in a slot, the new block author must import the last
+//! block produced by the previous author.
+//! If the import of the last block is not completed before the next relay chain slot starts,
+//! the new author will build on its parent (assuming it was imported). This will create a fork
+//! which degrades the teyrchain block confidence and block times.
+//!
+//! This means that, on reference hardware, a teyrchain with a slot time of 6s can
+//! effectively utilize up to 4 seconds of execution per relay chain block, because it needs to
+//! ensure the next block author has enough time to import the last block.
+//! Hardware with higher single-core performance can enable a teyrchain to fully utilize more
+//! cores.
+//!
+//! ### Fixed factor scaling.
+//!
+//! For true elasticity, a teyrchain needs to acquire more cores when needed in an automated
+//! manner. This functionality is not yet available in the SDK, thus acquiring additional
+//! on-demand or bulk cores has to be managed externally.
@@ -0,0 +1,88 @@
+//! # Enable metadata hash verification
+//!
+//! This guide will teach you how to enable the metadata hash verification in your runtime.
+//!
+//! ## What is metadata hash verification?
+//!
+//! Each FRAME based runtime exposes metadata about itself. This metadata is used by consumers of
+//! the runtime to interpret the state, to construct transactions etc. Part of this metadata are the
+//! type information. These type information can be used to e.g. decode storage entries or to decode
+//! a transaction. So, the metadata is quite useful for wallets to interact with a FRAME based
+//! chain. Online wallets can fetch the metadata directly from any node of the chain they are
+//! connected to, but offline wallets can not do this. So, for the offline wallet to have access to
+//! the metadata it needs to be transferred and stored on the device. The problem is that the
+//! metadata has a size of several hundreds of kilobytes, which takes quite a while to transfer to
+//! these offline wallets and the internal storage of these devices is also not big enough to store
+//! the metadata for one or more networks. The next problem is that the offline wallet/user can not
+//! trust the metadata to be correct. It is very important for the metadata to be correct or
+//! otherwise an attacker could change them in a way that the offline wallet decodes a transaction
+//! in a different way than what it will be decoded to on chain. So, the user may sign an incorrect
+//! transaction leading to unexpected behavior.
+//!
+//! The metadata hash verification circumvents the issues of the huge metadata and the need to trust
+//! some metadata blob to be correct. To generate a hash for the metadata, the metadata is chunked,
+//! these chunks are put into a merkle tree and then the root of this merkle tree is the "metadata
+//! hash". For a more technical explanation on how it works, see
+//! [RFC78](https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html). At compile
+//! time the metadata hash is generated and "baked" into the runtime. This makes it extremely cheap
+//! for the runtime to verify on chain that the metadata hash is correct. By having the runtime
+//! verify the hash on chain, the user also doesn't need to trust the offchain metadata. If the
+//! metadata hash doesn't match the on chain metadata hash the transaction will be rejected. The
+//! metadata hash itself is added to the data of the transaction that is signed, this means the
+//! actual hash does not appear in the transaction. On chain the same procedure is repeated with the
+//! metadata hash that is known by the runtime and if the metadata hash doesn't match the signature
+//! verification will fail. As the metadata hash is actually the root of a merkle tree, the offline
+//! wallet can get proofs of individual types to decode a transaction. This means that the offline
+//! wallet does not require the entire metadata to be present on the device.
+//!
+//! ## Integrating metadata hash verification into your runtime
+//!
+//! The integration of the metadata hash verification is split into two parts, first the actual
+//! integration into the runtime and secondly the enabling of the metadata hash generation at
+//! compile time.
+//!
+//! ### Runtime integration
+//!
+//! From the runtime side only the
+//! [`CheckMetadataHash`](frame_metadata_hash_extension::CheckMetadataHash) needs to be added to the
+//! list of signed extension:
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", template_signed_extra)]
+//!
+//! > **Note:**
+//! >
+//! > Adding the signed extension changes the encoding of the transaction and adds one extra byte
+//! > per transaction!
+//!
+//! This signed extension will make sure to decode the requested `mode` and will add the metadata
+//! hash to the signed data depending on the requested `mode`. The `mode` gives the user/wallet
+//! control over deciding if the metadata hash should be verified or not. The metadata hash itself
+//! is drawn from the `RUNTIME_METADATA_HASH` environment variable. If the environment variable is
+//! not set, any transaction that requires the metadata hash is rejected with the error
+//! `CannotLookup`. This is a security measurement to prevent including invalid transactions.
+//!
+//! <div class="warning">
+//!
+//! The extension does not work with the native runtime, because the
+//! `RUNTIME_METADATA_HASH` environment variable is not set when building the
+//! `frame-metadata-hash-extension` crate.
+//!
+//! </div>
+//!
+//! ### Enable metadata hash generation
+//!
+//! The metadata hash generation needs to be enabled when building the wasm binary. The
+//! `substrate-wasm-builder` supports this out of the box:
+#![doc = docify::embed!("../../templates/teyrchain/runtime/build.rs", template_enable_metadata_hash)]
+//!
+//! > **Note:**
+//! >
+//! > The `metadata-hash` feature needs to be enabled for the `substrate-wasm-builder` to enable the
+//! > code for being able to generate the metadata hash. It is also recommended to put the metadata
+//! > hash generation behind a feature in the runtime as shown above. The reason behind is that it
+//! > adds a lot of code which increases the compile time and the generation itself also increases
+//! > the compile time. Thus, it is recommended to enable the feature only when the metadata hash is
+//! > required (e.g. for an on-chain build).
+//!
+//! The two parameters to `enable_metadata_hash` are the token symbol and the number of decimals of
+//! the primary token of the chain. These information are included for the wallets to show token
+//! related operations in a more user friendly way.
@@ -0,0 +1,88 @@
+//! # Enable storage weight reclaiming
+//!
+//! This guide will teach you how to enable storage weight reclaiming for a teyrchain. The
+//! explanations in this guide assume a project structure similar to the one detailed in
+//! the [substrate documentation](crate::pezkuwi_sdk::substrate#anatomy-of-a-binary-crate). Full
+//! technical details are available in the original [pull request](https://github.com/paritytech/polkadot-sdk/pull/3002).
+//!
+//! # What is PoV reclaim?
+//! When a teyrchain submits a block to a relay chain like Pezkuwi or Kusama, it sends the block
+//! itself and a storage proof. Together they form the Proof-of-Validity (PoV). The PoV allows the
+//! relay chain to validate the teyrchain block by re-executing it. Relay chain
+//! validators distribute this PoV among themselves over the network. This distribution is costly
+//! and limits the size of the storage proof. The storage weight dimension of FRAME weights reflects
+//! this cost and limits the size of the storage proof. However, the storage weight determined
+//! during [benchmarking](crate::reference_docs::frame_benchmarking_weight) represents the worst
+//! case. In reality, runtime operations often consume less space in the storage proof. PoV reclaim
+//! offers a mechanism to reclaim the difference between the benchmarked worst-case and the real
+//! proof-size consumption.
+//!
+//!
+//! # How to enable PoV reclaim
+//! ## 1. Add the host function to your node
+//!
+//! To reclaim excess storage weight, a teyrchain runtime needs the
+//! ability to fetch the size of the storage proof from the node. The reclaim
+//! mechanism uses the
+//! [`storage_proof_size`](cumulus_primitives_proof_size_hostfunction::storage_proof_size)
+//! host function for this purpose. For convenience, cumulus provides
+//! [`TeyrchainHostFunctions`](cumulus_client_service::TeyrchainHostFunctions), a set of
+//! host functions typically used by cumulus-based teyrchains. In the binary crate of your
+//! teyrchain, find the instantiation of the [`WasmExecutor`](sc_executor::WasmExecutor) and set the
+//! correct generic type.
+//!
+//! This example from the teyrchain-template shows a type definition that includes the correct
+//! host functions.
+#![doc = docify::embed!("../../templates/teyrchain/node/src/service.rs", wasm_executor)]
+//!
+//! > **Note:**
+//! >
+//! > If you see error `runtime requires function imports which are not present on the host:
+//! > 'env:ext_storage_proof_size_storage_proof_size_version_1'`, it is likely
+//! > that this step in the guide was not set up correctly.
+//!
+//! ## 2. Enable storage proof recording during import
+//!
+//! The reclaim mechanism reads the size of the currently recorded storage proof multiple times
+//! during block authoring and block import. Proof recording during authoring is already enabled on
+//! teyrchains. You must also ensure that storage proof recording is enabled during block import.
+//! Find where your node builds the fundamental substrate components by calling
+//! [`new_full_parts`](sc_service::new_full_parts). Replace this
+//! with [`new_full_parts_record_import`](sc_service::new_full_parts_record_import) and
+//! pass `true` as the last parameter to enable import recording.
+#![doc = docify::embed!("../../templates/teyrchain/node/src/service.rs", component_instantiation)]
+//!
+//! > **Note:**
+//! >
+//! > If you see error `Storage root must match that calculated.` during block import, it is likely
+//! > that this step in the guide was not
+//! > set up correctly.
+//!
+//! ## 3. Add the TransactionExtension to your runtime
+//!
+//! In your runtime, you will find a list of TransactionExtensions.
+//! To enable the reclaiming,
+//! set [`StorageWeightReclaim`](cumulus_pallet_weight_reclaim::StorageWeightReclaim)
+//! as a warpper of that list.
+//! It is necessary that this extension wraps all the other transaction extensions in order to catch
+//! the whole PoV size of the transactions.
+//! The extension will check the size of the storage proof before and after an extrinsic execution.
+//! It reclaims the difference between the calculated size and the benchmarked size.
+#![doc = docify::embed!("../../templates/teyrchain/runtime/src/lib.rs", template_signed_extra)]
+//!
+//! ## Optional: Verify that reclaim works
+//!
+//! Start your node with the log target `runtime::storage_reclaim` set to `trace` to enable full
+//! logging for `StorageWeightReclaim`. The following log is an example from a local testnet. To
+//! trigger the log, execute any extrinsic on the network.
+//!
+//! ```ignore
+//! ...
+//! 2024-04-22 17:31:48.014 TRACE runtime::storage_reclaim: [ferdie] Reclaiming storage weight. benchmarked: 3593, consumed: 265 unspent: 0
+//! ...
+//! ```
+//!
+//! In the above example we see a benchmarked size of 3593 bytes, while the extrinsic only consumed
+//! 265 bytes of proof size. This results in 3328 bytes of reclaim.
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::private_intra_doc_links)]
@@ -0,0 +1,90 @@
+//! # Teyrchain forks
+//!
+//! In this guide, we will examine how AURA-based teyrchains handle forks. AURA (Authority Round) is
+//! a consensus mechanism where block authors rotate at fixed time intervals. Each author gets a
+//! predetermined time slice during which they are allowed to author a block. On its own, this
+//! mechanism is fork-free.
+//!
+//! However, since the relay chain provides security and serves as the source of truth for
+//! teyrchains, the teyrchain is dependent on it. This relationship can introduce complexities that
+//! lead to forking scenarios.
+//!
+//! ## Background
+//! Each teyrchain block has a relay parent, which is a relay chain block that provides context to
+//! our teyrchain block. The constraints the relay chain imposes on our teyrchain can cause forks
+//! under certain conditions. With asynchronous-backing enabled chains, the node side is building
+//! blocks on all relay chain forks. This means that no matter which fork of the relay chain
+//! ultimately progressed, the teyrchain would have a block ready for that fork. The situation
+//! changes when teyrchains want to produce blocks at a faster cadence. In a scenario where a
+//! teyrchain might author on 3 cores with elastic scaling, it is not possible to author on all
+//! relay chain forks. The time constraints do not allow it. Building on two forks would result in 6
+//! blocks. The authoring of these blocks would consume more time than we have available before the
+//! next relay chain block arrives. This limitation requires a more fork-resistant approach to
+//! block-building.
+//!
+//! ## Impact of Forks
+//! When a relay chain fork occurs and the teyrchain builds on a fork that will not be extended in
+//! the future, the blocks built on that fork are lost and need to be rebuilt. This increases
+//! latency and reduces throughput, affecting the overall performance of the teyrchain.
+//!
+//! # Building on Older Pelay Parents
+//! Cumulus offers a way to mitigate the occurence of forks. Instead of picking a block at the tip
+//! of the relay chain to build blocks, the node side can pick a relay chain block that is older. By
+//! building on 12s old relay chain blocks, forks will already have settled and the teyrchain can
+//! build fork-free.
+//!
+//! ```text
+//! Without offset:
+//! Relay Chain:    A --- B --- C --- D  --- E
+//!                              \
+//!                               --- D' --- E'
+//! Teyrchain:            X --- Y --- ? (builds on both D and D', wasting resources)
+//!
+//! With offset (2 blocks):
+//! Relay Chain:    A --- B --- C --- D  --- E
+//!                              \
+//!                               --- D' --- E'
+//! Teyrchain:            X(A) - Y (B) - Z (on C, fork already resolved)
+//! ```
+//! **Note:** It is possible that relay chain forks extend over more than 1-2 blocks. However, it is
+//! unlikely.
+//! ## Tradeoffs
+//! Fork-free teyrchains come with a few tradeoffs:
+//! - The latency of incoming XCM messages will be delayed by `N * 6s`, where `N` is the number of
+//!   relay chain blocks we want to offset by. For example, by building 2 relay chain blocks behind
+//!   the tip, the XCM latency will be increased by 12 seconds.
+//! - The available PoV space will be slightly reduced. Assuming a 10mb PoV, teyrchains need to be
+//!   ready to sacrifice around 0.5% of PoV space.
+//!
+//! ## Enabling Guide
+//! The decision whether the teyrchain should build on older relay parents is embedded into the
+//! runtime. After the changes are implemented, the runtime will enforce that no author can build
+//! with an offset smaller than the desired offset. If you wish to keep your current teyrchain
+//! behaviour and do not want aforementioned tradeoffs, set the offset to 0.
+//!
+//! **Note:** The APIs mentioned here are available in `pezkuwi-sdk` versions after `stable-2506`.
+//!
+//! 1. Define the relay parent offset your teyrchain should respect in the runtime.
+//! ```ignore
+//! const RELAY_PARENT_OFFSET = 2;
+//! ```
+//! 2. Pass this constant to the `teyrchain-system` pallet.
+//!
+//! ```ignore
+//! impl cumulus_pallet_teyrchain_system::Config for Runtime {
+//! 	// Other config items here
+//!     ...
+//! 	type RelayParentOffset = ConstU32<RELAY_PARENT_OFFSET>;
+//! }
+//! ```
+//! 3. Implement the `RelayParentOffsetApi` runtime API for your runtime.
+//!
+//! ```ignore
+//! impl cumulus_primitives_core::RelayParentOffsetApi<Block> for Runtime {
+//!     fn relay_parent_offset() -> u32 {
+//! 		RELAY_PARENT_OFFSET
+//! 	}
+//! }
+//! ```
+//! 4. Increase the `UNINCLUDED_SEGMENT_CAPICITY` for your runtime. It needs to be increased by
+//!    `RELAY_PARENT_OFFSET * BLOCK_PROCESSING_VELOCITY`.
@@ -0,0 +1,50 @@
+//! # Pezkuwi SDK Docs Guides
+//!
+//! This crate contains a collection of guides that are foundational to the developers of
+//! Pezkuwi SDK. They are common user-journeys that are traversed in the Pezkuwi ecosystem.
+//!
+//! The main user-journey covered by these guides is:
+//!
+//! * [`your_first_pallet`], where you learn what a FRAME pallet is, and write your first
+//!   application logic.
+//! * [`your_first_runtime`], where you learn how to compile your pallets into a WASM runtime.
+//! * [`your_first_node`], where you learn how to run the said runtime in a node.
+//!
+//! > By this step, you have already launched a full Pezkuwi-SDK-based blockchain!
+//!
+//! Once done, feel free to step up into one of our templates: [`crate::pezkuwi_sdk::templates`].
+//!
+//! [`your_first_pallet`]: crate::guides::your_first_pallet
+//! [`your_first_runtime`]: crate::guides::your_first_runtime
+//! [`your_first_node`]: crate::guides::your_first_node
+//!
+//! Other guides are related to other miscellaneous topics and are listed as modules below.
+
+/// Write your first simple pallet, learning the most most basic features of FRAME along the way.
+pub mod your_first_pallet;
+
+/// Write your first real [runtime](`crate::reference_docs::wasm_meta_protocol`),
+/// compiling it to [WASM](crate::pezkuwi_sdk::substrate#wasm-build).
+pub mod your_first_runtime;
+
+/// Running the given runtime with a node. No specific consensus mechanism is used at this stage.
+pub mod your_first_node;
+
+/// How to enhance a given runtime and node to be cumulus-enabled, run it as a teyrchain
+/// and connect it to a relay-chain.
+// pub mod your_first_teyrchain;
+
+/// How to enable storage weight reclaiming in a teyrchain node and runtime.
+pub mod enable_pov_reclaim;
+
+/// How to enable Async Backing on teyrchain projects that started in 2023 or before.
+pub mod async_backing_guide;
+
+/// How to enable metadata hash verification in the runtime.
+pub mod enable_metadata_hash;
+
+/// How to enable elastic scaling on a teyrchain.
+pub mod enable_elastic_scaling;
+
+/// How to parameterize teyrchain forking in relation to relay chain forking.
+pub mod handling_teyrchain_forks;
@@ -0,0 +1 @@
+//! # XCM Enabled Teyrchain
@@ -0,0 +1,342 @@
+//! # Your first Node
+//!
+//! In this guide, you will learn how to run a runtime, such as the one created in
+//! [`your_first_runtime`], in a node. Within the context of this guide, we will focus on running
+//! the runtime with an [`omni-node`]. Please first read this page to learn about the OmniNode, and
+//! other options when it comes to running a node.
+//!
+//! [`your_first_runtime`] is a runtime with no consensus related code, and therefore can only be
+//! executed with a node that also expects no consensus ([`sc_consensus_manual_seal`]).
+//! `pezkuwi-omni-node`'s [`--dev-block-time`] precisely does this.
+//!
+//! > All of the following steps are coded as unit tests of this module. Please see `Source` of the
+//! > page for more information.
+//!
+//! ## Running The Omni Node
+//!
+//! ### Installs
+//!
+//! The `pezkuwi-omni-node` can either be downloaded from the latest [Release](https://github.com/pezkuwichain/pezkuwi-sdk/releases/) of `pezkuwi-sdk`,
+//! or installed using `cargo`:
+//!
+//! ```text
+//! cargo install pezkuwi-omni-node
+//! ```
+//!
+//! Next, we need to install the `chain-spec-builder`. This is the tool that allows us to build
+//! chain-specifications, through interacting with the genesis related APIs of the runtime, as
+//! described in [`crate::guides::your_first_runtime#genesis-configuration`].
+//!
+//! ```text
+//! cargo install staging-chain-spec-builder
+//! ```
+//!
+//! > The name of the crate is prefixed with `staging` as the crate name `chain-spec-builder` on
+//! > crates.io is already taken and is not controlled by `pezkuwi-sdk` developers.
+//!
+//! ### Building Runtime
+//!
+//! Next, we need to build the corresponding runtime that we wish to interact with.
+//!
+//! ```text
+//! cargo build --release -p path-to-runtime
+//! ```
+//! Equivalent code in tests:
+#![doc = docify::embed!("./src/guides/your_first_runtime.rs", build_runtime)]
+//!
+//! This creates the wasm file under `./target/{release}/wbuild/release` directory.
+//!
+//! ### Building Chain Spec
+//!
+//! Next, we can generate the corresponding chain-spec file. For this example, we will use the
+//! `development` (`sp_genesis_config::DEVELOPMENT`) preset.
+//!
+//! Note that we intend to run this chain-spec with `pezkuwi-omni-node`, which is tailored for
+//! running teyrchains. This requires the chain-spec to always contain the `para_id` and a
+//! `relay_chain` fields, which are provided below as CLI arguments.
+//!
+//! ```text
+//! chain-spec-builder \
+//! 	-c <path-to-output> \
+//! 	create \
+//! 	--relay-chain dontcare \
+//! 	--runtime pezkuwi_sdk_docs_first_runtime.wasm \
+//! 	named-preset development
+//! ```
+//!
+//! Equivalent code in tests:
+#![doc = docify::embed!("./src/guides/your_first_node.rs", csb)]
+//!
+//!
+//! ### Running `pezkuwi-omni-node`
+//!
+//! Finally, we can run the node with the generated chain-spec file. We can also specify the block
+//! time using the `--dev-block-time` flag.
+//!
+//! ```text
+//! pezkuwi-omni-node \
+//! 	--tmp \
+//! 	--dev-block-time 1000 \
+//! 	--chain <chain_spec_file>.json
+//! ```
+//!
+//! > Note that we always prefer to use `--tmp` for testing, as it will save the chain state to a
+//! > temporary folder, allowing the chain-to be easily restarted without `purge-chain`. See
+//! > [`sc_cli::commands::PurgeChainCmd`] and [`sc_cli::commands::RunCmd::tmp`] for more info.
+//!
+//! This will start the node and import the blocks. Note while using `--dev-block-time`, the node
+//! will use the testing-specific manual-seal consensus. This is an efficient way to test the
+//! application logic of your runtime, without needing to yet care about consensus, block
+//! production, relay-chain and so on.
+//!
+//! ### Next Steps
+//!
+//! * See the rest of the steps in [`crate::reference_docs::omni_node#user-journey`].
+//!
+//! [`runtime`]: crate::reference_docs::glossary#runtime
+//! [`node`]: crate::reference_docs::glossary#node
+//! [`build_config`]: first_runtime::Runtime#method.build_config
+//! [`omni-node`]: crate::reference_docs::omni_node
+//! [`--dev-block-time`]: (pezkuwi_omni_node_lib::cli::Cli::dev_block_time)
+
+#[cfg(test)]
+mod tests {
+	use assert_cmd::assert::OutputAssertExt;
+	use cmd_lib::*;
+	use rand::Rng;
+	use sc_chain_spec::{DEV_RUNTIME_PRESET, LOCAL_TESTNET_RUNTIME_PRESET};
+	use sp_genesis_builder::PresetId;
+	use std::{
+		io::{BufRead, BufReader},
+		path::PathBuf,
+		process::{ChildStderr, Command, Stdio},
+		time::Duration,
+	};
+
+	const PARA_RUNTIME: &'static str = "teyrchain-template-runtime";
+	const CHAIN_SPEC_BUILDER: &'static str = "chain-spec-builder";
+	const OMNI_NODE: &'static str = "pezkuwi-omni-node";
+
+	fn cargo() -> Command {
+		Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_string()))
+	}
+
+	fn get_target_directory() -> Option<PathBuf> {
+		let output = cargo().arg("metadata").arg("--format-version=1").output().ok()?;
+
+		if !output.status.success() {
+			return None;
+		}
+
+		let metadata: serde_json::Value = serde_json::from_slice(&output.stdout).ok()?;
+		let target_directory = metadata["target_directory"].as_str()?;
+
+		Some(PathBuf::from(target_directory))
+	}
+
+	fn find_release_binary(name: &str) -> Option<PathBuf> {
+		let target_dir = get_target_directory()?;
+		let release_path = target_dir.join("release").join(name);
+
+		if release_path.exists() {
+			Some(release_path)
+		} else {
+			None
+		}
+	}
+
+	fn find_wasm(runtime_name: &str) -> Option<PathBuf> {
+		let target_dir = get_target_directory()?;
+		let wasm_path = target_dir
+			.join("release")
+			.join("wbuild")
+			.join(runtime_name)
+			.join(format!("{}.wasm", runtime_name.replace('-', "_")));
+
+		if wasm_path.exists() {
+			Some(wasm_path)
+		} else {
+			None
+		}
+	}
+
+	fn maybe_build_runtimes() {
+		if find_wasm(&PARA_RUNTIME).is_none() {
+			println!("Building teyrchain-template-runtime...");
+			Command::new("cargo")
+				.arg("build")
+				.arg("--release")
+				.arg("-p")
+				.arg(PARA_RUNTIME)
+				.assert()
+				.success();
+		}
+
+		assert!(find_wasm(PARA_RUNTIME).is_some());
+	}
+
+	fn maybe_build_chain_spec_builder() {
+		if find_release_binary(CHAIN_SPEC_BUILDER).is_none() {
+			println!("Building chain-spec-builder...");
+			Command::new("cargo")
+				.arg("build")
+				.arg("--release")
+				.arg("-p")
+				.arg("staging-chain-spec-builder")
+				.assert()
+				.success();
+		}
+		assert!(find_release_binary(CHAIN_SPEC_BUILDER).is_some());
+	}
+
+	fn maybe_build_omni_node() {
+		if find_release_binary(OMNI_NODE).is_none() {
+			println!("Building pezkuwi-omni-node...");
+			Command::new("cargo")
+				.arg("build")
+				.arg("--release")
+				.arg("-p")
+				.arg("pezkuwi-omni-node")
+				.assert()
+				.success();
+		}
+	}
+
+	async fn imported_block_found(stderr: ChildStderr, block: u64, timeout: u64) -> bool {
+		tokio::time::timeout(Duration::from_secs(timeout), async {
+			let want = format!("Imported #{}", block);
+			let reader = BufReader::new(stderr);
+			let mut found_block = false;
+			for line in reader.lines() {
+				if line.unwrap().contains(&want) {
+					found_block = true;
+					break;
+				}
+			}
+			found_block
+		})
+		.await
+		.unwrap()
+	}
+
+	async fn test_runtime_preset(
+		runtime: &'static str,
+		block_time: u64,
+		maybe_preset: Option<PresetId>,
+	) {
+		sp_tracing::try_init_simple();
+		maybe_build_runtimes();
+		maybe_build_chain_spec_builder();
+		maybe_build_omni_node();
+
+		let chain_spec_builder =
+			find_release_binary(&CHAIN_SPEC_BUILDER).expect("we built it above; qed");
+		let omni_node = find_release_binary(OMNI_NODE).expect("we built it above; qed");
+		let runtime_path = find_wasm(runtime).expect("we built it above; qed");
+
+		let random_seed: u32 = rand::thread_rng().gen();
+		let chain_spec_file = std::env::current_dir()
+			.unwrap()
+			.join(format!("{}_{}_{}.json", runtime, block_time, random_seed));
+
+		Command::new(chain_spec_builder)
+			.args(["-c", chain_spec_file.to_str().unwrap()])
+			.arg("create")
+			.args(["--relay-chain", "dontcare"])
+			.args(["-r", runtime_path.to_str().unwrap()])
+			.args(match maybe_preset {
+				Some(preset) => vec!["named-preset".to_string(), preset.to_string()],
+				None => vec!["default".to_string()],
+			})
+			.assert()
+			.success();
+
+		let mut child = Command::new(omni_node)
+			.arg("--tmp")
+			.args(["--chain", chain_spec_file.to_str().unwrap()])
+			.args(["--dev-block-time", block_time.to_string().as_str()])
+			.stderr(Stdio::piped())
+			.spawn()
+			.unwrap();
+
+		// Take stderr and parse it with timeout.
+		let stderr = child.stderr.take().unwrap();
+		let expected_blocks = (10_000 / block_time).saturating_div(2);
+		assert!(expected_blocks > 0, "test configuration is bad, should give it more time");
+		assert_eq!(imported_block_found(stderr, expected_blocks, 100).await, true);
+		std::fs::remove_file(chain_spec_file).unwrap();
+		child.kill().unwrap();
+	}
+
+	// Sets up omni-node to run a text exercise based on a chain spec.
+	async fn omni_node_test_setup(chain_spec_path: PathBuf) {
+		maybe_build_omni_node();
+		let omni_node = find_release_binary(OMNI_NODE).unwrap();
+
+		let mut child = Command::new(omni_node)
+			.arg("--dev")
+			.args(["--chain", chain_spec_path.to_str().unwrap()])
+			.stderr(Stdio::piped())
+			.spawn()
+			.unwrap();
+
+		let stderr = child.stderr.take().unwrap();
+		assert_eq!(imported_block_found(stderr, 7, 100).await, true);
+		child.kill().unwrap();
+	}
+
+	#[tokio::test]
+	async fn works_with_different_block_times() {
+		test_runtime_preset(PARA_RUNTIME, 100, Some(DEV_RUNTIME_PRESET.into())).await;
+		test_runtime_preset(PARA_RUNTIME, 3000, Some(DEV_RUNTIME_PRESET.into())).await;
+
+		// we need this snippet just for docs
+		#[docify::export_content(csb)]
+		fn build_teyrchain_spec_works() {
+			let chain_spec_builder = find_release_binary(&CHAIN_SPEC_BUILDER).unwrap();
+			let runtime_path = find_wasm(PARA_RUNTIME).unwrap();
+			let output = "/tmp/demo-chain-spec.json";
+			let runtime_str = runtime_path.to_str().unwrap();
+			run_cmd!(
+				$chain_spec_builder -c $output create --relay-chain dontcare -r $runtime_str named-preset development
+			).expect("Failed to run command");
+			std::fs::remove_file(output).unwrap();
+		}
+		build_teyrchain_spec_works();
+	}
+
+	#[tokio::test]
+	async fn teyrchain_runtime_works() {
+		// TODO: None doesn't work. But maybe it should? it would be misleading as many users might
+		// use it.
+		for preset in [Some(DEV_RUNTIME_PRESET.into()), Some(LOCAL_TESTNET_RUNTIME_PRESET.into())] {
+			test_runtime_preset(PARA_RUNTIME, 1000, preset).await;
+		}
+	}
+
+	#[tokio::test]
+	async fn omni_node_dev_mode_works() {
+		//Omni Node in dev mode works with teyrchain's template `dev_chain_spec`
+		let dev_chain_spec = std::env::current_dir()
+			.unwrap()
+			.parent()
+			.unwrap()
+			.parent()
+			.unwrap()
+			.join("templates")
+			.join("teyrchain")
+			.join("dev_chain_spec.json");
+		omni_node_test_setup(dev_chain_spec).await;
+	}
+
+	#[tokio::test]
+	// This is a regresion test so that we still remain compatible with runtimes that use
+	// `para-id` in chain specs, instead of implementing the
+	// `cumulus_primitives_core::GetTeyrchainInfo`.
+	async fn omni_node_dev_mode_works_without_getteyrchaininfo() {
+		let dev_chain_spec = std::env::current_dir()
+			.unwrap()
+			.join("src/guides/teyrchain_without_getteyrchaininfo.json");
+		omni_node_test_setup(dev_chain_spec).await;
+	}
+}
@@ -0,0 +1,789 @@
+//! # Currency Pallet
+//!
+//! By the end of this guide, you will have written a small FRAME pallet (see
+//! [`crate::pezkuwi_sdk::frame_runtime`]) that is capable of handling a simple crypto-currency.
+//! This pallet will:
+//!
+//! 1. Allow anyone to mint new tokens into accounts (which is obviously not a great idea for a real
+//!    system).
+//! 2. Allow any user that owns tokens to transfer them to others.
+//! 3. Track the total issuance of all tokens at all times.
+//!
+//! > This guide will build a currency pallet from scratch using only the lowest primitives of
+//! > FRAME, and is mainly intended for education, not *applicability*. For example, almost all
+//! > FRAME-based runtimes use various techniques to re-use a currency pallet instead of writing
+//! > one. Further advanced FRAME related topics are discussed in [`crate::reference_docs`].
+//!
+//! ## Writing Your First Pallet
+//!
+//! To get started, clone one of the templates mentioned in [`crate::pezkuwi_sdk::templates`]. We
+//! recommend using the `pezkuwi-sdk-minimal-template`. You might need to change small parts of
+//! this guide, namely the crate/package names, based on which template you use.
+//!
+//! > Be aware that you can read the entire source code backing this tutorial by clicking on the
+//! > `source` button at the top right of the page.
+//!
+//! You should have studied the following modules as a prelude to this guide:
+//!
+//! - [`crate::reference_docs::blockchain_state_machines`]
+//! - [`crate::reference_docs::trait_based_programming`]
+//! - [`crate::pezkuwi_sdk::frame_runtime`]
+//!
+//! ## Topics Covered
+//!
+//! The following FRAME topics are covered in this guide:
+//!
+//! - [`pallet::storage`]
+//! - [`pallet::call`]
+//! - [`pallet::event`]
+//! - [`pallet::error`]
+//! - Basics of testing a pallet
+//! - [Constructing a runtime](frame::runtime::prelude::construct_runtime)
+//!
+//! ### Shell Pallet
+//!
+//! Consider the following as a "shell pallet". We continue building the rest of this pallet based
+//! on this template.
+//!
+//! [`pallet::config`] and [`pallet::pallet`] are both mandatory parts of any
+//! pallet. Refer to the documentation of each to get an overview of what they do.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", shell_pallet)]
+//!
+//! All of the code that follows in this guide should live inside of the `mod pallet`.
+//!
+//! ### Storage
+//!
+//! First, we will need to create two onchain storage declarations.
+//!
+//! One should be a mapping from account-ids to a balance type, and one value that is the total
+//! issuance.
+//!
+//! > For the rest of this guide, we will opt for a balance type of `u128`. For the sake of
+//! > simplicity, we are hardcoding this type. In a real pallet is best practice to define it as a
+//! > generic bounded type in the `Config` trait, and then specify it in the implementation.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", Balance)]
+//!
+//! The definition of these two storage items, based on [`pallet::storage`] details, is as follows:
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", TotalIssuance)]
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", Balances)]
+//!
+//! ### Dispatchables
+//!
+//! Next, we will define the dispatchable functions. As per [`pallet::call`], these will be defined
+//! as normal `fn`s attached to `struct Pallet`.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", impl_pallet)]
+//!
+//! The logic of these functions is self-explanatory. Instead, we will focus on the FRAME-related
+//! details:
+//!
+//! - Where do `T::AccountId` and `T::RuntimeOrigin` come from? These are both defined in
+//!  [`frame::prelude::frame_system::Config`], therefore we can access them in `T`.
+//! - What is `ensure_signed`, and what does it do with the aforementioned `T::RuntimeOrigin`? This
+//!   is outside the scope of this guide, and you can learn more about it in the origin reference
+//!   document ([`crate::reference_docs::frame_origin`]). For now, you should only know the
+//!   signature of the function: it takes a generic `T::RuntimeOrigin` and returns a
+//!   `Result<T::AccountId, _>`. So by the end of this function call, we know that this dispatchable
+//!   was signed by `sender`.
+#![doc = docify::embed!("../../substrate/frame/system/src/lib.rs", ensure_signed)]
+//!
+//! - Where does `mutate`, `get` and `insert` and other storage APIs come from? All of them are
+//! explained in the corresponding `type`, for example, for `Balances::<T>::insert`, you can look
+//! into [`frame::prelude::StorageMap::insert`].
+//!
+//! - The return type of all dispatchable functions is [`frame::prelude::DispatchResult`]:
+#![doc = docify::embed!("../../substrate/frame/support/src/dispatch.rs", DispatchResult)]
+//!
+//! Which is more or less a normal Rust `Result`, with a custom [`frame::prelude::DispatchError`] as
+//! the `Err` variant. We won't cover this error in detail here, but importantly you should know
+//! that there is an `impl From<&'static string> for DispatchError` provided (see
+//! [here](`frame::prelude::DispatchError#impl-From<%26str>-for-DispatchError`)). Therefore,
+//! we can use basic string literals as our error type and `.into()` them into `DispatchError`.
+//!
+//! - Why are all `get` and `mutate` functions returning an `Option`? This is the default behavior
+//!   of FRAME storage APIs. You can learn more about how to override this by looking into
+//!   [`pallet::storage`], and [`frame::prelude::ValueQuery`]/[`frame::prelude::OptionQuery`]
+//!
+//! ### Improving Errors
+//!
+//! How we handle error in the above snippets is fairly rudimentary. Let's look at how this can be
+//! improved. First, we can use [`frame::prelude::ensure`] to express the error slightly better.
+//! This macro will call `.into()` under the hood.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", transfer_better)]
+//!
+//! Moreover, you will learn in the [Defensive Programming
+//! section](crate::reference_docs::defensive_programming) that it is always recommended to use
+//! safe arithmetic operations in your runtime. By using [`frame::traits::CheckedSub`], we can not
+//! only take a step in that direction, but also improve the error handing and make it slightly more
+//! ergonomic.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", transfer_better_checked)]
+//!
+//! This is more or less all the logic that there is in this basic currency pallet!
+//!
+//! ### Your First (Test) Runtime
+//!
+//! The typical testing code of a pallet lives in a module that imports some preludes useful for
+//! testing, similar to:
+//!
+//! ```
+//! pub mod pallet {
+//! 	// snip -- actually pallet code.
+//! }
+//!
+//! #[cfg(test)]
+//! mod tests {
+//! 	// bring in the testing prelude of frame
+//! 	use frame::testing_prelude::*;
+//! 	// bring in all pallet items
+//! 	use super::pallet::*;
+//!
+//! 	// snip -- rest of the testing code.
+//! }
+//! ```
+//!
+//! Next, we create a "test runtime" in order to test our pallet. Recall from
+//! [`crate::pezkuwi_sdk::frame_runtime`] that a runtime is a collection of pallets, expressed
+//! through [`frame::runtime::prelude::construct_runtime`]. All runtimes also have to include
+//! [`frame::prelude::frame_system`]. So we expect to see a runtime with two pallet, `frame_system`
+//! and the one we just wrote.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", runtime)]
+//!
+//! > [`frame::pallet_macros::derive_impl`] is a FRAME feature that enables developers to have
+//! > defaults for associated types.
+//!
+//! Recall that within our pallet, (almost) all blocks of code are generic over `<T: Config>`. And,
+//! because `trait Config: frame_system::Config`, we can get access to all items in `Config` (or
+//! `frame_system::Config`) using `T::NameOfItem`. This is all within the boundaries of how
+//! Rust traits and generics work. If unfamiliar with this pattern, read
+//! [`crate::reference_docs::trait_based_programming`] before going further.
+//!
+//! Crucially, a typical FRAME runtime contains a `struct Runtime`. The main role of this `struct`
+//! is to implement the `trait Config` of all pallets. That is, anywhere within your pallet code
+//! where you see `<T: Config>` (read: *"some type `T` that implements `Config`"*), in the runtime,
+//! it can be replaced with `<Runtime>`, because `Runtime` implements `Config` of all pallets, as we
+//! see above.
+//!
+//! Another way to think about this is that within a pallet, a lot of types are "unknown" and, we
+//! only know that they will be provided at some later point. For example, when you write
+//! `T::AccountId` (which is short for `<T as frame_system::Config>::AccountId`) in your pallet,
+//! you are in fact saying "*Some type `AccountId` that will be known later*". That "later" is in
+//! fact when you specify these types when you implement all `Config` traits for `Runtime`.
+//!
+//! As you see above, `frame_system::Config` is setting the `AccountId` to `u64`. Of course, a real
+//! runtime will not use this type, and instead reside to a proper type like a 32-byte standard
+//! public key. This is a HUGE benefit that FRAME developers can tap into: through the framework
+//! being so generic, different types can always be customized to simple things when needed.
+//!
+//! > Imagine how hard it would have been if all tests had to use a real 32-byte account id, as
+//! > opposed to just a u64 number 🙈.
+//!
+//! ### Your First Test
+//!
+//! The above is all you need to execute the dispatchables of your pallet. The last thing you need
+//! to learn is that all of your pallet testing code should be wrapped in
+//! [`frame::testing_prelude::TestState`]. This is a type that provides access to an in-memory state
+//! to be used in our tests.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", first_test)]
+//!
+//! In the first test, we simply assert that there is no total issuance, and no balance associated
+//! with Alice's account. Then, we mint some balance into Alice's, and re-check.
+//!
+//! As noted above, the `T::AccountId` is now `u64`. Moreover, `Runtime` is replacing `<T: Config>`.
+//! This is why for example you see `Balances::<Runtime>::get(..)`. Finally, notice that the
+//! dispatchables are simply functions that can be called on top of the `Pallet` struct.
+//!
+//! Congratulations! You have written your first pallet and tested it! Next, we learn a few optional
+//! steps to improve our pallet.
+//!
+//! ## Improving the Currency Pallet
+//!
+//! ### Better Test Setup
+//!
+//! Idiomatic FRAME pallets often use Builder pattern to define their initial state.
+//!
+//! > The Pezkuwi Blockchain Academy's Rust entrance exam has a
+//! > [section](https://github.com/pezkuwichain/kurdistan_blockchain-akademy/blob/main/src/m_builder.rs)
+//! > on this that you can use to learn the Builder Pattern.
+//!
+//! Let's see how we can implement a better test setup using this pattern. First, we define a
+//! `struct StateBuilder`.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", StateBuilder)]
+//!
+//! This struct is meant to contain the same list of accounts and balances that we want to have at
+//! the beginning of each block. We hardcoded this to `let accounts = vec![(ALICE, 100), (2, 100)];`
+//! so far. Then, if desired, we attach a default value for this struct.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", default_state_builder)]
+//!
+//! Like any other builder pattern, we attach functions to the type to mutate its internal
+//! properties.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", impl_state_builder_add)]
+//!
+//!  Finally --the useful part-- we write our own custom `build_and_execute` function on
+//! this type. This function will do multiple things:
+//!
+//! 1. It would consume `self` to produce our `TestState` based on the properties that we attached
+//!    to `self`.
+//! 2. It would execute any test function that we pass in as closure.
+//! 3. A nifty trick, this allows our test setup to have some code that is executed both before and
+//!    after each test. For example, in this test, we do some additional checking about the
+//!    correctness of the `TotalIssuance`. We leave it up to you as an exercise to learn why the
+//!    assertion should always hold, and how it is checked.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", impl_state_builder_build)]
+//!
+//! We can write tests that specifically check the initial state, and making sure our `StateBuilder`
+//! is working exactly as intended.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", state_builder_works)]
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", state_builder_add_balance)]
+//!
+//! ### More Tests
+//!
+//! Now that we have a more ergonomic test setup, let's see how a well written test for transfer and
+//! mint would look like.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", transfer_works)]
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", mint_works)]
+//!
+//! It is always a good idea to build a mental model where you write *at least* one test for each
+//! "success path" of a dispatchable, and one test for each "failure path", such as:
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", transfer_from_non_existent_fails)]
+//!
+//! We leave it up to you to write a test that triggers the `InsufficientBalance` error.
+//!
+//! ### Event and Error
+//!
+//! Our pallet is mainly missing two parts that are common in most FRAME pallets: Events, and
+//! Errors. First, let's understand what each is.
+//!
+//! - **Error**: The static string-based error scheme we used so far is good for readability, but it
+//!   has a few drawbacks. The biggest problem with strings are that they are not type safe, e.g. a
+//!   match statement cannot be exhaustive. These string literals will bloat the final wasm blob,
+//!   and are relatively heavy to transmit and encode/decode. Moreover, it is easy to mistype them
+//!   by one character. FRAME errors are exactly a solution to maintain readability, whilst fixing
+//!   the drawbacks mentioned. In short, we use an enum to represent different variants of our
+//!   error. These variants are then mapped in an efficient way (using only `u8` indices) to
+//!   [`sp_runtime::DispatchError::Module`]. Read more about this in [`pallet::error`].
+//!
+//! - **Event**: Events are akin to the return type of dispatchables. They are mostly data blobs
+//!   emitted by the runtime to let outside world know what is happening inside the pallet. Since
+//!   otherwise, the outside world does not have an easy access to the state changes. They should
+//!   represent what happened at the end of a dispatch operation. Therefore, the convention is to
+//!   use passive tense for event names (eg. `SomethingHappened`). This allows other sub-systems or
+//!   external parties (eg. a light-node, a DApp) to listen to particular events happening, without
+//!   needing to re-execute the whole state transition function.
+//!
+//! With the explanation out of the way, let's see how these components can be added. Both follow a
+//! fairly familiar syntax: normal Rust enums, with extra [`pallet::event`] and [`pallet::error`]
+//! attributes attached.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", Event)]
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", Error)]
+//!
+//! One slightly custom part of this is the [`pallet::generate_deposit`] part. Without going into
+//! too much detail, in order for a pallet to emit events to the rest of the system, it needs to do
+//! two things:
+//!
+//! 1. Declare a type in its `Config` that refers to the overarching event type of the runtime. In
+//! short, by doing this, the pallet is expressing an important bound: `type RuntimeEvent:
+//! From<Event<Self>>`. Read: a `RuntimeEvent` exists, and it can be created from the local `enum
+//! Event` of this pallet. This enables the pallet to convert its `Event` into `RuntimeEvent`, and
+//! store it where needed.
+//!
+//! 2. But, doing this conversion and storing is too much to expect each pallet to define. FRAME
+//! provides a default way of storing events, and this is what [`pallet::generate_deposit`] is
+//! doing.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", config_v2)]
+//!
+//! > These `Runtime*` types are better explained in
+//! > [`crate::reference_docs::frame_runtime_types`].
+//!
+//! Then, we can rewrite the `transfer` dispatchable as such:
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", transfer_v2)]
+//!
+//! Then, notice how now we would need to provide this `type RuntimeEvent` in our test runtime
+//! setup.
+#![doc = docify::embed!("./packages/guides/first-pallet/src/lib.rs", runtime_v2)]
+//!
+//! In this snippet, the actual `RuntimeEvent` type (right hand side of `type RuntimeEvent =
+//! RuntimeEvent`) is generated by
+//! [`construct_runtime`](frame::runtime::prelude::construct_runtime). An interesting way to inspect
+//! this type is to see its definition in rust-docs:
+//! [`crate::guides::your_first_pallet::pallet_v2::tests::runtime_v2::RuntimeEvent`].
+//!
+//!
+//! ## What Next?
+//!
+//! The following topics where used in this guide, but not covered in depth. It is suggested to
+//! study them subsequently:
+//!
+//! - [`crate::reference_docs::defensive_programming`].
+//! - [`crate::reference_docs::frame_origin`].
+//! - [`crate::reference_docs::frame_runtime_types`].
+//! - The pallet we wrote in this guide was using `dev_mode`, learn more in [`pallet::config`].
+//! - Learn more about the individual pallet items/macros, such as event and errors and call, in
+//!   [`frame::pallet_macros`].
+//!
+//! [`pallet::storage`]: frame_support::pallet_macros::storage
+//! [`pallet::call`]: frame_support::pallet_macros::call
+//! [`pallet::event`]: frame_support::pallet_macros::event
+//! [`pallet::error`]: frame_support::pallet_macros::error
+//! [`pallet::pallet`]: frame_support::pallet
+//! [`pallet::config`]: frame_support::pallet_macros::config
+//! [`pallet::generate_deposit`]: frame_support::pallet_macros::generate_deposit
+
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod shell_pallet {
+	use frame::prelude::*;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+}
+
+#[frame::pallet(dev_mode)]
+pub mod pallet {
+	use frame::prelude::*;
+
+	#[docify::export]
+	pub type Balance = u128;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[docify::export]
+	/// Single storage item, of type `Balance`.
+	#[pallet::storage]
+	pub type TotalIssuance<T: Config> = StorageValue<_, Balance>;
+
+	#[docify::export]
+	/// A mapping from `T::AccountId` to `Balance`
+	#[pallet::storage]
+	pub type Balances<T: Config> = StorageMap<_, _, T::AccountId, Balance>;
+
+	#[docify::export(impl_pallet)]
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		/// An unsafe mint that can be called by anyone. Not a great idea.
+		pub fn mint_unsafe(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			// ensure that this is a signed account, but we don't really check `_anyone`.
+			let _anyone = ensure_signed(origin)?;
+
+			// update the balances map. Notice how all `<T: Config>` remains as `<T>`.
+			Balances::<T>::mutate(dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			// update total issuance.
+			TotalIssuance::<T>::mutate(|t| *t = Some(t.unwrap_or(0) + amount));
+
+			Ok(())
+		}
+
+		/// Transfer `amount` from `origin` to `dest`.
+		pub fn transfer(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			// ensure sender has enough balance, and if so, calculate what is left after `amount`.
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			if sender_balance < amount {
+				return Err("InsufficientBalance".into());
+			}
+			let remainder = sender_balance - amount;
+
+			// update sender and dest balances.
+			Balances::<T>::mutate(dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			Balances::<T>::insert(&sender, remainder);
+
+			Ok(())
+		}
+	}
+
+	#[allow(unused)]
+	impl<T: Config> Pallet<T> {
+		#[docify::export]
+		pub fn transfer_better(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			ensure!(sender_balance >= amount, "InsufficientBalance");
+			let remainder = sender_balance - amount;
+
+			// .. snip
+			Ok(())
+		}
+
+		#[docify::export]
+		/// Transfer `amount` from `origin` to `dest`.
+		pub fn transfer_better_checked(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
+			let remainder = sender_balance.checked_sub(amount).ok_or("InsufficientBalance")?;
+
+			// .. snip
+			Ok(())
+		}
+	}
+
+	#[cfg(any(test, doc))]
+	pub(crate) mod tests {
+		use crate::guides::your_first_pallet::pallet::*;
+
+		#[docify::export(testing_prelude)]
+		use frame::testing_prelude::*;
+
+		pub(crate) const ALICE: u64 = 1;
+		pub(crate) const BOB: u64 = 2;
+		pub(crate) const CHARLIE: u64 = 3;
+
+		#[docify::export]
+		// This runtime is only used for testing, so it should be somewhere like `#[cfg(test)] mod
+		// tests { .. }`
+		mod runtime {
+			use super::*;
+			// we need to reference our `mod pallet` as an identifier to pass to
+			// `construct_runtime`.
+			// YOU HAVE TO CHANGE THIS LINE BASED ON YOUR TEMPLATE
+			use crate::guides::your_first_pallet::pallet as pallet_currency;
+
+			construct_runtime!(
+				pub enum Runtime {
+					// ---^^^^^^ This is where `enum Runtime` is defined.
+					System: frame_system,
+					Currency: pallet_currency,
+				}
+			);
+
+			#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+			impl frame_system::Config for Runtime {
+				type Block = MockBlock<Runtime>;
+				// within pallet we just said `<T as frame_system::Config>::AccountId`, now we
+				// finally specified it.
+				type AccountId = u64;
+			}
+
+			// our simple pallet has nothing to be configured.
+			impl pallet_currency::Config for Runtime {}
+		}
+
+		pub(crate) use runtime::*;
+
+		#[allow(unused)]
+		#[docify::export]
+		fn new_test_state_basic() -> TestState {
+			let mut state = TestState::new_empty();
+			let accounts = vec![(ALICE, 100), (BOB, 100)];
+			state.execute_with(|| {
+				for (who, amount) in &accounts {
+					Balances::<Runtime>::insert(who, amount);
+					TotalIssuance::<Runtime>::mutate(|b| *b = Some(b.unwrap_or(0) + amount));
+				}
+			});
+
+			state
+		}
+
+		#[docify::export]
+		pub(crate) struct StateBuilder {
+			balances: Vec<(<Runtime as frame_system::Config>::AccountId, Balance)>,
+		}
+
+		#[docify::export(default_state_builder)]
+		impl Default for StateBuilder {
+			fn default() -> Self {
+				Self { balances: vec![(ALICE, 100), (BOB, 100)] }
+			}
+		}
+
+		#[docify::export(impl_state_builder_add)]
+		impl StateBuilder {
+			fn add_balance(
+				mut self,
+				who: <Runtime as frame_system::Config>::AccountId,
+				amount: Balance,
+			) -> Self {
+				self.balances.push((who, amount));
+				self
+			}
+		}
+
+		#[docify::export(impl_state_builder_build)]
+		impl StateBuilder {
+			pub(crate) fn build_and_execute(self, test: impl FnOnce() -> ()) {
+				let mut ext = TestState::new_empty();
+				ext.execute_with(|| {
+					for (who, amount) in &self.balances {
+						Balances::<Runtime>::insert(who, amount);
+						TotalIssuance::<Runtime>::mutate(|b| *b = Some(b.unwrap_or(0) + amount));
+					}
+				});
+
+				ext.execute_with(test);
+
+				// assertions that must always hold
+				ext.execute_with(|| {
+					assert_eq!(
+						Balances::<Runtime>::iter().map(|(_, x)| x).sum::<u128>(),
+						TotalIssuance::<Runtime>::get().unwrap_or_default()
+					);
+				})
+			}
+		}
+
+		#[docify::export]
+		#[test]
+		fn first_test() {
+			TestState::new_empty().execute_with(|| {
+				// We expect Alice's account to have no funds.
+				assert_eq!(Balances::<Runtime>::get(&ALICE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), None);
+
+				// mint some funds into Alice's account.
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(
+					RuntimeOrigin::signed(ALICE),
+					ALICE,
+					100
+				));
+
+				// re-check the above
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(100));
+			})
+		}
+
+		#[docify::export]
+		#[test]
+		fn state_builder_works() {
+			StateBuilder::default().build_and_execute(|| {
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn state_builder_add_balance() {
+			StateBuilder::default().add_balance(CHARLIE, 42).build_and_execute(|| {
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), Some(42));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(242));
+			})
+		}
+
+		#[test]
+		#[should_panic]
+		fn state_builder_duplicate_genesis_fails() {
+			StateBuilder::default()
+				.add_balance(CHARLIE, 42)
+				.add_balance(CHARLIE, 43)
+				.build_and_execute(|| {
+					assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+					assert_eq!(TotalIssuance::<Runtime>::get(), Some(242));
+				})
+		}
+
+		#[docify::export]
+		#[test]
+		fn mint_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(RuntimeOrigin::signed(ALICE), BOB, 100));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(200));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(300));
+
+				// given:
+				assert_ok!(Pallet::<Runtime>::mint_unsafe(
+					RuntimeOrigin::signed(ALICE),
+					CHARLIE,
+					100
+				));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(400));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn transfer_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(ALICE), BOB, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(50));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(150));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+
+				// when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(BOB), ALICE, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+
+		#[docify::export]
+		#[test]
+		fn transfer_from_non_existent_fails() {
+			StateBuilder::default().build_and_execute(|| {
+				// given the initial state, when:
+				assert_err!(
+					Pallet::<Runtime>::transfer(RuntimeOrigin::signed(CHARLIE), ALICE, 10),
+					"NonExistentAccount"
+				);
+
+				// then nothing has changed.
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(100));
+				assert_eq!(Balances::<Runtime>::get(&CHARLIE), None);
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+			});
+		}
+	}
+}
+
+#[frame::pallet(dev_mode)]
+pub mod pallet_v2 {
+	use super::pallet::Balance;
+	use frame::prelude::*;
+
+	#[docify::export(config_v2)]
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		/// The overarching event type of the runtime.
+		#[allow(deprecated)]
+		type RuntimeEvent: From<Event<Self>>
+			+ IsType<<Self as frame_system::Config>::RuntimeEvent>
+			+ TryInto<Event<Self>>;
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[pallet::storage]
+	pub type Balances<T: Config> = StorageMap<_, _, T::AccountId, Balance>;
+
+	#[pallet::storage]
+	pub type TotalIssuance<T: Config> = StorageValue<_, Balance>;
+
+	#[docify::export]
+	#[pallet::error]
+	pub enum Error<T> {
+		/// Account does not exist.
+		NonExistentAccount,
+		/// Account does not have enough balance.
+		InsufficientBalance,
+	}
+
+	#[docify::export]
+	#[pallet::event]
+	#[pallet::generate_deposit(pub(super) fn deposit_event)]
+	pub enum Event<T: Config> {
+		/// A transfer succeeded.
+		Transferred { from: T::AccountId, to: T::AccountId, amount: Balance },
+	}
+
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		#[docify::export(transfer_v2)]
+		pub fn transfer(
+			origin: T::RuntimeOrigin,
+			dest: T::AccountId,
+			amount: Balance,
+		) -> DispatchResult {
+			let sender = ensure_signed(origin)?;
+
+			// ensure sender has enough balance, and if so, calculate what is left after `amount`.
+			let sender_balance =
+				Balances::<T>::get(&sender).ok_or(Error::<T>::NonExistentAccount)?;
+			let remainder =
+				sender_balance.checked_sub(amount).ok_or(Error::<T>::InsufficientBalance)?;
+
+			Balances::<T>::mutate(&dest, |b| *b = Some(b.unwrap_or(0) + amount));
+			Balances::<T>::insert(&sender, remainder);
+
+			Self::deposit_event(Event::<T>::Transferred { from: sender, to: dest, amount });
+
+			Ok(())
+		}
+	}
+
+	#[cfg(any(test, doc))]
+	pub mod tests {
+		use super::{super::pallet::tests::StateBuilder, *};
+		use frame::testing_prelude::*;
+		const ALICE: u64 = 1;
+		const BOB: u64 = 2;
+
+		#[docify::export]
+		pub mod runtime_v2 {
+			use super::*;
+			use crate::guides::your_first_pallet::pallet_v2 as pallet_currency;
+
+			construct_runtime!(
+				pub enum Runtime {
+					System: frame_system,
+					Currency: pallet_currency,
+				}
+			);
+
+			#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+			impl frame_system::Config for Runtime {
+				type Block = MockBlock<Runtime>;
+				type AccountId = u64;
+			}
+
+			impl pallet_currency::Config for Runtime {
+				type RuntimeEvent = RuntimeEvent;
+			}
+		}
+
+		pub(crate) use runtime_v2::*;
+
+		#[docify::export(transfer_works_v2)]
+		#[test]
+		fn transfer_works() {
+			StateBuilder::default().build_and_execute(|| {
+				// skip the genesis block, as events are not deposited there and we need them for
+				// the final assertion.
+				System::set_block_number(ALICE);
+
+				// given the initial state, when:
+				assert_ok!(Pallet::<Runtime>::transfer(RuntimeOrigin::signed(ALICE), BOB, 50));
+
+				// then:
+				assert_eq!(Balances::<Runtime>::get(&ALICE), Some(50));
+				assert_eq!(Balances::<Runtime>::get(&BOB), Some(150));
+				assert_eq!(TotalIssuance::<Runtime>::get(), Some(200));
+
+				// now we can also check that an event has been deposited:
+				assert_eq!(
+					System::read_events_for_pallet::<Event<Runtime>>(),
+					vec![Event::Transferred { from: ALICE, to: BOB, amount: 50 }]
+				);
+			});
+		}
+	}
+}
@@ -0,0 +1,186 @@
+//! # Your first Runtime
+//!
+//! This guide will walk you through the steps to add your pallet to a runtime.
+//!
+//! The good news is, in [`crate::guides::your_first_pallet`], we have already created a _test_
+//! runtime that was used for testing, and a real runtime is not that much different!
+//!
+//! ## Setup
+//!
+//! A runtime shares a few similar setup requirements as with a pallet:
+//!
+//! * importing [`frame`], [`codec`], and [`scale_info`] crates.
+//! * following the [`std` feature-gating](crate::pezkuwi_sdk::substrate#wasm-build) pattern.
+//!
+//! But, more specifically, it also contains:
+//!
+//! * a `build.rs` that uses [`substrate_wasm_builder`]. This entails declaring
+//!   `[build-dependencies]` in the Cargo manifest file:
+//!
+//! ```ignore
+//! [build-dependencies]
+//! substrate-wasm-builder = { ... }
+//! ```
+//!
+//! >Note that a runtime must always be one-runtime-per-crate. You cannot define multiple runtimes
+//! per rust crate.
+//!
+//! You can find the full code of this guide in [`first_runtime`].
+//!
+//! ## Your First Runtime
+//!
+//! The first new property of a real runtime that it must define its
+//! [`frame::runtime::prelude::RuntimeVersion`]:
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", VERSION)]
+//!
+//! The version contains a number of very important fields, such as `spec_version` and `spec_name`
+//! that play an important role in identifying your runtime and its version, more importantly in
+//! runtime upgrades. More about runtime upgrades in
+//! [`crate::reference_docs::frame_runtime_upgrades_and_migrations`].
+//!
+//! Then, a real runtime also contains the `impl` of all individual pallets' `trait Config` for
+//! `struct Runtime`, and a [`frame::runtime::prelude::construct_runtime`] macro that amalgamates
+//! them all.
+//!
+//! In the case of our example:
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", our_config_impl)]
+//!
+//! In this example, we bring in a number of other pallets from [`frame`] into the runtime, each of
+//! their `Config` need to be implemented for `struct Runtime`:
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", config_impls)]
+//!
+//! Notice how we use [`frame::pallet_macros::derive_impl`] to provide "default" configuration items
+//! for each pallet. Feel free to dive into the definition of each default prelude (eg.
+//! [`frame::prelude::frame_system::pallet::config_preludes`]) to learn more which types are exactly
+//! used.
+//!
+//! Recall that in test runtime in [`crate::guides::your_first_pallet`], we provided `type AccountId
+//! = u64` to `frame_system`, while in this case we rely on whatever is provided by
+//! [`SolochainDefaultConfig`], which is indeed a "real" 32 byte account id.
+//!
+//! Then, a familiar instance of `construct_runtime` amalgamates all of the pallets:
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", cr)]
+//!
+//! Recall from [`crate::reference_docs::wasm_meta_protocol`] that every (real) runtime needs to
+//! implement a set of runtime APIs that will then let the node to communicate with it. The final
+//! steps of crafting a runtime are related to achieving exactly this.
+//!
+//! First, we define a number of types that eventually lead to the creation of an instance of
+//! [`frame::runtime::prelude::Executive`]. The executive is a handy FRAME utility that, through
+//! amalgamating all pallets and further types, implements some of the very very core pieces of the
+//! runtime logic, such as how blocks are executed and other runtime-api implementations.
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", runtime_types)]
+//!
+//! Finally, we use [`frame::runtime::prelude::impl_runtime_apis`] to implement all of the runtime
+//! APIs that the runtime wishes to expose. As you will see in the code, most of these runtime API
+//! implementations are merely forwarding calls to `RuntimeExecutive` which handles the actual
+//! logic. Given that the implementation block is somewhat large, we won't repeat it here. You can
+//! look for `impl_runtime_apis!` in [`first_runtime`].
+//!
+//! ```ignore
+//! impl_runtime_apis! {
+//! 	impl apis::Core<Block> for Runtime {
+//! 		fn version() -> RuntimeVersion {
+//! 			VERSION
+//! 		}
+//!
+//! 		fn execute_block(block: Block) {
+//! 			RuntimeExecutive::execute_block(block)
+//! 		}
+//!
+//! 		fn initialize_block(header: &Header) -> ExtrinsicInclusionMode {
+//! 			RuntimeExecutive::initialize_block(header)
+//! 		}
+//! 	}
+//!
+//! 	// many more trait impls...
+//! }
+//! ```
+//!
+//! And that more or less covers the details of how you would write a real runtime!
+//!
+//! Once you compile a crate that contains a runtime as above, simply running `cargo build` will
+//! generate the wasm blobs and place them under `./target/release/wbuild`, as explained
+//! [here](crate::pezkuwi_sdk::substrate#wasm-build).
+//!
+//! ## Genesis Configuration
+//!
+//! Every runtime specifies a number of runtime APIs that help the outer world (most notably, a
+//! `node`) know what is the genesis state of this runtime. These APIs are then used to generate
+//! what is known as a  **Chain Specification, or chain spec for short**. A chain spec is the
+//! primary way to run a new chain.
+//!
+//! These APIs are defined in [`sp_genesis_builder`], and are re-exposed as a part of
+//! [`frame::runtime::apis`]. Therefore, the implementation blocks can be found inside of
+//! `impl_runtime_apis!` similar to:
+//!
+//! ```ignore
+//! impl_runtime_apis! {
+//!  	impl apis::GenesisBuilder<Block> for Runtime {
+//! 			fn build_state(config: Vec<u8>) -> GenesisBuilderResult {
+//! 				build_state::<RuntimeGenesisConfig>(config)
+//! 			}
+//!
+//! 			fn get_preset(id: &Option<PresetId>) -> Option<Vec<u8>> {
+//! 				get_preset::<RuntimeGenesisConfig>(id, self::genesis_config_presets::get_preset)
+//! 			}
+//!
+//! 			fn preset_names() -> Vec<PresetId> {
+//! 				crate::genesis_config_presets::preset_names()
+//! 			}
+//! 		}
+//!
+//! }
+//! ```
+//!
+//! The implementation of these function can naturally vary from one runtime to the other, but the
+//! overall pattern is common. For the case of this runtime, we do the following:
+//!
+//! 1. Expose one non-default preset, namely [`sp_genesis_builder::DEV_RUNTIME_PRESET`]. This means
+//!    our runtime has two "presets" of genesis state in total: `DEV_RUNTIME_PRESET` and `None`.
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", preset_names)]
+//!
+//! For `build_state` and `get_preset`, we use the helper functions provide by frame:
+//!
+//! * [`frame::runtime::prelude::build_state`] and [`frame::runtime::prelude::get_preset`].
+//!
+//! Indeed, our runtime needs to specify what its `DEV_RUNTIME_PRESET` genesis state should be like:
+#![doc = docify::embed!("./packages/guides/first-runtime/src/lib.rs", development_config_genesis)]
+//!
+//! For more in-depth information about `GenesisConfig`, `ChainSpec`, the `GenesisBuilder` API and
+//! `chain-spec-builder`, see [`crate::reference_docs::chain_spec_genesis`].
+//!
+//! ## Next Step
+//!
+//! See [`crate::guides::your_first_node`].
+//!
+//! ## Further Reading
+//!
+//! 1. To learn more about signed extensions, see [`crate::reference_docs::signed_extensions`].
+//! 2. `AllPalletsWithSystem` is also generated by `construct_runtime`, as explained in
+//!    [`crate::reference_docs::frame_runtime_types`].
+//! 3. `Executive` supports more generics, most notably allowing the runtime to configure more
+//!    runtime migrations, as explained in
+//!    [`crate::reference_docs::frame_runtime_upgrades_and_migrations`].
+//! 4. Learn more about adding and implementing runtime apis in
+//!    [`crate::reference_docs::custom_runtime_api_rpc`].
+//! 5. To see a complete example of a runtime+pallet that is similar to this guide, please see
+//!    [`crate::pezkuwi_sdk::templates`].
+//!
+//! [`SolochainDefaultConfig`]: struct@frame_system::pallet::config_preludes::SolochainDefaultConfig
+
+#[cfg(test)]
+mod tests {
+	use cmd_lib::run_cmd;
+
+	const FIRST_RUNTIME: &'static str = "pezkuwi-sdk-docs-first-runtime";
+
+	#[docify::export_content]
+	#[test]
+	fn build_runtime() {
+		run_cmd!(
+			cargo build --release -p $FIRST_RUNTIME
+		)
+		.expect("Failed to run command");
+	}
+}
@@ -0,0 +1,50 @@
+//! # Pezkuwi SDK Docs
+//!
+//! The Pezkuwi SDK Developer Documentation.
+//!
+//! This crate is a *minimal*, *always-accurate* and low level source of truth about Pezkuwi-SDK.
+//! For more high level docs, please go to [docs.pezkuwi.com](https://docs.pezkuwichain.io).
+//!
+//! ## Getting Started
+//!
+//! We suggest the following reading sequence:
+//!
+//! - Start by learning about [`pezkuwi_sdk`], its structure and context.
+//! - Then, head over to the [`guides`]. This modules contains in-depth guides about the most
+//!   important user-journeys of the Pezkuwi SDK.
+//! 	- Whilst reading the guides, you might find back-links to [`reference_docs`].
+//! - [`external_resources`] for a list of 3rd party guides and tutorials.
+//! - Finally, <https://paritytech.github.io> is the parent website of this crate that contains the
+//!   list of further tools related to the Pezkuwi SDK.
+//!
+//! ## Information Architecture
+//!
+//! This section paints a picture over the high-level information architecture of this crate.
+#![doc = simple_mermaid::mermaid!("../../mermaid/IA.mmd")]
+#![warn(rustdoc::broken_intra_doc_links)]
+#![warn(rustdoc::private_intra_doc_links)]
+// Frame macros reference features which this crate does not have
+#![allow(unexpected_cfgs)]
+#![doc(html_favicon_url = "https://pezkuwichain.io/favicon.ico")]
+#![doc(
+	html_logo_url = "https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/docs/images/Polkadot_Logo_Horizontal_Pink_White.png"
+)]
+#![doc(issue_tracker_base_url = "https://github.com/pezkuwichain/pezkuwi-sdk/issues")]
+
+/// Meta information about this crate, how it is built, what principles dictates its evolution and
+/// how one can contribute to it.
+pub mod meta_contributing;
+
+/// A list of external resources and learning material about Pezkuwi SDK.
+pub mod external_resources;
+
+/// In-depth guides about the most common components of the Pezkuwi SDK. They are slightly more
+/// high level and broad than [`reference_docs`].
+pub mod guides;
+
+/// An introduction to the Pezkuwi SDK. Read this module to learn about the structure of the SDK,
+/// the tools that are provided as a part of it, and to gain a high level understanding of each.
+pub mod pezkuwi_sdk;
+/// Reference documents covering in-depth topics across the Pezkuwi SDK. It is suggested to read
+/// these on-demand, while you are going through the [`guides`] or other content.
+pub mod reference_docs;
@@ -0,0 +1,151 @@
+//! # Contribution
+//!
+//! The following sections cover more detailed information about this crate and how it should be
+//! maintained.
+//!
+//! ## Why Rust Docs?
+//!
+//! We acknowledge that blockchain based systems, particularly a cutting-edge one like Pezkuwi SDK
+//! is a software artifact that is complex, and rapidly evolving. This makes the task of documenting
+//! it externally extremely difficult, especially with regards to making sure it is up-to-date.
+//!
+//! Consequently, we argue that the best hedge against this is to move as much of the documentation
+//! near the source code as possible. This would further incentivize developers to keep the
+//! documentation up-to-date, as the overhead is reduced by making sure everything is in one
+//! repository, and everything being in `.rs` files.
+//!
+//! > This is not to say that a more visually appealing version of this crate (for example as an
+//! > `md-book`) cannot exist, but it would be outside the scope of this crate.
+//!
+//! Moreover, we acknowledge that a major pain point has been not only outdated *concepts*, but also
+//! *outdated code*. For this, we commit to making sure no code-snippet in this crate is left as
+//! `///ignore` or `///no_compile`, making sure all code snippets are self-contained, compile-able,
+//! and correct at every single revision of the entire repository.
+//!
+//! > This also allows us to have a clear versioning on the entire content of this crate. For every
+//! commit of the Pezkuwi SDK, there would be one version of this crate that is guaranteed to be
+//! correct.
+//!
+//! > To achieve this, we often use [`docify`](https://github.com/sam0x17/docify), a nifty invention
+//! > of `@sam0x17`.
+//!
+//! Also see: <https://github.com/pezkuwichain/pezkuwi-sdk/issues/109>.
+//!
+//! ## Scope
+//!
+//! The above would NOT be attainable if we don't acknowledge that the scope of this crate MUST be
+//! limited, or else its maintenance burden would be infeasible or not worthwhile. In short, future
+//! maintainers should always strive to keep the content of this repository as minimal as possible.
+//! Some of the following principles are specifically there to be the guidance for this.
+//!
+//! ## Principles
+//!
+//! The following guidelines are meant to be the guiding torch of those who contribute to this
+//! crate.
+//!
+//! 1. 🔺 Ground Up: Information should be laid out in the most ground-up fashion. The lowest level
+//!    (i.e. "ground") is Rust-docs. The highest level (i.e. "up") is "outside of this crate". In
+//!    between lies [`reference_docs`] and [`guides`], from low to high. The point of this principle
+//!    is to document as much of the information as possible in the lower level media, as it is
+//!    easier to maintain and more reachable. Then, use excessive linking to back-link when writing
+//!    in a more high level.
+//!
+//! > A prime example of this, the details of the FRAME storage APIs should NOT be explained in a
+//! > high level tutorial. They should be explained in the rust-doc of the corresponding type or
+//! > macro.
+//!
+//! 2. 🧘 Less is More: For reasons mentioned [above](#why-rust-docs), the more concise this crate
+//!    is, the better.
+//! 3. √ Don’t Repeat Yourself – DRY: A summary of the above two points. Authors should always
+//!    strive to avoid any duplicate information. Every concept should ideally be documented in
+//!    *ONE* place and one place only. This makes the task of maintaining topics significantly
+//!    easier.
+//!
+//! > A prime example of this, the list of CLI arguments of a particular binary should not be
+//! > documented in multiple places across this crate. It should be only be documented in the
+//! > corresponding crate (e.g. `sc_cli`).
+//!
+//! > Moreover, this means that as a contributor, **it is your responsibility to have a grasp over
+//! > what topics are already covered in this crate, and how you can build on top of the information
+//! > that they already pose, rather than repeating yourself**.
+//!
+//! For more details see the [latest documenting
+//! guidelines](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md).
+//!
+//! #### Example: Explaining `#[pallet::call]`
+//!
+//! <details>
+//! <summary>
+//! Let's consider the seemingly simple example of explaining to someone dead-simple code of a FRAME
+//! call and see how we can use the above principles.
+//! </summary>
+//!
+//!
+//! ```
+//! #[frame::pallet(dev_mode)]
+//! pub mod pallet {
+//! #   use frame::prelude::*;
+//! #   #[pallet::config]
+//! #   pub trait Config: frame_system::Config {}
+//! #   #[pallet::pallet]
+//! #   pub struct Pallet<T>(_);
+//!     #[pallet::call]
+//!     impl<T: Config> Pallet<T> {
+//!         pub fn a_simple_call(origin: OriginFor<T>, data: u32) -> DispatchResult {
+//!             ensure!(data > 10, "SomeStaticString");
+//!             todo!();
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! * Before even getting started, what is with all of this `<T: Config>`? We link to
+//! [`crate::reference_docs::trait_based_programming`].
+//! * First, the name. Why is this called `pallet::call`? This goes back to `enum Call`, which is
+//! explained in [`crate::reference_docs::frame_runtime_types`]. Build on top of this!
+//! * Then, what is `origin`? Just an account id? [`crate::reference_docs::frame_origin`].
+//! * Then, what is `DispatchResult`? Why is this called *dispatch*? Probably something that can be
+//! explained in the documentation of [`frame::prelude::DispatchResult`].
+//! * Why is `"SomeStaticString"` a valid error? Because there is implementation for it that you can
+//!   see [here](frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError).
+//!
+//!
+//! All of these are examples of underlying information that a contributor should:
+//!
+//! 1. Try and create and they are going along.
+//! 2. Back-link to if they already exist.
+//!
+//! Of course, all of this is not set in stone as a either/or rule. Sometimes, it is necessary to
+//! rephrase a concept in a new context.
+//!
+//! </details>
+//!
+//! ## `crates.io` and Publishing
+//!
+//! As it stands now, this crate cannot be published to crates.io because of its use of
+//! [workspace-level `docify`](https://github.com/sam0x17/docify/issues/22). For now, we accept this
+//! compromise, but in the long term, we should work towards finding a way to maintain different
+//! revisions of this crate.
+//!
+//! ## Versioning
+//!
+//! So long as not deployed in `crates.io`, please notice that all of the information in this crate,
+//! namely in [`crate::guides`] and such are compatible with the master branch of `pezkuwi-sdk`. A
+//! few solutions have been proposed to improve this, please see
+//! [here](https://github.com/pezkuwichain/pezkuwi-sdk/issues/146).
+//!
+//! ## How to Develop Locally
+//!
+//! To view the docs specific [`crate`] locally for development, including the correct HTML headers
+//! injected, run:
+//!
+//! ```sh
+//! SKIP_WASM_BUILD=1 \
+//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/assets/header.html --extend-css $(pwd)/docs/sdk/assets/theme.css --default-theme=ayu" \
+//! cargo doc -p pezkuwi-sdk-docs --no-deps --open
+//! ```
+//!
+//! If even faster build time for docs is needed, you can temporarily remove most of the
+//! substrate/cumulus dependencies that are only used for linking purposes.
+//!
+//! For more on local development, see [`crate::reference_docs::development_environment_advice`].
@@ -0,0 +1,130 @@
+//! # Cumulus
+//!
+//! Substrate provides a framework ([FRAME]) through which a blockchain node and runtime can easily
+//! be created. Cumulus aims to extend the same approach to creation of Pezkuwi teyrchains.
+//!
+//! > Cumulus clouds are shaped sort of like dots; together they form a system that is intricate,
+//! > beautiful and functional.
+//!
+//! ## Example: Runtime
+//!
+//! A Cumulus-based runtime is fairly similar to other [FRAME]-based runtimes. Most notably, the
+//! following changes are applied to a normal FRAME-based runtime to make it a Cumulus-based
+//! runtime:
+//!
+//! #### Cumulus Pallets
+//!
+//! A teyrchain runtime should use a number of pallets that are provided by Cumulus and Substrate.
+//! Notably:
+//!
+//! - [`frame-system`](frame::prelude::frame_system), like all FRAME-based runtimes.
+//! - [`cumulus_pallet_teyrchain_system`]
+//! - [`teyrchain_info`]
+#![doc = docify::embed!("./src/pezkuwi_sdk/cumulus.rs", system_pallets)]
+//!
+//! Given that all Cumulus-based runtimes use a simple Aura-based consensus mechanism, the following
+//! pallets also need to be added:
+//!
+//! - [`pallet_timestamp`]
+//! - [`pallet_aura`]
+//! - [`cumulus_pallet_aura_ext`]
+#![doc = docify::embed!("./src/pezkuwi_sdk/cumulus.rs", consensus_pallets)]
+//!
+//!
+//! Finally, a separate macro, similar to
+//! [`impl_runtime_api`](frame::runtime::prelude::impl_runtime_apis), which creates the default set
+//! of runtime APIs, will generate the teyrchain runtime's validation runtime API, also known as
+//! teyrchain validation function (PVF). Without this API, the relay chain is unable to validate
+//! blocks produced by our teyrchain.
+#![doc = docify::embed!("./src/pezkuwi_sdk/cumulus.rs", validate_block)]
+//!
+//! ---
+//!
+//! [FRAME]: crate::pezkuwi_sdk::frame_runtime
+
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::private_intra_doc_links)]
+
+#[cfg(test)]
+mod tests {
+	mod runtime {
+		pub use frame::{
+			deps::sp_consensus_aura::sr25519::AuthorityId as AuraId, prelude::*,
+			runtime::prelude::*, testing_prelude::*,
+		};
+
+		#[docify::export(CR)]
+		construct_runtime!(
+			pub enum Runtime {
+				// system-level pallets.
+				System: frame_system,
+				Timestamp: pallet_timestamp,
+				TeyrchainSystem: cumulus_pallet_teyrchain_system,
+				TeyrchainInfo: teyrchain_info,
+
+				// teyrchain consensus support -- mandatory.
+				Aura: pallet_aura,
+				AuraExt: cumulus_pallet_aura_ext,
+			}
+		);
+
+		#[docify::export]
+		mod system_pallets {
+			use super::*;
+
+			#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+			impl frame_system::Config for Runtime {
+				type Block = MockBlock<Self>;
+				type OnSetCode = cumulus_pallet_teyrchain_system::TeyrchainSetCode<Self>;
+			}
+
+			impl cumulus_pallet_teyrchain_system::Config for Runtime {
+				type RuntimeEvent = RuntimeEvent;
+				type OnSystemEvent = ();
+				type SelfParaId = teyrchain_info::Pallet<Runtime>;
+				type OutboundXcmpMessageSource = ();
+				type XcmpMessageHandler = ();
+				type ReservedDmpWeight = ();
+				type ReservedXcmpWeight = ();
+				type CheckAssociatedRelayNumber =
+					cumulus_pallet_teyrchain_system::RelayNumberMonotonicallyIncreases;
+				type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook<
+					Runtime,
+					6000, // relay chain block time
+					1,
+					1,
+				>;
+				type WeightInfo = ();
+				type DmpQueue = frame::traits::EnqueueWithOrigin<(), sp_core::ConstU8<0>>;
+				type RelayParentOffset = ConstU32<0>;
+			}
+
+			impl teyrchain_info::Config for Runtime {}
+		}
+
+		#[docify::export]
+		mod consensus_pallets {
+			use super::*;
+
+			impl pallet_aura::Config for Runtime {
+				type AuthorityId = AuraId;
+				type DisabledValidators = ();
+				type MaxAuthorities = ConstU32<100_000>;
+				type AllowMultipleBlocksPerSlot = ConstBool<false>;
+				type SlotDuration = pallet_aura::MinimumPeriodTimesTwo<Self>;
+			}
+
+			#[docify::export(timestamp)]
+			#[derive_impl(pallet_timestamp::config_preludes::TestDefaultConfig)]
+			impl pallet_timestamp::Config for Runtime {}
+
+			impl cumulus_pallet_aura_ext::Config for Runtime {}
+		}
+
+		#[docify::export(validate_block)]
+		cumulus_pallet_teyrchain_system::register_validate_block! {
+			Runtime = Runtime,
+			BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::<Runtime, Executive>,
+		}
+	}
+}
@@ -0,0 +1,175 @@
+//! # FRAME
+//!
+//! ```no_compile
+//!   ______   ______    ________   ___ __ __   ______
+//!  /_____/\ /_____/\  /_______/\ /__//_//_/\ /_____/\
+//!  \::::_\/_\:::_ \ \ \::: _  \ \\::\| \| \ \\::::_\/_
+//!   \:\/___/\\:(_) ) )_\::(_)  \ \\:.      \ \\:\/___/\
+//!    \:::._\/ \: __ `\ \\:: __  \ \\:.\-/\  \ \\::___\/_
+//!     \:\ \    \ \ `\ \ \\:.\ \  \ \\. \  \  \ \\:\____/\
+//!      \_\/     \_\/ \_\/ \__\/\__\/ \__\/ \__\/ \_____\/
+//! ```
+//!
+//! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Substrate's
+//! > State Transition Function (Runtime) Framework.
+//!
+//! ## Introduction
+//!
+//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level Substrate-based
+//! blockchains are composed of two parts:
+//!
+//! 1. A *runtime* which represents the state transition function (i.e. "Business Logic") of a
+//! blockchain, and is encoded as a WASM blob.
+//! 2. A node whose primary purpose is to execute the given runtime.
+#![doc = simple_mermaid::mermaid!("../../../mermaid/substrate_simple.mmd")]
+//!
+//! *FRAME is the Substrate's framework of choice to build a runtime.*
+//!
+//! FRAME is composed of two major components, **pallets** and a **runtime**.
+//!
+//! ## Pallets
+//!
+//! A pallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be
+//! linked to other pallets. In order to be reusable, pallets shipped with FRAME strive to only care
+//! about its own responsibilities and make as few assumptions about the general runtime as
+//! possible. A pallet is analogous to a _module_ in the runtime.
+//!
+//! A pallet is defined as a `mod pallet` wrapped by the [`frame::pallet`] macro. Within this macro,
+//! pallet components/parts can be defined. Most notable of these parts are:
+//!
+//! - [Config](frame::pallet_macros::config), allowing a pallet to make itself configurable and
+//!   generic over types, values and such.
+//! - [Storage](frame::pallet_macros::storage), allowing a pallet to define onchain storage.
+//! - [Dispatchable function](frame::pallet_macros::call), allowing a pallet to define extrinsics
+//!   that are callable by end users, from the outer world.
+//! - [Events](frame::pallet_macros::event), allowing a pallet to emit events.
+//! - [Errors](frame::pallet_macros::error), allowing a pallet to emit well-formed errors.
+//!
+//! Some of these pallet components resemble the building blocks of a smart contract. While both
+//! models are programming state transition functions of blockchains, there are crucial differences
+//! between the two. See [`crate::reference_docs::runtime_vs_smart_contract`] for more.
+//!
+//! Most of these components are defined using macros, the full list of which can be found in
+//! [`frame::pallet_macros`].
+//!
+//! ### Example
+//!
+//! The following example showcases a minimal pallet.
+#![doc = docify::embed!("src/pezkuwi_sdk/frame_runtime.rs", pallet)]
+//!
+//! ## Runtime
+//!
+//! A runtime is a collection of pallets that are amalgamated together. Each pallet typically has
+//! some configurations (exposed as a `trait Config`) that needs to be *specified* in the runtime.
+//! This is done with [`frame::runtime::prelude::construct_runtime`].
+//!
+//! A (real) runtime that actually wishes to compile to WASM needs to also implement a set of
+//! runtime-apis. These implementation can be specified using the
+//! [`frame::runtime::prelude::impl_runtime_apis`] macro.
+//!
+//! ### Example
+//!
+//! The following example shows a (test) runtime that is composing the pallet demonstrated above,
+//! next to the [`frame::prelude::frame_system`] pallet, into a runtime.
+#![doc = docify::embed!("src/pezkuwi_sdk/frame_runtime.rs", runtime)]
+//!
+//! ## More Examples
+//!
+//! You can find more FRAME examples that revolve around specific features at [`pallet_examples`].
+//!
+//! ## Alternatives 🌈
+//!
+//! There is nothing in the Substrate's node side code-base that mandates the use of FRAME. While
+//! FRAME makes it very simple to write Substrate-based runtimes, it is by no means intended to be
+//! the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is
+//! a valid Runtime form the point of view of a Substrate client (see
+//! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are:
+//!
+//! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template).
+//! * writing a runtime in AssemblyScript, as explored in [this project](https://github.com/LimeChain/subsembly).
+
+/// A FRAME based pallet. This `mod` is the entry point for everything else. All
+/// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
+/// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
+/// more.
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod pallet {
+	use frame::prelude::*;
+
+	/// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
+	/// later point from the runtime that wishes to contain it. It allows the pallet to be
+	/// parameterized over both types and values.
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		/// A type that is not known now, but the runtime that will contain this pallet will
+		/// know it later, therefore we define it here as an associated type.
+		#[allow(deprecated)]
+		type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent> + From<Event<Self>>;
+
+		/// A parameterize-able value that we receive later via the `Get<_>` trait.
+		type ValueParameter: Get<u32>;
+
+		/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
+		/// equal, but offer different tradeoffs.
+		const ANOTHER_VALUE_PARAMETER: u32;
+	}
+
+	/// A mandatory struct in each pallet. All functions callable by external users (aka.
+	/// transactions) must be attached to this type (see [`frame::pallet_macros::call`]). For
+	/// convenience, internal (private) functions can also be attached to this type.
+	#[pallet::pallet]
+	pub struct Pallet<T>(PhantomData<T>);
+
+	/// The events that this pallet can emit.
+	#[pallet::event]
+	pub enum Event<T: Config> {}
+
+	/// A storage item that this pallet contains. This will be part of the state root trie
+	/// of the blockchain.
+	#[pallet::storage]
+	pub type Value<T> = StorageValue<Value = u32>;
+
+	/// All *dispatchable* call functions (aka. transactions) are attached to `Pallet` in a
+	/// `impl` block.
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		/// This will be callable by external users, and has two u32s as a parameter.
+		pub fn some_dispatchable(
+			_origin: OriginFor<T>,
+			_param: u32,
+			_other_para: u32,
+		) -> DispatchResult {
+			Ok(())
+		}
+	}
+}
+
+/// A simple runtime that contains the above pallet and `frame_system`, the mandatory pallet of
+/// all runtimes. This runtime is for testing, but it shares a lot of similarities with a *real*
+/// runtime.
+#[docify::export]
+pub mod runtime {
+	use super::pallet as pallet_example;
+	use frame::{prelude::*, testing_prelude::*};
+
+	// The major macro that amalgamates pallets into `enum Runtime`
+	construct_runtime!(
+		pub enum Runtime {
+			System: frame_system,
+			Example: pallet_example,
+		}
+	);
+
+	// These `impl` blocks specify the parameters of each pallet's `trait Config`.
+	#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+	impl frame_system::Config for Runtime {
+		type Block = MockBlock<Self>;
+	}
+
+	impl pallet_example::Config for Runtime {
+		type RuntimeEvent = RuntimeEvent;
+		type ValueParameter = ConstU32<42>;
+		const ANOTHER_VALUE_PARAMETER: u32 = 42;
+	}
+}
@@ -0,0 +1,158 @@
+//! # Pezkuwi SDK
+//!
+//! [Pezkuwi SDK](https://github.com/pezkuwichain/pezkuwi-sdk) provides the main resources needed to
+//! start building on the [Pezkuwi network](https://pezkuwichain.io/), a scalable, multi-chain
+//! blockchain platform that enables different blockchains to securely interoperate.
+//!
+//! [![StackExchange](https://img.shields.io/badge/StackExchange-Polkadot%20and%20Substrate-222222?logo=stackexchange)](https://exchange.pezkuwichain.app/)
+//!
+//! [![awesomeDot](https://img.shields.io/badge/polkadot-awesome-e6007a?logo=polkadot)](https://github.com/Awsmdot/awesome-dot)
+//! [![wiki](https://img.shields.io/badge/polkadot-wiki-e6007a?logo=polkadot)](https://wiki.network.pezkuwichain.io/)
+//! [![forum](https://img.shields.io/badge/polkadot-forum-e6007a?logo=polkadot)](https://forum.polkadot.network/)
+//!
+//! [![RFCs](https://img.shields.io/badge/fellowship-RFCs-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/rfcs)
+//! [![Runtime](https://img.shields.io/badge/fellowship-runtimes-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/runtimes)
+//! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf)
+//!
+//! ## Getting Started
+//!
+//! The primary way to get started with the Pezkuwi SDK is to start writing a FRAME-based runtime.
+//! See:
+//!
+//! * [`pezkuwi`], to understand what is Pezkuwi as a development platform.
+//! * [`substrate`], for an overview of what Substrate as the main blockchain framework of Pezkuwi
+//!   SDK.
+//! * [`frame`], to learn about how to write blockchain applications aka. "App Chains".
+//! * Continue with the [`pezkuwi_sdk_docs`'s "getting started"](crate#getting-started).
+//!
+//! ## Components
+//!
+//! #### Substrate
+//!
+//! [![Substrate-license](https://img.shields.io/badge/License-GPL3%2FApache2.0-blue)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/substrate/LICENSE-APACHE2)
+//! [![GitHub
+//! Repo](https://img.shields.io/badge/github-substrate-2324CC85)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/substrate)
+//!
+//! [`substrate`] is the base blockchain framework used to power the Pezkuwi SDK. It is a full
+//! toolkit to create sovereign blockchains, including but not limited to those which connect to
+//! Pezkuwi as teyrchains.
+//!
+//! #### FRAME
+//!
+//! [![Substrate-license](https://img.shields.io/badge/License-Apache2.0-blue)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/substrate/LICENSE-APACHE2)
+//! [![GitHub
+//! Repo](https://img.shields.io/badge/github-frame-2324CC85)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/substrate/frame)
+//!
+//! [`frame`] is the framework used to create Substrate-based application logic, aka. runtimes.
+//! Learn more about the distinction of a runtime and node in
+//! [`reference_docs::wasm_meta_protocol`].
+//!
+//! #### Cumulus
+//!
+//! [![Cumulus-license](https://img.shields.io/badge/License-GPL3-blue)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/cumulus/LICENSE)
+//! [![GitHub
+//! Repo](https://img.shields.io/badge/github-cumulus-white)](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/cumulus)
+//!
+//! [`cumulus`] transforms FRAME-based runtimes into Pezkuwi-compatible teyrchain runtimes, and
+//! Substrate-based nodes into Pezkuwi/Teyrchain-compatible nodes.
+//!
+//! #### XCM
+//!
+//! [![XCM-license](https://img.shields.io/badge/License-GPL3-blue)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
+//! [![GitHub
+//! Repo](https://img.shields.io/badge/github-XCM-e6007a?logo=polkadot)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/xcm)
+//!
+//! [`xcm`], short for "cross consensus message", is the primary format that is used for
+//! communication between teyrchains, but is intended to be extensible to other use cases as well.
+//!
+//! #### Pezkuwi
+//!
+//! [![Pezkuwi-license](https://img.shields.io/badge/License-GPL3-blue)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
+//! [![GitHub
+//! Repo](https://img.shields.io/badge/github-polkadot-e6007a?logo=polkadot)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot)
+//!
+//! [`pezkuwi`] is an implementation of a Pezkuwi node in Rust, by `@paritytech`. The Pezkuwi
+//! runtimes are located under the
+//! [`pezkuwi-fellows/runtimes`](https://github.com/polkadot-fellows/runtimes) repository.
+//!
+//! ### Binaries
+//!
+//! The main binaries that are part of the Pezkuwi SDK are:
+
+//! * [`pezkuwi`]: The Pezkuwi relay chain node binary, as noted above.
+//! * [`pezkuwi-omni-node`]: A white-labeled teyrchain collator node. See more in
+//!   [`crate::reference_docs::omni_node`].
+//! * [`pezkuwi-teyrchain-bin`]: The collator node used to run collators for all Pezkuwi system
+//!   teyrchains.
+//! * [`frame-omni-bencher`]: a benchmarking tool for FRAME-based runtimes. Nodes typically contain
+//!   a
+//!  `benchmark` subcommand that does the same.
+//! * [`chain_spec_builder`]: Utility to build chain-specs Nodes  typically contain a `build-spec`
+//!   subcommand that does the same.
+//! * [`subkey`]: Substrate's key management utility.
+//! * [`substrate-node`](node_cli) is an extensive substrate node that contains the superset of all
+//!   runtime and node side features. The corresponding runtime, called [`kitchensink_runtime`]
+//!   contains all of the modules that are provided with `FRAME`. This node and runtime is only used
+//!   for testing and demonstration.
+//!
+//! ### Summary
+//!
+//! The following diagram summarizes how some of the components of Pezkuwi SDK work together:
+#![doc = simple_mermaid::mermaid!("../../../mermaid/pezkuwi_sdk_substrate.mmd")]
+//!
+//! A Substrate-based chain is a blockchain composed of a runtime and a node. As noted above, the
+//! runtime is the application logic of the blockchain, and the node is everything else.
+//! See [`reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The
+//! former is built with [`frame`], and the latter is built with rest of Substrate.
+//!
+//! > You can think of a Substrate-based chain as a white-labeled blockchain.
+#![doc = simple_mermaid::mermaid!("../../../mermaid/pezkuwi_sdk_pezkuwi.mmd")]
+//! Pezkuwi is itself a Substrate-based chain, composed of the exact same two components. It has
+//! specialized logic in both the node and the runtime side, but it is not "special" in any way.
+//!
+//! A teyrchain is a "special" Substrate-based chain, whereby both the node and the runtime
+//! components have became "Pezkuwi-aware" using Cumulus.
+#![doc = simple_mermaid::mermaid!("../../../mermaid/pezkuwi_sdk_teyrchain.mmd")]
+//!
+//! ## Notable Upstream Crates
+//!
+//! - [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec)
+//! - [`parity-db`](https://github.com/paritytech/parity-db)
+//! - [`trie`](https://github.com/paritytech/trie)
+//! - [`parity-common`](https://github.com/paritytech/parity-common)
+//!
+//! ## Trophy Section: Notable Downstream Projects
+//!
+//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of
+//! the Pezkuwi SDK:
+//!
+//! * [Avail](https://github.com/availproject/avail)
+//! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/)
+//! * [Starknet's Madara Sequencer](https://github.com/keep-starknet-strange/madara)
+//! * [Polymesh](https://polymesh.network/)
+//!
+//! [`substrate`]: crate::pezkuwi_sdk::substrate
+//! [`frame`]: crate::pezkuwi_sdk::frame_runtime
+//! [`cumulus`]: crate::pezkuwi_sdk::cumulus
+//! [`pezkuwi`]: crate::pezkuwi_sdk::pezkuwi
+//! [`xcm`]: crate::pezkuwi_sdk::xcm
+//! [`frame-omni-bencher`]: https://crates.io/crates/frame-omni-bencher
+//! [`pezkuwi-teyrchain-bin`]: https://crates.io/crates/polkadot-parachain-bin
+//! [`pezkuwi-omni-node`]: https://crates.io/crates/polkadot-omni-node
+
+/// Learn about Cumulus, the framework that transforms [`substrate`]-based chains into
+/// [`pezkuwi`]-enabled teyrchains.
+pub mod cumulus;
+/// Learn about FRAME, the framework used to build Substrate runtimes.
+pub mod frame_runtime;
+/// Learn about Pezkuwi as a platform.
+pub mod pezkuwi;
+/// Learn about different ways through which smart contracts can be utilized on top of Substrate,
+/// and in the Pezkuwi ecosystem.
+pub mod smart_contracts;
+/// Learn about Substrate, the main blockchain framework used in the Pezkuwi ecosystem.
+pub mod substrate;
+/// Index of all the templates that can act as first scaffold for a new project.
+pub mod templates;
+/// Learn about XCM, the de-facto communication language between different consensus systems.
+pub mod xcm;
@@ -0,0 +1,96 @@
+//! # Pezkuwi
+//!
+//! Implementation of the Pezkuwi node/host in Rust.
+//!
+//! ## Learn More and Get Involved
+//!
+//! - [Pezkuwi Forum](https://forum.polkadot.network/)
+//! - [Pezkuwi Teyrchains](https://parachains.info/)
+//! - [Pezkuwi (multi-chain) Explorer: Subscan](https://subscan.io/)
+//! - Pezkuwi Fellowship
+//!     - [Manifesto](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf)
+//!     - [Runtimes](https://github.com/polkadot-fellows/runtimes)
+//!     - [RFCs](https://github.com/polkadot-fellows/rfcs)
+//! 	- [Dashboard](https://polkadot-fellows.github.io/dashboard/)
+//! - [Pezkuwi Specs](http://spec.polkadot.network)
+//! - [The Pezkuwi Teyrchain Host Implementers' Guide](https://docs.pezkuwichain.io/sdk/book/)
+//! - [Pezkuwi papers](https://pezkuwichain.io/papers/)
+//! - [JAM Graypaper](https://graypaper.com)
+//!
+//! ## Alternative Node Implementations 🌈
+//!
+//! - [Smoldot](https://docs.rs/crate/smoldot-light/latest). Pezkuwi light node/client.
+//! - [KAGOME](https://github.com/qdrvm/kagome). C++ implementation of the Pezkuwi host.
+//! - [Gossamer](https://github.com/ChainSafe/gossamer). Golang implementation of the Pezkuwi host.
+//!
+//! ## Platform
+//!
+//! In this section, we examine what platform Pezkuwi exactly provides to developers.
+//!
+//! ### Pezkuwi White Paper
+//!
+//! The original vision of Pezkuwi (everything in the whitepaper, which was eventually called
+//! **Pezkuwi 1.0**) revolves around the following arguments:
+//!
+//! * Future is multi-chain, because we need different chains with different specialization to
+//!   achieve widespread goals.
+//! * In other words, no single chain is good enough to achieve all goals.
+//! * A multi-chain future will inadvertently suffer from fragmentation of economic security.
+//!   * This stake fragmentation will make communication over consensus system with varying security
+//!     levels inherently unsafe.
+//!
+//! Pezkuwi's answer to the above is:
+//!
+//! > The chains of the future must have a way to share their economic security, whilst maintaining
+//! > their execution and governance sovereignty. These chains are called "Teyrchains".
+//!
+//! * Shared Security: The idea of shared economic security sits at the core of Pezkuwi. Pezkuwi
+//!   enables different teyrchains to pool their economic security from Pezkuwi (i.e. "*Relay
+//!   Chain*").
+//! * (heterogenous) Sharded Execution: Yet, each teyrchain is free to have its own execution logic
+//!   (runtime), which also encompasses governance and sovereignty. Moreover, Pezkuwi ensures the
+//!   correct execution of all teyrchains, without having all of its validators re-execute all
+//!   teyrchain blocks. When seen from this perspective, Pezkuwi achieves the ability to verify
+//!   the validity of the block execution of multiple teyrchains using the same set of validators as
+//!   the Relay Chain. In practice, this means that the shards (teyrchains) share the same economic
+//!   security as the Relay Chain.
+//!   Learn about this process called [Approval Checking](https://pezkuwichain.io/blog/polkadot-v1-0-sharding-and-economic-security#approval-checking-and-finality).
+//! * A framework to build blockchains: In order to materialize the ecosystem of teyrchains, an easy
+//!   blockchain framework must exist. This is [Substrate](crate::pezkuwi_sdk::substrate),
+//!   [FRAME](crate::pezkuwi_sdk::frame_runtime) and [Cumulus](crate::pezkuwi_sdk::cumulus).
+//! * A communication language between blockchains: In order for these blockchains to communicate,
+//!   they need a shared language. [XCM](crate::pezkuwi_sdk::xcm) is one such language, and the one
+//!   that is most endorsed in the Pezkuwi ecosystem.
+//!
+//! > Note that the interoperability promised by Pezkuwi is unparalleled in that any two teyrchains
+//! > connected to Pezkuwi have the same security and can have much better guarantees about the
+//! > security of the recipient of any message.
+//! > Bridges enable transaction and information flow between different consensus systems, crucial
+//! > for Pezkuwi's multi-chain architecture. However, they can become the network's most
+//! > vulnerable points. If a bridge's security measures are weaker than those of the connected
+//! > blockchains, it poses a significant risk. Attackers might exploit these weaknesses to launch
+//! > attacks such as theft or disruption of services.
+//!
+//! Pezkuwi delivers the above vision, alongside a flexible means for teyrchains to schedule
+//! themselves with the Relay Chain. To achieve this, Pezkuwi has been developed with an
+//! architecture similar to that of a computer. Pezkuwi Relay Chain has a number of "cores". Each
+//! core is (in simple terms) capable of progressing 1 teyrchain at a time. For example, a teyrchain
+//! can schedule itself on a single core for 5 relay chain blocks.
+//!
+//! Within the scope of Pezkuwi 1.x, two main scheduling ways have been considered:
+//!
+//! * Long term Teyrchains, obtained through locking a sum of HEZ in an auction system.
+//! * On-demand Teyrchains, purchased through paying HEZ to the relay-chain whenever needed.
+//!
+//! ### The Future
+//!
+//! After delivering Pezkuwi 1.x, the future of Pezkuwi as a protocol and platform is in the hands
+//! of the community and the fellowship. This is happening most notable through the RFC process.
+//! Some of the RFCs that do alter Pezkuwi as a platform and have already passed are as follows:
+//!
+//! - RFC#1: [Agile-coretime](https://github.com/polkadot-fellows/RFCs/blob/main/text/0001-agile-coretime.md):
+//!   Agile periodic-sale-based model for assigning Coretime on the Pezkuwi Ubiquitous Computer.
+//! - RFC#5: [Coretime-interface](https://github.com/polkadot-fellows/RFCs/blob/main/text/0005-coretime-interface.md):
+//!   Interface for manipulating the usage of cores on the Pezkuwi Ubiquitous Computer.
+//!
+//! Learn more about [Pezkuwi as a Computational Resource](https://wiki.network.pezkuwichain.io/docs/polkadot-direction#polkadot-as-a-computational-resource).
@@ -0,0 +1,9 @@
+//! # Smart Contracts
+//!
+//! TODO: @cmichi <https://github.com/pezkuwichain/pezkuwi-sdk/issues/161>
+//!
+//! - WASM and EVM based, pallet-contracts and pallet-evm.
+//! - single-daap-chain, transition from ink! to FRAME.
+//! - Link to `use.ink`
+//! - Link to [`crate::reference_docs::runtime_vs_smart_contract`].
+//! - <https://use.ink/migrate-ink-contracts-to-polkadot-frame-parachain/>
@@ -0,0 +1,137 @@
+//! # Substrate
+//!
+//! Substrate is a Rust framework for building blockchains in a modular and extensible way. While in
+//! itself un-opinionated, it is the main engine behind the Pezkuwi ecosystem.
+//!
+//! ## Overview, Philosophy
+//!
+//! Substrate approaches blockchain development with an acknowledgement of a few self-evident
+//! truths:
+//!
+//! 1. Society and technology evolves.
+//! 2. Humans are fallible.
+//!
+//! This makes the task of designing a correct, safe and long-lasting blockchain system hard.
+//!
+//! Nonetheless, in strive towards achieving this goal, Substrate embraces the following:
+//!
+//! 1. Use of **Rust** as a modern and safe programming language, which limits human error through
+//!    various means, most notably memory and type safety.
+//! 2. Substrate is written from the ground-up with a *generic, modular and extensible* design. This
+//!    ensures that software components can be easily swapped and upgraded. Examples of this is
+//!    multiple consensus mechanisms provided by Substrate, as listed below.
+//! 3. Lastly, the final blockchain system created with the above properties needs to be
+//!    upgradeable. In order to achieve this, Substrate is designed as a meta-protocol, whereby the
+//!    application logic of the blockchain (called "Runtime") is encoded as a WASM blob, and is
+//!    stored in the state. The rest of the system (called "node") acts as the executor of the WASM
+//!    blob.
+//!
+//! In essence, the meta-protocol of all Substrate based chains is the "Runtime as WASM blob"
+//! accord. This enables the Runtime to become inherently upgradeable, crucially without [forks](https://en.wikipedia.org/wiki/Fork_(blockchain)). The
+//! upgrade is merely a matter of the WASM blob being changed in the state, which is, in principle,
+//! same as updating an account's balance. Learn more about this in detail in
+//! [`crate::reference_docs::wasm_meta_protocol`].
+//!
+//! > A great analogy for substrate is the following: Substrate node is a gaming console, and a WASM
+//! > runtime, possibly created with FRAME is the game being inserted into the console.
+//!
+//! [`frame`], Substrate's default runtime development library, takes the above safety practices
+//! even further by embracing a declarative programming model whereby correctness is enhanced and
+//! the system is highly configurable through parameterization. Learn more about this in
+//! [`crate::reference_docs::trait_based_programming`].
+//!
+//! ## How to Get Started
+//!
+//! Substrate offers different options at the spectrum of technical freedom <-> development ease.
+//!
+//! * The easiest way to use Substrate is to use one of the templates (some of which listed at
+//!   [`crate::pezkuwi_sdk::templates`]) and only tweak the parameters of the runtime or node. This
+//!   allows you to launch a blockchain in minutes, but is limited in technical freedom.
+//! * Next, most developers wish to develop their custom runtime modules, for which the de-facto way
+//! is [`frame`](crate::pezkuwi_sdk::frame_runtime).
+//! * Finally, Substrate is highly configurable at the node side as well, but this is the most
+//!   technically demanding.
+//!
+//! > A notable Substrate-based blockchain that has built both custom FRAME pallets and custom
+//! > node-side components is <https://github.com/Cardinal-Cryptography/aleph-node>.
+#![doc = simple_mermaid::mermaid!("../../../mermaid/substrate_dev.mmd")]
+//!
+//! ## Structure
+//!
+//! Substrate contains a large number of crates, therefore it is useful to have an overview of what
+//! they are, and how they are organized. In broad terms, these crates are divided into three
+//! categories:
+//!
+//! * `sc-*` (short for *Substrate-client*) crates, located under `./client` folder. These are all
+//!   the crates that lead to the node software. Notable examples are [`sc_network`], various
+//!   consensus crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are
+//!   expected to reside in the node side.
+//! * `sp-*` (short for *substrate-primitives*) crates, located under `./primitives` folder. These
+//!   are crates that facilitate both the node and the runtime, but are not opinionated about what
+//!   framework is using for building the runtime. Notable examples are [`sp_api`] and [`sp_io`],
+//!   which form the communication bridge between the node and runtime.
+//! * `pallet-*` and `frame-*` crates, located under `./frame` folder. These are the crates related
+//!   to FRAME. See [`frame`] for more information.
+//!
+//! ### WASM Build
+//!
+//! Many of the Substrate crates, such as entire `sp-*`, need to compile to both WASM (when a WASM
+//! runtime is being generated) and native (for example, when testing). To achieve this, Substrate
+//! follows the convention of the Rust community, and uses a `feature = "std"` to signify that a
+//!  crate is being built with the standard library, and is built for native. Otherwise, it is built
+//!  for `no_std`.
+//!
+//! This can be summarized in `#![cfg_attr(not(feature = "std"), no_std)]`, which you can often find
+//! in any Substrate-based runtime.
+//!
+//! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically
+//! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the
+//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`.
+//!
+//! In order to ensure that the WASM build is **deterministic**, the [Substrate Runtime Toolbox (srtool)](https://github.com/paritytech/srtool) can be used.
+//!
+//! ### Anatomy of a Binary Crate
+//!
+//! From the above, [`node_cli`]/[`kitchensink_runtime`] and `node-template` are essentially
+//! blueprints of a Substrate-based project, as the name of the latter is implying. Each
+//! Substrate-based project typically contains the following:
+//!
+//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
+//!   This file typically contains the [`frame::runtime::prelude::construct_runtime`] and
+//!   [`frame::runtime::prelude::impl_runtime_apis`] macro calls, which is the final definition of a
+//!   runtime.
+//!
+//! * Under `./node`, a `main.rs`, which is the starting point, and a `./service.rs`, which contains
+//!   all the node side components. Skimming this file yields an overview of the networking,
+//!   database, consensus and similar node side components.
+//!
+//! > The above two are conventions, not rules.
+//!
+//! > See <https://github.com/pezkuwichain/pezkuwi-sdk/issues/94> for an update on how the node side
+//! > components are being amalgamated.
+//!
+//! ## Teyrchain?
+//!
+//! As noted above, Substrate is the main engine behind the Pezkuwi ecosystem. One of the ways
+//! through which Pezkuwi can be utilized is by building "teyrchains", blockchains that are
+//! connected to Pezkuwi's shared security.
+//!
+//! To build a teyrchain, one could use [Cumulus](crate::pezkuwi_sdk::cumulus), the library on
+//! top of Substrate, empowering any substrate-based chain to be a Pezkuwi teyrchain.
+//!
+//! ## Where To Go Next?
+//!
+//! Additional noteworthy crates within substrate:
+//!
+//! - RPC APIs of a Substrate node: [`sc_rpc_api`]/[`sc_rpc`]
+//! - CLI Options of a Substrate node: [`sc_cli`]
+//! - All of the consensus related crates provided by Substrate:
+//!     - [`sc_consensus_aura`]
+//!     - [`sc_consensus_babe`]
+//!     - [`sc_consensus_grandpa`]
+//!     - [`sc_consensus_beefy`] (TODO: @adrian, add some high level docs <https://github.com/pezkuwichain/pezkuwi-sdk/issues/162>)
+//!     - [`sc_consensus_manual_seal`]
+//!     - [`sc_consensus_pow`]
+
+#[doc(hidden)]
+pub use crate::pezkuwi_sdk;
@@ -0,0 +1,44 @@
+//! # Templates
+//!
+//! This document enumerates a non-exhaustive list of templates that one can use to get started with
+//! pezkuwi-sdk.
+//!
+//! > Know more tools/templates that are not listed here? please contribute them by opening a PR.
+//!
+//! ## Internal
+//!
+//! The following templates are maintained as a part of the `pezkuwi-sdk` repository:
+//!
+//! - [`minimal-template`](https://github.com/pezkuwichain/pezkuwi-sdk/issues/25): A minimal
+//!   template that contains the least amount of features to be a functioning blockchain. Suitable
+//!   for learning and testing.
+//! - [`solochain-template`](https://github.com/pezkuwichain/pezkuwi-sdk/issues/25): Formerly known
+//!   as "substrate-node-template", is a white-labeled substrate-based blockchain (aka. solochain)
+//!   that contains moderate features, such as a basic consensus engine and some FRAME pallets. This
+//!   template can act as a good starting point for those who want to launch a solochain.
+//! - [`teyrchain-template`](https://github.com/pezkuwichain/pezkuwi-sdk-teyrchain-template):
+//! A teyrchain template ready to be connected to a relay-chain, such as [Paseo](https://github.com/paseo-network/.github)
+//! , Kusama  or Pezkuwi.
+//!
+//! Note that these templates are mirrored automatically from [this](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/templates)
+//! directory of pezkuwi-sdk, therefore any changes to them should be made as a PR to this repo.
+//!
+//! ## OpenZeppelin
+//!
+//! In June 2023, OpenZeppelin was awarded a grant from the Pezkuwi
+//! treasury for building a number of Pezkuwi-sdk
+//! based templates. These templates are a great starting point for developers and newcomers.
+//! So far OpenZeppelin has released two templates, which have been fully [audited](https://github.com/pezkuwichain/polkadot-runtime-templates/tree/main/audits):
+//! - [`generic-runtime-template`](https://github.com/pezkuwichain/polkadot-runtime-templates?tab=readme-ov-file#generic-runtime-template):
+//!   A minimal template that has all the common pallets that teyrchains use with secure defaults.
+//! - [`evm-runtime-template`](https://github.com/pezkuwichain/polkadot-runtime-templates/tree/main?tab=readme-ov-file#evm-template):
+//! This template has EVM compatibility out of the box and allows migrating your solidity contracts
+//! or EVM compatible dapps easily. It also uses 20 byte addresses like Ethereum and has some
+//! Account Abstraction support.
+//!
+//! ## POP-CLI
+//!
+//! Is a CLI tool capable of scaffolding a new pezkuwi-sdk-based project, possibly removing the
+//! need for templates.
+//!
+//! - <https://pop.r0gue.io/cli/>
@@ -0,0 +1,70 @@
+//! # XCM
+//!
+//! XCM, or Cross-Consensus Messaging, is a **language** to communicate **intentions** between
+//! **consensus systems**.
+//!
+//! ## Overview
+//!
+//! XCM is a standard, specification of which lives in the [xcm format repo](https://github.com/paritytech/xcm-format).
+//! It's agnostic both in programming language and blockchain platform, which means it could be used
+//! in Rust in Pezkuwi, or in Go or C++ in any other platform like Cosmos or Ethereum.
+//!
+//! It enables different consensus systems to communicate with each other in an expressive manner.
+//! Consensus systems include blockchains, smart contracts, and any other state machine that
+//! achieves consensus in some way.
+//!
+//! XCM is executed on a virtual machine called the XCVM.
+//! Scripts can be written with the XCM language, which are often called XCMs, messages or XCM
+//! programs. Each program is a series of instructions, which get executed one after the other by
+//! the virtual machine. These instructions aim to encompass all major things users typically do in
+//! consensus systems. There are instructions on asset transferring, teleporting, locking, among
+//! others. New instructions are added and changes to the XCVM are made via the [RFC process](https://github.com/paritytech/xcm-format/blob/master/proposals/0032-process.md).
+//!
+//! ## In Pezkuwi SDK
+//!
+//! The Pezkuwi SDK allows for easily deploying sovereign blockchains from scratch, all very
+//! customizable. Dealing with many heterogeneous blockchains can be cumbersome.
+//! XCM allows all these blockchains to communicate with an agreed-upon language.
+//! As long as an implementation of the XCVM is implemented, the same XCM program can be executed in
+//! all blockchains and perform the same task.
+//!
+//! ## Implementation
+//!
+//! A ready-to-use Rust implementation lives in the [pezkuwi-sdk repo](https://github.com/paritytech/polkadot-sdk/tree/master/polkadot/xcm),
+//! but will be moved to its own repo in the future.
+//!
+//! Its main components are:
+//! - [`xcm`](::xcm): The definition of the basic types and instructions.
+//! - [`xcm_executor`]: An implementation of the virtual machine to execute instructions.
+//! - [`pallet_xcm`]: A FRAME pallet for interacting with the executor.
+//! - [`xcm_builder`]: A collection of types to configure the executor.
+//! - [`xcm_simulator`]: A playground for trying out different XCM programs and executor
+//!   configurations.
+//!
+//! ## Example
+//!
+//! To perform the very usual operation of transferring assets, the following XCM program can be
+//! used:
+#![doc = docify::embed!("src/pezkuwi_sdk/xcm.rs", example_transfer)]
+//!
+//! ## Get started
+//!
+//! To learn how it works and to get started, go to the [XCM docs](xcm_docs).
+
+#[cfg(test)]
+mod tests {
+	use xcm::latest::prelude::*;
+
+	#[docify::export]
+	#[test]
+	fn example_transfer() {
+		let _transfer_program = Xcm::<()>(vec![
+			WithdrawAsset((Here, 100u128).into()),
+			BuyExecution { fees: (Here, 100u128).into(), weight_limit: Unlimited },
+			DepositAsset {
+				assets: All.into(),
+				beneficiary: AccountId32 { id: [0u8; 32].into(), network: None }.into(),
+			},
+		]);
+	}
+}
@@ -0,0 +1,29 @@
+//! # State Transition Function
+//!
+//! This document briefly explains how in the context of Substrate-based blockchains, we view the
+//! blockchain as a **decentralized state transition function**.
+//!
+//! Recall that a blockchain's main purpose is to help a permissionless set of entities to agree on
+//! a shared data-set, and how it evolves. This is called the **State**, also referred to as
+//! "onchain" data, or *Storage* in the context of FRAME. The state is where the account balance of
+//! each user is, for example, stored, and there is a canonical version of it that everyone agrees
+//! upon.
+//!
+//! Then, recall that a typical blockchain system will alter its state through execution of blocks.
+//! *The component that dictates how this state alteration can happen is called the state transition
+//! function*.
+#![doc = simple_mermaid::mermaid!("../../../mermaid/stf_simple.mmd")]
+//!
+//! In Substrate-based blockchains, the state transition function is called the *Runtime*. This is
+//! explained further in [`crate::reference_docs::wasm_meta_protocol`].
+//!
+//! With this in mind, we can paint a complete picture of a blockchain as a state machine:
+#![doc = simple_mermaid::mermaid!("../../../mermaid/stf.mmd")]
+//!
+//! In essence, the state of the blockchain at block N is the outcome of applying the state
+//! transition function to the previous state, and the current block as input. This can be
+//! mathematically represented as:
+//!
+//! ```math
+//! STF = F(State_N, Block_N) -> State_{N+1}
+//! ```
@@ -0,0 +1,200 @@
+//! # What is a chain specification
+//!
+//! A chain specification file defines the set of properties that are required to run the node as
+//! part of the chain. The chain specification consists of two main parts:
+//! - initial state of the runtime,
+//! - network / logical properties of the chain, the most important property being the list of
+//!   bootnodes.
+//!
+//! This document describes how the initial state is handled in pallets and runtime, and how to
+//! interact with the runtime in order to build the genesis state.
+//!
+//! For more information on chain specification and its properties, refer to
+//! [`sc_chain_spec#from-initial-state-to-raw-genesis`].
+//!
+//! The initial genesis state can be provided in the following formats:
+//!   - full
+//!   - patch
+//!   - raw
+//!
+//! Each of the formats is explained in [_chain-spec-format_][`sc_chain_spec#chain-spec-formats`].
+//!
+//!
+//! # `GenesisConfig` for `pallet`
+//!
+//! Every frame pallet may have its initial state which is defined by the `GenesisConfig` internal
+//! struct. It is a regular Rust struct, annotated with the [`pallet::genesis_config`] attribute.
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar_GenesisConfig)]
+//!
+//! The struct shall be defined within the pallet `mod`, as in the following code:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar)]
+//!
+//! The initial state conveyed in  the `GenesisConfig` struct is transformed into state storage
+//! items by means of the [`BuildGenesisConfig`] trait, which shall be implemented for the pallet's
+//! `GenesisConfig` struct. The [`pallet::genesis_build`] attribute shall be attached to the `impl`
+//! block:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_bar_build)]
+//!
+//! `GenesisConfig` may also contain more complicated types, including nested structs or enums, as
+//! in the example for `pallet_foo`:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_foo_GenesisConfig)]
+//!
+//! Note that [`serde`] attributes can be used to control how the data
+//! structures are stored into JSON. In the following example, the [`sp_core::bytes`] function is
+//! used to serialize the `values` field.
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", SomeFooData2)]
+//!
+//! Please note that fields of `GenesisConfig` may not be directly mapped to storage items. In the
+//! following example, the initial struct fields are used to compute (sum) the value that will be
+//! stored in the state as `ProcessedEnumValue`:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/pallets.rs", pallet_foo_build)]
+//!
+//! # `GenesisConfig` for `runtimes`
+//!
+//! The runtime genesis config struct consists of configs for every pallet. For the [_demonstration
+//! runtime_][`chain_spec_guide_runtime`] used in this guide, it consists of `SystemConfig`,
+//! `BarConfig`, and `FooConfig`. This structure was automatically generated by a macro and it can
+//! be sneak-peeked here: [`RuntimeGenesisConfig`]. For further reading on generated runtime
+//! types, refer to [`frame_runtime_types`].
+//!
+//! The macro automatically adds an attribute that renames all the fields to [`camelCase`]. It is a
+//! good practice to add it to nested structures too, to have the naming of the JSON keys consistent
+//! across the chain-spec file.
+//!
+//! ## `Default` for `GenesisConfig`
+//!
+//! `GenesisConfig` of all pallets must implement the `Default` trait. These are aggregated into
+//! the runtime's `RuntimeGenesisConfig`'s `Default`.
+//!
+//! The default value of `RuntimeGenesisConfig` can be queried by the [`GenesisBuilder::get_preset`]
+//! function provided by the runtime with `id:None`.
+//!
+//! A default value for `RuntimeGenesisConfig` usually is not operational. This is because for some
+//! pallets it is not possible to define good defaults (e.g. an initial set of authorities).
+//!
+//! A default value is a base upon which a patch for `GenesisConfig` is applied. A good description
+//! of how it exactly works is provided in [`get_storage_for_patch`] (and also in
+//! [`GenesisBuilder::get_preset`]). A patch can be provided as an external file (manually created)
+//! or as a built-in runtime preset. More info on presets is in the material to follow.
+//!
+//! ## Implementing `GenesisBuilder` for runtime
+//!
+//! The runtime exposes a dedicated runtime API for interacting with its genesis config:
+//! [`sp_genesis_builder::GenesisBuilder`]. The implementation shall be provided within
+//! the [`sp_api::impl_runtime_apis`] macro, typically making use of some helpers provided:
+//! [`build_state`], [`get_preset`].
+//! A typical implementation of [`sp_genesis_builder::GenesisBuilder`] looks as follows:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/runtime.rs", runtime_impl)]
+//!
+//! Please note that two functions are customized: `preset_names` and `get_preset`. The first one
+//! just provides a `Vec` of the names of supported presets, while the latter delegates the call
+//! to a function that maps the name to an actual preset:
+//! [`chain_spec_guide_runtime::presets::get_builtin_preset`]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", get_builtin_preset)]
+//!
+//! ## Genesis state presets for runtime
+//!
+//! The runtime may provide many flavors of initial genesis state. This may be useful for predefined
+//! testing networks, local development, or CI integration tests. Predefined genesis state may
+//! contain a list of pre-funded accounts, predefined authorities for consensus, sudo key, and many
+//! others useful for testing.
+//!
+//! Internally, presets can be provided in a number of ways:
+//! - using [`build_struct_json_patch`] macro (**recommended**):
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_2)]
+//! - JSON using runtime types to serialize values:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_3)]
+//! - JSON in string form:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_1)]
+//!
+//! It is worth noting that a preset does not have to be the full `RuntimeGenesisConfig`, in that
+//! sense that it does not have to contain all the keys of the struct. The preset is actually a JSON
+//! patch that will be merged with the default value of `RuntimeGenesisConfig`. This approach should
+//! simplify maintenance of built-in presets. The following example illustrates a runtime genesis
+//! config patch with a single key built using [`build_struct_json_patch`] macro:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_4)]
+//! This results in the following JSON blob:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", preset_4_json)]
+//!
+//!
+//! ## Note on the importance of testing presets
+//!
+//! It is recommended to always test presets by adding tests that convert the preset into the
+//! raw storage. Converting to raw storage involves the deserialization of the provided JSON blob,
+//! which enforces the verification of the preset. The following code shows one of the approaches
+//! that can be taken for testing:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", check_presets)]
+//!
+//! ## Note on the importance of using the `deny_unknown_fields` attribute
+//!
+//! It is worth noting that when manually building preset JSON blobs it is easy to make a
+//! hard-to-spot mistake, as in the following example ([`FooStruct`] does not contain `fieldC`):
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", preset_invalid)]
+//! Even though `preset_invalid` contains a key that does not exist, the deserialization of the JSON
+//! blob does not fail. The misspelling is silently ignored due to the lack of the
+//! [`deny_unknown_fields`] attribute on the [`FooStruct`] struct, which is internally used in
+//! `GenesisConfig`.
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/src/presets.rs", invalid_preset_works)]
+//!
+//! To avoid this problem [`build_struct_json_patch`] macro shall be used whenever possible (it
+//! internally instantiates the struct before serializang it JSON blob, so all unknown fields shall
+//! be caught at compilation time).
+//!
+//! ## Runtime `GenesisConfig` raw format
+//!
+//! A raw format of genesis config contains just the state's keys and values as they are stored in
+//! the storage. This format is used to directly initialize the genesis storage. This format is
+//! useful for long-term running chains, where the `GenesisConfig` structure for pallets may be
+//! evolving over time. The JSON representation created at some point in time may no longer be
+//! deserializable in the future, making a chain specification useless. The raw format is
+//! recommended for production chains.
+//!
+//! For a detailed description of how the raw format is built, please refer to
+//! [_chain-spec-raw-genesis_][`sc_chain_spec#from-initial-state-to-raw-genesis`]. Plain and
+//! corresponding raw examples of chain-spec are given in
+//! [_chain-spec-examples_][`sc_chain_spec#json-chain-specification-example`].
+//! The [`chain_spec_builder`] util supports building the raw storage.
+//!
+//! # Interacting with the tool
+//!
+//! The [`chain_spec_builder`] util allows interaction with the runtime in order to list or display
+//! presets and build the chain specification file. It is possible to use the tool with the
+//! [_demonstration runtime_][`chain_spec_guide_runtime`]. To build the required packages, just run
+//! the following command:
+//!
+//! ```ignore
+//! cargo build -p staging-chain-spec-builder -p chain-spec-guide-runtime --release
+//! ```
+//!
+//! The `chain-spec-builder` util can also be installed with `cargo install`:
+//!
+//! ```ignore
+//! cargo install staging-chain-spec-builder
+//! cargo build -p chain-spec-guide-runtime --release
+//! ```
+//! Here are some examples in the form of rust tests:
+//! ## Listing available preset names:
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_list_presets)]
+//! ## Displaying preset with given name
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_get_preset)]
+//! ## Building a solo chain-spec (the default) using given preset
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_generate_chain_spec)]
+//! ## Building a teyrchain chain-spec using given preset
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_generate_para_chain_spec)]
+//!
+//! [`RuntimeGenesisConfig`]:
+//!     chain_spec_guide_runtime::runtime::RuntimeGenesisConfig
+//! [`FooStruct`]:
+//!     chain_spec_guide_runtime::pallets::FooStruct
+//! [`impl_runtime_apis`]: frame::runtime::prelude::impl_runtime_apis
+//! [`build_state`]: frame_support::genesis_builder_helper::build_state
+//! [`get_preset`]: frame_support::genesis_builder_helper::get_preset
+//! [`pallet::genesis_build`]: frame_support::pallet_macros::genesis_build
+//! [`pallet::genesis_config`]: frame_support::pallet_macros::genesis_config
+//! [`build_struct_json_patch`]: frame_support::build_struct_json_patch
+//! [`BuildGenesisConfig`]: frame_support::traits::BuildGenesisConfig
+//! [`serde`]: https://serde.rs/field-attrs.html
+//! [`get_storage_for_patch`]: sc_chain_spec::GenesisConfigBuilderRuntimeCaller::get_storage_for_patch
+//! [`GenesisBuilder::get_preset`]: sp_genesis_builder::GenesisBuilder::get_preset
+//! [`deny_unknown_fields`]: https://serde.rs/container-attrs.html#deny_unknown_fields
+//! [`camelCase`]: https://serde.rs/container-attrs.html#rename_all
@@ -0,0 +1,64 @@
+[package]
+name = "chain-spec-guide-runtime"
+description = "A minimal runtime for chain spec guide"
+version = "0.0.0"
+license = "MIT-0"
+authors.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+publish = false
+
+[dependencies]
+codec = { workspace = true }
+docify = { workspace = true }
+frame-support = { workspace = true }
+scale-info = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+# this is a frame-based runtime, thus importing `frame` with runtime feature enabled.
+frame = { features = ["experimental", "runtime"], workspace = true }
+
+# genesis builder that allows us to interact with runtime genesis config
+sp-application-crypto = { features = ["serde"], workspace = true }
+sp-core = { workspace = true }
+sp-genesis-builder = { workspace = true }
+sp-keyring = { workspace = true }
+sp-runtime = { features = ["serde"], workspace = true }
+
+[dev-dependencies]
+cmd_lib = { workspace = true }
+sc-chain-spec = { workspace = true, default-features = true }
+
+[build-dependencies]
+substrate-wasm-builder = { optional = true, workspace = true, default-features = true }
+
+[features]
+default = ["std"]
+std = [
+	"codec/std",
+	"scale-info/std",
+
+	"frame-support/std",
+	"frame/std",
+
+	"sp-application-crypto/std",
+	"sp-core/std",
+	"sp-genesis-builder/std",
+	"sp-keyring/std",
+	"sp-runtime/std",
+
+	"serde/std",
+	"serde_json/std",
+	"substrate-wasm-builder",
+]
+runtime-benchmarks = [
+	"frame-support/runtime-benchmarks",
+	"frame/runtime-benchmarks",
+	"sc-chain-spec/runtime-benchmarks",
+	"sp-genesis-builder/runtime-benchmarks",
+	"sp-keyring/runtime-benchmarks",
+	"sp-runtime/runtime-benchmarks",
+	"substrate-wasm-builder?/runtime-benchmarks",
+]
@@ -0,0 +1,23 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+fn main() {
+	#[cfg(feature = "std")]
+	{
+		substrate_wasm_builder::WasmBuilder::build_using_defaults();
+	}
+}
@@ -0,0 +1,29 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! A minimal runtime that shows runtime genesis state.
+
+extern crate alloc;
+
+pub mod pallets;
+pub mod presets;
+pub mod runtime;
+
+#[cfg(feature = "std")]
+pub use runtime::{WASM_BINARY, WASM_BINARY_BLOATY};
@@ -0,0 +1,138 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Pallets for the chain-spec demo runtime.
+
+use alloc::vec::Vec;
+use frame::prelude::*;
+
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod pallet_bar {
+	use super::*;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[pallet::storage]
+	pub(super) type InitialAccount<T: Config> = StorageValue<Value = T::AccountId>;
+
+	/// Simple `GenesisConfig`.
+	#[pallet::genesis_config]
+	#[derive(DefaultNoBound)]
+	#[docify::export(pallet_bar_GenesisConfig)]
+	pub struct GenesisConfig<T: Config> {
+		pub initial_account: Option<T::AccountId>,
+	}
+
+	#[pallet::genesis_build]
+	#[docify::export(pallet_bar_build)]
+	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
+		/// The storage building function that presents a direct mapping of the initial config
+		/// values to the storage items.
+		fn build(&self) {
+			InitialAccount::<T>::set(self.initial_account.clone());
+		}
+	}
+}
+
+/// The sample structure used in `GenesisConfig`.
+///
+/// This structure does not deny unknown fields. This may lead to some problems.
+#[derive(Default, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FooStruct {
+	pub field_a: u8,
+	pub field_b: u8,
+}
+
+/// The sample structure used in `GenesisConfig`.
+///
+/// This structure does not deny unknown fields. This may lead to some problems.
+#[derive(Default, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub struct SomeFooData1 {
+	pub a: u8,
+	pub b: u8,
+}
+
+/// Another sample structure used in `GenesisConfig`.
+///
+/// The user defined serialization is used.
+#[derive(Default, serde::Serialize, serde::Deserialize)]
+#[docify::export]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub struct SomeFooData2 {
+	#[serde(default, with = "sp_core::bytes")]
+	pub values: Vec<u8>,
+}
+
+/// Sample enum used in `GenesisConfig`.
+#[derive(Default, serde::Serialize, serde::Deserialize)]
+pub enum FooEnum {
+	#[default]
+	Data0,
+	Data1(SomeFooData1),
+	Data2(SomeFooData2),
+}
+
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod pallet_foo {
+	use super::*;
+
+	#[pallet::config]
+	pub trait Config: frame_system::Config {}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(_);
+
+	#[pallet::storage]
+	pub type ProcessedEnumValue<T> = StorageValue<Value = u64>;
+	#[pallet::storage]
+	pub type SomeInteger<T> = StorageValue<Value = u32>;
+
+	/// The more sophisticated structure for conveying initial state.
+	#[docify::export(pallet_foo_GenesisConfig)]
+	#[pallet::genesis_config]
+	#[derive(DefaultNoBound)]
+	pub struct GenesisConfig<T: Config> {
+		pub some_integer: u32,
+		pub some_enum: FooEnum,
+		pub some_struct: FooStruct,
+		#[serde(skip)]
+		pub _phantom: PhantomData<T>,
+	}
+
+	#[pallet::genesis_build]
+	#[docify::export(pallet_foo_build)]
+	impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
+		/// The build method that indirectly maps an initial config values into the storage items.
+		fn build(&self) {
+			let processed_value: u64 = match &self.some_enum {
+				FooEnum::Data0 => 0,
+				FooEnum::Data1(v) => (v.a + v.b).into(),
+				FooEnum::Data2(v) => v.values.iter().map(|v| *v as u64).sum(),
+			};
+			ProcessedEnumValue::<T>::set(Some(processed_value));
+			SomeInteger::<T>::set(Some(self.some_integer));
+		}
+	}
+}
@@ -0,0 +1,164 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Presets for the chain-spec demo runtime.
+
+use crate::{
+	pallets::{FooEnum, SomeFooData1, SomeFooData2},
+	runtime::{BarConfig, FooConfig, RuntimeGenesisConfig},
+};
+use alloc::vec;
+use frame_support::build_struct_json_patch;
+use serde_json::{json, to_string, Value};
+use sp_application_crypto::Ss58Codec;
+use sp_keyring::Sr25519Keyring;
+
+/// A demo preset with strings only.
+pub const PRESET_1: &str = "preset_1";
+/// A demo preset with real types.
+pub const PRESET_2: &str = "preset_2";
+/// Another demo preset with real types and manually created json object.
+pub const PRESET_3: &str = "preset_3";
+/// A single value patch preset.
+pub const PRESET_4: &str = "preset_4";
+/// A single value patch preset.
+pub const PRESET_INVALID: &str = "preset_invalid";
+
+#[docify::export]
+/// Function provides a preset demonstrating how use string representation of preset's internal
+/// values.
+fn preset_1() -> Value {
+	json!({
+		"bar": {
+			"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
+		},
+		"foo": {
+			"someEnum": {
+				"Data2": {
+					"values": "0x0c0f"
+				}
+			},
+			"someStruct" : {
+				"fieldA": 10,
+				"fieldB": 20
+			},
+			"someInteger": 100
+		},
+	})
+}
+
+#[docify::export]
+/// Function provides a preset demonstrating how to create a preset using
+/// [`build_struct_json_patch`] macro.
+fn preset_2() -> Value {
+	build_struct_json_patch!(RuntimeGenesisConfig {
+		foo: FooConfig {
+			some_integer: 200,
+			some_enum: FooEnum::Data2(SomeFooData2 { values: vec![0x0c, 0x10] })
+		},
+		bar: BarConfig { initial_account: Some(Sr25519Keyring::Ferdie.public().into()) },
+	})
+}
+
+#[docify::export]
+/// Function provides a preset demonstrating how use the actual types to manually create a JSON
+/// representing the preset.
+fn preset_3() -> Value {
+	json!({
+		"bar": {
+			"initialAccount": Sr25519Keyring::Alice.public().to_ss58check(),
+		},
+		"foo": {
+			"someEnum": FooEnum::Data1(
+				SomeFooData1 {
+					a: 12,
+					b: 16
+				}
+			),
+			"someInteger": 300
+		},
+	})
+}
+
+#[docify::export]
+/// Function provides a minimal preset demonstrating how to patch single key in
+/// `RuntimeGenesisConfig` using [`build_struct_json_patch`] macro.
+pub fn preset_4() -> Value {
+	build_struct_json_patch!(RuntimeGenesisConfig {
+		foo: FooConfig { some_enum: FooEnum::Data2(SomeFooData2 { values: vec![0x0c, 0x10] }) },
+	})
+}
+
+#[docify::export]
+/// Function provides an invalid preset demonstrating how important is use of
+/// `deny_unknown_fields` in data structures used in `GenesisConfig`.
+fn preset_invalid() -> Value {
+	json!({
+		"foo": {
+			"someStruct": {
+				"fieldC": 5
+			},
+		},
+	})
+}
+
+/// Provides a JSON representation of preset identified by given `id`.
+///
+/// If no preset with given `id` exits `None` is returned.
+#[docify::export]
+pub fn get_builtin_preset(id: &sp_genesis_builder::PresetId) -> Option<alloc::vec::Vec<u8>> {
+	let preset = match id.as_ref() {
+		PRESET_1 => preset_1(),
+		PRESET_2 => preset_2(),
+		PRESET_3 => preset_3(),
+		PRESET_4 => preset_4(),
+		PRESET_INVALID => preset_invalid(),
+		_ => return None,
+	};
+
+	Some(
+		to_string(&preset)
+			.expect("serialization to json is expected to work. qed.")
+			.into_bytes(),
+	)
+}
+
+#[test]
+#[docify::export]
+fn check_presets() {
+	let builder = sc_chain_spec::GenesisConfigBuilderRuntimeCaller::<()>::new(
+		crate::WASM_BINARY.expect("wasm binary shall exists"),
+	);
+	assert!(builder.get_storage_for_named_preset(Some(&PRESET_1.to_string())).is_ok());
+	assert!(builder.get_storage_for_named_preset(Some(&PRESET_2.to_string())).is_ok());
+	assert!(builder.get_storage_for_named_preset(Some(&PRESET_3.to_string())).is_ok());
+	assert!(builder.get_storage_for_named_preset(Some(&PRESET_4.to_string())).is_ok());
+}
+
+#[test]
+#[docify::export]
+fn invalid_preset_works() {
+	let builder = sc_chain_spec::GenesisConfigBuilderRuntimeCaller::<()>::new(
+		crate::WASM_BINARY.expect("wasm binary shall exists"),
+	);
+	// Even though a preset contains invalid_key, conversion to raw storage does not fail. This is
+	// because the [`FooStruct`] structure is not annotated with `deny_unknown_fields` [`serde`]
+	// attribute.
+	// This may lead to hard to debug problems, that's why using ['deny_unknown_fields'] is
+	// recommended.
+	assert!(builder.get_storage_for_named_preset(Some(&PRESET_INVALID.to_string())).is_ok());
+}
@@ -0,0 +1,127 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! A minimal runtime that shows runtime genesis state.
+
+// Make the WASM binary available.
+#[cfg(feature = "std")]
+include!(concat!(env!("OUT_DIR"), "/wasm_binary.rs"));
+
+use crate::{
+	pallets::{pallet_bar, pallet_foo},
+	presets::*,
+};
+use alloc::{vec, vec::Vec};
+use frame::{
+	deps::frame_support::{
+		genesis_builder_helper::{build_state, get_preset},
+		runtime,
+	},
+	prelude::*,
+	runtime::{apis, prelude::*},
+};
+use sp_genesis_builder::PresetId;
+
+/// The runtime version.
+#[runtime_version]
+pub const VERSION: RuntimeVersion = RuntimeVersion {
+	spec_name: alloc::borrow::Cow::Borrowed("minimal-template-runtime"),
+	impl_name: alloc::borrow::Cow::Borrowed("minimal-template-runtime"),
+	authoring_version: 1,
+	spec_version: 0,
+	impl_version: 1,
+	apis: RUNTIME_API_VERSIONS,
+	transaction_version: 1,
+	system_version: 1,
+};
+
+/// The signed extensions that are added to the runtime.
+type SignedExtra = ();
+
+// Composes the runtime by adding all the used pallets and deriving necessary types.
+#[runtime]
+mod runtime {
+	/// The main runtime type.
+	#[runtime::runtime]
+	#[runtime::derive(
+		RuntimeCall,
+		RuntimeEvent,
+		RuntimeError,
+		RuntimeOrigin,
+		RuntimeTask,
+		RuntimeViewFunction
+	)]
+	pub struct Runtime;
+
+	/// Mandatory system pallet that should always be included in a FRAME runtime.
+	#[runtime::pallet_index(0)]
+	pub type System = frame_system;
+
+	/// Sample pallet 1
+	#[runtime::pallet_index(1)]
+	pub type Bar = pallet_bar;
+
+	/// Sample pallet 2
+	#[runtime::pallet_index(2)]
+	pub type Foo = pallet_foo;
+}
+
+parameter_types! {
+	pub const Version: RuntimeVersion = VERSION;
+}
+
+/// Implements the types required for the system pallet.
+#[derive_impl(frame_system::config_preludes::SolochainDefaultConfig)]
+impl frame_system::Config for Runtime {
+	type Block = Block;
+	type Version = Version;
+}
+
+impl pallet_bar::Config for Runtime {}
+impl pallet_foo::Config for Runtime {}
+
+type Block = frame::runtime::types_common::BlockOf<Runtime, SignedExtra>;
+type Header = HeaderFor<Runtime>;
+
+#[docify::export(runtime_impl)]
+impl_runtime_apis! {
+	impl sp_genesis_builder::GenesisBuilder<Block> for Runtime {
+		fn build_state(config: Vec<u8>) -> sp_genesis_builder::Result {
+			build_state::<RuntimeGenesisConfig>(config)
+		}
+
+		fn get_preset(id: &Option<sp_genesis_builder::PresetId>) -> Option<Vec<u8>> {
+			get_preset::<RuntimeGenesisConfig>(id, get_builtin_preset)
+		}
+
+		fn preset_names() -> Vec<sp_genesis_builder::PresetId> {
+			vec![
+				PresetId::from(PRESET_1),
+				PresetId::from(PRESET_2),
+				PresetId::from(PRESET_3),
+				PresetId::from(PRESET_4),
+				PresetId::from(PRESET_INVALID)
+			]
+		}
+	}
+
+	impl apis::Core<Block> for Runtime {
+		fn version() -> RuntimeVersion { VERSION }
+		fn execute_block(_: <Block as frame::traits::Block>::LazyBlock) { }
+		fn initialize_block(_: &Header) -> ExtrinsicInclusionMode { ExtrinsicInclusionMode::default() }
+	}
+}
@@ -0,0 +1,203 @@
+use cmd_lib::*;
+use serde_json::{json, Value};
+use std::str;
+
+fn wasm_file_path() -> &'static str {
+	chain_spec_guide_runtime::runtime::WASM_BINARY_PATH
+		.expect("chain_spec_guide_runtime wasm should exist. qed")
+}
+
+const CHAIN_SPEC_BUILDER_PATH: &str = "../../../../../target/release/chain-spec-builder";
+
+macro_rules! bash(
+	( chain-spec-builder $($a:tt)* ) => {{
+		let path = get_chain_spec_builder_path();
+		spawn_with_output!(
+			$path $($a)*
+		)
+		.expect("a process running. qed")
+		.wait_with_output()
+		.expect("to get output. qed.")
+
+	}}
+);
+
+fn get_chain_spec_builder_path() -> &'static str {
+	run_cmd!(
+		cargo build --release -p staging-chain-spec-builder --bin chain-spec-builder
+	)
+	.expect("Failed to execute command");
+	CHAIN_SPEC_BUILDER_PATH
+}
+
+#[docify::export_content]
+fn cmd_list_presets(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder list-presets -r $runtime_path
+	)
+}
+
+#[test]
+fn list_presets() {
+	let output: serde_json::Value =
+		serde_json::from_slice(cmd_list_presets(wasm_file_path()).as_bytes()).unwrap();
+	assert_eq!(
+		output,
+		json!({
+			"presets":[
+				"preset_1",
+				"preset_2",
+				"preset_3",
+				"preset_4",
+				"preset_invalid"
+			]
+		}),
+		"Output did not match expected"
+	);
+}
+
+#[docify::export_content]
+fn cmd_get_preset(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder display-preset -r $runtime_path -p preset_2
+	)
+}
+
+#[test]
+fn get_preset() {
+	let output: serde_json::Value =
+		serde_json::from_slice(cmd_get_preset(wasm_file_path()).as_bytes()).unwrap();
+	assert_eq!(
+		output,
+		json!({
+			"bar": {
+				"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
+			},
+			"foo": {
+				"someEnum": {
+					"Data2": {
+						"values": "0x0c10"
+					}
+				},
+				"someInteger": 200
+			},
+		}),
+		"Output did not match expected"
+	);
+}
+
+#[docify::export_content]
+fn cmd_generate_chain_spec(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder -c /dev/stdout create -r $runtime_path named-preset preset_2
+	)
+}
+
+#[test]
+fn generate_chain_spec() {
+	let mut output: serde_json::Value =
+		serde_json::from_slice(cmd_generate_chain_spec(wasm_file_path()).as_bytes()).unwrap();
+	if let Some(code) = output["genesis"]["runtimeGenesis"].as_object_mut().unwrap().get_mut("code")
+	{
+		*code = Value::String("0x123".to_string());
+	}
+	assert_eq!(
+		output,
+		json!({
+		  "name": "Custom",
+		  "id": "custom",
+		  "chainType": "Live",
+		  "bootNodes": [],
+		  "telemetryEndpoints": null,
+		  "protocolId": null,
+		  "properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
+		  "codeSubstitutes": {},
+		  "genesis": {
+			"runtimeGenesis": {
+			  "code": "0x123",
+			  "patch": {
+				"bar": {
+				  "initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
+				},
+				"foo": {
+				  "someEnum": {
+					"Data2": {
+					  "values": "0x0c10"
+					}
+				  },
+				  "someInteger": 200
+				}
+			  }
+			}
+		  }
+		}),
+		"Output did not match expected"
+	);
+}
+
+#[docify::export_content]
+fn cmd_generate_para_chain_spec(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder -c /dev/stdout create -c pezkuwi -p 1000 -r $runtime_path named-preset preset_2
+	)
+}
+
+#[test]
+fn generate_para_chain_spec() {
+	let mut output: serde_json::Value =
+		serde_json::from_slice(cmd_generate_para_chain_spec(wasm_file_path()).as_bytes()).unwrap();
+	if let Some(code) = output["genesis"]["runtimeGenesis"].as_object_mut().unwrap().get_mut("code")
+	{
+		*code = Value::String("0x123".to_string());
+	}
+	assert_eq!(
+		output,
+		json!({
+		"name": "Custom",
+		"id": "custom",
+		"chainType": "Live",
+		"bootNodes": [],
+		"telemetryEndpoints": null,
+		"protocolId": null,
+		"relay_chain": "pezkuwi",
+		"para_id": 1000,
+		"properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
+		"codeSubstitutes": {},
+		"genesis": {
+		  "runtimeGenesis": {
+			"code": "0x123",
+			"patch": {
+			  "bar": {
+				"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
+			  },
+			  "foo": {
+				"someEnum": {
+				  "Data2": {
+					"values": "0x0c10"
+				  }
+				},
+				"someInteger": 200
+			  }
+			}
+		  }
+		}}),
+		"Output did not match expected"
+	);
+}
+
+#[test]
+#[docify::export_content]
+fn preset_4_json() {
+	assert_eq!(
+		chain_spec_guide_runtime::presets::preset_4(),
+		json!({
+			"foo": {
+				"someEnum": {
+					"Data2": {
+						"values": "0x0c10"
+					}
+				},
+			},
+		})
+	);
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1,2 @@`
				`<script> mermaid.init({ startOnLoad: true, theme: "dark" }, "pre.language-mermaid > code");</script>`