diff --git a/docs/Parachain/beginner/section1/index.md b/docs/Parachain/beginner/section1/index.md index 580763255..c780f7d18 100644 --- a/docs/Parachain/beginner/section1/index.md +++ b/docs/Parachain/beginner/section1/index.md @@ -4,6 +4,12 @@ title: Parachain Architecture Overview Before beginning the journey to starting your parachain, it's important to realize how exactly the notion of a parachain fits into the wider architecture of Polkadot. +:::tip Clone this repository! + +If you plan on following along, clone this repository which contains everything you need to follow the guide: [`parachain-guide-resources`](https://github.com/CrackTheCode016/parachain-guide-resources) + +::: + Note that we will be using Polkadot binaries and dependencies, as indicative later, but we will be provisioning and locally running our own relay chain. We will also create and run our own parachain, which will connect to our relay chain. import DocCardList from '@theme/DocCardList'; diff --git a/docs/Parachain/beginner/section1/network-components.md b/docs/Parachain/beginner/section1/network-components.md index 5fd9b0935..b2d0a08d1 100644 --- a/docs/Parachain/beginner/section1/network-components.md +++ b/docs/Parachain/beginner/section1/network-components.md @@ -5,16 +5,31 @@ sidebar_label: Polkadot Network Components description: Get a brief overview of how the Polkadot network operates and crucial components. --- -Before diving into development, there is some common nomenclature and components that will be persistent throughout this guide. Oftentimes, these components work together to achieve the scalability and interoperability that Polkadot provides. +Before diving into development, some standard terminology and components will be persistent throughout this guide. Often, these components work together to achieve the scalability and interoperability that Polkadot provides. + +:::info When in doubt, read the wiki! + +For more in-depth explanations, be sure to check out the [Polkadot Wiki](https://wiki.polkadot.network/docs/learn-architecture-index), which covers specifics on how Polkadot works at multiple levels. + +::: ## Building "Blocks" -Before elaborating on the network components of a network like Polkadot, the following is important to realize the following as they will be assumed knowledge throughout the guide: +Before elaborating on the network components of a network like Polkadot, the following is essential to realize as they will be assumed knowledge throughout the guide: -- Blocks, in the most pure definition, is simply a bundle of state transitions. Each transaction, or extrinsic, is a state transition. -- When we refer to "blocks", this usually refers to the **relay chain**. +- Blocks, in the most basic sense, are simply bundles of state transitions. Each transaction, or extrinsic, is a state transition. +- When we refer to **blocks**, this usually refers to the **relay chain's** concept of a block. - Blocks on the relay chain represent the state of all the subsequent parachains. -- **Parablocks** are blocks coming from the parachain to the relay chain. Parablocks carry state transitions from their respective parachain. +- **Parablocks** are blocks from the parachain to the relay chain. Parablocks carry state transitions from their respective parachain. + + +:::info Headers, not blocks! + +When we refer to blocks being stored, it almost **always** meaning that the **header** of the block is stored. Doing so would cause a lot of on-chain bloat, especially considering the state of other parachains, where each parachain may have varying amounts of data per block. + +The same goes for parablocks within relay chain blocks - it's **paraheaders** being stored within the relay chain block, not the actual state transition themselves. + +::: ```mermaid --- @@ -38,21 +53,21 @@ flowchart TD ## Relay Chains & Parachains -**Relay chains** are networks that provide validation and economic security to parachains. They are referred to as "Layer 0" in the stack, as they contain the core functionality needed to host parachains. Typically, the relay chain itself is kept to a few core reponsbilities, one of which is containing the logic for validating its parachains. +**Relay chains** are networks that provide validation and economic security to parachains. They are called "Layer 0" in the stack, containing the core functionality to host parachains. Typically, the relay chain itself is kept to a few core responsibilities, one containing the logic for validating its parachains. -Relay chains can also be thought of as **blockspace** allocators, where parachains pay for the secure blockspace that relay chains inherently provide as a result of their economic security. +Relay chains can also be thought of as [**blockspace**](https://wiki.polkadot.network/docs/glossary#blockspace) allocators, where parachains pay for the secure blockspace that relay chains inherently provide as a result of their economic security. :::info Relay Chains and Sharding You will often hear Polkadot described as a "sharded" blockchain network, which enables scalability in an otherwise resource-constrained environment. -The primary idea behind having a series of parachains is to introduce the notion of **sharding**. Each parachain can run its own, unique application specific state transition function (also referred to as a **runtime**). Parachains can now work in parallel to one another, focusing on their specific application, whilst still being finalized by the relay chain's validator set. +The primary idea behind having a series of parachains is to introduce the notion of **sharding**. Each parachain can run its unique application-specific state transition function (also called a **runtime**). Parachains can now work in parallel to one another, focusing on their specific application while still being finalized by the relay chain's validator set. ![](../../assets/relay_chain.png) ::: -**Parachains** are also full-fledged blockchains, but unlike a **solo chain**, they are able to interoperate with other parachains on the relay chain. Parachains have the advantage of the relay chain finalizing and validating their state transitions - meaning the relay chain represents the state of all of its parachains on the network. +**Parachains** are also full-fledged blockchains, but unlike a **solo chain**, they can interoperate with other parachains on the relay chain. Parachains have the advantage of the relay chain finalizing and validating their state transitions - meaning the relay chain represents the state of all of its parachains on the network. ![](../../assets/relay_chain_zoomed.png) @@ -60,12 +75,12 @@ Polkadot is a relay chain that contains functionality for balances, staking, gov ## Validators -As with any proof of stake network, such as Polkadot, validators are needed to validate state transitions on the network. When validators are referenced, it usually refers to the **relay chain's** validators. +As with any proof of stake network, such as Polkadot, [validators](https://wiki.polkadot.network/docs/learn-validator) are needed to validate state transitions on the network. When validators are referenced, it usually refers to the **relay chain's** validators. ### Paravalidators -Paravalidators are a *subset* of the relay chain's validators selected to valdiate a particular parachain. Using a PoV (Proof of Validity) function, each block candidate becomes backable via parachain validators (paravalidators). It is only later, after a block is considered backable, that the wider validator set provides a series of secondary checks and includes finalized blocks on the chain. +[Paravalidators](https://wiki.polkadot.network/docs/learn-validator#para-validators) is a *subset* of the relay chain's validators selected to validate a particular parachain. Using a PoV (Proof of Validity) function, each block candidate becomes backable via parachain validators (paravalidators). After a block is considered backable, it is only later that the wider validator set provides a series of secondary checks and includes finalized blocks on the chain. ## Collators -Collators are full nodes that pass state in the form of **block candidates** from the **parachain** to **relay chain**. Collators play the role of a validator for a parachain, except no security guarantees are needed. Only one honest collator is needed to ensure proposed state transitions from the parachain are sent to the relay chain. +[Collators](https://wiki.polkadot.network/docs/learn-collator) are full nodes that pass state in the form of **block candidates** from the **parachain** to **relay chain**. Collators play the role of a validator for a parachain, except no security guarantees are needed. Only one honest collator is needed to ensure proposed state transitions from the parachain are sent to the relay chain. diff --git a/docs/Parachain/beginner/section1/parachain.md b/docs/Parachain/beginner/section1/parachain.md index ca56675a4..1b8ee18c9 100644 --- a/docs/Parachain/beginner/section1/parachain.md +++ b/docs/Parachain/beginner/section1/parachain.md @@ -5,21 +5,21 @@ sidebar_label: Parachain Architecture Overview description: Learn the structure of a parachain, what tools are used to develop it, and how it relates to the relay chain. --- -Recall that parachains are shards in the relay chain network. A relay chain without parachains is not terribly useful from a user's perspective, as parachains provide application-specific runtimes that can work in parallel. +Recall that parachains are shards in the relay chain network. Each parachain defines a runtime, or state transition function, specific to their parachain. A relay chain without parachains is not helpful from a user's perspective, as parachains provide application-specific platforms that can work in parallel. ## Examples of Existing Parachains -There are many existing parachains on both Polkadot and Kusama, all of which harness the relay chain's validation schemes to faciliate their application-specific parachains: +Many existing parachains on Polkadot and Kusama all of which harness the relay chain's validation schemes to facilitate their application-specific parachains. Some are **system** parachains, which fulfill some specific functionality for the ecosystem. Below are examples of these [system parachains](https://wiki.polkadot.network/docs/learn-system-chains): -- Acala - Liquid Staking Platform -- Moonbeam - Smart Contract and Interoperbility Platform -- Astar - Cross Chain Smart Contract Platform +- [Asset Hub](https://wiki.polkadot.network/docs/learn-system-chains#asset-hub) - a generic assets parachain that provides functionality for deploying and transferring assets — both Fungible and Non-Fungible Tokens (NFTs). +- [Bridge Hub](https://wiki.polkadot.network/docs/learn-system-chains#bridge-hubs) - a parachain that contains the logic needed for bridging to other relay chains or ecosystems. +- [Collectives](https://wiki.polkadot.network/docs/learn-system-chains#collectives) - The Collectives chain hosts on-chain collectives that serve the Polkadot network. These on-chain collectives will play essential roles in the future of network stewardship and decentralized governance. ## Cumulus - Parachain Development Kit (PDK) -The chains mentioned above use **Cumulus** to build their parachain. Cumulus is a parachain development kit that uses Substrate and FRAME to make building parachains a streamlined process for a developer. +The chains mentioned above use [**Cumulus**](https://github.com/paritytech/cumulus/blob/master/docs/overview.md) to build their parachains. Cumulus is a parachain development kit that uses Substrate and FRAME to make building parachains a streamlined process for a developer. -More notably, besides providing the necessary tools for building a Substrate runtime, Cumulus provides functions needed for connecting to and validating blocks from collators to the relay chain. +More notably, besides providing the necessary tools for building a Substrate runtime, Cumulus provides the means to fulfill the requirements for validating blocks supplied from collators to the relay chain. ### Relation to Substrate & FRAME @@ -28,9 +28,14 @@ More notably, besides providing the necessary tools for building a Substrate run title: Cumulus Parachain Development Kit (PDK) --- flowchart LR - a(Substrate) --> b(FRAME) --> c(Cumulus) + subgraph Substrate + direction LR + a(FRAME) --> b[Wasm Runtime] --> c(Cumulus) + c -- supplies --- pvf("Parachain Validation Function") + c -- facilitates --- pov("Candidate Block Generation") + end ``` -Although this diagram is simplified, this is essentially the relationship between these tools. For more information refer to the documentation for [Substrate](https://paritytech.github.io/substrate/master/substrate/index.html), FRAME, and Cumulus. +Although this diagram is simplified, this is essentially the relationship between these tools. For more information, refer to the documentation for [Substrate](https://paritytech.github.io/substrate/master/substrate/index.html), FRAME, and Cumulus. For a more [detailed diagram](https://paritytech.github.io/substrate/master/substrate/substrate_diagram/index.html), refer to the official Substrate documentation. \ No newline at end of file diff --git a/docs/Parachain/beginner/section1/relay-chain.md b/docs/Parachain/beginner/section1/relay-chain.md index 7c74da4fa..8964c77c6 100644 --- a/docs/Parachain/beginner/section1/relay-chain.md +++ b/docs/Parachain/beginner/section1/relay-chain.md @@ -5,11 +5,11 @@ sidebar_label: Relay Chain Architecture Overview description: Learn the role of the relay chain, and how it registers and validates parachains. --- -The relay chain relieves the parachain of the responsibility of economic security while also facilities interoperability. There are several stages invovled from the collator, paravalidators, and the wider relay chain's validator set. +The relay chain relieves the parachain of economic security's responsibility while facilitating interoperability. Several stages are involved, from the collator, paravalidators, and the wider relay chain's validator set. ## The Path of a Parablock -If you recall the diagram from Network Components, you will notice a simplified path that the parablock travels in order to be included to the relay chain: +If you recall the diagram from Network Components, you will notice a simplified path that the parablock travels to be included in the relay chain: ```mermaid --- @@ -31,15 +31,15 @@ flowchart TD ``` -However, there is a more involved process that is enabling for state transitions from a parachain to be validated and included on the relay chain. +However, a more involved process enables parablocks to be validated and included on the relay chain. -:::info State transition? Transaction? Extrinsic? What's the difference? +:::info State transition? Transaction? Extrinsic? What's the difference? -Up until this point, the term **state transition** has been repeated a few times. To reiterate, a state transition merely represent some State A moving to some State B, of which the blockchain must validate as honest and abiding, or reject due to invalidity. +Until now, the term **state transition** has been repeated a few times. A state transition merely represents some State A moving to some State B, which the blockchain must validate as honest and abiding or reject due to invalidity. ::: -The path of the parablock, at a high level, must undergo several stages before it is to be included and finalized on the relay chain. +At a high level, the path of the parablock must undergo several stages before it is to be included and finalized on the relay chain. ```mermaid --- @@ -79,19 +79,19 @@ flowchart TD There are three primary stages of a parablock before it is included: -- A subset of paravalidators are selected on the relay chain to validate a particular parachain. +- A subset of paravalidators is selected on the relay chain to validate a particular parachain. - The parachain's collator passes the block, considered a "Candidate" to the relay chain. -- The collator also passes the PVF, or **parachain validation function**, to the paravalidators. The PVF validates that the transitions in the candidate block is valid. +- The collator also passes the PVF, or **parachain validation function**, to the paravalidators. The PVF validates that the transitions in the candidate block are valid. - A candidate block gets **backed** by the paravalidators, and contains a **Proof of Validity**, or **PoV**. -- The validators on the relay chain, after a second series of checks, include the block. +- After a second series of checks, the relay chain's validators include the block. For a more thorough explanation, refer to the ["The Path of a Parachain Block" by Joe Petrowski](https://polkadot.network/blog/the-path-of-a-parachain-block) and the [Polkadot Wiki](https://wiki.polkadot.network/docs/learn-parachains-protocol). ## Requirements for a Parachain -In the list above, note the terms: **Parachain Validation Functio**n and **Proof of Validity** conc +In the list above, note the terms: **Parachain Validation Functio**n and **Proof of Validity**. These both are requirements needed for the parachain to communicate with the relay chain: -- A Parachain Validation Function, or **PVF**, is essentially the Wasm runtime of a parachain. It defines how state is supposed to transition for that certain parachain. -- The proof of validity is generated once the state is able to be verified. The entire state of the parachain doesn't need to be verified - just the proposed state changes for that particular parablock. +- A Parachain Validation Function, or **PVF**, is essentially the Wasm runtime of a parachain. It defines how the state is supposed to transition for that certain parachain. +- The proof of validity is generated once the state can be verified. The entire state of the parachain doesn't need to be verified - just the proposed state changes for that particular parablock. In the section page, we also discussed Cumulus, a Parachain Development Kit based on FRAME and Substrate. Cumulus provides the functions needed for collators to provide the PVF and information for the proof of validity to be generated, which is required for the parachain to finalize its state on the relay chain. \ No newline at end of file