From 5ed867080298495ffa8b541bf0119df41e7c6650 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:18:54 +0200 Subject: [PATCH 01/23] Update minimal template readme --- templates/minimal/README.md | 81 ++++++++++++++++++-- templates/minimal/node/README.md | 38 +++++++++ templates/minimal/pallets/template/README.md | 23 ++++++ templates/minimal/runtime/README.md | 23 ++++++ 4 files changed, 158 insertions(+), 7 deletions(-) create mode 100644 templates/minimal/node/README.md create mode 100644 templates/minimal/pallets/template/README.md create mode 100644 templates/minimal/runtime/README.md diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 0541e393db93b..93b1ca9b88730 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -1,13 +1,80 @@ -# Minimal Template +
-This is a minimal template for creating a blockchain using the Polkadot SDK. +# Polkadot SDK's Minimal Template -# Docs +> This is a minimal template for creating a [Substrate](https://substrate.io/) blockchain. +> +> This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). -You can generate and view the [Rust -Docs](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for this template -with this command: +
+ +## Getting Started + +Depending on your operating system and Rust version, there might be additional +packages required to compile this template. + +Check the +[Substrate Install](https://docs.substrate.io/install/) instructions for your platform for +the most common dependencies. + +### Build + +Use the following command to build the node without launching it: ```sh -cargo doc -p minimal-template --open +cargo build --release +``` + +Alternatively, build the docker image: + +```sh +docker build . -t polkadot-sdk-minimal-template +``` + +### Single-Node Development Chain + +The following command starts a single-node development chain that doesn't +persist state: + +```sh +./target/release/minimal-template-node --dev + +# docker version: +docker run --rm polkadot-sdk-minimal-template --dev ``` + +Development chains: + +- Maintain state in a `tmp` folder while the node is running. +- Are preconfigured with a genesis state (see [`chain_spec.rs`](./node/src/chain_spec.rs)) that + includes several prefunded development accounts. +- Development accounts are used as default validator authorities and a `sudo` account. + +### Multi-Node Local Testnet + +If you want to see the multi-node consensus algorithm in action, see [Simulate a +network](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/). + +## Template Structure + +A Polkadot SDK based project such as this one consists of: + +- a [Node](./node/README.md) - the binary application. +- the [Runtime](./runtime/README.md) - the core logic of the blockchain. +- the [Pallets](./pallets/README.md) - from which the runtime is constructed. + +## Contributing + +๐Ÿ”„ This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). + +โžก๏ธ Any pull requests should be directed to this [source](https://github.com/paritytech/polkadot-sdk/tree/master/templates/minimal). + +๐Ÿ˜‡ Please refer to the monorepo's [contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and [Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CODE_OF_CONDUCT.md). + +## Getting Help + +๐Ÿง‘โ€๐Ÿซ To learn about Polkadot in general, [Polkadot.network](https://polkadot.network/) website is a good starting point. + +๐Ÿง‘โ€๐Ÿ”ง For technical introduction, [here](https://github.com/paritytech/polkadot-sdk#-documentation) are the Polkadot SDK documentation resources. + +๐Ÿ‘ฅ Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and [Substrate StackExchange](https://substrate.stackexchange.com/). diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md new file mode 100644 index 0000000000000..9e2ea1e1f048c --- /dev/null +++ b/templates/minimal/node/README.md @@ -0,0 +1,38 @@ +# Node + +A blockchain node is an application that allows users to participate in a +blockchain network. Substrate-based blockchain nodes expose a number of +capabilities: + +- Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking + stack to allow the nodes in the network to communicate with one another. +- Consensus: Blockchains must have a way to come to + [consensus](https://docs.substrate.io/fundamentals/consensus/) on the state of + the network. Substrate makes it possible to supply custom consensus engines + and also ships with several consensus mechanisms that have been built on top + of [Web3 Foundation + research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html). +- RPC Server: A remote procedure call (RPC) server is used to interact with + Substrate nodes. + +There are several files in the `node` directory. Take special note of the +following: + +- [`chain_spec.rs`](./src/chain_spec.rs): A [chain + specification](https://docs.substrate.io/build/chain-spec/) is a source code + file that defines a Substrate chain's initial (genesis) state. Chain + specifications are useful for development and testing, and critical when + architecting the launch of a production chain. Take note of the + `development_config` and `testnet_genesis` functions. These functions are + used to define the genesis state for the local development chain + configuration. These functions identify some [well-known + accounts](https://docs.substrate.io/reference/command-line-tools/subkey/) and + use them to configure the blockchain's initial state. +- [`service.rs`](./src/service.rs): This file defines the node + implementation. Take note of the libraries that this file imports and the + names of the functions it invokes. In particular, there are references to + consensus-related topics, such as the [block finalization and + forks](https://docs.substrate.io/fundamentals/consensus/#finalization-and-forks) + and other [consensus + mechanisms](https://docs.substrate.io/fundamentals/consensus/#default-consensus-models) + such as Aura for block authoring and GRANDPA for finality. diff --git a/templates/minimal/pallets/template/README.md b/templates/minimal/pallets/template/README.md new file mode 100644 index 0000000000000..c79cdf51c6a4b --- /dev/null +++ b/templates/minimal/pallets/template/README.md @@ -0,0 +1,23 @@ +# Pallets + +The runtime in this project is constructed using many FRAME pallets that ship +with [the Substrate +repository](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) and a +template pallet that is [defined in the +`pallets`](./template/src/lib.rs) directory. + +A FRAME pallet is comprised of a number of blockchain primitives, including: + +- Storage: FRAME defines a rich set of powerful [storage + abstractions](https://docs.substrate.io/build/runtime-storage/) that makes it + easy to use Substrate's efficient key-value database to manage the evolving + state of a blockchain. +- Dispatchables: FRAME pallets define special types of functions that can be + invoked (dispatched) from outside of the runtime in order to update its state. +- Events: Substrate uses + [events](https://docs.substrate.io/build/events-and-errors/) to notify users + of significant state changes. +- Errors: When a dispatchable fails, it returns an error. + +Each pallet has its own `Config` trait which serves as a configuration interface +to generically define the types and parameters it depends on. diff --git a/templates/minimal/runtime/README.md b/templates/minimal/runtime/README.md new file mode 100644 index 0000000000000..dae6f0788bfd4 --- /dev/null +++ b/templates/minimal/runtime/README.md @@ -0,0 +1,23 @@ +# Runtime + +In Substrate, the terms "runtime" and "state transition function" are analogous. +Both terms refer to the core logic of the blockchain that is responsible for +validating blocks and executing the state changes they define. The Substrate +project in this repository uses +[FRAME](https://docs.substrate.io/learn/runtime-development/#frame) to construct +a blockchain runtime. FRAME allows runtime developers to declare domain-specific +logic in modules called "pallets". At the heart of FRAME is a helpful [macro +language](https://docs.substrate.io/reference/frame-macros/) that makes it easy +to create pallets and flexibly compose them to create blockchains that can +address [a variety of needs](https://substrate.io/ecosystem/projects/). + +Review the [FRAME runtime implementation](./src/lib.rs) included in this +template and note the following: + +- This file configures several pallets to include in the runtime. Each pallet + configuration is defined by a code block that begins with `impl + $PALLET_NAME::Config for Runtime`. +- The pallets are composed into a single runtime by way of the + [`construct_runtime!`](https://paritytech.github.io/substrate/master/frame_support/macro.construct_runtime.html) + macro, which is part of the [core FRAME pallet + library](https://docs.substrate.io/reference/frame-pallets/#system-pallets). From 099d5ac40d405491f8f20395e926f24e654f9f6c Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:29:09 +0200 Subject: [PATCH 02/23] img --- templates/minimal/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 93b1ca9b88730..4d3eef3e4a932 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -2,6 +2,9 @@ # Polkadot SDK's Minimal Template +Polkadot SDK Logo +Polkadot SDK Logo + > This is a minimal template for creating a [Substrate](https://substrate.io/) blockchain. > > This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). From 5d3a023fc46b8ef54862470f4b70f17ea3bdb6b5 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:31:34 +0200 Subject: [PATCH 03/23] broken link --- templates/minimal/node/README.md | 2 +- templates/solochain/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index 9e2ea1e1f048c..0727955160b5f 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -11,7 +11,7 @@ capabilities: the network. Substrate makes it possible to supply custom consensus engines and also ships with several consensus mechanisms that have been built on top of [Web3 Foundation - research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html). + research](https://research.web3.foundation/Polkadot/protocols/NPoS). - RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes. diff --git a/templates/solochain/README.md b/templates/solochain/README.md index 37c65797dcb00..37f1e9d07cf0e 100644 --- a/templates/solochain/README.md +++ b/templates/solochain/README.md @@ -131,7 +131,7 @@ capabilities: the network. Substrate makes it possible to supply custom consensus engines and also ships with several consensus mechanisms that have been built on top of [Web3 Foundation - research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html). + research](https://research.web3.foundation/Polkadot/protocols/NPoS). - RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes. From 99344c33a60a43423cf96bfe63985b9604a11044 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:31:36 +0200 Subject: [PATCH 04/23] mv --- templates/minimal/pallets/{template => }/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename templates/minimal/pallets/{template => }/README.md (100%) diff --git a/templates/minimal/pallets/template/README.md b/templates/minimal/pallets/README.md similarity index 100% rename from templates/minimal/pallets/template/README.md rename to templates/minimal/pallets/README.md From f919b608397dc2daa06adae49d676e07365dd758 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:35:05 +0200 Subject: [PATCH 05/23] pjs --- templates/minimal/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 4d3eef3e4a932..f82de9313eb98 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -58,6 +58,17 @@ Development chains: If you want to see the multi-node consensus algorithm in action, see [Simulate a network](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/). +### Connect with the Polkadot-JS Apps Front-End + +After you start the node template locally, you can interact with it using the +hosted version of the [Polkadot/Substrate +Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) +front-end by connecting to the local node endpoint. A hosted version is also +available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) +here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can +also find the source code and instructions for hosting your own instance on the +[`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. + ## Template Structure A Polkadot SDK based project such as this one consists of: From 55bfc70166c2000dd2e849ff71e75abeb9153983 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:39:45 +0200 Subject: [PATCH 06/23] link fix --- templates/minimal/README.md | 3 +-- templates/solochain/README.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index f82de9313eb98..5d95c2c9bdd1d 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -64,8 +64,7 @@ After you start the node template locally, you can interact with it using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also -available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) -here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can +available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can also find the source code and instructions for hosting your own instance on the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. diff --git a/templates/solochain/README.md b/templates/solochain/README.md index 37f1e9d07cf0e..6a4e25b050950 100644 --- a/templates/solochain/README.md +++ b/templates/solochain/README.md @@ -103,8 +103,7 @@ After you start the node template locally, you can interact with it using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also -available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) -here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can +available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can also find the source code and instructions for hosting your own instance on the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. From c0a64c7a7095701433ceae781c1a6473ac9da958 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:42:09 +0200 Subject: [PATCH 07/23] links were not working on github render --- templates/minimal/README.md | 2 +- templates/solochain/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 5d95c2c9bdd1d..ea8c5f52a7385 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -64,7 +64,7 @@ After you start the node template locally, you can interact with it using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also -available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can +available on [IPFS](https://dotapps.io/). You can also find the source code and instructions for hosting your own instance on the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. diff --git a/templates/solochain/README.md b/templates/solochain/README.md index 6a4e25b050950..532fce3a211ed 100644 --- a/templates/solochain/README.md +++ b/templates/solochain/README.md @@ -103,7 +103,7 @@ After you start the node template locally, you can interact with it using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also -available on [IPFS (redirect) here](https://dotapps.io/) or [IPNS (direct) here](ipns://dotapps.io/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer). You can +available on [IPFS](https://dotapps.io/). You can also find the source code and instructions for hosting your own instance on the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. From 48cf53753fa0d5cf1b71fe589245180992e22f8e Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:42:49 +0200 Subject: [PATCH 08/23] typo? --- templates/minimal/README.md | 2 +- templates/solochain/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index ea8c5f52a7385..4f38690de69b0 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -65,7 +65,7 @@ hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also available on [IPFS](https://dotapps.io/). You can -also find the source code and instructions for hosting your own instance on the +also find the source code and instructions for hosting your own instance in the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. ## Template Structure diff --git a/templates/solochain/README.md b/templates/solochain/README.md index 532fce3a211ed..2e3b1146a8fde 100644 --- a/templates/solochain/README.md +++ b/templates/solochain/README.md @@ -104,7 +104,7 @@ hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) front-end by connecting to the local node endpoint. A hosted version is also available on [IPFS](https://dotapps.io/). You can -also find the source code and instructions for hosting your own instance on the +also find the source code and instructions for hosting your own instance in the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. ### Multi-Node Local Testnet From df1a1c2df8ee6d3a37d91948f55010762708cdda Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:56:39 +0200 Subject: [PATCH 09/23] zing and pep --- templates/minimal/README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 4f38690de69b0..d1014b73a4cea 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -13,22 +13,22 @@ ## Getting Started -Depending on your operating system and Rust version, there might be additional +๐Ÿ› ๏ธ Depending on your operating system and Rust version, there might be additional packages required to compile this template. -Check the +๐Ÿ‘‰ Check the [Substrate Install](https://docs.substrate.io/install/) instructions for your platform for the most common dependencies. ### Build -Use the following command to build the node without launching it: +๐Ÿ”จ Use the following command to build the node without launching it: ```sh cargo build --release ``` -Alternatively, build the docker image: +๐Ÿณ Alternatively, build the docker image: ```sh docker build . -t polkadot-sdk-minimal-template @@ -36,8 +36,7 @@ docker build . -t polkadot-sdk-minimal-template ### Single-Node Development Chain -The following command starts a single-node development chain that doesn't -persist state: +๐Ÿ‘ค The following command starts a single-node development chain: ```sh ./target/release/minimal-template-node --dev @@ -48,33 +47,36 @@ docker run --rm polkadot-sdk-minimal-template --dev Development chains: -- Maintain state in a `tmp` folder while the node is running. +- Maintain state in a `tmp` folder while the node is running - it is not persistent. - Are preconfigured with a genesis state (see [`chain_spec.rs`](./node/src/chain_spec.rs)) that includes several prefunded development accounts. - Development accounts are used as default validator authorities and a `sudo` account. ### Multi-Node Local Testnet -If you want to see the multi-node consensus algorithm in action, see [Simulate a +๐Ÿ‘ฅ If you want to see the multi-node consensus algorithm in action, see [Simulate a network](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/). ### Connect with the Polkadot-JS Apps Front-End -After you start the node template locally, you can interact with it using the +๐ŸŒ After you start the node template locally, you can interact with it using the hosted version of the [Polkadot/Substrate Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) -front-end by connecting to the local node endpoint. A hosted version is also -available on [IPFS](https://dotapps.io/). You can -also find the source code and instructions for hosting your own instance in the +front-end by connecting to the local node endpoint. + +๐Ÿช A hosted version is also +available on [IPFS](https://dotapps.io/). + +๐Ÿง‘โ€๐Ÿ”ง You can also find the source code and instructions for hosting your own instance in the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. ## Template Structure A Polkadot SDK based project such as this one consists of: -- a [Node](./node/README.md) - the binary application. -- the [Runtime](./runtime/README.md) - the core logic of the blockchain. -- the [Pallets](./pallets/README.md) - from which the runtime is constructed. +- ๐Ÿ’ฟ [Node](./node/README.md) - the binary application. +- ๐Ÿงฎ [Runtime](./runtime/README.md) - the core logic of the blockchain. +- ๐ŸŽจ [Pallets](./pallets/README.md) - from which the runtime is constructed. ## Contributing From 357de65658858f8710933408df2298cae40171ea Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 14:58:00 +0200 Subject: [PATCH 10/23] seems more natural --- templates/minimal/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index d1014b73a4cea..019336cfd98e2 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -74,9 +74,9 @@ available on [IPFS](https://dotapps.io/). A Polkadot SDK based project such as this one consists of: -- ๐Ÿ’ฟ [Node](./node/README.md) - the binary application. -- ๐Ÿงฎ [Runtime](./runtime/README.md) - the core logic of the blockchain. -- ๐ŸŽจ [Pallets](./pallets/README.md) - from which the runtime is constructed. +- ๐Ÿ’ฟ a [Node](./node/README.md) - the binary application. +- ๐Ÿงฎ the [Runtime](./runtime/README.md) - the core logic of the blockchain. +- ๐ŸŽจ the [Pallets](./pallets/README.md) - from which the runtime is constructed. ## Contributing From 0349e1e5b36b80e32a79f95bea9b6296c870b065 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 15:01:53 +0200 Subject: [PATCH 11/23] simplify --- templates/minimal/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 019336cfd98e2..457d5adaddcf2 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -47,10 +47,9 @@ docker run --rm polkadot-sdk-minimal-template --dev Development chains: -- Maintain state in a `tmp` folder while the node is running - it is not persistent. -- Are preconfigured with a genesis state (see [`chain_spec.rs`](./node/src/chain_spec.rs)) that - includes several prefunded development accounts. -- Development accounts are used as default validator authorities and a `sudo` account. +- ๐Ÿงน Do not persist the state. +- ๐Ÿ’ฐ Are preconfigured with a genesis state that includes several prefunded development accounts. +- ๐Ÿง‘โ€โš–๏ธ Development accounts are used as default validator authorities and a `sudo` account. ### Multi-Node Local Testnet From dd06a8a9e33f7927a1ec4cc61536340f6ffe396c Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 30 May 2024 15:03:06 +0200 Subject: [PATCH 12/23] simplify --- templates/minimal/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 457d5adaddcf2..282be421316e1 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -58,10 +58,9 @@ network](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network ### Connect with the Polkadot-JS Apps Front-End -๐ŸŒ After you start the node template locally, you can interact with it using the +๐ŸŒ You can interact with your local node using the hosted version of the [Polkadot/Substrate -Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) -front-end by connecting to the local node endpoint. +Portal](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944). ๐Ÿช A hosted version is also available on [IPFS](https://dotapps.io/). From 32d79b50ffd4f7eb2cf7c6aaff726c14a8c11174 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 12:48:47 +0200 Subject: [PATCH 13/23] Remove substrate.io links --- templates/minimal/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 282be421316e1..7e208c31413ef 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -5,7 +5,7 @@ Polkadot SDK Logo Polkadot SDK Logo -> This is a minimal template for creating a [Substrate](https://substrate.io/) blockchain. +> This is a minimal template for creating a blockchain based on Polkadot SDK. > > This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). From 94327e2b6dc0020cac243add259c1f5af7148f10 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:02:35 +0200 Subject: [PATCH 14/23] rewrite and shorten pallets readme --- templates/minimal/pallets/README.md | 22 ++++------------------ 1 file changed, 4 insertions(+), 18 deletions(-) diff --git a/templates/minimal/pallets/README.md b/templates/minimal/pallets/README.md index c79cdf51c6a4b..26003638e9acb 100644 --- a/templates/minimal/pallets/README.md +++ b/templates/minimal/pallets/README.md @@ -1,23 +1,9 @@ # Pallets -The runtime in this project is constructed using many FRAME pallets that ship -with [the Substrate -repository](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) and a -template pallet that is [defined in the -`pallets`](./template/src/lib.rs) directory. +โ„น๏ธ A pallet is a unit of encapsulated logic, with a clearly defined responsibility. A pallet is analogous to a module in the runtime. -A FRAME pallet is comprised of a number of blockchain primitives, including: +๐Ÿ’ In this template, there is a simple custom pallet based on the FRAME framework. -- Storage: FRAME defines a rich set of powerful [storage - abstractions](https://docs.substrate.io/build/runtime-storage/) that makes it - easy to use Substrate's efficient key-value database to manage the evolving - state of a blockchain. -- Dispatchables: FRAME pallets define special types of functions that can be - invoked (dispatched) from outside of the runtime in order to update its state. -- Events: Substrate uses - [events](https://docs.substrate.io/build/events-and-errors/) to notify users - of significant state changes. -- Errors: When a dispatchable fails, it returns an error. +๐Ÿ‘‰ Learn more about FRAME [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html). -Each pallet has its own `Config` trait which serves as a configuration interface -to generically define the types and parameters it depends on. +๐Ÿง‘โ€๐Ÿซ Please refer to [this guide](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/guides/your_first_pallet/index.html) to learn how to write a basic pallet. From 89e622e7689f009e52a15597df90f1ae3d7a54ee Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:23:38 +0200 Subject: [PATCH 15/23] rewrite / shorten runtime readme --- templates/minimal/runtime/README.md | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/templates/minimal/runtime/README.md b/templates/minimal/runtime/README.md index dae6f0788bfd4..a7e163f1046eb 100644 --- a/templates/minimal/runtime/README.md +++ b/templates/minimal/runtime/README.md @@ -1,23 +1,8 @@ # Runtime -In Substrate, the terms "runtime" and "state transition function" are analogous. -Both terms refer to the core logic of the blockchain that is responsible for -validating blocks and executing the state changes they define. The Substrate -project in this repository uses -[FRAME](https://docs.substrate.io/learn/runtime-development/#frame) to construct -a blockchain runtime. FRAME allows runtime developers to declare domain-specific -logic in modules called "pallets". At the heart of FRAME is a helpful [macro -language](https://docs.substrate.io/reference/frame-macros/) that makes it easy -to create pallets and flexibly compose them to create blockchains that can -address [a variety of needs](https://substrate.io/ecosystem/projects/). +โ„น๏ธ The runtime (in other words, a state transition function), refers to the core logic of the blockchain that is responsible for +validating blocks and executing the state changes they define. -Review the [FRAME runtime implementation](./src/lib.rs) included in this -template and note the following: +๐Ÿ’ The runtime in this template is constructed using ready-made FRAME pallets that ship with [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and a template for a custom pallet. -- This file configures several pallets to include in the runtime. Each pallet - configuration is defined by a code block that begins with `impl - $PALLET_NAME::Config for Runtime`. -- The pallets are composed into a single runtime by way of the - [`construct_runtime!`](https://paritytech.github.io/substrate/master/frame_support/macro.construct_runtime.html) - macro, which is part of the [core FRAME pallet - library](https://docs.substrate.io/reference/frame-pallets/#system-pallets). +๐Ÿ‘‰ Learn more about FRAME [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html). From 48bf863f514fb0ba6fad3d7537a6af532a8c7e88 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:55:17 +0200 Subject: [PATCH 16/23] revamp node readme --- templates/minimal/node/README.md | 40 ++++++-------------------------- 1 file changed, 7 insertions(+), 33 deletions(-) diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index 0727955160b5f..9e85cc51ad2db 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -1,38 +1,12 @@ # Node -A blockchain node is an application that allows users to participate in a -blockchain network. Substrate-based blockchain nodes expose a number of -capabilities: +โ„น๏ธ A node - in the Polkadot SDK nomenclature - is a normal binary executable, whose primary purpose is to execute the given [runtime](../runtime/README.md). -- Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking - stack to allow the nodes in the network to communicate with one another. -- Consensus: Blockchains must have a way to come to - [consensus](https://docs.substrate.io/fundamentals/consensus/) on the state of - the network. Substrate makes it possible to supply custom consensus engines - and also ships with several consensus mechanisms that have been built on top - of [Web3 Foundation - research](https://research.web3.foundation/Polkadot/protocols/NPoS). -- RPC Server: A remote procedure call (RPC) server is used to interact with - Substrate nodes. +๐Ÿ”— It communicated with other nodes in the network, and aims for [consensus](https://wiki.polkadot.network/docs/learn-consensus) among them. -There are several files in the `node` directory. Take special note of the -following: +โš™๏ธ It acts as a remote procedure call (RPC) server, allowing interaction with the blockchain. -- [`chain_spec.rs`](./src/chain_spec.rs): A [chain - specification](https://docs.substrate.io/build/chain-spec/) is a source code - file that defines a Substrate chain's initial (genesis) state. Chain - specifications are useful for development and testing, and critical when - architecting the launch of a production chain. Take note of the - `development_config` and `testnet_genesis` functions. These functions are - used to define the genesis state for the local development chain - configuration. These functions identify some [well-known - accounts](https://docs.substrate.io/reference/command-line-tools/subkey/) and - use them to configure the blockchain's initial state. -- [`service.rs`](./src/service.rs): This file defines the node - implementation. Take note of the libraries that this file imports and the - names of the functions it invokes. In particular, there are references to - consensus-related topics, such as the [block finalization and - forks](https://docs.substrate.io/fundamentals/consensus/#finalization-and-forks) - and other [consensus - mechanisms](https://docs.substrate.io/fundamentals/consensus/#default-consensus-models) - such as Aura for block authoring and GRANDPA for finality. +๐Ÿ‘‡ Here are the most important files in this node template: + +- [`chain_spec.rs`](./src/chain_spec.rs): A chain specification is a source code file that defines the chain's initial (genesis) state. +- [`service.rs`](./src/service.rs): This file defines the node implementation. It's a place to configure consensus-related topics. From c45f7d79354b5215a1d95d7f9fe1321ba727bf05 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:55:26 +0200 Subject: [PATCH 17/23] link --- templates/minimal/runtime/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/minimal/runtime/README.md b/templates/minimal/runtime/README.md index a7e163f1046eb..2fdfef8bc35b1 100644 --- a/templates/minimal/runtime/README.md +++ b/templates/minimal/runtime/README.md @@ -3,6 +3,6 @@ โ„น๏ธ The runtime (in other words, a state transition function), refers to the core logic of the blockchain that is responsible for validating blocks and executing the state changes they define. -๐Ÿ’ The runtime in this template is constructed using ready-made FRAME pallets that ship with [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and a template for a custom pallet. +๐Ÿ’ The runtime in this template is constructed using ready-made FRAME pallets that ship with [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and a [template for a custom pallet](../pallets/README.md). ๐Ÿ‘‰ Learn more about FRAME [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html). From 5e57bb39f0ce93f523a51f41d815bec1caffe40c Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:55:38 +0200 Subject: [PATCH 18/23] main readme, and last substrate.io link --- templates/minimal/README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 7e208c31413ef..059a25bc89712 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -11,14 +11,17 @@ +โ„น๏ธ This template is a minimal (in terms of complexity and the number of components) template for building a blockchain node. + ## Getting Started -๐Ÿ› ๏ธ Depending on your operating system and Rust version, there might be additional -packages required to compile this template. +๐Ÿฆ€ The template is using the Rust language. ๐Ÿ‘‰ Check the -[Substrate Install](https://docs.substrate.io/install/) instructions for your platform for -the most common dependencies. +[Rust installation instructions](https://www.rust-lang.org/tools/install) for your system. + +๐Ÿ› ๏ธ Depending on your operating system and Rust version, there might be additional +packages required to compile this template - please take note of the Rust compiler output. ### Build @@ -51,11 +54,6 @@ Development chains: - ๐Ÿ’ฐ Are preconfigured with a genesis state that includes several prefunded development accounts. - ๐Ÿง‘โ€โš–๏ธ Development accounts are used as default validator authorities and a `sudo` account. -### Multi-Node Local Testnet - -๐Ÿ‘ฅ If you want to see the multi-node consensus algorithm in action, see [Simulate a -network](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/). - ### Connect with the Polkadot-JS Apps Front-End ๐ŸŒ You can interact with your local node using the From 02d0879491a99a71b5a52ffd7dbc3bfe46f2014e Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 13:59:03 +0200 Subject: [PATCH 19/23] link --- templates/minimal/node/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index 9e85cc51ad2db..10fc12f1e20da 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -6,6 +6,8 @@ โš™๏ธ It acts as a remote procedure call (RPC) server, allowing interaction with the blockchain. +๐Ÿ‘‰ Learn more about the architecture, and a difference between a node and a runtime [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/wasm_meta_protocol/index.html). + ๐Ÿ‘‡ Here are the most important files in this node template: - [`chain_spec.rs`](./src/chain_spec.rs): A chain specification is a source code file that defines the chain's initial (genesis) state. From d99f819b21cbd3818b22a57aaab6d8a09daac9da Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 15:03:58 +0200 Subject: [PATCH 20/23] restructure and info --- templates/minimal/README.md | 22 +++++++++++++--------- templates/minimal/node/README.md | 2 +- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 059a25bc89712..285f27f0b67c2 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -11,7 +11,19 @@ -โ„น๏ธ This template is a minimal (in terms of complexity and the number of components) template for building a blockchain node. +๐Ÿค This template is a minimal (in terms of complexity and the number of components) template for building a blockchain node. + +๐Ÿ”ง It's runtime is configured of a single custom pallet as a staring point, and a handful of ready-made pallets such as a [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html). + +๐Ÿ‘ค The template has no consensus configured - it is best for experimenting with a single node network. + +## Template Structure + +A Polkadot SDK based project such as this one consists of: + +- ๐Ÿ’ฟ a [Node](./node/README.md) - the binary application. +- ๐Ÿงฎ the [Runtime](./runtime/README.md) - the core logic of the blockchain. +- ๐ŸŽจ the [Pallets](./pallets/README.md) - from which the runtime is constructed. ## Getting Started @@ -66,14 +78,6 @@ available on [IPFS](https://dotapps.io/). ๐Ÿง‘โ€๐Ÿ”ง You can also find the source code and instructions for hosting your own instance in the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. -## Template Structure - -A Polkadot SDK based project such as this one consists of: - -- ๐Ÿ’ฟ a [Node](./node/README.md) - the binary application. -- ๐Ÿงฎ the [Runtime](./runtime/README.md) - the core logic of the blockchain. -- ๐ŸŽจ the [Pallets](./pallets/README.md) - from which the runtime is constructed. - ## Contributing ๐Ÿ”„ This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index 10fc12f1e20da..b24d6733d616b 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -11,4 +11,4 @@ ๐Ÿ‘‡ Here are the most important files in this node template: - [`chain_spec.rs`](./src/chain_spec.rs): A chain specification is a source code file that defines the chain's initial (genesis) state. -- [`service.rs`](./src/service.rs): This file defines the node implementation. It's a place to configure consensus-related topics. +- [`service.rs`](./src/service.rs): This file defines the node implementation. It's a place to configure consensus-related topics. In favor of minimalism, this template has no consensus configured. From 89f00b0864edfec409df479d53584d2038549d65 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 31 May 2024 15:13:27 +0200 Subject: [PATCH 21/23] shorten sentence --- templates/minimal/node/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index b24d6733d616b..ae0d1572bdf03 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -1,6 +1,6 @@ # Node -โ„น๏ธ A node - in the Polkadot SDK nomenclature - is a normal binary executable, whose primary purpose is to execute the given [runtime](../runtime/README.md). +โ„น๏ธ A node - in Polkadot - is a binary executable, whose primary purpose is to execute the [runtime](../runtime/README.md). ๐Ÿ”— It communicated with other nodes in the network, and aims for [consensus](https://wiki.polkadot.network/docs/learn-consensus) among them. From bc2cbacbc3fa54375d61c3d4a5783323febd0cef Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 3 Jun 2024 09:42:50 +0200 Subject: [PATCH 22/23] no validators in this template --- templates/minimal/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 285f27f0b67c2..3488bc43cc902 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -64,7 +64,7 @@ Development chains: - ๐Ÿงน Do not persist the state. - ๐Ÿ’ฐ Are preconfigured with a genesis state that includes several prefunded development accounts. -- ๐Ÿง‘โ€โš–๏ธ Development accounts are used as default validator authorities and a `sudo` account. +- ๐Ÿง‘โ€โš–๏ธ Development accounts are used as `sudo` accounts. ### Connect with the Polkadot-JS Apps Front-End From bb98cff008bde4fb3622486e5df8596cc82af144 Mon Sep 17 00:00:00 2001 From: Przemek Rzad Date: Mon, 3 Jun 2024 11:28:00 +0200 Subject: [PATCH 23/23] Update templates/minimal/node/README.md Co-authored-by: gupnik --- templates/minimal/node/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/minimal/node/README.md b/templates/minimal/node/README.md index ae0d1572bdf03..04a916f5053b4 100644 --- a/templates/minimal/node/README.md +++ b/templates/minimal/node/README.md @@ -2,7 +2,7 @@ โ„น๏ธ A node - in Polkadot - is a binary executable, whose primary purpose is to execute the [runtime](../runtime/README.md). -๐Ÿ”— It communicated with other nodes in the network, and aims for [consensus](https://wiki.polkadot.network/docs/learn-consensus) among them. +๐Ÿ”— It communicates with other nodes in the network, and aims for [consensus](https://wiki.polkadot.network/docs/learn-consensus) among them. โš™๏ธ It acts as a remote procedure call (RPC) server, allowing interaction with the blockchain.