Merge pull request #128 from w3f/substrate-refactor

Better resources and small semantics for Substrate course

docs/Substrate/section1/capstone.md

@@ -9,7 +9,7 @@ The purpose of this capstone project is to bring something both engaging and inf
 student. You, the student, should be able to build a Substrate pallet in the Substrate Node
 Template, run it, and modify and view its state in real time.
 
-An honorable mention and inspiration behind this project are
+An honorable mention and inspiration behind this project is
 [Substrate Kitties](https://www.shawntabrizi.com/substrate-collectables-workshop/) by Shawn Tabrizi.
 
 ## Required Functionality - What You Will Build
@@ -29,7 +29,7 @@ The following will be created as a result of this project:
 
 1.  A runtime pallet, which the student can publish and modify as they will.
 2.  An instance of the node template with this pallet integrated.
-3.  A simple front end to display all profiles on a network.
+3.  A simple front end to display all profiles on a network. (optional)
 
 ## Student Objectives
 
@@ -53,7 +53,7 @@ The following Substrate topics and nuances will be covered as a result of this p
   discussed.
 - Going over the Rust language for each pallet concept.
 - Creating any storage mappings or associations for storing data in the chain
-- Learn how to utilize BoundedVec and the importance of bounded data in general in blockchain
+- Learn how to utilize `BoundedVec` and the importance of bounded data in general in blockchain
   development.
 - Learning safe math via the Like or Dislike mechanism to prevent integer overflows. Explain the
   importance of safe math in the runtime.

docs/Substrate/section1/substrate-design.md

@@ -15,8 +15,8 @@ adaptable comes from its heavy use of
 ## What is a generic code base?
 
 At a basic level, a generic code base represents a way to define very reusable code. The Substrate
-libraries use this design pattern to optionally leave some of the definitions of primitives up to
-the developer.
+libraries use this design pattern to optionally leave some definitions of primitives up to the
+developer.
 
 Blockchains often have standard 'primitives': Polkadot, Bitcoin, or Ethereum all have concepts and
 primitives that are commonplace, i.e., transactions, blocks, storage, and hashing algorithms.

docs/Substrate/section1/substrate-history.md

@@ -15,3 +15,9 @@ that uses Substrate libraries and FRAME. Substrate is a blockchain developer fra
 the creation of solo chains or parachains. Initially, much of what was Substrate came from Polkadot
 due to necessity. The reasoning behind this choice was if parachains were to be built, it would be
 sensible to make all standard blockchain protocols and primitives available to parachain developers.
+
+## The Polkadot SDK
+
+As of August 25th, 2023, Substrate, Polkadot, and Cumulus were merged under a
+[single monorepo](https://github.com/paritytech/polkadot-sdk) after being in three separate
+repositories.

docs/Substrate/section1/what-is-substrate.md

@@ -5,22 +5,34 @@ sidebar_label: What is Substrate and FRAME?
 description: Learn what Substrate it is, and why it's the future of building infrastructure in web3.
 ---
 
-Substrate is a modular framework that enables you to create domain-specific blockchains by composing
-custom or pre-built components. The _Framework for Runtime Aggregation of Modularized Entities
-(**FRAME**)_ is a set of modules and support libraries that simplify runtime development. In
-Substrate, these modules are called **pallets**, each hosting domain-specific logic to include in a
-chain's runtime.
+[Substrate](https://paritytech.github.io/substrate/master/substrate/index.html) is a modular
+framework that enables you to create domain-specific blockchains by composing custom or pre-built
+components. It is part of the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and is
+responsible for providing the tools needed to build blockchain **runtimes**.
+
+:::info Substrate is part of the Polkadot SDK (monorepo)
+
+As of August, 2023, the **Polkadot**, **Substrate**, and **Cumulus** codebases were merged into one
+monorepo. Now referred to as the [**Polkadot SDK**](https://github.com/paritytech/polkadot-sdk),
+this monorepo represents all the primary tools needed to build blockchains using Substrate.
+
+:::
+
+The _Framework for Runtime Aggregation of Modularized Entities (**FRAME**)_ is a set of modules and
+support libraries that simplify runtime development within Substrate. In Substrate, these modules
+are called **pallets**, each hosting domain-specific logic to include in a chain's runtime.
 
 Substrate may be utilized to create a solo chain or a parachain for a relay chain like Polkadot or
-Kusama. At its core, it is a set of Rust crates that provide the most basic primitives and protocols
-to implement a distributed state machine, such as a blockchain.
+Kusama. At its core, it is a set of Rust libraries that provide the most basic primitives and
+protocols to implement a distributed, peer-to-peer state machine, such as a blockchain.
 
 :::info An analogy: React, the library for web and native user interfaces
 
-Another way to think about Substrate is similar to how a web developer may use/think about React.
-Where React provides core libraries for manipulating the elements of the DOM via developer-defined
-components, Substrate also provides the base libraries and primitives needed to create a blockchain.
-It was designed to not be opinionated via a highly generic codebase, enabling high customizability.
+Another way to think about Substrate is similar to how a web developer may use/think about
+**React**. Where React provides core libraries for manipulating the elements of the DOM via
+developer-defined components, Substrate also provides the base libraries and primitives needed to
+create a blockchain. It was designed to not be opinionated via a highly generic codebase, enabling
+high customizability.
 
 :::
 
@@ -38,14 +50,22 @@ runtime-related primitives.
 
 A few significant crates that you will encounter are:
 
-- [`sp_runtime`](https://crates.parity.io/sp_runtime/index.html) - Runtime modules shared primitive
-  types
-- [`sp_core`](https://crates.parity.io/sp_core/index.html) - Shareable Substrate types
-- [`sp_io`](https://crates.parity.io/sp_io/index.html) - I/O host interface for substrate runtime.
-  Substrate runtime standard library as compiled when linked with Rust’s standard library.
-
-These, along with many more, all pertain to building certain aspects of a particular distributed
-system.
+- [`sp_runtime`](https://paritytech.github.io/substrate/master/sp_runtime/index.html) - Runtime
+  modules shared primitive types
+- [`sp_core`](https://paritytech.github.io/substrate/master/sp_core/index.html) - Shareable
+  Substrate types
+- [`sp_io`](https://paritytech.github.io/substrate/master/sp_io/index.html) - I/O host interface for
+  substrate runtime. Substrate runtime standard library as compiled when linked with Rust’s standard
+  library.
+
+These, along with many more, all pertain to building certain aspects of distributed systems,
+including but not limited to:
+
+- Consensus mechanisms
+- Peer-to-peer networking
+- Fork-choice rules
+- Block authoring
+- State management
 
 ## A Brief Introduction to FRAME (Framework for Runtime Aggregation of Modularized Entities)
 

docs/Substrate/section2/substrate-pallets.md

@@ -34,7 +34,7 @@ a few standard pallets that you might often encounter as a developer:
   [OpenGov - the next generation of decentralized on-chain governance](https://wiki.polkadot.network/docs/learn-polkadot-opengov).
 
 To view all pallets included with FRAME, look at the
-[repository on GitHub](https://github.com/paritytech/substrate/tree/master/frame).
+[repository on GitHub](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame).
 
 ## Our Pallet: pallet_connect
 

docs/Substrate/section8/origins-calls.md

@@ -39,6 +39,6 @@ Custom origins allow a developer to define a stringent set of requirements for w
 contain to be valid for that specific use case.
 
 For example, the `pallet_collectives` defines custom origins that represent a
-[`Member(AccountId)`](https://github.com/paritytech/substrate/blob/master/frame/collective/src/lib.rs#L139)
+[`Member(AccountId)`](https://github.com/paritytech/polkadot-sdk/blob/2c8021f998a4b3f3e9c0416c7886ef05803aba9d/substrate/frame/collective/src/lib.rs#L141)
 of a particular collective. In the pallet's context, a call containing this origin would imply that
 a member of that collective condoned that action.

docs/Substrate/section8/pallet-coupling.md

@@ -40,8 +40,9 @@ pub trait Config: frame_system::Config {
 **Tight** coupling a pallet involves explicitly declaring an entire, **specific** pallet as a
 dependency. This would also mean that this pallet has to be within your pallet's `Cargo.toml` file,
 precisely just that specific pallet's instance. An example of this is the Bounties pallet, which
-tightly couples the [Treasury](https://github.com/paritytech/substrate/tree/master/frame/treasury)
-pallet to it:
+tightly couples the
+[Treasury](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/treasury) pallet
+to it:
 
 ```rust
 /// Notice the use of the '+' operator to tightly couple the Config of pallet_treasury
@@ -50,9 +51,10 @@ pub trait Config<I: 'static = ()>: frame_system::Config + pallet_treasury::Confi
 
 Tightly coupling two pallets in this manner is helpful when they share very similar goals and
 objectives and for pallets that are simple enough. Because the
-[Bounties](https://github.com/paritytech/substrate/tree/master/frame/bounties) pallet solely depends
-on the [Treasury](https://github.com/paritytech/substrate/tree/master/frame/treasury) pallet for
-payouts (and its subsequent types), it is sensible to couple it tightly.
+[Bounties](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/bounties) pallet
+solely depends on the
+[Treasury](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/treasury) pallet
+for payouts (and its subsequent types), it is sensible to couple it tightly.
 
 ## Which to use?
 

docs/introsubstrate.md

@@ -3,7 +3,7 @@ id: introsubstrate
 sidebar_position: 1
 ---
 
-# Introduction to Substrate & FRAME
+# Introduction to Polkadot SDK - Substrate & FRAME
 
 Developed by the Technical Education team at the Web3 Foundation, this course provides a
 comprehensive overview of the Substrate blockchain framework and building blockchains.