diff --git a/substrate/bin/node-template/README.md b/substrate/bin/node-template/README.md index 0f6fd9450aeee6c1de2e3a22e84380433ef33eb8..c42b58449565dc2914086ae20a970381f23f32f2 100644 --- a/substrate/bin/node-template/README.md +++ b/substrate/bin/node-template/README.md @@ -1,38 +1,22 @@ # Substrate Node Template -[](https://docs.substrate.io/playground/) [](https://matrix.to/#/#substrate-technical:matrix.org) +A fresh [Substrate](https://substrate.io/) node, ready for hacking :rocket: -A fresh FRAME-based [Substrate](https://www.substrate.io/) node, ready for hacking :rocket: +A standalone version of this template is available for each release of Polkadot in the [Substrate Developer Hub Parachain Template](https://github.com/substrate-developer-hub/substrate-parachain-template/) repository. +The parachain template is generated directly at each Polkadot release branch form the [Node Template in Substreate](https://github.com/paritytech/substrate/tree/master/bin/node-template) upstream -## Getting Started - -Follow the steps below to get started with the Node Template, or get it up and running right from -your browser in just a few clicks using -the [Substrate Playground](https://docs.substrate.io/playground/) :hammer_and_wrench: - -### Using Nix - -Install [nix](https://nixos.org/) and optionally [direnv](https://github.com/direnv/direnv) and -[lorri](https://github.com/nix-community/lorri) for a fully plug and play experience for setting up -the development environment. To get all the correct dependencies activate direnv `direnv allow` and -lorri `lorri shell`. - -### Rust Setup +It is usually best to to use the stand-alone version to start a new project. +All bugs, suggestions, and feature requests should be made upstream in the [Substrate](https://github.com/paritytech/substrate/tree/master/bin/node-template) repository. -First, complete the [basic Rust setup instructions](./docs/rust-setup.md). - -### Run +## Getting Started -Use Rust's native `cargo` command to build and launch the template node: - -```sh -cargo run --release -- --dev -``` +Depending on your operating system and Rust version, there might be additional packages required to compile this template. +Check the [Install](https://docs.substrate.io/install/) instructions for your platform for the most common dependencies. +Alternatively, you can use one of the [alternative installation](#alternatives-installations) options. ### Build -The `cargo run` command will perform an initial 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 @@ -40,54 +24,49 @@ cargo build --release ### Embedded Docs -Once the project has been built, the following command can be used to explore all parameters and -subcommands: +After you build the project, you can use the following command to explore its parameters and subcommands: ```sh ./target/release/node-template -h ``` -## Run +You can generate and view the [Rust Docs](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for this template with this command: -The provided `cargo run` command will launch a temporary node and its state will be discarded after -you terminate the process. After the project has been built, there are other ways to launch the -node. +```sh +cargo +nightly doc --open +``` ### Single-Node Development Chain -This command will start the single-node development chain with non-persistent state: +The following command starts a single-node development chain that doesn't persist state: -```bash +```sh ./target/release/node-template --dev ``` -Purge the development chain's state: +To purge the development chain's state, run the following command: -```bash +```sh ./target/release/node-template purge-chain --dev ``` -Start the development chain with detailed logging: +To start the development chain with detailed logging, run the following command: -```bash +```sh RUST_BACKTRACE=1 ./target/release/node-template -ldebug --dev ``` -> Development chain means that the state of our chain will be in a tmp folder while the nodes are -> running. Also, **alice** account will be authority and sudo account as declared in the -> [genesis state](https://github.com/substrate-developer-hub/substrate-node-template/blob/main/node/src/chain_spec.rs#L49). -> At the same time the following accounts will be pre-funded: -> - Alice -> - Bob -> - Alice//stash -> - Bob//stash - -In case of being interested in maintaining the chain' state between runs a base path must be added -so the db can be stored in the provided folder instead of a temporal one. We could use this folder -to store different chain databases, as a different folder will be created per different chain that -is ran. The following commands shows how to use a newly created folder as our db base path. - -```bash +Development chains: + +- Maintain state in a `tmp` folder while the node is running. +- Use the **Alice** and **Bob** accounts as default validator authorities. +- Use the **Alice** account as the default `sudo` account. +- Are preconfigured with a genesis state (`/node/src/chain_spec.rs`) that includes several prefunded development accounts. + + +To persist chain state between runs, specify a base path by running a command similar to the following: + +```sh // Create a folder to use as the db base path $ mkdir my-chain-state @@ -103,23 +82,19 @@ $ ls ./my-chain-state/chains/dev db keystore network ``` +### Connect with Polkadot-JS Apps Front-End -### Connect with Polkadot-JS Apps Front-end - -Once the node template is running locally, you can connect it with **Polkadot-JS Apps** front-end -to interact with your chain. [Click -here](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) connecting the Apps to your -local node template. +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. ### Multi-Node Local Testnet -If you want to see the multi-node consensus algorithm in action, refer to our -[Simulate a network tutorial](https://docs.substrate.io/tutorials/get-started/simulate-network/). +If you want to see the multi-node consensus algorithm in action, see [Simulate a network](https://docs.substrate.io/tutorials/get-started/simulate-network/). ## Template Structure -A Substrate project such as this consists of a number of components that are spread across a few -directories. +A Substrate project such as this consists of a number of components that are spread across a few directories. ### Node @@ -128,98 +103,74 @@ 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/main-docs/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). +- 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`](./node/src/chain_spec.rs): A - [chain specification](https://docs.substrate.io/main-docs/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, which - 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`](./node/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/main-docs/fundamentals/consensus/#finalization-and-forks) - and other [consensus mechanisms](https://docs.substrate.io/main-docs/fundamentals/consensus/#default-consensus-models) - such as Aura for block authoring and GRANDPA for finality. - -After the node has been [built](#build), refer to the embedded documentation to learn more about the -capabilities and configuration parameters that it exposes: - -```shell -./target/release/node-template --help -``` +There are several files in the `node` directory. +Take special note of the following: + +- [`chain_spec.rs`](./node/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`](./node/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. + + ### Runtime -In Substrate, the terms -"runtime" and "state transition function" -are analogous - they 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/main-docs/fundamentals/runtime-intro/#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](./runtime/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://crates.parity.io/frame_support/macro.construct_runtime.html) - macro, which is part of the core - FRAME Support [system](https://docs.substrate.io/reference/frame-pallets/#system-pallets) library. +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/fundamentals/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](./runtime/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://crates.parity.io/frame_support/macro.construct_runtime.html) macro, which is part of the core FRAME Support [system](https://docs.substrate.io/reference/frame-pallets/#system-pallets) library. ### Pallets -The runtime in this project is constructed using many FRAME pallets that ship with the -[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a -template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory. +The runtime in this project is constructed using many FRAME pallets that ship with the [core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory. A FRAME pallet is compromised of a number of blockchain primitives: -- Storage: FRAME defines a rich set of powerful - [storage abstractions](https://docs.substrate.io/main-docs/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 and errors](https://docs.substrate.io/main-docs/build/events-errors/) - to notify users of important changes in the runtime. +- 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 and errors](https://docs.substrate.io/build/events-and-errors/) to notify users of important changes in the runtime. - Errors: When a dispatchable fails, it returns an error. -- Config: The `Config` configuration interface is used to define the types and parameters upon - which a FRAME pallet depends. +- Config: The `Config` configuration interface is used to define the types and parameters upon which a FRAME pallet depends. + +## Alternatives Installations + +Instead of installing dependencies and building this source directly, consider the following alternatives. -### Run in Docker +### Nix -First, install [Docker](https://docs.docker.com/get-docker/) and -[Docker Compose](https://docs.docker.com/compose/install/). +Install [nix](https://nixos.org/), and optionally [direnv](https://github.com/direnv/direnv) and [lorri](https://github.com/nix-community/lorri) for a fully plug-and-play experience for setting up the development environment. +To get all the correct dependencies, activate direnv `direnv allow` and lorri `lorri shell`. + +### Docker + +First, install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/). Then run the following command to start a single node development chain. -```bash +```sh ./scripts/docker_run.sh ``` -This command will firstly compile your code, and then start a local development network. You can -also replace the default command -(`cargo build --release && ./target/release/node-template --dev --ws-external`) -by appending your own. A few useful ones are as follow. +This command compiles the code and starts a local development network. +You can also replace the default command (`cargo build --release && ./target/release/node-template --dev --ws-external`) by appending your own. +For example: -```bash +```sh # Run Substrate node without re-compiling ./scripts/docker_run.sh ./target/release/node-template --dev --ws-external diff --git a/substrate/bin/node-template/scripts/docker_run.sh b/substrate/bin/node-template/scripts/docker_run.sh old mode 100644 new mode 100755