From d592a021b38188fc0bf3c077edcd6d052f29bf16 Mon Sep 17 00:00:00 2001 From: bader y Date: Tue, 7 May 2024 03:06:24 -0400 Subject: [PATCH] Improve Build Docs and Agile Coretime - Coreify The Build Section (#5811) * start the grand refactor (bye substrate.io) * working draft * parachain -> task * fmt * create place for coretime guides * grammar * address most feedback, start towards kusama * kusamafy * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Update docs/build/build-guide.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> * Address feedback * Add link * condense installation guides * fix * fix mermaid for kusama * add links --------- Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/build/build-guide.md | 287 +++++++-------- docs/build/build-guides-coretime-start.md | 70 ++++ docs/build/build-guides-install-deps.md | 420 ++++++++++++++++++++++ docs/build/build-network-overview.md | 8 + docs/general/start-building.md | 2 +- docs/learn/learn-parachains.md | 23 ++ kusama-guide/docusaurus.config.js | 5 + kusama-guide/sidebars.js | 65 +++- polkadot-wiki/sidebars.js | 8 +- 9 files changed, 714 insertions(+), 174 deletions(-) create mode 100644 docs/build/build-guides-coretime-start.md create mode 100644 docs/build/build-guides-install-deps.md diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md index 520c1654cbdc..5c6c38c14e43 100644 --- a/docs/build/build-guide.md +++ b/docs/build/build-guide.md @@ -7,34 +7,41 @@ 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 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 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. +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 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 you can use to start building immediately. -This build guide provides three different tracks: +:::note For Developers! -1. [Protocol Development - Blockchain & Parachain Development](#building-parachains) -2. [Developing Smart Contracts](#developing-smart-contracts) -3. [Developing a dApp](#developing-a-dappuapp) +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 out the +[Learn](../learn/learn-index) section. -:::tip Keep reading to find out more, or visit each respective track +::: + +This build guide covers three different areas, taking a **top-down** approach from protocol +development to user-facing applications: + + + + +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) + +:::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! @@ -45,54 +52,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"]-->SSC["Shared Security - Cumulus"] - 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"] + 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. @@ -101,54 +108,53 @@ 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. +[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. Parachains connect to a relay chain using the -[Parachains Protocol](../learn/learn-parachains-protocol.md). +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. ![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, -Substrate contexts. +extensively in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and Substrate. ::: -Parachains 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. -:::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. +### Polkadot SDK Overview -::: +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: -### Constructing FRAME Runtimes with Substrate +- **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 -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 @@ -157,28 +163,28 @@ 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 -[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 +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)). +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. 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 of 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. @@ -187,50 +193,20 @@ 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._ +[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 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. - ### Building a Pallet While parachains are highly customizable, they are often complex to develop. If you wish to get @@ -239,9 +215,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. -To learn how to build a pallet, follow the -[Substrate documentation](https://docs.substrate.io/tutorials/build-application-logic/). - ## Developing Smart Contracts Smart contracts are another option that enables an often simpler developer experience. Below is a @@ -266,25 +239,28 @@ 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 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 are sandboxed, executable programs that live +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 @@ -303,7 +279,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. @@ -312,7 +288,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) @@ -320,11 +296,10 @@ 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) -- [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/build/build-guides-coretime-start.md b/docs/build/build-guides-coretime-start.md new file mode 100644 index 000000000000..3bbe089b547a --- /dev/null +++ b/docs/build/build-guides-coretime-start.md @@ -0,0 +1,70 @@ +--- +id: build-guides-coretime-start +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 and moving! (Expect Chaos) + +::: + +:::warning Only for Kusama and testnets! + +Agile coretime is only for the Kusama and testnet networks at the moment, and is not yet deployed on +Polkadot. + +::: + +## 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** repositories: + +- [**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) + +:::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 +[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. **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](../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. +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). +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 + +Try out the above by deploying the +[adder collator, a very simple "counter" parachain implementation.](../learn/learn-guides-coretime-parachains.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..a55a78a29b86 --- /dev/null +++ b/docs/build/build-guides-install-deps.md @@ -0,0 +1,420 @@ +--- +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.](#verifying-installation) + +## 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) + +## 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-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 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). ::: diff --git a/docs/learn/learn-parachains.md b/docs/learn/learn-parachains.md index a8dc04dc9147..31f17eb2e92d 100644 --- a/docs/learn/learn-parachains.md +++ b/docs/learn/learn-parachains.md @@ -84,6 +84,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 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", diff --git a/kusama-guide/sidebars.js b/kusama-guide/sidebars.js index 9fb801aa7a2f..32983dcd0763 100644 --- a/kusama-guide/sidebars.js +++ b/kusama-guide/sidebars.js @@ -696,28 +696,67 @@ 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: "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-install-deps", + "build/build-guides-coretime-start" + ], + }, + "build/build-smart-contracts", + { + 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" ], }, { type: "category", - label: "Tools", + label: "Tooling", + link: { + type: 'doc', + id: "build/build-tools-index" + }, items: [ - "build/build-tools-index", - 'build/build-open-source' + "build/build-data", + "build/build-open-source", ], }, { @@ -726,7 +765,7 @@ module.exports = { items: ["build/build-hackathon"], }, ], - }, + }, { type: "category", label: "What to Break", diff --git a/polkadot-wiki/sidebars.js b/polkadot-wiki/sidebars.js index 58fef8a6a773..35b9bb964e54 100644 --- a/polkadot-wiki/sidebars.js +++ b/polkadot-wiki/sidebars.js @@ -718,6 +718,7 @@ module.exports = { id: "build/build-guide" }, items: [ + "build/build-network-overview", { type: "category", label: "Client-side Development", @@ -736,11 +737,11 @@ module.exports = { "build/build-smart-contracts", { type: "category", - label: "Protocol Development", + label: "Protocol Development Resources", link: { type: 'generated-index', - title: "Protocol & Parachain Development", - description: "Learn how to get started with building parachains, solo-chains, and other aspects of protocol development.", + title: "Protocol Development Resources", + description: "Miscellaneous aspects concerning protocol and parachain development", slug: '/build-protocol-index', }, items: [ @@ -749,7 +750,6 @@ module.exports = { "build/build-hrmp-channels" ], }, - "build/build-network-overview", { type: "category", label: "Tooling",