Enhancement on Substrate Node Template (#8473)

Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>
This commit is contained in:
Jimmy Chu
2021-03-30 07:47:37 +08:00
committed by GitHub
parent a946c3343e
commit fb73a4eef6
15 changed files with 313 additions and 150 deletions
+1 -1
View File
@@ -10,7 +10,7 @@ if [ "$#" -ne 1 ]; then
exit 1
fi
PATH_TO_ARCHIVE=$(pwd)/$1
PATH_TO_ARCHIVE=$1
cd $PROJECT_ROOT/.maintain/node-template-release
cargo run $PROJECT_ROOT/bin/node-template $PATH_TO_ARCHIVE
@@ -1,6 +1,6 @@
[package]
name = "node-template-release"
version = "2.0.0"
version = "3.0.0"
authors = ["Parity Technologies <admin@parity.io>"]
edition = "2018"
license = "GPL-3.0"
+3 -3
View File
@@ -4352,7 +4352,7 @@ dependencies = [
[[package]]
name = "node-template"
version = "2.0.0"
version = "3.0.0"
dependencies = [
"frame-benchmarking",
"frame-benchmarking-cli",
@@ -4389,7 +4389,7 @@ dependencies = [
[[package]]
name = "node-template-runtime"
version = "2.0.0"
version = "3.0.0"
dependencies = [
"frame-benchmarking",
"frame-executive",
@@ -5482,7 +5482,7 @@ dependencies = [
[[package]]
name = "pallet-template"
version = "2.0.0"
version = "3.0.0"
dependencies = [
"frame-benchmarking",
"frame-support",
+16
View File
@@ -0,0 +1,16 @@
root = true
[*]
indent_style=space
indent_size=2
tab_width=2
end_of_line=lf
charset=utf-8
trim_trailing_whitespace=true
insert_final_newline = true
[*.{rs,toml}]
indent_style=tab
indent_size=tab
tab_width=4
max_line_length=100
+58 -80
View File
@@ -1,97 +1,71 @@
# Substrate Node Template
A new FRAME-based Substrate node, ready for hacking :rocket:
A fresh FRAME-based [Substrate](https://www.substrate.io/) node, ready for hacking :rocket:
## Local Development
## Getting Started
Follow these steps to prepare a local Substrate development environment :hammer_and_wrench:
Follow these steps to get started with the Node Template :hammer_and_wrench:
### Simple Setup
### Rust Setup
Install all the required dependencies with a single command (be patient, this can take up to 30
minutes).
First, complete the [basic Rust setup instructions](./doc/rust-setup.md).
```bash
curl https://getsubstrate.io -sSf | bash -s -- --fast
### Run
Use Rust's native `cargo` command to build and launch the template node:
```sh
cargo run --release -- --dev --tmp
```
### Manual Setup
Find manual setup instructions at the
[Substrate Developer Hub](https://substrate.dev/docs/en/knowledgebase/getting-started/#manual-installation).
### Build
Once the development environment is set up, build the node template. This command will build the
[Wasm](https://substrate.dev/docs/en/knowledgebase/advanced/executor#wasm-execution) and
[native](https://substrate.dev/docs/en/knowledgebase/advanced/executor#native-execution) code:
The `cargo run` command will perform an initial build. Use the following command to build the node
without launching it:
```bash
```sh
cargo build --release
```
### Embedded Docs
Once the project has been built, the following command can be used to explore all parameters and
subcommands:
```sh
./target/release/node-template -h
```
## Run
### Single Node Development Chain
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.
Purge any existing dev chain state:
### Single-Node Development Chain
```bash
./target/release/node-template purge-chain --dev
```
Start a dev chain:
This command will start the single-node development chain with persistent state:
```bash
./target/release/node-template --dev
```
Or, start a dev chain with detailed logging:
Purge the development chain's state:
```bash
RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/node-template -lruntime=debug --dev
./target/release/node-template purge-chain --dev
```
Start the development chain with detailed logging:
```bash
RUST_BACKTRACE=1 ./target/release/node-template -ldebug --dev
```
### Multi-Node Local Testnet
To see the multi-node consensus algorithm in action, run a local testnet with two validator nodes,
Alice and Bob, that have been [configured](./node/src/chain_spec.rs) as the initial
authorities of the `local` testnet chain and endowed with testnet units.
Note: this will require two terminal sessions (one for each node).
Start Alice's node first. The command below uses the default TCP port (30333) and specifies
`/tmp/alice` as the chain database location. Alice's node ID will be
`12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp` (legacy representation:
`QmRpheLN4JWdAnY7HGJfWFNbfkQCb6tFf4vvA6hgjMZKrR`); this is determined by the `node-key`.
```bash
cargo run -- \
--base-path /tmp/alice \
--chain=local \
--alice \
--node-key 0000000000000000000000000000000000000000000000000000000000000001 \
--telemetry-url 'ws://telemetry.polkadot.io:1024 0' \
--validator
```
In another terminal, use the following command to start Bob's node on a different TCP port (30334)
and with a chain database location of `/tmp/bob`. The `--bootnodes` option will connect his node to
Alice's on TCP port 30333:
```bash
cargo run -- \
--base-path /tmp/bob \
--bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp \
--chain=local \
--bob \
--port 30334 \
--ws-port 9945 \
--telemetry-url 'ws://telemetry.polkadot.io:1024 0' \
--validator
```
Execute `cargo run -- --help` to learn more about the template node's CLI options.
If you want to see the multi-node consensus algorithm in action, refer to
[our Start a Private Network tutorial](https://substrate.dev/docs/en/tutorials/start-a-private-network/).
## Template Structure
@@ -184,24 +158,28 @@ A FRAME pallet is compromised of a number of blockchain primitives:
- Config: The `Config` configuration interface is used to define the types and parameters upon
which a FRAME pallet depends.
## Generate a Custom Node Template
### Run in Docker
Generate a Substrate node template based on a particular commit by running the following commands:
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
# Clone from the main Substrate repo
git clone https://github.com/paritytech/substrate.git
cd substrate
# Switch to the branch or commit to base the template on
git checkout <branch/tag/sha1>
# Run the helper script to generate a node template. This script compiles Substrate, so it will take
# a while to complete. It expects a single parameter: the location for the script's output expressed
# as a relative path.
.maintain/node-template-release.sh ../node-template.tar.gz
./scripts/docker_run.sh
```
Custom node templates are not supported. Please use a recently tagged version of the
[Substrate Developer Node Template](https://github.com/substrate-developer-hub/substrate-node-template)
in order to receive support.
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.
```bash
# Run Substrate node without re-compiling
./scripts/docker_run.sh ./target/release/node-template --dev --ws-external
# Purge the local dev chain
./scripts/docker_run.sh ./target/release/node-template purge-chain --dev
# Check whether the code is compilable
./scripts/docker_run.sh cargo check
```
@@ -0,0 +1,17 @@
version: "3.2"
services:
dev:
container_name: node-template
image: paritytech/ci-linux:974ba3ac-20201006
working_dir: /var/www/node-template
ports:
- "9944:9944"
environment:
- CARGO_HOME=/var/www/node-template/.cargo
volumes:
- .:/var/www/node-template
- type: bind
source: ./.local
target: /root/.local
command: bash -c "cargo build --release && ./target/release/node-template --dev --ws-external"
@@ -0,0 +1,81 @@
---
title: Installation
---
This page will guide you through the steps needed to prepare a computer for development with the
Substrate Node Template. Since Substrate is built with
[the Rust programming language](https://www.rust-lang.org/), the first thing you will need to do is
prepare the computer for Rust development - these steps will vary based on the computer's operating
system. Once Rust is configured, you will use its toolchains to interact with Rust projects; the
commands for Rust's toolchains will be the same for all supported, Unix-based operating systems.
## Unix-Based Operating Systems
Substrate development is easiest on Unix-based operating systems like macOS or Linux. The examples
in the Substrate [Tutorials](https://substrate.dev/tutorials) and [Recipes](https://substrate.dev/recipes/)
use Unix-style terminals to demonstrate how to interact with Substrate from the command line.
### macOS
Open the Terminal application and execute the following commands:
```bash
# Install Homebrew if necessary https://brew.sh/
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
# Make sure Homebrew is up-to-date, install openssl and cmake
brew update
brew install openssl cmake
```
### Ubuntu/Debian
Use a terminal shell to execute the following commands:
```bash
sudo apt update
# May prompt for location information
sudo apt install -y cmake pkg-config libssl-dev git build-essential clang libclang-dev curl
```
### Arch Linux
Run these commands from a terminal:
```bash
pacman -Syu --needed --noconfirm cmake gcc openssl-1.0 pkgconf git clang
export OPENSSL_LIB_DIR="/usr/lib/openssl-1.0"
export OPENSSL_INCLUDE_DIR="/usr/include/openssl-1.0"
```
### Fedora/RHEL/CentOS
Use a terminal to run the following commands:
```bash
# Update
sudo dnf update
# Install packages
sudo dnf install cmake pkgconfig rocksdb rocksdb-devel llvm git libcurl libcurl-devel curl-devel clang
```
## Rust Developer Environment
This project uses [`rustup`](https://rustup.rs/) to help manage the Rust toolchain. First install
and configure `rustup`:
```bash
# Install
curl https://sh.rustup.rs -sSf | sh
# Configure
source ~/.cargo/env
```
Finally, configure the Rust toolchain:
```bash
rustup default stable
rustup update nightly
rustup update stable
rustup target add wasm32-unknown-unknown --toolchain nightly
```
+5 -5
View File
@@ -1,13 +1,13 @@
[package]
name = "node-template"
version = "2.0.0"
authors = ["Anonymous"]
description = "A new FRAME-based Substrate node, ready for hacking."
version = "3.0.0"
authors = ["Substrate DevHub <https://github.com/substrate-developer-hub>"]
description = "A fresh FRAME-based Substrate node, ready for hacking."
edition = "2018"
license = "Unlicense"
build = "build.rs"
homepage = "https://substrate.dev"
repository = "https://github.com/paritytech/substrate/"
repository = "https://github.com/substrate-developer-hub/substrate-node-template/"
[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]
@@ -51,7 +51,7 @@ pallet-transaction-payment-rpc = { version = "3.0.0", path = "../../../frame/tra
frame-benchmarking = { version = "3.1.0", path = "../../../frame/benchmarking" }
frame-benchmarking-cli = { version = "3.0.0", path = "../../../utils/frame/benchmarking-cli" }
node-template-runtime = { version = "2.0.0", path = "../runtime" }
node-template-runtime = { version = "3.0.0", path = "../runtime" }
[build-dependencies]
substrate-build-script-utils = { version = "3.0.0", path = "../../../utils/build-script-utils" }
@@ -1,11 +1,11 @@
[package]
authors = ['Anonymous']
authors = ['Substrate DevHub <https://github.com/substrate-developer-hub>']
edition = '2018'
name = 'pallet-template'
version = "2.0.0"
version = "3.0.0"
license = "Unlicense"
homepage = "https://substrate.dev"
repository = "https://github.com/paritytech/substrate/"
repository = "https://github.com/substrate-developer-hub/substrate-node-template/"
description = "FRAME pallet template for defining custom runtime logic."
readme = "README.md"
@@ -14,40 +14,15 @@ targets = ["x86_64-unknown-linux-gnu"]
[dependencies]
codec = { package = "parity-scale-codec", version = "2.0.0", default-features = false, features = ["derive"] }
[dependencies.frame-support]
default-features = false
version = "3.0.0"
path = "../../../../frame/support"
[dependencies.frame-system]
default-features = false
version = "3.0.0"
path = "../../../../frame/system"
[dependencies.frame-benchmarking]
default-features = false
version = "3.1.0"
path = "../../../../frame/benchmarking"
optional = true
frame-support = { default-features = false, version = "3.0.0", path = "../../../../frame/support" }
frame-system = { default-features = false, version = "3.0.0", path = "../../../../frame/system" }
frame-benchmarking = { default-features = false, version = "3.1.0", path = "../../../../frame/benchmarking", optional = true }
[dev-dependencies]
serde = { version = "1.0.101" }
[dev-dependencies.sp-core]
default-features = false
version = "3.0.0"
path = "../../../../primitives/core"
[dev-dependencies.sp-io]
default-features = false
version = "3.0.0"
path = "../../../../primitives/io"
[dev-dependencies.sp-runtime]
default-features = false
version = "3.0.0"
path = "../../../../primitives/runtime"
serde = { version = "1.0.119" }
sp-core = { default-features = false, version = "3.0.0", path = "../../../../primitives/core" }
sp-io = { default-features = false, version = "3.0.0", path = "../../../../primitives/io" }
sp-runtime = { default-features = false, version = "3.0.0", path = "../../../../primitives/runtime" }
[features]
default = ['std']
@@ -57,5 +32,6 @@ std = [
'frame-system/std',
'frame-benchmarking/std',
]
runtime-benchmarks = ["frame-benchmarking"]
try-runtime = ["frame-support/try-runtime"]
@@ -17,7 +17,7 @@ mod benchmarking;
#[frame_support::pallet]
pub mod pallet {
use frame_support::{dispatch::DispatchResultWithPostInfo, pallet_prelude::*};
use frame_support::{dispatch::DispatchResult, pallet_prelude::*};
use frame_system::pallet_prelude::*;
/// Configure the pallet by specifying the parameters and types on which it depends.
@@ -70,7 +70,7 @@ pub mod pallet {
/// An example dispatchable that takes a singles value as a parameter, writes the value to
/// storage and emits an event. This function must be dispatched by a signed extrinsic.
#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]
pub fn do_something(origin: OriginFor<T>, something: u32) -> DispatchResultWithPostInfo {
pub fn do_something(origin: OriginFor<T>, something: u32) -> DispatchResult {
// Check that the extrinsic was signed and get the signer.
// This function will return an error if the extrinsic is not signed.
// https://substrate.dev/docs/en/knowledgebase/runtime/origin
@@ -82,12 +82,12 @@ pub mod pallet {
// Emit an event.
Self::deposit_event(Event::SomethingStored(something, who));
// Return a successful DispatchResultWithPostInfo
Ok(().into())
Ok(())
}
/// An example dispatchable that may throw a custom error.
#[pallet::weight(10_000 + T::DbWeight::get().reads_writes(1,1))]
pub fn cause_error(origin: OriginFor<T>) -> DispatchResultWithPostInfo {
pub fn cause_error(origin: OriginFor<T>) -> DispatchResult {
let _who = ensure_signed(origin)?;
// Read a value from storage.
@@ -99,7 +99,7 @@ pub mod pallet {
let new = old.checked_add(1).ok_or(Error::<T>::StorageOverflow)?;
// Update the value in storage with the incremented result.
<Something<T>>::put(new);
Ok(().into())
Ok(())
},
}
}
+11 -11
View File
@@ -1,11 +1,11 @@
[package]
name = "node-template-runtime"
version = "2.0.0"
authors = ["Anonymous"]
version = "3.0.0"
authors = ["Substrate DevHub <https://github.com/substrate-developer-hub>"]
edition = "2018"
license = "Unlicense"
homepage = "https://substrate.dev"
repository = "https://github.com/paritytech/substrate/"
repository = "https://github.com/substrate-developer-hub/substrate-node-template/"
[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]
@@ -45,7 +45,7 @@ frame-benchmarking = { version = "3.1.0", default-features = false, path = "../.
frame-system-benchmarking = { version = "3.0.0", default-features = false, path = "../../../frame/system/benchmarking", optional = true }
hex-literal = { version = "0.3.1", optional = true }
template = { version = "2.0.0", default-features = false, path = "../pallets/template", package = "pallet-template" }
pallet-template = { version = "3.0.0", default-features = false, path = "../pallets/template" }
[build-dependencies]
substrate-wasm-builder = { version = "4.0.0", path = "../../../utils/wasm-builder" }
@@ -56,14 +56,17 @@ std = [
"codec/std",
"frame-executive/std",
"frame-support/std",
"frame-system-rpc-runtime-api/std",
"frame-system/std",
"pallet-aura/std",
"pallet-balances/std",
"pallet-grandpa/std",
"pallet-randomness-collective-flip/std",
"pallet-sudo/std",
"pallet-template/std",
"pallet-timestamp/std",
"pallet-transaction-payment/std",
"pallet-transaction-payment-rpc-runtime-api/std",
"pallet-transaction-payment/std",
"serde",
"sp-api/std",
"sp-block-builder/std",
@@ -76,18 +79,15 @@ std = [
"sp-std/std",
"sp-transaction-pool/std",
"sp-version/std",
"frame-system/std",
"frame-system-rpc-runtime-api/std",
"template/std",
]
runtime-benchmarks = [
"sp-runtime/runtime-benchmarks",
"frame-benchmarking",
"frame-support/runtime-benchmarks",
"frame-system-benchmarking",
"hex-literal",
"frame-system/runtime-benchmarks",
"hex-literal",
"pallet-balances/runtime-benchmarks",
"pallet-template/runtime-benchmarks",
"pallet-timestamp/runtime-benchmarks",
"template/runtime-benchmarks",
"sp-runtime/runtime-benchmarks",
]
+15 -8
View File
@@ -40,7 +40,7 @@ pub use frame_support::{
use pallet_transaction_payment::CurrencyAdapter;
/// Import the template pallet.
pub use template;
pub use pallet_template;
/// An index to a block.
pub type BlockNumber = u32;
@@ -92,17 +92,24 @@ pub mod opaque {
}
}
// To learn more about runtime versioning and what each of the following value means:
// https://substrate.dev/docs/en/knowledgebase/runtime/upgrades#runtime-versioning
pub const VERSION: RuntimeVersion = RuntimeVersion {
spec_name: create_runtime_str!("node-template"),
impl_name: create_runtime_str!("node-template"),
authoring_version: 1,
spec_version: 1,
// The version of the runtime specification. A full node will not attempt to use its native
// runtime in substitute for the on-chain Wasm runtime unless all of `spec_name`,
// `spec_version`, and `authoring_version` are the same between Wasm and native.
// This value is set to 100 to notify Polkadot-JS App (https://polkadot.js.org/apps) to use
// the compatible custom types.
spec_version: 100,
impl_version: 1,
apis: RUNTIME_API_VERSIONS,
transaction_version: 1,
};
/// This determines the average expected block time that we are targetting.
/// This determines the average expected block time that we are targeting.
/// Blocks will be produced at a minimum duration defined by `SLOT_DURATION`.
/// `SLOT_DURATION` is picked up by `pallet_timestamp` which is in turn picked
/// up by `pallet_aura` to implement `fn slot_duration()`.
@@ -258,8 +265,8 @@ impl pallet_sudo::Config for Runtime {
type Call = Call;
}
/// Configure the pallet template in pallets/template.
impl template::Config for Runtime {
/// Configure the pallet-template in pallets/template.
impl pallet_template::Config for Runtime {
type Event = Event;
}
@@ -278,8 +285,8 @@ construct_runtime!(
Balances: pallet_balances::{Pallet, Call, Storage, Config<T>, Event<T>},
TransactionPayment: pallet_transaction_payment::{Pallet, Storage},
Sudo: pallet_sudo::{Pallet, Call, Config<T>, Storage, Event<T>},
// Include the custom logic from the template pallet in the runtime.
TemplateModule: template::{Pallet, Call, Storage, Event<T>},
// Include the custom logic from the pallet-template in the runtime.
TemplateModule: pallet_template::{Pallet, Call, Storage, Event<T>},
}
);
@@ -475,7 +482,7 @@ impl_runtime_apis! {
add_benchmark!(params, batches, frame_system, SystemBench::<Runtime>);
add_benchmark!(params, batches, pallet_balances, Balances);
add_benchmark!(params, batches, pallet_timestamp, Timestamp);
add_benchmark!(params, batches, template, TemplateModule);
add_benchmark!(params, batches, pallet_template, TemplateModule);
if batches.is_empty() { return Err("Benchmark not found for this pallet.".into()) }
Ok(batches)
@@ -0,0 +1,10 @@
#!/usr/bin/env bash
# This script is meant to be run on Unix/Linux based systems
set -e
echo "*** Start Substrate node template ***"
cd $(dirname ${BASH_SOURCE[0]})/..
docker-compose down --remove-orphans
docker-compose run --rm --service-ports dev $@
+1 -1
View File
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
# This script is meant to be run on Unix/Linux based systems
set -e
echo "*** Initializing WASM build environment"
+78
View File
@@ -0,0 +1,78 @@
# Substrate Node Template Release Process
1. This release process has to be run in a github checkout Substrate directory with your work
committed into `https://github.com/paritytech/substrate/`, because the build script will check
the existence of your current git commit ID in the remote repository.
Assume you are in root directory of Substrate. Run:
```bash
cd .maintain/
./node-template-release.sh <output tar.gz file>
```
2. Expand the output tar gzipped file and replace files in current Substrate Node Template
by running the following command.
```bash
# This is where the tar.gz file uncompressed
cd substrate-node-template
# rsync with force copying. Note the slash at the destination directory is important
rsync -avh * <destination node-template directory>/
# For dry-running add `-n` argument
# rsync -avhn * <destination node-template directory>/
```
The above command only copies existing files from the source to the destination, but does not
delete files/directories that are removed from the source. So you need to manually check and
remove them in the destination.
3. There are actually three packages in the Node Template, `node-template` (the node),
`node-template-runtime` (the runtime), and `pallet-template`, and each has its own `Cargo.toml`.
Inside these three files, dependencies are listed in expanded form and linked to a certain git
commit in Substrate remote repository, such as:
```toml
[dev-dependencies.sp-core]
default-features = false
git = 'https://github.com/paritytech/substrate.git'
rev = 'c1fe59d060600a10eebb4ace277af1fee20bad17'
version = '3.0.0'
```
We will update each of them to the shortened form and link them to the Rust
[crate registry](https://crates.io/). After confirming the versioned package is published in
the crate, the above will become:
```toml
[dev-dependencies]
sp-core = { version = '3.0.0', default-features = false }
```
P.S: This step can be automated if we update `node-template-release` package in
`.maintain/node-template-release`.
4. Once the three `Cargo.toml`s are updated, compile and confirm that the Node Template builds. Then
commit the changes to a new branch in [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template), and make a PR.
> Note that there is a chance the code in Substrate Node Template works with the linked Substrate git
commit but not with published packages due to the latest (as yet) unpublished features. In this case,
rollback that section of the Node Template to its previous version to ensure the Node Template builds.
5. Once the PR is merged, tag the merged commit in master branch with the version number
`vX.Y.Z+A` (e.g. `v3.0.0+1`). The `X`(major), `Y`(minor), and `Z`(patch) version number should
follow Substrate release version. The last digit is any significant fixes made in the Substrate
Node Template apart from Substrate. When the Substrate version is updated, this digit is reset to 0.
## Troubleshooting
- Running the script `./node-template-release.sh <output tar.gz file>`, after all tests passed
successfully, seeing the following error message:
```
thread 'main' panicked at 'Creates output file: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:250:10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
This is likely due to that your output path is not a valid `tar.gz` filename or you don't have write
permission to the destination. Try with a simple output path such as `~/node-tpl.tar.gz`.