From dfb01aaa046ddfb4d7606c8e0b7112c9f719288a Mon Sep 17 00:00:00 2001 From: Przemek Rzad <przemek@parity.io> Date: Mon, 3 Jun 2024 11:51:51 +0200 Subject: [PATCH] Revamp the Readme of the minimal template (#4649) - Addresses [this](https://github.com/paritytech/polkadot-sdk/issues/3155#issuecomment-2126934939). - Technical content got adopted from the existing [solochain readme](https://github.com/paritytech/polkadot-sdk/tree/master/templates/solochain). - Updated some broken links there. - The docker instructions will work after https://github.com/paritytech/polkadot-sdk/pull/4637. - See the [rendered version](https://github.com/paritytech/polkadot-sdk/blob/rzadp/minimal-template-readme/templates/minimal/README.md). --------- Co-authored-by: gupnik <nikhilgupta.iitk@gmail.com> --- templates/minimal/README.md | 96 ++++++++++++++++++++++++++--- templates/minimal/node/README.md | 14 +++++ templates/minimal/pallets/README.md | 9 +++ templates/minimal/runtime/README.md | 8 +++ templates/solochain/README.md | 7 +-- 5 files changed, 123 insertions(+), 11 deletions(-) create mode 100644 templates/minimal/node/README.md create mode 100644 templates/minimal/pallets/README.md create mode 100644 templates/minimal/runtime/README.md diff --git a/templates/minimal/README.md b/templates/minimal/README.md index 0541e393db9..3488bc43cc9 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -1,13 +1,95 @@ -# Minimal Template +<div align="center"> -This is a minimal template for creating a blockchain using the Polkadot SDK. +# Polkadot SDK's Minimal Template -# Docs +<img height="70px" alt="Polkadot SDK Logo" src="https://github.com/paritytech/polkadot-sdk/raw/master/docs/images/Polkadot_Logo_Horizontal_Pink_White.png#gh-dark-mode-only"/> +<img height="70px" alt="Polkadot SDK Logo" src="https://github.com/paritytech/polkadot-sdk/raw/master/docs/images/Polkadot_Logo_Horizontal_Pink_Black.png#gh-light-mode-only"/> -You can generate and view the [Rust -Docs](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for this template -with this command: +> 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). + +</div> + +🤠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 + +🦀 The template is using the Rust language. + +👉 Check the +[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 + +🔨 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: + +```sh +./target/release/minimal-template-node --dev + +# docker version: +docker run --rm polkadot-sdk-minimal-template --dev +``` + +Development chains: + +- 🧹 Do not persist the state. +- 💰 Are preconfigured with a genesis state that includes several prefunded development accounts. +- 🧑â€âš–ï¸ Development accounts are used as `sudo` accounts. + +### Connect with the Polkadot-JS Apps Front-End + +🌠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). + +🪠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. + +## 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 00000000000..04a916f5053 --- /dev/null +++ b/templates/minimal/node/README.md @@ -0,0 +1,14 @@ +# Node + +â„¹ï¸ A node - in Polkadot - is a binary executable, whose primary purpose is to execute the [runtime](../runtime/README.md). + +🔗 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. + +👉 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. +- [`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. diff --git a/templates/minimal/pallets/README.md b/templates/minimal/pallets/README.md new file mode 100644 index 00000000000..26003638e9a --- /dev/null +++ b/templates/minimal/pallets/README.md @@ -0,0 +1,9 @@ +# Pallets + +â„¹ï¸ A pallet is a unit of encapsulated logic, with a clearly defined responsibility. A pallet is analogous to a module in the runtime. + +💠In this template, there is a simple custom pallet based on the FRAME framework. + +👉 Learn more about FRAME [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html). + +🧑â€ðŸ« 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. diff --git a/templates/minimal/runtime/README.md b/templates/minimal/runtime/README.md new file mode 100644 index 00000000000..2fdfef8bc35 --- /dev/null +++ b/templates/minimal/runtime/README.md @@ -0,0 +1,8 @@ +# Runtime + +â„¹ï¸ 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](../pallets/README.md). + +👉 Learn more about FRAME [here](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html). diff --git a/templates/solochain/README.md b/templates/solochain/README.md index 37c65797dcb..2e3b1146a8f 100644 --- a/templates/solochain/README.md +++ b/templates/solochain/README.md @@ -103,9 +103,8 @@ 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 +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. ### Multi-Node Local Testnet @@ -131,7 +130,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. -- GitLab