Revamp the Readme of the minimal template #4649
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,93 @@ | ||
| <div align="center"> | ||
|
|
||
| # Polkadot SDK's Minimal Template | ||
|
|
||
| <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"/> | ||
|
|
||
| > This is a minimal template for creating a [Substrate](https://substrate.io/) blockchain. | ||
| > | ||
|
There was a problem hiding this comment. Can we already avoid linking to substrate.io overall? it is all future refactor if we leave it like this. I suppose for all of this we can either find a replacement, or bring it to There was a problem hiding this comment. OK, I'll try to find replacement for those substrate.io links. There was a problem hiding this comment. I have removed all |
||
| > This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). | ||
|
|
||
| </div> | ||
|
|
||
| ## 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. | ||
|
There was a problem hiding this comment. For this, we have: rust-setup.md in solochain template For now I suggest is to remove both of these, add one single bash file to There was a problem hiding this comment. There used to be this Do you know why it was abandoned and eventually removed? There was a problem hiding this comment. For now I wrote a minimal instruction, until we have a script or a doc that could be linked. |
||
|
|
||
| ### Build | ||
|
|
||
| 🔨 Use the following command to build the node without launching it: | ||
|
|
||
| ```sh | ||
| 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 default validator authorities and a `sudo` account. | ||
|
|
||
|
There was a problem hiding this comment. Does the template actually have this? needs to be double checked There was a problem hiding this comment. The accounts are prefunded, and I sent a
There was a problem hiding this comment. there are no validators in this setup, you can remove it. |
||
| ### 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 | ||
| 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. | ||
|
|
||
| ## 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/). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # Node | ||
|
|
||
| A blockchain node is an application that allows users to participate in a | ||
|
There was a problem hiding this comment. |
||
| 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/Polkadot/protocols/NPoS). | ||
| - 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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So the question is what is the minimal template?
The main difference between the minimal template and others is that it has the least number of components to run.
In the runtime side, this template only has a handful of pallets, which you can list.
On the node side, this template has no consensus and can run both with custom block time via CLI. see
enum Consensusin thenodefolder.In general, for palying around with a single node, this template is best.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I felt like some more introduction of what you're looking at is missing.
I added something based on this comment.