From 2e55e138f875f440f51a029827e9a8cf37e4bb91 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 22 Apr 2024 21:04:51 -0400 Subject: [PATCH 01/21] start the grand refactor (bye substrate.io) --- docs/build/build-guide.md | 97 ++++++++++++++++------------------ docs/general/start-building.md | 2 +- 2 files changed, 48 insertions(+), 51 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 520c1654cbdc..dd8809005f67 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -12,23 +12,34 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Doc -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol with two -goals: providing **shared security** among all connected parachains and allowing all connected -chains to **interoperate** by using [XCM](../learn/learn-xcm.md). With the advent of -[PDKs](../build/build-parachains.md#parachain-development-kit) like -[Substrate](https://substrate.io/) and -[Cumulus](https://github.com/paritytech/polkadot-sdk/tree/master/cumulus), the time it takes to -develop and launch a new chain has dropped significantly. While before, it would take years to -launch a new chain, now it may only take weeks or even days, depending on your goals. +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol that +providing **shared security** among all connected [tasks](../learn/learn-agile-coretime.md#task) and +allowing all connected tasks to **interoperate** by using [XCM](../learn/learn-xcm.md). + +:::info What is a task? + +You might see the term "task" references quite a bit, but in most cases refers to a protocol which +is running using Polkadot. This could be a parachain, or any other computational process, so long as +it adheres to the Polkadot protocol. + +A better definition can be found [here](../learn/learn-agile-coretime.md#task). + +::: + +The time it takes to develop and launch a new chain has dropped significantly with the tools +Polkadot provides. While before, it would take years to launch a new chain, now it may only take +weeks or even days, depending on your goals. This guide will walk you through the steps you can take today to get started building your vision with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will explain the difference between a [parachain](../learn/learn-parachains.md) and a smart contract in deciding which best fits your architectural needs. +After + This build guide provides three different tracks: -1. [Protocol Development - Blockchain & Parachain Development](#building-parachains) +1. [Protocol Development - Blockchain & Parachain Development](#building-tasks) 2. [Developing Smart Contracts](#developing-smart-contracts) 3. [Developing a dApp](#developing-a-dappuapp) @@ -101,19 +112,20 @@ Before diving into any one of these tracks, it is encouraged to read about {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and its networks in order to gain context about the application you could make. -## Building Parachains +## Building Tasks {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is canonically referred to as the Relay Chain. It is also considered a _layer zero_ protocol, as it enables the interoperability and shared security of multiple [parachains](../learn/learn-parachains.md), which are _layer one_ -protocols. Parachains connect to a relay chain using the -[Parachains Protocol](../learn/learn-parachains-protocol.md). +protocols. Tasks currently connect to a relay chain using the +[Parachains Protocol](../learn/learn-parachains-protocol.md). In the future, more elaborate (or +simple!) tasks could be constructed. ![build 1](../assets/build-1.png) :::info -Throughout this document, you will encounter the term **runtime** or **STF (State Transition +Throughout this document, you may encounter the term **runtime** or **STF (State Transition Function)**. Both refer to the same concept, as they define how a particular system, i.e., a blockchain, should deal with state changes externally and internally. Both of these terms are used extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, and by association, @@ -121,7 +133,7 @@ Substrate contexts. ::: -Parachains open possibilities to construct complex **runtime**, or **STF** (state transition +The Polkadot SDK opens possibilities to construct complex **runtime**, or **STF** (state transition function) the logic that would be too expensive to execute with smart contracts. However, unlike smart contracts, parachains lack a mandatory gas metering system entirely and could potentially be vulnerable to bugs that cause infinite loops (something that is prevented by design in smart @@ -130,25 +142,20 @@ contracts). This vulnerability is mitigated by the -- although it places more of a burden on the developer of the parachain to perform properly benchmarks. -:::info What is a parathread? - -Parathreads, or "on-demand parachains," are like parachains and enable the developer to have -lower-level control of the logic of their application. The main difference between the two is -economical since parathreads will be much less expensive to secure than a parachain and is a -"pay-as-you-go" model. The lower costs of parathreads are because parathreads will only produce a -block when needed, unlike parachains, which have secured a slot to produce a block at every block of -the Relay Chain. When building a parathread, you will use the same tools (like PDKs) and get all the -benefits of building a parachain without the cost drawback. +### Constructing FRAME Runtimes with Substrate -::: +Polkadot is built using the Polkadot SDK, which within contains the source code for: -### Constructing FRAME Runtimes with Substrate +- The Polkadot client implemenation +- Substrate - the core libraries used for constructing blockchains +- Cumulus - parachain/task specific functions which allow for solo chains to become compatible with + Polkadot -Polkadot is built using the [Substrate](https://substrate.io/) framework. -[Substrate](https://substrate.io/) is a highly configurable and dynamic framework for building -blockchains. At a lower level, Substrate provides a set of tools and libraries ranging from -[block production, finality gadgets to peer-to-peer networking](https://docs.substrate.io/reference/rust-api/). -Both Polkadot and Kusama, as well as most parachains, are built using Substrate. +[Substrate](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/substrate/index.html) +is a highly configurable and dynamic framework for building blockchains. At a lower level, Substrate +provides a set of tools and libraries ranging from block production, finality gadgets to +peer-to-peer networking. Both Polkadot and Kusama, as well as most parachains, are built using +Substrate. In essence, Substrate can break down a blockchain's development process by providing crucial building blocks of functionality, removing the need for re-engineering complex mechanisms that @@ -158,14 +165,13 @@ Substrate can be used as a basis for a parachain to connect to a relay chain lik Kusama, or even as a basis to form a conventional layer one solo chain. Currently, the most streamlined way of utilizing Substrate is -[FRAME](https://docs.substrate.io/learn/runtime-development/#frame), which conveniently allows for a -runtime/STF to be generated from a set of modules (called -[pallets](https://docs.substrate.io/reference/frame-pallets/)). -[Runtimes](https://docs.substrate.io/learn/architecture/#runtime) in Substrate are built using -[WebAssembly](../learn/learn-wasm.md) (Wasm), and represent the state transition function for a -network. FRAME allows for a collection of business logic-oriented modules, called -[pallets](https://docs.substrate.io/reference/frame-pallets/), to construct a runtime/STF and define -how exactly the blockchain is supposed to behave. Ranging from +[FRAME](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html), +which conveniently allows for a runtime/STF to be generated from a set of modules (called +[pallets](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html#pallets)). +Runtimes in Substrate are built using [WebAssembly](../learn/learn-wasm.md) (Wasm), and represent +the state transition function for a network. FRAME provides a framework for +[pallets](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html#pallets), +to construct a runtime/STF and define how your task is supposed to behave. Ranging from [identity](https://paritytech.github.io/substrate/master/pallet_identity/index.html) to [smart contracts](https://paritytech.github.io/substrate/master/pallet_contracts/index.html), pallets can be quite extensive in providing on-chain functionality. @@ -187,19 +193,11 @@ comparably minimal effort. #### Building Parachains with Cumulus -Diving further into building parachains, [Cumulus](https://github.com/paritytech/polkadot-sdk/tree/master/cumulus) is another set of tools that aid in building a parachain-ready blockchain for Polkadot or Kusama. Cumulus utilizes FRAME and Substrate to create an easy way to build your first parachain. It ensures the chain follows the Parachain Protocol. -:::info - -_Cumulus clouds are shaped like dots; together, they form an intricate, beautiful and functional -system._ - -::: - For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building process. This way, one can view how various paradigms are applied and decide on integrating or @@ -271,9 +269,9 @@ Pallets require more engineering and thought, as they can directly affect the ch ### ink! and EVM-based Smart Contracts At a high level, a _smart contract_ is simply some code that exists at an address on a chain and is -callable by external actors. Whether it's -[EVM-based](https://docs.substrate.io/tutorials/integrate-with-tools/evm-integration/), or written -using [ink!](https://use.ink/), smart contracts sandboxed, executable programs that live on-chain. +callable by external actors. Whether it's [EVM-based](https://polkadot-evm.github.io/frontier/), or +written using [ink!](https://use.ink/), smart contracts sandboxed, executable programs that live +on-chain. :::note @@ -325,6 +323,5 @@ For a complete list of tools, please take a look here: - [Polkadot Bridges](https://medium.com/polkadot-network/polkadot-bridges-connecting-the-polkadot-ecosystem-with-external-networks-1118916392e3) - [The Path of a Parachain Block](https://polkadot.network/blog/the-path-of-a-parachain-block/) - [The Path of a Parachain Block (Video)](https://www.crowdcast.io/e/polkadot-path-of-a-parachain-block?utm_source=profile&utm_medium=profile_web&utm_campaign=profile) -- [Polkadot Parachain Slots](https://polkadot.network/polkadot-parachain-slots/) - [How to become a parachain on Polkadot (Video)](https://www.youtube.com/watch?v=fYc1yolanoE) - [Trusted Execution Environments and the Polkadot Ecosystem](https://polkadot.network/blog/trusted-execution-environments-and-the-polkadot-ecosystem/) diff --git a/docs/general/start-building.md b/docs/general/start-building.md index 0cf9c1cd0ce3..66045392844b 100644 --- a/docs/general/start-building.md +++ b/docs/general/start-building.md @@ -21,7 +21,7 @@ The programming language used for development is [Rust](https://www.rust-lang.or :::info -For more information about building on Polkadot, see [the Builder's Guide](../build/build-index.md). +For more information about building on Polkadot, see [the Builder's Guide](../build/build-guide.md). ::: From a0464d23faf46d287ec232b8c00d52b02de0640a Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 24 Apr 2024 19:02:50 -0400 Subject: [PATCH 02/21] working draft --- docs/build/build-guide.md | 157 ++++++++++++++------------- docs/build/build-network-overview.md | 8 ++ 2 files changed, 92 insertions(+), 73 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index dd8809005f67..4f3a2df7c966 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -7,22 +7,20 @@ keywords: [build, how to build, develop, parachain, smart contract] slug: ../build-guide --- -import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import DocCardList from -'@theme/DocCardList'; +import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; - - -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol that -providing **shared security** among all connected [tasks](../learn/learn-agile-coretime.md#task) and -allowing all connected tasks to **interoperate** by using [XCM](../learn/learn-xcm.md). +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol and network +that provides **shared security** amongst all connected parachains (which are +[tasks](../learn/learn-agile-coretime.md#task)) and allowing all connected tasks to **interoperate** +by using [XCM](../learn/learn-xcm.md). :::info What is a task? -You might see the term "task" references quite a bit, but in most cases refers to a protocol which -is running using Polkadot. This could be a parachain, or any other computational process, so long as -it adheres to the Polkadot protocol. +You might see the term "task" references quite a bit, but in most cases refers to a process which is +utilizing the compute that Polkadot provides. This could be a parachain or any other computational +process, so long as it adheres to the Polkadot protocol. -A better definition can be found [here](../learn/learn-agile-coretime.md#task). +The full definition can be found [here](../learn/learn-agile-coretime.md#task). ::: @@ -30,22 +28,34 @@ The time it takes to develop and launch a new chain has dropped significantly wi Polkadot provides. While before, it would take years to launch a new chain, now it may only take weeks or even days, depending on your goals. -This guide will walk you through the steps you can take today to get started building your vision -with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will explain the difference -between a [parachain](../learn/learn-parachains.md) and a smart contract in deciding which best fits -your architectural needs. +This starters guide will walk you through the steps you can take today to get started building your +vision with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will also point to +resources which you can use to start building right away. + +:::note For Developers! + +Please note that the following documentation is more geared towards developers. If you are looking +for more general knowledge related to Polkadot, be sure to check otu the +[Learn](../learn/learn-index) section. + +Looking to jump into a guide? Check out our starter developer guides for creating a minimal +blockchain and deploying it on a testnet. -After +::: + +This build guide covers four different areas, taking a **top-down** approach, from protocol +development to user-facing applications: -This build guide provides three different tracks: + -1. [Protocol Development - Blockchain & Parachain Development](#building-tasks) -2. [Developing Smart Contracts](#developing-smart-contracts) -3. [Developing a dApp](#developing-a-dappuapp) +1. [Protocol Development - Developing parachains/blockchains](#building-parachains) +2. [Deploying on a Core](#deploying-on-a-core) +3. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) +4. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) -:::tip Keep reading to find out more, or visit each respective track +:::tip Keep reading to find out more, or explore each respective area -Keep in mind that these tracks are merely suggestive, and there are many ways to utilize +Keep in mind that these areas are merely suggestive, and there are many ways to utilize {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, Substrate, and their various developmental components. For more inspiration, look at the [open source projects](./build-open-source.md) featured here in the wiki! @@ -83,7 +93,7 @@ flowchart TB subgraph PSL ["Blockchain Development"] direction LR PS["Polkadot SDK"] --> R[WASM Runtime - Substrate & FRAME] - R -->Parachain["Parachain"]-->SSC["Shared Security - Cumulus"] + R -->Parachain["Parachain/Task"]-->SSC["Shared Security - Cumulus"]-->Core("Deployed on a Core") R -->SoloChain[Solo Chain]-->NSS["No Shared Security"] end end @@ -112,15 +122,21 @@ Before diving into any one of these tracks, it is encouraged to read about {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and its networks in order to gain context about the application you could make. -## Building Tasks +[Take a look at the various development network options here.](./build-network-overview.md) + +## Building Parachains {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is canonically referred to as the Relay Chain. It is also considered a _layer zero_ protocol, as it enables the interoperability and shared security of multiple [parachains](../learn/learn-parachains.md), which are _layer one_ -protocols. Tasks currently connect to a relay chain using the +protocols. Parachains currently connect to a relay chain using the [Parachains Protocol](../learn/learn-parachains-protocol.md). In the future, more elaborate (or simple!) tasks could be constructed. +A parachain one of the examples of a type of **task**, which runs on a core on Polkadot. In theory, +one could develop other types of tasks, not just other blockchains, that are able to run on a +Polkadot core. + ![build 1](../assets/build-1.png) :::info @@ -128,8 +144,7 @@ simple!) tasks could be constructed. Throughout this document, you may encounter the term **runtime** or **STF (State Transition Function)**. Both refer to the same concept, as they define how a particular system, i.e., a blockchain, should deal with state changes externally and internally. Both of these terms are used -extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, and by association, -Substrate contexts. +extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and Substrate. ::: @@ -142,14 +157,16 @@ contracts). This vulnerability is mitigated by the -- although it places more of a burden on the developer of the parachain to perform properly benchmarks. -### Constructing FRAME Runtimes with Substrate +### Polkadot SDK Overview -Polkadot is built using the Polkadot SDK, which within contains the source code for: +Polkadot is built using the Polkadot SDK, which besides, +[the Polkadot node/host implementation](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/polkadot/index.html), +within contains the source code for: -- The Polkadot client implemenation -- Substrate - the core libraries used for constructing blockchains -- Cumulus - parachain/task specific functions which allow for solo chains to become compatible with - Polkadot +- **Substrate** - a set of core libraries used for constructing blockchains - mostly un-opinionated + - **FRAME** - the framework used to build Substrate runtimes - more opinionated +- **Cumulus** - parachain/task specific functions which allow for solo chains to become compatible + with Polkadot [Substrate](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/substrate/index.html) is a highly configurable and dynamic framework for building blockchains. At a lower level, Substrate @@ -164,7 +181,7 @@ usually involved when developing a blockchain. Substrate can be used as a basis for a parachain to connect to a relay chain like Polkadot or Kusama, or even as a basis to form a conventional layer one solo chain. -Currently, the most streamlined way of utilizing Substrate is +Currently, the most streamlined way of utilizing Substrate is through [FRAME](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html), which conveniently allows for a runtime/STF to be generated from a set of modules (called [pallets](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html#pallets)). @@ -177,8 +194,9 @@ to construct a runtime/STF and define how your task is supposed to behave. Rangi pallets can be quite extensive in providing on-chain functionality. Even though FRAME is heavily used, it is not the only way to create a valid runtime/STF using -Substrate. Substrate can be used to create new paradigms and abstractions that build on the concept -of web3. +Substrate. Substrate can be used to create new paradigms and abstractions, one such example is the +[Open Runtime Module Library (ORML)](https://github.com/open-web3-stack/open-runtime-module-library), +which is another way creating and using runtime modules. :::note @@ -193,41 +211,20 @@ comparably minimal effort. #### Building Parachains with Cumulus -[Cumulus](https://github.com/paritytech/polkadot-sdk/tree/master/cumulus) is another set of tools -that aid in building a parachain-ready blockchain for Polkadot or Kusama. Cumulus utilizes FRAME and -Substrate to create an easy way to build your first parachain. It ensures the chain follows the -Parachain Protocol. +[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) +transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and Substrate-based +nodes into Polkadot/Parachain-compatible nodes. In other words, Cumulus can enable a regular runtime +to meet the necessary requirements to have its state verified by Polkadot and take part in shared +security. For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building process. This way, one can view how various paradigms are applied and decide on integrating or utilizing Substrate for their particular use case. -Please see the [parachain development guide](build-parachains.md) for how to get started on building -a parachain or parathread. + -#### Parachains Benefits - -Parachains contain their own runtime/STF logic and benefit from the shared security and the -cross-consensus messaging provided by the {{ polkadot: Polkadot :polkadot }} relay chain. Parachains -permit high flexibility and customization but require more effort to create and maintain over time. -A production-grade parachain is typically more involved to create due to the complexity involved in -blockchain networks' technical and economic aspects. - -Parachains grant the creators more space to build the monetary system and other chain aspects from -the ground up. They will allow for a more concise and efficient execution of complex logic than a -smart contract platform could offer. Parachains also provide more flexibility in the form of -governance and can perform complete upgrades in a less controversial way than the current process of -hard forks. - -Some examples of features you can have on a parachain or parathread: - -- Custom fee structure (for example, pay a flat transaction fee or pay per byte). -- Shared security and finalization via the relay chain (Polkadot or Kusama). -- Custom monetary policy for the native token and local economy. -- Treasury to be funded through transitions in your state function. -- A governance mechanism that could manage a DAO that is responsible for allocating your on-chain - treasury. +Please see the parachain development guide for how to get started on building a parachain. ### Building a Pallet @@ -237,8 +234,19 @@ environment. A pallet is a fully customizable module that allows you to implemen with relatively minimal development time on a fundamental level while still allowing the possibility of building advanced functionality into your custom chain. -To learn how to build a pallet, follow the -[Substrate documentation](https://docs.substrate.io/tutorials/build-application-logic/). +## Deploying on a Core + +Once you have your runtime and pallets developed, you will be able to deploy it on a +[core](../learn/learn-agile-coretime.md#core), which is how one utilizes the shared security of the +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. One does so by: + +1. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your + state transitions from one state to the next. +2. **Generating** your genesis state. +3. **Obtaining** a core, most likely through a + [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). +4. **Registering** the runtime blob and genesis state with that core. +5. **Ensuring** you have at least one honest, synced collator for your task ## Developing Smart Contracts @@ -264,6 +272,9 @@ runtime/STF, whereas smart contracts are a product of a pallet (see: [pallet_contracts](https://paritytech.github.io/substrate/master/pallet_contracts/index.html)). Pallets require more engineering and thought, as they can directly affect the chain's state. +For a more comprehensive (and maintained) comparison, be sure to check out the +[comparison from the Polkadot SDK documentation](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/runtime_vs_smart_contract/index.html). + ::: ### ink! and EVM-based Smart Contracts @@ -275,14 +286,14 @@ on-chain. :::note -The Polkadot relay chain does not support smart contracts. However, several parachains do. See the -[smart contracts guide](build-smart-contracts.md#smart-contract-environments-are-still-maturing) for -more information about the environments provided. +_The Polkadot relay chain does not support smart contracts._ However, several parachains do. See the +[smart contracts guide](build-smart-contracts.md#parachains) for the exact chains in which you can +deploy contracts on Polkadot. ::: -A popular choice for smart contracts is [ink!](https://use.ink/). Other parachains that offer -EVM-based contracts written in Solidity alongside ink! +A Polkadot-native choice for smart contracts is [ink!](https://use.ink/). Other parachains that +offer EVM-based contracts written in Solidity alongside ink! [are also available](./build-smart-contracts#parachains). Because smart contracts exist on a single chain at a time, they can have smooth interoperability @@ -301,7 +312,7 @@ a smart contract. ::: -## Developing a dApp/uApp +## Developing a dApp If one aims to develop a **dApp** (Decentralized App), the Polkadot ecosystem contains various SDKs to tap into the relay chain and parachains. @@ -318,8 +329,8 @@ For a complete list of tools, please take a look here: ## Resources - [System (Common Good) Parachains](https://polkadot.network/blog/common-good-parachains-an-introduction-to-governance-allocated-parachain-slots/) +- [Agile Coretime Fellowship RFC](https://polkadot-fellows.github.io/RFCs/approved/0001-agile-coretime.html) - [The Launch of Parachains](https://polkadot.network/blog/the-launch-of-parachains/) -- [Parathreads: Pay-as-you-go Parachains](https://medium.com/polkadot-network/parathreads-pay-as-you-go-parachains-7440d23dde06) - [Polkadot Bridges](https://medium.com/polkadot-network/polkadot-bridges-connecting-the-polkadot-ecosystem-with-external-networks-1118916392e3) - [The Path of a Parachain Block](https://polkadot.network/blog/the-path-of-a-parachain-block/) - [The Path of a Parachain Block (Video)](https://www.crowdcast.io/e/polkadot-path-of-a-parachain-block?utm_source=profile&utm_medium=profile_web&utm_campaign=profile) diff --git a/docs/build/build-network-overview.md b/docs/build/build-network-overview.md index 86ce98a2bb05..46480c9c24c5 100644 --- a/docs/build/build-network-overview.md +++ b/docs/build/build-network-overview.md @@ -10,6 +10,12 @@ slug: ../build-network-overview While Polkadot itself is the mainnet, there are several networks that can cater to different development or application-driven contexts. +:::info Looking for faucets? + +[See here for all available faucets and how to obtain testnet tokens.](../learn/learn-DOT.md#obtaining-testnet-tokens) + +::: + ## Polkadot Ecosystem Networks - Mainnet: **Polkadot** @@ -20,6 +26,8 @@ development or application-driven contexts. - **Westend** - Functionality equal to the current Polkadot mainnet, with possible next-generation testing of features from time to time that will eventually migrate onto Polkadot. Perma-testnet (is not reset back to genesis block). + - **Paseo** - A community-run testnet which mirrors the Polkadot runtime. It is maintained by the + community. - **Rococo** - Parachains and XCM testnet. Occasionally reset (started over again with a new genesis block). - **Contracts** - Wasm-based Smart Contract enabled parachain testnet on Rococo, primarily for From 4f65470b61b16f80587fd2f356960d19748c45fd Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 24 Apr 2024 19:04:34 -0400 Subject: [PATCH 03/21] parachain -> task --- docs/build/build-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 4f3a2df7c966..72b70c869ec9 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -48,7 +48,7 @@ development to user-facing applications: -1. [Protocol Development - Developing parachains/blockchains](#building-parachains) +1. [Protocol Development - Developing parachains/blockchains](#building-parachains-tasks) 2. [Deploying on a Core](#deploying-on-a-core) 3. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) 4. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) @@ -124,7 +124,7 @@ context about the application you could make. [Take a look at the various development network options here.](./build-network-overview.md) -## Building Parachains +## Building Parachains (Tasks) {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is canonically referred to as the Relay Chain. It is also considered a _layer zero_ protocol, as it enables the interoperability and From 3003d827852596ef10ad6fa14fddc6c5ff092b56 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 24 Apr 2024 19:05:37 -0400 Subject: [PATCH 04/21] fmt --- docs/build/build-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 72b70c869ec9..17ef591f7707 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -46,6 +46,7 @@ blockchain and deploying it on a testnet. This build guide covers four different areas, taking a **top-down** approach, from protocol development to user-facing applications: + 1. [Protocol Development - Developing parachains/blockchains](#building-parachains-tasks) From 90bd8c968a940b3a96e16f39763f1846a9ac60ce Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 24 Apr 2024 19:13:41 -0400 Subject: [PATCH 05/21] create place for coretime guides --- .../build-guides-coretime-adder-collator.md} | 10 +++++----- polkadot-wiki/sidebars.js | 20 +++++++++++++++---- 2 files changed, 21 insertions(+), 9 deletions(-) rename docs/{learn/learn-guides-coretime-parachains.md => build/build-guides-coretime-adder-collator.md} (96%) diff --git a/docs/learn/learn-guides-coretime-parachains.md b/docs/build/build-guides-coretime-adder-collator.md similarity index 96% rename from docs/learn/learn-guides-coretime-parachains.md rename to docs/build/build-guides-coretime-adder-collator.md index 20dad4d8f610..16dd257b8ca4 100644 --- a/docs/learn/learn-guides-coretime-parachains.md +++ b/docs/build/build-guides-coretime-adder-collator.md @@ -1,10 +1,10 @@ --- -id: learn-guides-coretime-parachains -title: Agile Coretime for Parachains -sidebar_label: Coretime for Parachains -description: Agile Coretime from Parachains perspective +id: build-guides-coretime-adder-collator +title: Getting Started - Adder Collator +sidebar_label: Getting Started - Adder Collator +description: Getting started with Agile Coretime with Adder Collator keywords: [coretime, blockspace, parathread, parachain, cores] -slug: ../learn-guides-coretime-parachains +slug: ../build-guides-coretime-adder-collator --- import RPC from "./../../components/RPC-Connection"; diff --git a/polkadot-wiki/sidebars.js b/polkadot-wiki/sidebars.js index 52669c1521a8..1f5f34a26b20 100644 --- a/polkadot-wiki/sidebars.js +++ b/polkadot-wiki/sidebars.js @@ -458,7 +458,6 @@ module.exports = { items: [ "learn/learn-agile-coretime", "learn/learn-guides-coretime-marketplaces", - "learn/learn-guides-coretime-parachains", ], }, { @@ -706,6 +705,7 @@ module.exports = { id: "build/build-guide" }, items: [ + "build/build-network-overview", { type: "category", label: "Client-side Development", @@ -724,20 +724,32 @@ module.exports = { "build/build-smart-contracts", { type: "category", - label: "Protocol Development", + label: "Getting Started with Coretime", link: { type: 'generated-index', - title: "Protocol & Parachain Development", + title: "Getting Started with Coretime", description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", slug: '/build-protocol-index', }, + items: [ + "build/build-guides-coretime-adder-collator" + ], + }, + { + type: "category", + label: "Protocol Development Resources", + link: { + type: 'generated-index', + title: "Protocol Development Resources", + description: "Miscellaneous aspects concerning protocol and parachain development", + slug: '/build-protocol-index', + }, items: [ "build/build-protocol-info", "build/build-integrate-assets", "build/build-hrmp-channels" ], }, - "build/build-network-overview", { type: "category", label: "Tooling", From 1f146377431c58b9d2922d5fe74dae34b5f8aa54 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 24 Apr 2024 19:39:38 -0400 Subject: [PATCH 06/21] grammar --- docs/build/build-guide.md | 121 +++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 61 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 17ef591f7707..c0626dbee81a 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -16,9 +16,9 @@ by using [XCM](../learn/learn-xcm.md). :::info What is a task? -You might see the term "task" references quite a bit, but in most cases refers to a process which is -utilizing the compute that Polkadot provides. This could be a parachain or any other computational -process, so long as it adheres to the Polkadot protocol. +You might see the term "task" referenced quite a bit, but in most cases, it refers to a process +utilizing Polkadot's compute. This could be a parachain or any other computational process, provided +that it adheres to the Polkadot protocol. The full definition can be found [here](../learn/learn-agile-coretime.md#task). @@ -30,7 +30,7 @@ weeks or even days, depending on your goals. This starters guide will walk you through the steps you can take today to get started building your vision with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will also point to -resources which you can use to start building right away. +resources you can use to start building immediately. :::note For Developers! @@ -43,7 +43,7 @@ blockchain and deploying it on a testnet. ::: -This build guide covers four different areas, taking a **top-down** approach, from protocol +This build guide covers four different areas, taking a **top-down** approach from protocol development to user-facing applications: @@ -67,54 +67,54 @@ developmental components. For more inspiration, look at the ```mermaid %%{ - init: { - 'theme': 'base', - 'themeVariables': { - 'fontFamily': 'Unbounded', - 'primaryColor': '#E6007A', - 'fontSize': '16px', - 'primaryTextColor': '#fff', - 'primaryBorderColor': '#7C0000', - 'lineColor': '#140523', - 'secondaryColor': '#552BBF', - 'tertiaryColor': '#fff' - } - } + init: { + 'theme': 'base', + 'themeVariables': { + 'fontFamily': 'Unbounded', + 'primaryColor': '#E6007A', + 'fontSize': '16px', + 'primaryTextColor': '#fff', + 'primaryBorderColor': '#7C0000', + 'lineColor': '#140523', + 'secondaryColor': '#552BBF', + 'tertiaryColor': '#fff' + } + } }%% flowchart TB - subgraph PL ["Protocol Land (Parachains, Smart Contracts)"] - - subgraph SCD ["Smart Contract Development"] - direction LR - SC["Use Smart Contract Parachain"] - SC --> ink! - SC --> Solidity - end - - subgraph PSL ["Blockchain Development"] - direction LR - PS["Polkadot SDK"] --> R[WASM Runtime - Substrate & FRAME] - R -->Parachain["Parachain/Task"]-->SSC["Shared Security - Cumulus"]-->Core("Deployed on a Core") - R -->SoloChain[Solo Chain]-->NSS["No Shared Security"] - end - end - - PL-->| Develop apps| CS - - subgraph CS ["Client/User Land (dApps/uApps)"] - LC["Light Clients (Smoldot)"] - UA[uApp] - UA --> PAPI[Polkadot API] - UA --> PJS[Polkadot JS] - UA --> SubXT - PAPI --> LC - PJS --> LC - SubXT --> LC - end + subgraph PL ["Protocol Land (Parachains, Smart Contracts)"] + + subgraph SCD ["Smart Contract Development"] + direction LR + SC["Use Smart Contract Parachain"] + SC --> ink! + SC --> Solidity + end + + subgraph PSL ["Blockchain Development"] + direction LR + PS["Polkadot SDK"] --> R[WASM Runtime - Substrate & FRAME] + R -->Parachain["Parachain/Task"]-->SSC["Shared Security - Cumulus"]-->Core("Deployed on a Core") + R -->SoloChain[Solo Chain]-->NSS["No Shared Security"] + end + end + + PL-->| Develop apps| CS + + subgraph CS ["Client/User Land (dApps/uApps)"] + LC["Light Clients (Smoldot)"] + UA[uApp] + UA --> PAPI[Polkadot API] + UA --> PJS[Polkadot JS] + UA --> SubXT + PAPI --> LC + PJS --> LC + SubXT --> LC + end ``` -Before diving into the various paths, one can take in developing on -{{ polkadot: Polkadot :polkadot }}, it's important to realize and know key terms that make up the +Before diving into the various paths one can take in developing on +{{ polkadot: Polkadot :polkadot }}, it's essential to realize and know key terms that make up the following sections. Even before considering what kind of application you want to build, it's prudent to understand what {{ polkadot: Polkadot :polkadot }} _is_ and how {{ kusama: Kusama :kusama }} relates to it, and what each developmental component can do for you within the Polkadot ecosystem. @@ -131,11 +131,11 @@ context about the application you could make. Relay Chain. It is also considered a _layer zero_ protocol, as it enables the interoperability and shared security of multiple [parachains](../learn/learn-parachains.md), which are _layer one_ protocols. Parachains currently connect to a relay chain using the -[Parachains Protocol](../learn/learn-parachains-protocol.md). In the future, more elaborate (or -simple!) tasks could be constructed. +[Parachains Protocol](../learn/learn-parachains-protocol.md). More elaborate (or simpler) tasks +could be constructed in the future. -A parachain one of the examples of a type of **task**, which runs on a core on Polkadot. In theory, -one could develop other types of tasks, not just other blockchains, that are able to run on a +A parachain is one of the examples of a type of **task**, which runs on a core on Polkadot. In +theory, one could develop other types of tasks, not just other blockchains, that can run on a Polkadot core. ![build 1](../assets/build-1.png) @@ -160,12 +160,12 @@ benchmarks. ### Polkadot SDK Overview -Polkadot is built using the Polkadot SDK, which besides, +Polkadot is built using the Polkadot SDK, which, [the Polkadot node/host implementation](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/polkadot/index.html), within contains the source code for: - **Substrate** - a set of core libraries used for constructing blockchains - mostly un-opinionated - - **FRAME** - the framework used to build Substrate runtimes - more opinionated +- **FRAME** - the framework used to build Substrate runtimes - more opinionated - **Cumulus** - parachain/task specific functions which allow for solo chains to become compatible with Polkadot @@ -202,8 +202,8 @@ which is another way creating and using runtime modules. :::note Although most parachains utilize FRAME and Substrate to build runtime/STFs for connecting to the -relay chain, it is not contingent. Building a parachain using other tools is possible, as long as -they follow the [Parachains Protocol](../learn/learn-parachains-protocol.md). +relay chain, it is not contingent. Building a parachain using other tools is possible if they follow +the [Parachains Protocol](../learn/learn-parachains-protocol.md). As a general rule of thumb, Substrate provides the means for this to become possible through comparably minimal effort. @@ -215,8 +215,7 @@ comparably minimal effort. [Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and Substrate-based nodes into Polkadot/Parachain-compatible nodes. In other words, Cumulus can enable a regular runtime -to meet the necessary requirements to have its state verified by Polkadot and take part in shared -security. +to meet the requirements to have its state verified by Polkadot and take part in shared security. For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building @@ -225,7 +224,7 @@ utilizing Substrate for their particular use case. -Please see the parachain development guide for how to get started on building a parachain. +Please see the parachain development guide for how to start building a parachain. ### Building a Pallet @@ -322,7 +321,7 @@ For front-end applications, several options exist for interfacing with Substrate (parachains, relay chains, etc.) and smart contracts. These often will interact with the RPC of a Substrate node. -[Please visit the full documentation for developing dApps and other general client-side development resources.](build-dapp) +[Please visit the documentation for developing dApps and other general client-side development resources.](build-dapp) For a complete list of tools, please take a look here: [Tools, APIs, and Languages](build-open-source.md) From fc96b218e86903b5e9bb833dacded06df8fedce8 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Thu, 25 Apr 2024 17:04:20 -0400 Subject: [PATCH 07/21] address most feedback, start towards kusama --- docs/build/build-guide.md | 48 +++---------------- docs/build/build-guides-coretime-start.md | 41 ++++++++++++++++ .../learn-guides-coretime-parachains.md} | 10 ++-- kusama-guide/sidebars.js | 13 +++++ polkadot-wiki/sidebars.js | 14 +----- 5 files changed, 67 insertions(+), 59 deletions(-) create mode 100644 docs/build/build-guides-coretime-start.md rename docs/{build/build-guides-coretime-adder-collator.md => learn/learn-guides-coretime-parachains.md} (96%) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index c0626dbee81a..518d0f6ab5b3 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -10,19 +10,8 @@ slug: ../build-guide import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol and network -that provides **shared security** amongst all connected parachains (which are -[tasks](../learn/learn-agile-coretime.md#task)) and allowing all connected tasks to **interoperate** -by using [XCM](../learn/learn-xcm.md). - -:::info What is a task? - -You might see the term "task" referenced quite a bit, but in most cases, it refers to a process -utilizing Polkadot's compute. This could be a parachain or any other computational process, provided -that it adheres to the Polkadot protocol. - -The full definition can be found [here](../learn/learn-agile-coretime.md#task). - -::: +that provides **shared security** amongst all connected parachains and allowing all connected tasks +to **interoperate** by using [XCM](../learn/learn-xcm.md). The time it takes to develop and launch a new chain has dropped significantly with the tools Polkadot provides. While before, it would take years to launch a new chain, now it may only take @@ -43,16 +32,15 @@ blockchain and deploying it on a testnet. ::: -This build guide covers four different areas, taking a **top-down** approach from protocol +This build guide covers three different areas, taking a **top-down** approach from protocol development to user-facing applications: 1. [Protocol Development - Developing parachains/blockchains](#building-parachains-tasks) -2. [Deploying on a Core](#deploying-on-a-core) -3. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) -4. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) +2. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) +3. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) :::tip Keep reading to find out more, or explore each respective area @@ -94,7 +82,7 @@ flowchart TB subgraph PSL ["Blockchain Development"] direction LR PS["Polkadot SDK"] --> R[WASM Runtime - Substrate & FRAME] - R -->Parachain["Parachain/Task"]-->SSC["Shared Security - Cumulus"]-->Core("Deployed on a Core") + R -->Parachain["Parachain/Task"]-->SSC["Shared Security - Cumulus"] R -->SoloChain[Solo Chain]-->NSS["No Shared Security"] end end @@ -125,7 +113,7 @@ context about the application you could make. [Take a look at the various development network options here.](./build-network-overview.md) -## Building Parachains (Tasks) +## Building Parachains {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is canonically referred to as the Relay Chain. It is also considered a _layer zero_ protocol, as it enables the interoperability and @@ -134,10 +122,6 @@ protocols. Parachains currently connect to a relay chain using the [Parachains Protocol](../learn/learn-parachains-protocol.md). More elaborate (or simpler) tasks could be constructed in the future. -A parachain is one of the examples of a type of **task**, which runs on a core on Polkadot. In -theory, one could develop other types of tasks, not just other blockchains, that can run on a -Polkadot core. - ![build 1](../assets/build-1.png) :::info @@ -222,10 +206,6 @@ followed by FRAME, with Cumulus as the final step to understanding the entire pa process. This way, one can view how various paradigms are applied and decide on integrating or utilizing Substrate for their particular use case. - - -Please see the parachain development guide for how to start building a parachain. - ### Building a Pallet While parachains are highly customizable, they are often complex to develop. If you wish to get @@ -234,20 +214,6 @@ environment. A pallet is a fully customizable module that allows you to implemen with relatively minimal development time on a fundamental level while still allowing the possibility of building advanced functionality into your custom chain. -## Deploying on a Core - -Once you have your runtime and pallets developed, you will be able to deploy it on a -[core](../learn/learn-agile-coretime.md#core), which is how one utilizes the shared security of the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. One does so by: - -1. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your - state transitions from one state to the next. -2. **Generating** your genesis state. -3. **Obtaining** a core, most likely through a - [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). -4. **Registering** the runtime blob and genesis state with that core. -5. **Ensuring** you have at least one honest, synced collator for your task - ## Developing Smart Contracts Smart contracts are another option that enables an often simpler developer experience. Below is a diff --git a/docs/build/build-guides-coretime-start.md b/docs/build/build-guides-coretime-start.md new file mode 100644 index 000000000000..85d3a8861bd7 --- /dev/null +++ b/docs/build/build-guides-coretime-start.md @@ -0,0 +1,41 @@ +--- +id: build-guides-coretime-start +title: Getting Started - Deploying on Coretime +sidebar_label: Getting Started with Coretime +description: Getting started with Agile Coretime +keywords: [coretime, blockspace, parathread, parachain, cores] +slug: ../build-guides-coretime-start +--- + +:::warning Only for Kusama and testnets! + +The following content is only for the Kusama and testnet networks at the moment, and is not yet +deployed on Polkadot. + +::: + +## Deploying on a Core + +Once you have your runtime and pallets developed, you will be able to deploy it on a +[core](../learn/learn-agile-coretime.md#core), which is how one utilizes the shared security of the +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. One does so by: + +1. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your + state transitions from one state to the next. +2. **Generating** your genesis state. +3. **Obtaining** a core, most likely through a + [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). +4. **Registering** the runtime blob and genesis state with that core. +5. **Ensuring** you have at least one honest, synced collator for your task + +:::info What is a task? + +You might see the term "task" referenced quite a bit, but in most cases, it refers to a process +utilizing Polkadot's compute. This could be a parachain or any other computational process, provided +that it adheres to the Polkadot protocol. + +The full definition can be found here. + +::: + +## Polkadot SDK Templates diff --git a/docs/build/build-guides-coretime-adder-collator.md b/docs/learn/learn-guides-coretime-parachains.md similarity index 96% rename from docs/build/build-guides-coretime-adder-collator.md rename to docs/learn/learn-guides-coretime-parachains.md index 16dd257b8ca4..20dad4d8f610 100644 --- a/docs/build/build-guides-coretime-adder-collator.md +++ b/docs/learn/learn-guides-coretime-parachains.md @@ -1,10 +1,10 @@ --- -id: build-guides-coretime-adder-collator -title: Getting Started - Adder Collator -sidebar_label: Getting Started - Adder Collator -description: Getting started with Agile Coretime with Adder Collator +id: learn-guides-coretime-parachains +title: Agile Coretime for Parachains +sidebar_label: Coretime for Parachains +description: Agile Coretime from Parachains perspective keywords: [coretime, blockspace, parathread, parachain, cores] -slug: ../build-guides-coretime-adder-collator +slug: ../learn-guides-coretime-parachains --- import RPC from "./../../components/RPC-Connection"; diff --git a/kusama-guide/sidebars.js b/kusama-guide/sidebars.js index 56219908ce4d..ca6c11978a8f 100644 --- a/kusama-guide/sidebars.js +++ b/kusama-guide/sidebars.js @@ -722,6 +722,19 @@ module.exports = { 'build/build-open-source' ], }, + { + type: "category", + label: "Getting Started with Coretime", + link: { + type: 'generated-index', + title: "Getting Started with Coretime", + description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", + slug: '/build-coretime-index', + }, + items: [ + "build/build-guides-coretime-adder-collator" + ], + }, { type: "category", label: "Resources", diff --git a/polkadot-wiki/sidebars.js b/polkadot-wiki/sidebars.js index 1f5f34a26b20..c12badf19a66 100644 --- a/polkadot-wiki/sidebars.js +++ b/polkadot-wiki/sidebars.js @@ -458,6 +458,7 @@ module.exports = { items: [ "learn/learn-agile-coretime", "learn/learn-guides-coretime-marketplaces", + "learn/learn-guides-coretime-parachains", ], }, { @@ -722,19 +723,6 @@ module.exports = { ], }, "build/build-smart-contracts", - { - type: "category", - label: "Getting Started with Coretime", - link: { - type: 'generated-index', - title: "Getting Started with Coretime", - description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", - slug: '/build-protocol-index', - }, - items: [ - "build/build-guides-coretime-adder-collator" - ], - }, { type: "category", label: "Protocol Development Resources", From 6b97a3ec45fc4554779268c367b50da39c5552f9 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Wed, 1 May 2024 20:09:59 -0400 Subject: [PATCH 08/21] kusamafy --- docs/build/build-guides-coretime-start.md | 46 ++++-- docs/build/build-guides-install-linux.md | 140 +++++++++++++++++ docs/build/build-guides-install-macos.md | 152 +++++++++++++++++++ docs/build/build-guides-install-windows.md | 165 +++++++++++++++++++++ kusama-guide/sidebars.js | 76 +++++++--- 5 files changed, 548 insertions(+), 31 deletions(-) create mode 100644 docs/build/build-guides-install-linux.md create mode 100644 docs/build/build-guides-install-macos.md create mode 100644 docs/build/build-guides-install-windows.md diff --git a/docs/build/build-guides-coretime-start.md b/docs/build/build-guides-coretime-start.md index 85d3a8861bd7..90141afe76bd 100644 --- a/docs/build/build-guides-coretime-start.md +++ b/docs/build/build-guides-coretime-start.md @@ -1,32 +1,54 @@ --- id: build-guides-coretime-start -title: Getting Started - Deploying on Coretime -sidebar_label: Getting Started with Coretime -description: Getting started with Agile Coretime +title: Getting Started - Intro to the Polkadot SDK +sidebar_label: Intro to the Polkadot SDK +description: Introduction to the Polkadot SDK keywords: [coretime, blockspace, parathread, parachain, cores] slug: ../build-guides-coretime-start --- +:::warning This section is under construction! + +::: + :::warning Only for Kusama and testnets! -The following content is only for the Kusama and testnet networks at the moment, and is not yet -deployed on Polkadot. +Agile coretime is only for the Kusama and testnet networks at the moment, and is not yet deployed on +Polkadot. ::: +## Polkadot SDK + +At first glance, the Polkadot SDK can be rather overwhelming, and in a way it is - it packs a lot of +tech into one place. The Polkadot SDK used to be overarching **three** respositories: + +- **Polkadot** - Which for a time, included both the client implementation and runtime, until the + runtime was moved to the Polkadot Fellows organization. +- **Substrate** - The underlying, core primitives and libraries for building blockchains (any + blockchain, not just one for Polkadot). Much of Polkadot is built with Substrate! +- **Cumulus** - A set of libraries and tools which pertain specifically with connecting blockchains + to Polkadot, known as parachains. + +> For an in-depth dive into the monorepo, I highly recommend you look into the +> [Polkadot SDK Docs, which explains everything.](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html) + ## Deploying on a Core Once you have your runtime and pallets developed, you will be able to deploy it on a [core](../learn/learn-agile-coretime.md#core), which is how one utilizes the shared security of the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. One does so by: -1. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your - state transitions from one state to the next. -2. **Generating** your genesis state. -3. **Obtaining** a core, most likely through a +1. **Reserving** a [`ParaId`](../general/glossary.md#paraid), where you will upload your runtime and + genesis state. +2. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your + state transitions from one state to the next. This runtime is created using the Polkadot SDK. 2a. + **Ensure** your chain spec is viable and ready to be deployed as a live, working parachain. +3. **Generating** your genesis state and wasm. +4. **Obtaining** a core, most likely through a [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). -4. **Registering** the runtime blob and genesis state with that core. -5. **Ensuring** you have at least one honest, synced collator for your task +5. **Assigning** that core to your[ `ParaId`](../general/glossary.md#paraid). +6. **Ensuring** you have at least one honest, synced collator for your task :::info What is a task? @@ -37,5 +59,3 @@ that it adheres to the Polkadot protocol. The full definition can be found here. ::: - -## Polkadot SDK Templates diff --git a/docs/build/build-guides-install-linux.md b/docs/build/build-guides-install-linux.md new file mode 100644 index 000000000000..cd24bf5dad24 --- /dev/null +++ b/docs/build/build-guides-install-linux.md @@ -0,0 +1,140 @@ +--- +id: build-guides-install-linux +title: Linux +sidebar_label: Linux +description: Install dependencies for Linux +keywords: [coretime, blockspace, parathread, parachain, cores] +slug: ../build-guides-install-linux +--- + +Rust supports most Linux distributions. Depending on the specific distribution and version of the +operating system you use, you might need to add some software dependencies to your environment. In +general, your development environment should include a linker or C-compatible compiler such as +`clang` and an appropriate integrated development environment (IDE). + +## Before you begin + +Check the documentation for your operating system for information about the packages that are +installed and how to download and install any additional packages you might need. For example, if +you use Ubuntu, you can use the Ubuntu Advanced Packaging Tool (`apt`) to install the +`build-essential` package: + +```bash +sudo apt install build-essential +``` + +At a minimum, you need the following packages before you install Rust: + +```text +clang curl git make +``` + +Because the blockchain requires standard cryptography to support the generation of public/private +key pairs and the validation of transaction signatures, you must also have a package that provides +cryptography, such as `libssl-dev` or `openssl-devel`. + +## Install required packages and Rust + +To install the Rust toolchain on Linux: + +1. Log on to your computer and open a terminal shell. + +2. Check the packages you have installed on the local computer by running an appropriate package + management command for your Linux distribution. + +3. Add any package dependencies you are missing to your local development environment by running an + appropriate package management command for your Linux distribution. + + For example, on Ubuntu Desktop or Ubuntu Server, you might run a command similar to the + following: + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev protobuf-compiler + ``` + + Click the tab titles to see examples for other Linux operating systems: + +
+ + [[tabbedCode]] |```Debian | sudo apt install --assume-yes git clang curl libssl-dev llvm + libudev-dev make protobuf-compiler + + [[tabbedCode]] |```Arch | pacman -Syu --needed --noconfirm curl git clang make protobuf + + [[tabbedCode]] | ```fedora | sudo dnf update | sudo dnf install clang curl git openssl-devel make + protobuf-compiler + + [[tabbedCode]] | ```opensuse | sudo zypper install clang curl git openssl-devel llvm-devel + libudev-devel make protobuf + +
+ + Remember that different distributions might use different package managers and bundle packages in + different ways. For example, depending on your installation selections, Ubuntu Desktop and Ubuntu + Server might have different packages and different requirements. However, the packages listed in + the command-line examples are applicable for many common Linux distributions, including Debian, + Linux Mint, MX Linux, and Elementary OS. + +4. Download the `rustup` installation program and use it to install Rust by running the following + command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +5. Follow the prompts displayed to proceed with a default installation. + +6. Update your current shell to include Cargo by running the following command: + + ```bash + source $HOME/.cargo/env + ``` + +7. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +8. Configure the Rust toolchain to default to the latest stable version by running the following + commands: + + ```bash + rustup default stable + rustup update + ``` + +9. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development + environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +10. Verify the configuration of your development environment by running the following command: + +```bash +rustup show +rustup +nightly show +``` + +The command displays output similar to the following: + +```bash +# rustup show + +active toolchain +---------------- + +stable-x86_64-unknown-linux-gnu (default) +rustc 1.62.1 (e092d0b6b 2022-07-16) + +# rustup +nightly show + +active toolchain +---------------- + +nightly-x86_64-unknown-linux-gnu (overridden by +toolchain on the command line) +rustc 1.65.0-nightly (34a6cae28 2022-08-09) +``` diff --git a/docs/build/build-guides-install-macos.md b/docs/build/build-guides-install-macos.md new file mode 100644 index 000000000000..23c2ae2bf3c0 --- /dev/null +++ b/docs/build/build-guides-install-macos.md @@ -0,0 +1,152 @@ +--- +id: build-guides-install-macos +title: macOS +sidebar_label: macOS +description: Install dependencies for macOS +keywords: [coretime, blockspace, parathread, parachain, cores] +slug: ../build-guides-install-macos +--- + +You can install Rust and set up a Substrate development environment on Apple macOS computers with +either Intel or an Apple M1 processors. + +## Before you begin + +Before you install Rust and set up your development environment on macOS, verify that your computer +meets the following basic requirements: + +- Operating system version is 10.7 Lion, or later. +- Processor speed of at least 2Ghz, 3Ghz recommended. +- Memory of at least 8 GB RAM, 16 GB recommended. +- Storage of at 10 GB available space. +- Broadband Internet connection. + +### Support for Apple Silicon + +Protobuf must be installed before the build process can begin. To install it, run the following +command: + +`brew install protobuf` + +### Install Homebrew + +In most cases, you should use Homebrew to install and manage packages on macOS computers. If you +don't already have Homebrew installed on your local computer, you should download and install it +before continuing. + +To install Homebrew: + +1. Open the Terminal application. + +2. Download and install Homebrew by running the following command: + + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" + ``` + +3. Verify Homebrew has been successfully installed by running the following command: + + ```bash + brew --version + ``` + + The command displays output similar to the following: + + ```bash + Homebrew 3.3.1 + Homebrew/homebrew-core (git revision c6c488fbc0f; last commit 2021-10-30) + Homebrew/homebrew-cask (git revision 66bab33b26; last commit 2021-10-30) + ``` + +## Installation + +Because the blockchain requires standard cryptography to support the generation of public/private +key pairs and the validation of transaction signatures, you must also have a package that provides +cryptography, such as `openssl`. + +To install `openssl` and the Rust toolchain on macOS: + +1. Open the Terminal application. + +2. Ensure you have an updated version of Homebrew by running the following command: + + ```bash + brew update + ``` + +3. Install the `openssl` package by running the following command: + + ```bash + brew install openssl + ``` + +4. Download the `rustup` installation program and use it to install Rust by running the following + command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +5. Follow the prompts displayed to proceed with a default installation. + +6. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +7. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +8. Configure the Rust toolchain to default to the latest stable version by running the following + commands: + + ```bash + rustup default stable + rustup update + rustup target add wasm32-unknown-unknown + ``` + +9. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development + environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +10. Verify the configuration of your development environment by running the following command: + +```bash +rustup show +rustup +nightly show +``` + +The command displays output similar to the following: + +```bash +# rustup show + +active toolchain +---------------- + +stable-x86_64-apple-darwin (default) +rustc 1.61.0 (fe5b13d68 2022-05-18) + +# rustup +nightly show + +active toolchain +---------------- + +nightly-x86_64-apple-darwin (overridden by +toolchain on the command line) +rustc 1.63.0-nightly (e71440575 2022-06-02) +``` + +11. Install `cmake` using the following command: + +``` +brew install cmake +``` diff --git a/docs/build/build-guides-install-windows.md b/docs/build/build-guides-install-windows.md new file mode 100644 index 000000000000..e1ca48783fbf --- /dev/null +++ b/docs/build/build-guides-install-windows.md @@ -0,0 +1,165 @@ +--- +id: build-guides-install-windows +title: Windows +sidebar_label: Windows +description: Install dependencies for Windows +keywords: [coretime, blockspace, parathread, parachain, cores] +slug: ../build-guides-install-windows +--- + +In general, UNIX-based operating systems—like macOS or Linux—provide a better development +environment for building Substrate-based blockchains. + +However, if your local computer uses Microsoft Windows instead of a UNIX-based operating system, you +can configure it with additional software to make it a suitable development environment for building +Substrate-based blockchains. To prepare a development environment on a computer running Microsoft +Windows, you can use Windows Subsystem for Linux (WSL) to emulate a UNIX operating environment. + +## Before you begin + +Before installing on Microsoft Windows, verify the following basic requirements: + +- You have a computer running a supported version of the Microsoft Windows operating system. +- You must be running Microsoft Windows 10, version 2004 or later, or Microsoft Windows 11 to + install Windows Subsystem for Linux on a computer with the Windows desktop operating system. +- You must be running Microsoft Windows Server 2019, or later, to install Windows Subsystem for + Linux on a computer with the Windows server operating system. +- You have good internet connection and access to a shell terminal on your local computer. + +## Set up Windows Subsystem for Linux + +Windows Subsystem for Linux (WSL) enables you to emulate a Linux environment on a computer that uses +the Windows operating system. The primary advantage of this approach for Substrate development is +that you can use all of the code and command-line examples as described in the Substrate +documentation. For example, you can run common commands—such as `ls` and `ps`—unmodified. By using +Windows Subsystem for Linux, you can avoid configuring a virtual machine image or a dual-boot +operating system. + +To prepare a development environment using Windows Subsystem for Linux: + +1. Check your Windows version and build number to see if Windows Subsystem for Linux is enabled by + default. + + If you have Microsoft Windows 10, version 2004 (Build 19041 and higher), or Microsoft Windows 11, + Windows Subsystem for Linux is available by default and you can continue to the next step. + + If you have an older version of Microsoft Windows installed, see + [WSL manual installation steps for older versions](https://docs.microsoft.com/en-us/windows/wsl/install-manual). + If you are installing on an older version of Microsoft Windows, you can download and install WLS + 2 if your computer has Windows 10, version 1903 or higher. + +2. Select Windows PowerShell or Command Prompt from the Start menu, right-click, then **Run as + administrator**. + +3. In the PowerShell or Command Prompt terminal, run the following command: + + ```bash + wsl --install + ``` + + This command enables the required WSL 2 components that are part of the Windows operating system, + downloads the latest Linux kernel, and installs the Ubuntu Linux distribution by default. + + If you want to review the other Linux distributions available, run the following command: + + ```bash + wsl --list --online + ``` + +4. After the distribution is downloaded, close the terminal. + +5. Click the Start menu, select **Shut down or sign out**, then click **Restart** to restart the + computer. + + Restarting the computer is required to start the installation of the Linux distribution. It can + take a few minutes for the installation to complete after you restart. + + For more information about setting up WSL as a development environment, see + [Set up a WSL development environment](https://docs.microsoft.com/en-us/windows/wsl/setup/environment). + +## Install required packages and Rust + +To install the Rust toolchain on WSL: + +1. Click the Start menu, then select **Ubuntu**. + +2. Type a UNIX user name to create user account. + +3. Type a password for your UNIX user, then retype the password to confirm it. + +4. Download the latest updates for the Ubuntu distribution using the Ubuntu Advanced Packaging Tool + (`apt`) by running the following command: + + ```bash + sudo apt update + ``` + +5. Add the required packages for the Ubuntu distribution by running the following command: + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler + ``` + +6. Download the `rustup` installation program and use it to install Rust for the Ubuntu distribution + by running the following command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +7. Follow the prompts displayed to proceed with a default installation. + +8. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +9. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +10. Configure the Rust toolchain to use the latest stable version as the default toolchain by + running the following commands: + +```bash +rustup default stable +rustup update +``` + +11. Add the `nightly` version of the toolchain and the `nightly` WebAssembly (`wasm`) target to your + development environment by running the following commands: + +```bash +rustup update nightly +rustup target add wasm32-unknown-unknown --toolchain nightly +``` + +12. Verify the configuration of your development environment by running the following command: + +```bash +rustup show +rustup +nightly show +``` + +The command displays output similar to the following: + +```bash +# rustup show + +active toolchain +---------------- + +stable-x86_64-unknown-linux-gnu (default) +rustc 1.61.0 (fe5b13d68 2022-05-18) + +# rustup +nightly show + +active toolchain +---------------- + +nightly-x86_64-unknown-linux-gnu (overridden by +toolchain on the command line) +rustc 1.63.0-nightly (e7144 +``` diff --git a/kusama-guide/sidebars.js b/kusama-guide/sidebars.js index ca6c11978a8f..e1ef660a1ad9 100644 --- a/kusama-guide/sidebars.js +++ b/kusama-guide/sidebars.js @@ -698,41 +698,81 @@ module.exports = { { type: "category", label: "Build", + link: { + type: 'doc', + id: "build/build-guide" + }, items: [ - "build/build-index", - "maintain/maintain-endpoints", + "build/build-network-overview", { type: "category", - label: "Development Guide", + label: "Client-side Development", + link: { + type: 'generated-index', + title: "Client-side Development", + description: "Learn about different options for building client-side apps on Polkadot.", + slug: '/build-client-index', + }, items: [ - "build/build-guide", - "build/build-parachains", - "build/build-storage", - "build/build-smart-contracts", - "build/build-oracle", - "build/build-data", + "build/build-client-side", "build/build-light-clients", + "build/build-node-interaction", ], }, { type: "category", - label: "Tools", + label: "Getting Started with Coretime", + link: { + type: 'generated-index', + title: "Getting Started with Coretime", + description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", + slug: '/build-coretime-index', + }, items: [ - "build/build-tools-index", - 'build/build-open-source' + { + type: "category", + label: "Installing Dependencies", + link: { + type: 'generated-index', + title: "Installing Dependencies", + description: "Install the necessary development dependencies needed to start with the Polkadot SDK", + slug: '/build-install-dependencies', + }, + items: [ + "build/build-guides-install-macos", + "build/build-guides-install-linux", + "build/build-guides-install-windows" + ] + }, + "build/build-guides-coretime-start" ], }, + "build/build-smart-contracts", { type: "category", - label: "Getting Started with Coretime", + label: "Protocol Development Resources", link: { type: 'generated-index', - title: "Getting Started with Coretime", - description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", - slug: '/build-coretime-index', + title: "Protocol Development Resources", + description: "Miscellaneous aspects concerning protocol and parachain development", + slug: '/build-protocol-index', }, items: [ - "build/build-guides-coretime-adder-collator" + "build/build-protocol-info", + "build/build-integrate-assets", + "build/build-hrmp-channels" + ], + }, + { + type: "category", + label: "Tooling", + link: { + type: 'doc', + id: "build/build-tools-index" + }, + items: [ + "build/build-data", + "build/build-open-source", ], }, { @@ -741,7 +781,7 @@ module.exports = { items: ["build/build-hackathon"], }, ], - }, + }, { type: "category", label: "What to Break", From 4b1086567b86dfee125a27f5a393ed364ab39f16 Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:50:47 -0400 Subject: [PATCH 09/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 518d0f6ab5b3..f344d81250b0 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -9,8 +9,8 @@ slug: ../build-guide import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain protocol and network -that provides **shared security** amongst all connected parachains and allowing all connected tasks +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain network protocol +that provides **shared security** among all connected parachains and allowing all connected tasks to **interoperate** by using [XCM](../learn/learn-xcm.md). The time it takes to develop and launch a new chain has dropped significantly with the tools From 59a852086504532dcce58eec10e09a465eb04a26 Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:50:59 -0400 Subject: [PATCH 10/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index f344d81250b0..27674adf82bf 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -13,9 +13,7 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; that provides **shared security** among all connected parachains and allowing all connected tasks to **interoperate** by using [XCM](../learn/learn-xcm.md). -The time it takes to develop and launch a new chain has dropped significantly with the tools -Polkadot provides. While before, it would take years to launch a new chain, now it may only take -weeks or even days, depending on your goals. +With the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) and [Agile Coretime](../learn/learn-agile-coretime.md), the time it takes to develop and launch a new chain has dropped significantly. Depending on your goals, it may only take weeks or even days. This starters guide will walk you through the steps you can take today to get started building your vision with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will also point to From 1af6cd999750e3a07ee04c08689bb13e6d88dcac Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:51:15 -0400 Subject: [PATCH 11/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 27674adf82bf..7bbab3103479 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -131,7 +131,7 @@ extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} an ::: -The Polkadot SDK opens possibilities to construct complex **runtime**, or **STF** (state transition +Parachains built through the Polkadot SDK, open possibilities to construct complex **runtime**, or **STF** (state transition function) the logic that would be too expensive to execute with smart contracts. However, unlike smart contracts, parachains lack a mandatory gas metering system entirely and could potentially be vulnerable to bugs that cause infinite loops (something that is prevented by design in smart From d6f4507596db7b387700fbfcfaf8fbef866bb27e Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:51:23 -0400 Subject: [PATCH 12/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 7bbab3103479..0d795413b2fc 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -22,7 +22,7 @@ resources you can use to start building immediately. :::note For Developers! Please note that the following documentation is more geared towards developers. If you are looking -for more general knowledge related to Polkadot, be sure to check otu the +for more general knowledge related to Polkadot, be sure to check out the [Learn](../learn/learn-index) section. Looking to jump into a guide? Check out our starter developer guides for creating a minimal From 749c58e54d53670ee5588128552408ed0c7ba2bd Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:51:36 -0400 Subject: [PATCH 13/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 0d795413b2fc..80f92a3af948 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -177,9 +177,9 @@ to construct a runtime/STF and define how your task is supposed to behave. Rangi pallets can be quite extensive in providing on-chain functionality. Even though FRAME is heavily used, it is not the only way to create a valid runtime/STF using -Substrate. Substrate can be used to create new paradigms and abstractions, one such example is the +Substrate. Substrate can be used to create new paradigms and abstractions. One such example is the [Open Runtime Module Library (ORML)](https://github.com/open-web3-stack/open-runtime-module-library), -which is another way creating and using runtime modules. +which is another way of creating and using runtime modules. :::note From 38a7949376fcef78ccc2846c4062a2db6c93bac0 Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:51:47 -0400 Subject: [PATCH 14/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 80f92a3af948..e3e188c5b918 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -244,8 +244,8 @@ For a more comprehensive (and maintained) comparison, be sure to check out the ### ink! and EVM-based Smart Contracts At a high level, a _smart contract_ is simply some code that exists at an address on a chain and is -callable by external actors. Whether it's [EVM-based](https://polkadot-evm.github.io/frontier/), or -written using [ink!](https://use.ink/), smart contracts sandboxed, executable programs that live +callable by external actors. Whether it's [EVM-based](https://polkadot-evm.github.io/frontier/) or +written using [ink!](https://use.ink/), smart contracts are sandboxed, executable programs that live on-chain. :::note From 977a4a5887eb34154eacd3bb53e9a7a1d901a51f Mon Sep 17 00:00:00 2001 From: bader y Date: Thu, 2 May 2024 11:52:12 -0400 Subject: [PATCH 15/21] Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index e3e188c5b918..fbb42788c4bc 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -194,10 +194,12 @@ comparably minimal effort. #### Building Parachains with Cumulus -[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) -transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and Substrate-based -nodes into Polkadot/Parachain-compatible nodes. In other words, Cumulus can enable a regular runtime -to meet the requirements to have its state verified by Polkadot and take part in shared security. +[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) is a set of tools that allows you to convert a blockchain developed using Substrate and FRAME into a Polkadot-compatible Parachain. More specifically, it provides libraries for all of the necessary parts of the Polkadot protocol necessary for Parachains to work, for example: + +- Creating new parachain blocks via Collators +- Listening to the relay chain for updates +- Synchronizing upgrades between the parachain and relay chain + For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building From 0879f3dda1f94af2686bfc89f45c21d6167680b9 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Thu, 2 May 2024 16:24:01 -0400 Subject: [PATCH 16/21] Address feedback --- docs/build/build-guide.md | 31 ++++++++++++++++--------------- docs/learn/learn-parachains.md | 23 +++++++++++++++++++++++ 2 files changed, 39 insertions(+), 15 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index fbb42788c4bc..7ecc1af96369 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -9,11 +9,13 @@ slug: ../build-guide import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain network protocol -that provides **shared security** among all connected parachains and allowing all connected tasks -to **interoperate** by using [XCM](../learn/learn-xcm.md). +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain network protocol that +provides **shared security** among all connected parachains and allowing all connected tasks to +**interoperate** by using [XCM](../learn/learn-xcm.md). -With the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) and [Agile Coretime](../learn/learn-agile-coretime.md), the time it takes to develop and launch a new chain has dropped significantly. Depending on your goals, it may only take weeks or even days. +With the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) and +[Agile Coretime](../learn/learn-agile-coretime.md), the time it takes to develop and launch a new +chain has dropped significantly. Depending on your goals, it may only take weeks or even days. This starters guide will walk you through the steps you can take today to get started building your vision with {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It will also point to @@ -25,9 +27,6 @@ Please note that the following documentation is more geared towards developers. for more general knowledge related to Polkadot, be sure to check out the [Learn](../learn/learn-index) section. -Looking to jump into a guide? Check out our starter developer guides for creating a minimal -blockchain and deploying it on a testnet. - ::: This build guide covers three different areas, taking a **top-down** approach from protocol @@ -36,7 +35,7 @@ development to user-facing applications: -1. [Protocol Development - Developing parachains/blockchains](#building-parachains-tasks) +1. [Runtime Development - Developing parachains/blockchains](#building-parachains-tasks) 2. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) 3. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) @@ -131,11 +130,11 @@ extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} an ::: -Parachains built through the Polkadot SDK, open possibilities to construct complex **runtime**, or **STF** (state transition -function) the logic that would be too expensive to execute with smart contracts. However, unlike -smart contracts, parachains lack a mandatory gas metering system entirely and could potentially be -vulnerable to bugs that cause infinite loops (something that is prevented by design in smart -contracts). This vulnerability is mitigated by the +Parachains built through the Polkadot SDK, open possibilities to construct complex **runtime**, or +**STF** (state transition function) the logic that would be too expensive to execute with smart +contracts. However, unlike smart contracts, parachains lack a mandatory gas metering system entirely +and could potentially be vulnerable to bugs that cause infinite loops (something that is prevented +by design in smart contracts). This vulnerability is mitigated by the [weight system](https://docs.substrate.io/build/tx-weights-fees/) that is implemented in Substrate -- although it places more of a burden on the developer of the parachain to perform properly benchmarks. @@ -194,13 +193,15 @@ comparably minimal effort. #### Building Parachains with Cumulus -[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) is a set of tools that allows you to convert a blockchain developed using Substrate and FRAME into a Polkadot-compatible Parachain. More specifically, it provides libraries for all of the necessary parts of the Polkadot protocol necessary for Parachains to work, for example: +[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) +is a set of tools that allows you to convert a blockchain developed using Substrate and FRAME into a +Polkadot-compatible Parachain. More specifically, it provides libraries for all of the necessary +parts of the Polkadot protocol necessary for Parachains to work, for example: - Creating new parachain blocks via Collators - Listening to the relay chain for updates - Synchronizing upgrades between the parachain and relay chain - For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building process. This way, one can view how various paradigms are applied and decide on integrating or diff --git a/docs/learn/learn-parachains.md b/docs/learn/learn-parachains.md index aa9c721f08ea..31f2574b0c2b 100644 --- a/docs/learn/learn-parachains.md +++ b/docs/learn/learn-parachains.md @@ -80,6 +80,29 @@ Parachains are a solution to two fundamental problems in blockchains: specific problem has more leverage toward itself and its users. Parachains are purpose-built blockchains are highly specialized and can take advantage of each other through cooperation. +### Parachain Benefits + +Parachains contain their own runtime/STF logic and benefit from the shared security and the +cross-consensus messaging provided by the {{ polkadot: Polkadot :polkadot }} relay chain. Parachains +permit high flexibility and customization but require more effort to create and maintain over time. +A production-grade parachain is typically more involved to create due to the complexity involved in +blockchain networks' technical and economic aspects. + +Parachains grant the creators more space to build the monetary system and other chain aspects from +the ground up. They will allow for a more concise and efficient execution of complex logic than a +smart contract platform could offer. Parachains also provide more flexibility in the form of +governance and can perform complete upgrades in a less controversial way than the current process of +hard forks. + +Some examples of features you can have on a parachain or parathread: + +- Custom fee structure (for example, pay a flat transaction fee or pay per byte). +- Shared security and finalization via the relay chain (Polkadot or Kusama). +- Custom monetary policy for the native token and local economy. +- Treasury to be funded through transitions in your state function. +- A governance mechanism that could manage a DAO that is responsible for allocating your on-chain + treasury. + ### Shared Security Shared security, sometimes referred as _pooled security_, is one of the unique value propositions From e86c0bd645ee73413ad2fd82427a8034a1008ced Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Thu, 2 May 2024 16:34:36 -0400 Subject: [PATCH 17/21] Add link --- docs/build/build-guide.md | 2 +- docs/build/build-guides-coretime-start.md | 34 +++++++++++++---------- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 7ecc1af96369..5c6c38c14e43 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -35,7 +35,7 @@ development to user-facing applications: -1. [Runtime Development - Developing parachains/blockchains](#building-parachains-tasks) +1. [Runtime Development - Developing parachains/blockchains](#building-parachains) 2. [Smart Contract Development - How Polkadot handles smart contracts](#developing-smart-contracts) 3. [dApp Development - The tools available for dApp development on Polkadot](#developing-a-dapp) diff --git a/docs/build/build-guides-coretime-start.md b/docs/build/build-guides-coretime-start.md index 90141afe76bd..e68cb908b48e 100644 --- a/docs/build/build-guides-coretime-start.md +++ b/docs/build/build-guides-coretime-start.md @@ -18,10 +18,10 @@ Polkadot. ::: -## Polkadot SDK +## Using the Polkadot SDK At first glance, the Polkadot SDK can be rather overwhelming, and in a way it is - it packs a lot of -tech into one place. The Polkadot SDK used to be overarching **three** respositories: +tech into one place. The Polkadot SDK used to be overarching **three** repositories: - **Polkadot** - Which for a time, included both the client implementation and runtime, until the runtime was moved to the Polkadot Fellows organization. @@ -30,9 +30,19 @@ tech into one place. The Polkadot SDK used to be overarching **three** resposito - **Cumulus** - A set of libraries and tools which pertain specifically with connecting blockchains to Polkadot, known as parachains. -> For an in-depth dive into the monorepo, I highly recommend you look into the +> For an in-depth dive into the monorepo, it is highly recommended that you look into the > [Polkadot SDK Docs, which explains everything.](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html) +:::info What is a task? + +You might see the term "task" referenced quite a bit, but in most cases, it refers to a process +utilizing Polkadot's compute. This could be a parachain or any other computational process, provided +that it adheres to the Polkadot protocol. + +The full definition can be found [here](../learn/learn-agile-coretime.md#task). + +::: + ## Deploying on a Core Once you have your runtime and pallets developed, you will be able to deploy it on a @@ -41,21 +51,17 @@ Once you have your runtime and pallets developed, you will be able to deploy it 1. **Reserving** a [`ParaId`](../general/glossary.md#paraid), where you will upload your runtime and genesis state. -2. **Compiling** the runtime (written in Rust) to a WebAssembly blob, thereby defining how your - state transitions from one state to the next. This runtime is created using the Polkadot SDK. 2a. - **Ensure** your chain spec is viable and ready to be deployed as a live, working parachain. +2. **Compiling** the runtime (written in Rust) to a [WebAssembly](../learn/learn-wasm.md) blob, + thereby defining how your state transitions from one state to the next. This runtime is created + using the Polkadot SDK. 2a. **Ensure** your chain spec is viable and ready to be deployed as a + live, working parachain. 3. **Generating** your genesis state and wasm. 4. **Obtaining** a core, most likely through a [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). 5. **Assigning** that core to your[ `ParaId`](../general/glossary.md#paraid). 6. **Ensuring** you have at least one honest, synced collator for your task -:::info What is a task? - -You might see the term "task" referenced quite a bit, but in most cases, it refers to a process -utilizing Polkadot's compute. This could be a parachain or any other computational process, provided -that it adheres to the Polkadot protocol. - -The full definition can be found here. +### Deploy adder collator -::: +Try out the above by deploying the +[adder collator, a very simple "counter" parachain implementation.](../learn/learn-guides-coretime-parachains.md). From 1ab2bd9f4fc887068fc5884c4eeb59c092667656 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 May 2024 15:06:34 -0400 Subject: [PATCH 18/21] condense installation guides --- docs/build/build-guides-install-deps.md | 425 +++++++++++++++++++++ docs/build/build-guides-install-linux.md | 140 ------- docs/build/build-guides-install-macos.md | 152 -------- docs/build/build-guides-install-windows.md | 165 -------- kusama-guide/sidebars.js | 16 +- 5 files changed, 426 insertions(+), 472 deletions(-) create mode 100644 docs/build/build-guides-install-deps.md delete mode 100644 docs/build/build-guides-install-linux.md delete mode 100644 docs/build/build-guides-install-macos.md delete mode 100644 docs/build/build-guides-install-windows.md diff --git a/docs/build/build-guides-install-deps.md b/docs/build/build-guides-install-deps.md new file mode 100644 index 000000000000..7ef835bb176b --- /dev/null +++ b/docs/build/build-guides-install-deps.md @@ -0,0 +1,425 @@ +--- +id: build-guides-install-deps +title: Install Polkadot SDK Dependencies +sidebar_label: Install Dependencies +description: Install dependencies for developing for using the Polkadot SDK +keywords: [coretime, blockspace, parathread, parachain, cores] +slug: ../build-guides-install-deps +--- + +import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; + +## macOS + +You can install Rust and set up a Substrate development environment on Apple macOS computers with +either Intel or an Apple M1 processors. + +### Before you begin + +Before you install Rust and set up your development environment on macOS, verify that your computer +meets the following basic requirements: + +- Operating system version is 10.7 Lion, or later. +- Processor speed of at least 2Ghz, 3Ghz recommended. +- Memory of at least 8 GB RAM, 16 GB recommended. +- Storage of at 10 GB available space. +- Broadband Internet connection. + +#### Support for Apple Silicon + +Protobuf must be installed before the build process can begin. To install it, run the following +command: + +`brew install protobuf` + +#### Install Homebrew + +In most cases, you should use Homebrew to install and manage packages on macOS computers. If you +don't already have Homebrew installed on your local computer, you should download and install it +before continuing. + +To install Homebrew: + +1. Open the Terminal application. + +2. Download and install Homebrew by running the following command: + + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" + ``` + +3. Verify Homebrew has been successfully installed by running the following command: + + ```bash + brew --version + ``` + + The command displays output similar to the following: + + ```bash + Homebrew 3.3.1 + Homebrew/homebrew-core (git revision c6c488fbc0f; last commit 2021-10-30) + Homebrew/homebrew-cask (git revision 66bab33b26; last commit 2021-10-30) + ``` + +### Installation + +Because the blockchain requires standard cryptography to support the generation of public/private +key pairs and the validation of transaction signatures, you must also have a package that provides +cryptography, such as `openssl`. + +To install `openssl` and the Rust toolchain on macOS: + +1. Open the Terminal application. + +2. Ensure you have an updated version of Homebrew by running the following command: + + ```bash + brew update + ``` + +3. Install the `openssl` package by running the following command: + + ```bash + brew install openssl + ``` + +4. Download the `rustup` installation program and use it to install Rust by running the following + command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +5. Follow the prompts displayed to proceed with a default installation. + +6. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +7. Configure the Rust toolchain to default to the latest stable version by running the following + commands: + + ```bash + rustup default stable + rustup update + rustup target add wasm32-unknown-unknown + ``` + +8. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development + environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +9. [Verify your installation here.](#verifying-installation) + +10. Install `cmake` using the following command: + +``` +brew install cmake +``` + +## Linux + +Rust supports most Linux distributions. Depending on the specific distribution and version of the +operating system you use, you might need to add some software dependencies to your environment. In +general, your development environment should include a linker or C-compatible compiler such as +`clang` and an appropriate integrated development environment (IDE). + +### Before you begin + +Check the documentation for your operating system for information about the packages that are +installed and how to download and install any additional packages you might need. For example, if +you use Ubuntu, you can use the Ubuntu Advanced Packaging Tool (`apt`) to install the +`build-essential` package: + +```bash +sudo apt install build-essential +``` + +At a minimum, you need the following packages before you install Rust: + +```text +clang curl git make +``` + +Because the blockchain requires standard cryptography to support the generation of public/private +key pairs and the validation of transaction signatures, you must also have a package that provides +cryptography, such as `libssl-dev` or `openssl-devel`. + +### Install required packages and Rust + +To install the Rust toolchain on Linux: + +1. Log on to your computer and open a terminal shell. + +2. Check the packages you have installed on the local computer by running an appropriate package + management command for your Linux distribution. + +3. Add any package dependencies you are missing to your local development environment by running an + appropriate package management command for your Linux distribution. + + For example, on Ubuntu Desktop or Ubuntu Server, you might run a command similar to the + following: + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev protobuf-compiler + ``` + + Click the tab titles to see examples for other Linux operating systems: + + + + + + +```sh +sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler +``` + + + + + +```sh +pacman -Syu --needed --noconfirm curl git clang make protobuf +``` + + + + + +```sh +sudo dnf update +sudo dnf install clang curl git openssl-devel make protobuf-compiler +``` + + + + + +```sh +sudo zypper install clang curl git openssl-devel llvm-devel libudev-devel make protobuf +``` + + + + + +Remember that different distributions might use different package managers and bundle packages in +different ways. For example, depending on your installation selections, Ubuntu Desktop and Ubuntu +Server might have different packages and different requirements. However, the packages listed in the +command-line examples are applicable for many common Linux distributions, including Debian, Linux +Mint, MX Linux, and Elementary OS. + +1. Download the `rustup` installation program and use it to install Rust by running the following + command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +2. Follow the prompts displayed to proceed with a default installation. + +3. Update your current shell to include Cargo by running the following command: + + ```bash + source $HOME/.cargo/env + ``` + +4. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +5. Configure the Rust toolchain to default to the latest stable version by running the following + commands: + + ```bash + rustup default stable + rustup update + ``` + +6. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development + environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +7. Verify your installation here. + +## Windows (WSL) + +In general, UNIX-based operating systems—like macOS or Linux—provide a better development +environment for building Substrate-based blockchains. + +However, if your local computer uses Microsoft Windows instead of a UNIX-based operating system, you +can configure it with additional software to make it a suitable development environment for building +Substrate-based blockchains. To prepare a development environment on a computer running Microsoft +Windows, you can use Windows Subsystem for Linux (WSL) to emulate a UNIX operating environment. + +### Before you begin + +Before installing on Microsoft Windows, verify the following basic requirements: + +- You have a computer running a supported version of the Microsoft Windows operating system. +- You must be running Microsoft Windows 10, version 2004 or later, or Microsoft Windows 11 to + install Windows Subsystem for Linux on a computer with the Windows desktop operating system. +- You must be running Microsoft Windows Server 2019, or later, to install Windows Subsystem for + Linux on a computer with the Windows server operating system. +- You have good internet connection and access to a shell terminal on your local computer. + +### Set up Windows Subsystem for Linux + +Windows Subsystem for Linux (WSL) enables you to emulate a Linux environment on a computer that uses +the Windows operating system. The primary advantage of this approach for Substrate development is +that you can use all of the code and command-line examples as described in the Substrate +documentation. For example, you can run common commands—such as `ls` and `ps`—unmodified. By using +Windows Subsystem for Linux, you can avoid configuring a virtual machine image or a dual-boot +operating system. + +To prepare a development environment using Windows Subsystem for Linux: + +1. Check your Windows version and build number to see if Windows Subsystem for Linux is enabled by + default. + + If you have Microsoft Windows 10, version 2004 (Build 19041 and higher), or Microsoft Windows 11, + Windows Subsystem for Linux is available by default and you can continue to the next step. + + If you have an older version of Microsoft Windows installed, see + [WSL manual installation steps for older versions](https://docs.microsoft.com/en-us/windows/wsl/install-manual). + If you are installing on an older version of Microsoft Windows, you can download and install WLS + 2 if your computer has Windows 10, version 1903 or higher. + +2. Select Windows PowerShell or Command Prompt from the Start menu, right-click, then **Run as + administrator**. + +3. In the PowerShell or Command Prompt terminal, run the following command: + + ```bash + wsl --install + ``` + + This command enables the required WSL 2 components that are part of the Windows operating system, + downloads the latest Linux kernel, and installs the Ubuntu Linux distribution by default. + + If you want to review the other Linux distributions available, run the following command: + + ```bash + wsl --list --online + ``` + +4. After the distribution is downloaded, close the terminal. + +5. Click the Start menu, select **Shut down or sign out**, then click **Restart** to restart the + computer. + + Restarting the computer is required to start the installation of the Linux distribution. It can + take a few minutes for the installation to complete after you restart. + + For more information about setting up WSL as a development environment, see + [Set up a WSL development environment](https://docs.microsoft.com/en-us/windows/wsl/setup/environment). + +### Install required packages and Rust + +To install the Rust toolchain on WSL: + +1. Click the Start menu, then select **Ubuntu**. + +2. Type a UNIX user name to create user account. + +3. Type a password for your UNIX user, then retype the password to confirm it. + +4. Download the latest updates for the Ubuntu distribution using the Ubuntu Advanced Packaging Tool + (`apt`) by running the following command: + + ```bash + sudo apt update + ``` + +5. Add the required packages for the Ubuntu distribution by running the following command: + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler + ``` + +6. Download the `rustup` installation program and use it to install Rust for the Ubuntu distribution + by running the following command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +7. Follow the prompts displayed to proceed with a default installation. + +8. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +9. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +10. Configure the Rust toolchain to use the latest stable version as the default toolchain by + running the following commands: + +```bash +rustup default stable +rustup update +``` + +11. Add the `nightly` version of the toolchain and the `nightly` WebAssembly (`wasm`) target to your + development environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +12. [Verify your installation here.](#verifying-installation) + +```bash +rustup update nightly +rustup target add wasm32-unknown-unknown --toolchain nightly +``` + +## Verifying Installation + +Verify the configuration of your development environment by running the following command: + +```bash +rustup show +rustup +nightly show +``` + +The command displays output similar to the following: + +```bash +# rustup show + +active toolchain +---------------- + +stable-x86_64-unknown-linux-gnu (default) +rustc 1.61.0 (fe5b13d68 2022-05-18) + +# rustup +nightly show + +active toolchain +---------------- + +nightly-x86_64-unknown-linux-gnu (overridden by +toolchain on the command line) +rustc 1.63.0-nightly (e7144 +``` diff --git a/docs/build/build-guides-install-linux.md b/docs/build/build-guides-install-linux.md deleted file mode 100644 index cd24bf5dad24..000000000000 --- a/docs/build/build-guides-install-linux.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -id: build-guides-install-linux -title: Linux -sidebar_label: Linux -description: Install dependencies for Linux -keywords: [coretime, blockspace, parathread, parachain, cores] -slug: ../build-guides-install-linux ---- - -Rust supports most Linux distributions. Depending on the specific distribution and version of the -operating system you use, you might need to add some software dependencies to your environment. In -general, your development environment should include a linker or C-compatible compiler such as -`clang` and an appropriate integrated development environment (IDE). - -## Before you begin - -Check the documentation for your operating system for information about the packages that are -installed and how to download and install any additional packages you might need. For example, if -you use Ubuntu, you can use the Ubuntu Advanced Packaging Tool (`apt`) to install the -`build-essential` package: - -```bash -sudo apt install build-essential -``` - -At a minimum, you need the following packages before you install Rust: - -```text -clang curl git make -``` - -Because the blockchain requires standard cryptography to support the generation of public/private -key pairs and the validation of transaction signatures, you must also have a package that provides -cryptography, such as `libssl-dev` or `openssl-devel`. - -## Install required packages and Rust - -To install the Rust toolchain on Linux: - -1. Log on to your computer and open a terminal shell. - -2. Check the packages you have installed on the local computer by running an appropriate package - management command for your Linux distribution. - -3. Add any package dependencies you are missing to your local development environment by running an - appropriate package management command for your Linux distribution. - - For example, on Ubuntu Desktop or Ubuntu Server, you might run a command similar to the - following: - - ```bash - sudo apt install --assume-yes git clang curl libssl-dev protobuf-compiler - ``` - - Click the tab titles to see examples for other Linux operating systems: - -
- - [[tabbedCode]] |```Debian | sudo apt install --assume-yes git clang curl libssl-dev llvm - libudev-dev make protobuf-compiler - - [[tabbedCode]] |```Arch | pacman -Syu --needed --noconfirm curl git clang make protobuf - - [[tabbedCode]] | ```fedora | sudo dnf update | sudo dnf install clang curl git openssl-devel make - protobuf-compiler - - [[tabbedCode]] | ```opensuse | sudo zypper install clang curl git openssl-devel llvm-devel - libudev-devel make protobuf - -
- - Remember that different distributions might use different package managers and bundle packages in - different ways. For example, depending on your installation selections, Ubuntu Desktop and Ubuntu - Server might have different packages and different requirements. However, the packages listed in - the command-line examples are applicable for many common Linux distributions, including Debian, - Linux Mint, MX Linux, and Elementary OS. - -4. Download the `rustup` installation program and use it to install Rust by running the following - command: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` - -5. Follow the prompts displayed to proceed with a default installation. - -6. Update your current shell to include Cargo by running the following command: - - ```bash - source $HOME/.cargo/env - ``` - -7. Verify your installation by running the following command: - - ```bash - rustc --version - ``` - -8. Configure the Rust toolchain to default to the latest stable version by running the following - commands: - - ```bash - rustup default stable - rustup update - ``` - -9. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development - environment by running the following commands: - - ```bash - rustup update nightly - rustup target add wasm32-unknown-unknown --toolchain nightly - ``` - -10. Verify the configuration of your development environment by running the following command: - -```bash -rustup show -rustup +nightly show -``` - -The command displays output similar to the following: - -```bash -# rustup show - -active toolchain ----------------- - -stable-x86_64-unknown-linux-gnu (default) -rustc 1.62.1 (e092d0b6b 2022-07-16) - -# rustup +nightly show - -active toolchain ----------------- - -nightly-x86_64-unknown-linux-gnu (overridden by +toolchain on the command line) -rustc 1.65.0-nightly (34a6cae28 2022-08-09) -``` diff --git a/docs/build/build-guides-install-macos.md b/docs/build/build-guides-install-macos.md deleted file mode 100644 index 23c2ae2bf3c0..000000000000 --- a/docs/build/build-guides-install-macos.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -id: build-guides-install-macos -title: macOS -sidebar_label: macOS -description: Install dependencies for macOS -keywords: [coretime, blockspace, parathread, parachain, cores] -slug: ../build-guides-install-macos ---- - -You can install Rust and set up a Substrate development environment on Apple macOS computers with -either Intel or an Apple M1 processors. - -## Before you begin - -Before you install Rust and set up your development environment on macOS, verify that your computer -meets the following basic requirements: - -- Operating system version is 10.7 Lion, or later. -- Processor speed of at least 2Ghz, 3Ghz recommended. -- Memory of at least 8 GB RAM, 16 GB recommended. -- Storage of at 10 GB available space. -- Broadband Internet connection. - -### Support for Apple Silicon - -Protobuf must be installed before the build process can begin. To install it, run the following -command: - -`brew install protobuf` - -### Install Homebrew - -In most cases, you should use Homebrew to install and manage packages on macOS computers. If you -don't already have Homebrew installed on your local computer, you should download and install it -before continuing. - -To install Homebrew: - -1. Open the Terminal application. - -2. Download and install Homebrew by running the following command: - - ```bash - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" - ``` - -3. Verify Homebrew has been successfully installed by running the following command: - - ```bash - brew --version - ``` - - The command displays output similar to the following: - - ```bash - Homebrew 3.3.1 - Homebrew/homebrew-core (git revision c6c488fbc0f; last commit 2021-10-30) - Homebrew/homebrew-cask (git revision 66bab33b26; last commit 2021-10-30) - ``` - -## Installation - -Because the blockchain requires standard cryptography to support the generation of public/private -key pairs and the validation of transaction signatures, you must also have a package that provides -cryptography, such as `openssl`. - -To install `openssl` and the Rust toolchain on macOS: - -1. Open the Terminal application. - -2. Ensure you have an updated version of Homebrew by running the following command: - - ```bash - brew update - ``` - -3. Install the `openssl` package by running the following command: - - ```bash - brew install openssl - ``` - -4. Download the `rustup` installation program and use it to install Rust by running the following - command: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` - -5. Follow the prompts displayed to proceed with a default installation. - -6. Update your current shell to include Cargo by running the following command: - - ```bash - source ~/.cargo/env - ``` - -7. Verify your installation by running the following command: - - ```bash - rustc --version - ``` - -8. Configure the Rust toolchain to default to the latest stable version by running the following - commands: - - ```bash - rustup default stable - rustup update - rustup target add wasm32-unknown-unknown - ``` - -9. Add the `nightly` release and the `nightly` WebAssembly (wasm) targets to your development - environment by running the following commands: - - ```bash - rustup update nightly - rustup target add wasm32-unknown-unknown --toolchain nightly - ``` - -10. Verify the configuration of your development environment by running the following command: - -```bash -rustup show -rustup +nightly show -``` - -The command displays output similar to the following: - -```bash -# rustup show - -active toolchain ----------------- - -stable-x86_64-apple-darwin (default) -rustc 1.61.0 (fe5b13d68 2022-05-18) - -# rustup +nightly show - -active toolchain ----------------- - -nightly-x86_64-apple-darwin (overridden by +toolchain on the command line) -rustc 1.63.0-nightly (e71440575 2022-06-02) -``` - -11. Install `cmake` using the following command: - -``` -brew install cmake -``` diff --git a/docs/build/build-guides-install-windows.md b/docs/build/build-guides-install-windows.md deleted file mode 100644 index e1ca48783fbf..000000000000 --- a/docs/build/build-guides-install-windows.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -id: build-guides-install-windows -title: Windows -sidebar_label: Windows -description: Install dependencies for Windows -keywords: [coretime, blockspace, parathread, parachain, cores] -slug: ../build-guides-install-windows ---- - -In general, UNIX-based operating systems—like macOS or Linux—provide a better development -environment for building Substrate-based blockchains. - -However, if your local computer uses Microsoft Windows instead of a UNIX-based operating system, you -can configure it with additional software to make it a suitable development environment for building -Substrate-based blockchains. To prepare a development environment on a computer running Microsoft -Windows, you can use Windows Subsystem for Linux (WSL) to emulate a UNIX operating environment. - -## Before you begin - -Before installing on Microsoft Windows, verify the following basic requirements: - -- You have a computer running a supported version of the Microsoft Windows operating system. -- You must be running Microsoft Windows 10, version 2004 or later, or Microsoft Windows 11 to - install Windows Subsystem for Linux on a computer with the Windows desktop operating system. -- You must be running Microsoft Windows Server 2019, or later, to install Windows Subsystem for - Linux on a computer with the Windows server operating system. -- You have good internet connection and access to a shell terminal on your local computer. - -## Set up Windows Subsystem for Linux - -Windows Subsystem for Linux (WSL) enables you to emulate a Linux environment on a computer that uses -the Windows operating system. The primary advantage of this approach for Substrate development is -that you can use all of the code and command-line examples as described in the Substrate -documentation. For example, you can run common commands—such as `ls` and `ps`—unmodified. By using -Windows Subsystem for Linux, you can avoid configuring a virtual machine image or a dual-boot -operating system. - -To prepare a development environment using Windows Subsystem for Linux: - -1. Check your Windows version and build number to see if Windows Subsystem for Linux is enabled by - default. - - If you have Microsoft Windows 10, version 2004 (Build 19041 and higher), or Microsoft Windows 11, - Windows Subsystem for Linux is available by default and you can continue to the next step. - - If you have an older version of Microsoft Windows installed, see - [WSL manual installation steps for older versions](https://docs.microsoft.com/en-us/windows/wsl/install-manual). - If you are installing on an older version of Microsoft Windows, you can download and install WLS - 2 if your computer has Windows 10, version 1903 or higher. - -2. Select Windows PowerShell or Command Prompt from the Start menu, right-click, then **Run as - administrator**. - -3. In the PowerShell or Command Prompt terminal, run the following command: - - ```bash - wsl --install - ``` - - This command enables the required WSL 2 components that are part of the Windows operating system, - downloads the latest Linux kernel, and installs the Ubuntu Linux distribution by default. - - If you want to review the other Linux distributions available, run the following command: - - ```bash - wsl --list --online - ``` - -4. After the distribution is downloaded, close the terminal. - -5. Click the Start menu, select **Shut down or sign out**, then click **Restart** to restart the - computer. - - Restarting the computer is required to start the installation of the Linux distribution. It can - take a few minutes for the installation to complete after you restart. - - For more information about setting up WSL as a development environment, see - [Set up a WSL development environment](https://docs.microsoft.com/en-us/windows/wsl/setup/environment). - -## Install required packages and Rust - -To install the Rust toolchain on WSL: - -1. Click the Start menu, then select **Ubuntu**. - -2. Type a UNIX user name to create user account. - -3. Type a password for your UNIX user, then retype the password to confirm it. - -4. Download the latest updates for the Ubuntu distribution using the Ubuntu Advanced Packaging Tool - (`apt`) by running the following command: - - ```bash - sudo apt update - ``` - -5. Add the required packages for the Ubuntu distribution by running the following command: - - ```bash - sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler - ``` - -6. Download the `rustup` installation program and use it to install Rust for the Ubuntu distribution - by running the following command: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` - -7. Follow the prompts displayed to proceed with a default installation. - -8. Update your current shell to include Cargo by running the following command: - - ```bash - source ~/.cargo/env - ``` - -9. Verify your installation by running the following command: - - ```bash - rustc --version - ``` - -10. Configure the Rust toolchain to use the latest stable version as the default toolchain by - running the following commands: - -```bash -rustup default stable -rustup update -``` - -11. Add the `nightly` version of the toolchain and the `nightly` WebAssembly (`wasm`) target to your - development environment by running the following commands: - -```bash -rustup update nightly -rustup target add wasm32-unknown-unknown --toolchain nightly -``` - -12. Verify the configuration of your development environment by running the following command: - -```bash -rustup show -rustup +nightly show -``` - -The command displays output similar to the following: - -```bash -# rustup show - -active toolchain ----------------- - -stable-x86_64-unknown-linux-gnu (default) -rustc 1.61.0 (fe5b13d68 2022-05-18) - -# rustup +nightly show - -active toolchain ----------------- - -nightly-x86_64-unknown-linux-gnu (overridden by +toolchain on the command line) -rustc 1.63.0-nightly (e7144 -``` diff --git a/kusama-guide/sidebars.js b/kusama-guide/sidebars.js index e1ef660a1ad9..f2e60a03b6f4 100644 --- a/kusama-guide/sidebars.js +++ b/kusama-guide/sidebars.js @@ -729,21 +729,7 @@ module.exports = { slug: '/build-coretime-index', }, items: [ - { - type: "category", - label: "Installing Dependencies", - link: { - type: 'generated-index', - title: "Installing Dependencies", - description: "Install the necessary development dependencies needed to start with the Polkadot SDK", - slug: '/build-install-dependencies', - }, - items: [ - "build/build-guides-install-macos", - "build/build-guides-install-linux", - "build/build-guides-install-windows" - ] - }, + "build/build-guides-install-deps", "build/build-guides-coretime-start" ], }, From 3091e6291ee51d94ad880d6c866be54b7b95e517 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 May 2024 15:07:57 -0400 Subject: [PATCH 19/21] fix --- docs/build/build-guides-install-deps.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/build/build-guides-install-deps.md b/docs/build/build-guides-install-deps.md index 7ef835bb176b..a55a78a29b86 100644 --- a/docs/build/build-guides-install-deps.md +++ b/docs/build/build-guides-install-deps.md @@ -254,7 +254,7 @@ Mint, MX Linux, and Elementary OS. rustup target add wasm32-unknown-unknown --toolchain nightly ``` -7. Verify your installation here. +7. [Verify your installation here.](#verifying-installation) ## Windows (WSL) @@ -375,10 +375,10 @@ To install the Rust toolchain on WSL: 10. Configure the Rust toolchain to use the latest stable version as the default toolchain by running the following commands: -```bash -rustup default stable -rustup update -``` + ```bash + rustup default stable + rustup update + ``` 11. Add the `nightly` version of the toolchain and the `nightly` WebAssembly (`wasm`) target to your development environment by running the following commands: @@ -390,11 +390,6 @@ rustup update 12. [Verify your installation here.](#verifying-installation) -```bash -rustup update nightly -rustup target add wasm32-unknown-unknown --toolchain nightly -``` - ## Verifying Installation Verify the configuration of your development environment by running the following command: From 100fb6d9022f4f5e5c7bb48d5752a31fd46e43ba Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 May 2024 15:12:15 -0400 Subject: [PATCH 20/21] fix mermaid for kusama --- kusama-guide/docusaurus.config.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/kusama-guide/docusaurus.config.js b/kusama-guide/docusaurus.config.js index 63138abb1899..029a6de79c57 100644 --- a/kusama-guide/docusaurus.config.js +++ b/kusama-guide/docusaurus.config.js @@ -1,3 +1,4 @@ +const { markdown } = require("../polkadot-wiki/docusaurus.config"); const { injectPlugin } = require("../scripts/injectPlugin"); const i18n = require("./i18n"); const isPub = process.env.PUBLISHING === "true"; @@ -10,6 +11,10 @@ module.exports = { baseUrl: "/", projectName: isPub ? "kusama-guide-hosting" : "", organizationName: "w3f", + markdown: { + mermaid: true + }, + themes: ['@docusaurus/theme-mermaid'], i18n, scripts: [ "https://buttons.github.io/buttons.js", From 5411e8b8d5f92950ae00b54504f6542daacd2fe6 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 May 2024 15:15:22 -0400 Subject: [PATCH 21/21] add links --- docs/build/build-guides-coretime-start.md | 29 +++++++++++++---------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/build/build-guides-coretime-start.md b/docs/build/build-guides-coretime-start.md index e68cb908b48e..3bbe089b547a 100644 --- a/docs/build/build-guides-coretime-start.md +++ b/docs/build/build-guides-coretime-start.md @@ -7,7 +7,7 @@ keywords: [coretime, blockspace, parathread, parachain, cores] slug: ../build-guides-coretime-start --- -:::warning This section is under construction! +:::warning This section is under construction and moving! (Expect Chaos) ::: @@ -23,12 +23,15 @@ Polkadot. At first glance, the Polkadot SDK can be rather overwhelming, and in a way it is - it packs a lot of tech into one place. The Polkadot SDK used to be overarching **three** repositories: -- **Polkadot** - Which for a time, included both the client implementation and runtime, until the - runtime was moved to the Polkadot Fellows organization. -- **Substrate** - The underlying, core primitives and libraries for building blockchains (any - blockchain, not just one for Polkadot). Much of Polkadot is built with Substrate! -- **Cumulus** - A set of libraries and tools which pertain specifically with connecting blockchains - to Polkadot, known as parachains. +- [**Polkadot**](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html#polkadot) - + Which for a time, included both the client implementation and runtime, until the runtime was moved + to the Polkadot Fellows organization. +- [**Substrate**](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html#substrate) - + The underlying, core primitives and libraries for building blockchains (any blockchain, not just + one for Polkadot). Much of Polkadot is built with Substrate! +- [**Cumulus**](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html#cumulus) - + A set of libraries and tools which pertain specifically with connecting blockchains to Polkadot, + known as parachains. > For an in-depth dive into the monorepo, it is highly recommended that you look into the > [Polkadot SDK Docs, which explains everything.](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html) @@ -53,13 +56,13 @@ Once you have your runtime and pallets developed, you will be able to deploy it genesis state. 2. **Compiling** the runtime (written in Rust) to a [WebAssembly](../learn/learn-wasm.md) blob, thereby defining how your state transitions from one state to the next. This runtime is created - using the Polkadot SDK. 2a. **Ensure** your chain spec is viable and ready to be deployed as a - live, working parachain. -3. **Generating** your genesis state and wasm. -4. **Obtaining** a core, most likely through a + using the Polkadot SDK. +3. **Ensure** your chain spec is viable and ready to be deployed as a live, working parachain. +4. **Generating** your genesis state and wasm. +5. **Obtaining** a core, most likely through a [Coretime marketplace](../learn/learn-guides-coretime-marketplaces.md). -5. **Assigning** that core to your[ `ParaId`](../general/glossary.md#paraid). -6. **Ensuring** you have at least one honest, synced collator for your task +6. **Assigning** that core to your[ `ParaId`](../general/glossary.md#paraid). +7. **Ensuring** you have at least one honest, synced collator for your task ### Deploy adder collator