polkadot-developers/tutorials

Substrate Tutorials

Substrate Tutorials

This repository holds documentation for Substrate tutorials. The main website is hosted in substrate-cms.

Structure

All docs are written in markdown format. Each tutorial is in its own folder and has subfolders for each of its versions; supporting figures and images for all versions of all tutorials go in the assets folder.

Contributing

Feel free to add an issue if there is documentation that you'd like to see. See the contributing guide for guidance on making PRs.

Prettier

This repository uses Prettier to ensure consistent formatting. Please run Prettier before submitting any changes to the files in this repository. Prettier ships as an NPM package, so NPM must installed to use it. Prettier can be installed globally with npm i -g prettier in which case you can run prettier --write . in the project root. If you prefer not to install Prettier you can run it on-the-fly with npx prettier --write .. In either case, the .prettierrc.json file that ships with repository will be used to ensure consistent formatting.

License

All documentation is under the Apache 2 License.

tutorials's Issues

Private network, no peer seeing.

Hello,
I am trying to launch my private network using the pre-generated keys. Everything goes well but I do not see any peer appearing :/ The image may help.

Any idea?

Encountered consensus error when trying to launch my private network.

Hello,

I am following this tutorial: https://www.substrate.io/tutorials/start-a-private-network/v2.0.0-rc2/customchain and I am facing this issue:

Can somebody let me know what I am doing wrong? I am using the pre-generated keys.

Update tutorials to alpha.6

Substrate v2.0.0-alpha.6 was tagged recently. We should update all of our tutorials to use the new APIs.

A heads up specifically about the start a private network tutorial taken from #1

The telemetry CLI parameter was updated recently. The tutorial needs to be adapted.

See: paritytech/substrate#5552

Smart contracts are temporarily broken

There is a relatively new PR #5712 that got into alpha.7 and introduced breaking changes.
The UI can't handle this changes until #2604 is resolved.

This change impacts 2 tutorials:

1. The execution of SC after completing the "Add a Pallet" tutorial.
2. ink! tutorial

Port ink! tutorial

The ink! smart contract tutorial which is hosted at https://substrate.dev/substrate-contracts-workshop/#/0/setup and live in the repo https://github.com/substrate-developer-hub/substrate-contracts-workshop should be ported to this new tutorial repository.

error[E0424] building substrate template for first tutorial

I'm trying to complete the 1st tutorial from https://www.substrate.io/tutorials/create-your-first-substrate-chain/v2.0.0-rc2

The following error from running the command cargo build --release resulted

  error[E0424]: expected value, found module `self`
      --> /Users/wlopez/.cargo/git/checkouts/substrate- 7e08433d4c370a21/45b9f0a/frame/support/src/traits.rs:913:11
      |
  911 | / bitmask! {
  912 | |     /// Reasons for moving funds out of an account.
  913 | |     #[derive(Encode, Decode)]
      | |              ^^^^^^ `self` value is a keyword only available in methods with a `self` parameter
  914 | |     pub mask WithdrawReasons: i8 where
  ...   |
  929 | |     }
  930 | | }
     | |_- this function has a `self` parameter, but a macro invocation can only access identifiers it   receives from parameters
      |
       = note: this error originates in a derive macro (in Nightly builds, run with -Z macro-backtrace for more info)

Advanced start a network tutorial

The existing private network tutorial walks the learner through starting a 2-node poa network using the node template. It teaches many important skills, but also leaves some questions.

This tutorial should walk through the process of starting a PoS network using the full substrate node (/bin/node). This is a useful exercise becuase there are several differences from the existing tutorial.

• Uses the session pallet
• More nodes - minor difference
• Requires initial stakes
• More session keys

The process

• build the node and subkey (no messing around with generating keys through Apps)
• Generate keys
• make a custom spec
  • Keys in session pallet
  • leave consensus pallets blank
  • initial stakes
• Start the network with three validators
• Start fourth node as non-validating full node
• Bond a fourth validator
• Insert keys into the fourth node and observe that it starts authoring.

I wrote some useful tidbits for this exercise in this support issue paritytech/substrate#5078

update readme for tutorial repo

@JoshOrndorff i only copied and pasted what @joepetrowski wrote for the knowledgebase readme. you may want to customize it to your preference.

Finished all tutorials. What is next?

Hi @danforbes, I would like to thank you for your support. Because of you, I finished all the substrate tutorials.
Now I am looking for something else to work on.
Do you have any suggestions?

Is there any tutorial that can help me develop additional consensus algorithms to substrate?

We are developing some new consensus algorithms, and I would like to test it on the substrate. Are there any tutorials or help available to make the development easier?

Add a pallet tutorial bug

Due to some recent changes, the alpha.7 tutorial for adding pallets has two build errors:

error[E0425]: cannot find value `MILLICENTS` in this scope
   --> node/src/chain_spec.rs:129:28
    |
129 |             gas_price: 1 * MILLICENTS,
    |                            ^^^^^^^^^^ not found in this scope
    |
help: possible candidate is found in another module, you can import it into scope
    |
1   | use node_template_runtime::MILLICENTS;
    |

error[E0560]: struct `pallet_contracts::GenesisConfig` has no field named `gas_price`
   --> node/src/chain_spec.rs:129:13
    |
129 |             gas_price: 1 * MILLICENTS,
    |             ^^^^^^^^^ `pallet_contracts::GenesisConfig` does not have this field
    |
    = note: available fields are: `current_schedule`

The former is easily resolved using the suggested import, the latter will need other tweaks due to Gas no longer being a thing.

TCR Pallet Tutorial

In the old substrate.dev there is an outdated tutorial to write a TCR dApp. https://substrate.dev/docs/en/tutorials/tcr/ This old tutorial is deprecated and will not be ported directly to the new site.

The code has been mostly updated and the new code lives at https://github.com/substrate-developer-hub/tcr-substrate . This issue is to finish updating the code and write a tutorial about just the pallet, not the UI.

Tasks

• Update code to alpha.6
• Improve on_finalize to call two separate helper methods for expiring applications and polls.
• Write the tutorial

Followup task: A separate tutorial about about writing the front end. See #5

[substrate] dot is not recognized as an internal or external command, operable program or batch file.

Dear All,
I am very new to this scene and have depleted source in finding the answer for this error.

Please do advise or direct me for the following issue:-

1. I have followed the guide as per the tutorial on : Create Your First Substrate Chain
2. I'm using Windows 10 and followed the extra steps in installing the necessary applications
3. I'm unable to proceed further when I type ./target/release/node-template purge-chain --dev as it gives me the following error:
   '.' is not recognized as an internal or external command, operable program or batch file.

Appreciate your assistance.

Thank you.

Start your own private network needs to be updated

The telemetry CLI parameter was updated recently. The tutorial needs to be adapted.

See: paritytech/substrate#5552

Playground integration

Quoting @jeluard

A simple mechanism must be defined so that each tutorial can generate an up-to-date docker image compliant with the playground. It could provide basic customisation hooks (open custom ports, commands to be run as part of the image generation, ..)

Migrate rustdocs links

Now that our crates are published on crates.io, our docs are also published on docs.rs.

We should replace all substrate.dev/rustdocs links with the corresponding docs.rs links. For example https://docs.rs/sc-service/ (which points to latest published version) or https://docs.rs/sc-service/0.8.0-alpha.3/sc_service/ which points to a specific version.

context: paritytech/substrate#5652

Tutorial for TCR Front End

Write a tutorial that takes the learner through the process of writing a custom front-end starting with the front-end template.

`--rpc-methods` isn't valid in this context

the tutorial need to be updated: first-participant-starts-a-bootnode

 ~/workspace/blockchain/substrate-node-template   my-first-chain  ./target/release/node-template \
  --base-path /tmp/node01 \
  --chain=./customSpecRaw.json \
  --port 30333 \
  --ws-port 9944 \
  --rpc-port 9933 \
  --telemetry-url 'ws://telemetry.polkadot.io:1024 0' \
  --validator \
  --rpc-methods=Unsafe \
  --name MyNode01
error: Found argument '--rpc-methods' which wasn't expected, or isn't valid in this context
	Did you mean --rpc-cors?

USAGE:
    node-template --base-path <PATH> --chain <CHAIN_SPEC> --port <PORT> --rpc-cors <ORIGINS> --rpc-port <PORT> --telemetry-url <URL VERBOSITY>... --validator --ws-port <PORT>

For more information try --help

Building failed.

Hello guys,

I am trying to build in release either in developing but I am facing the issue below:

Code section of front-end tutorial page has trouble loading

Problem page: https://www.substrate.io/tutorials/build-a-dapp/v2.0.0-alpha.6/front-end

The code which is supposed to render after "Delete the contents of that file, and instead use the following component." takes a very long time to render, or never loads in some cases.

The code is there in the DOM but not shown due to an overflow display bug. Disabling overflow on the parent enclosing div fixes things.

two packages named `pallet-template` in this workspace:

I am following this tutorial: https://www.substrate.io/tutorials/pallet-in-own-crate/v2.0.0-rc2#install-the-node-template and I am facing the issue described below:

If you see, I have cloned the substrate-pallet-template repo into pallets package:

Am I doing something wrong?

Basic Add a pallet tutorial

We currently have a thorough and comprehensive tutorial teaching how to add the contracts pallet to the node. That is quite a complex pallet with many associated types, and an RPC that must be wired all the way through the runtime and the node. That tutorial is excellent for learners who are at that level.

We should add another tutorial that teaches how to add a simpler pallet to the runtime. Some good candidates might be:

• Identity
• Collective
• Nicks
• Recovery
• Something from recipes
• Something from ORML

Should This Repository Be Archived?

Port visualizing node metrics tutorial

The node metrics tutorial from https://substrate.dev/docs/en/next/tutorials/visualizing-node-metrics/ should be ported to this new repo

Images in tutorials not rendering on main site

The create your first chain tutorial has several embedded images. This page should show them. You can see they are listed in the source code https://github.com/substrate-developer-hub/tutorials/blame/3a784997b5f1b907ba0d11e10218ef86182e4359/tuts/create-your-first-substrate-chain/v2.0.0-alpha.5/background.md#L33

We've tried a few different ways to link to that image including an absolute path starting with /tutorials. @thisisvilla Do you know how we might fix these images?

Can't connect polkadot ui to local subtrate node

Using tutorial 1: https://www.substrate.io/tutorials/create-your-first-substrate-chain/v2.0.0-rc2/interact

After starting node and ui, the ui is not connecting to the node and there is no data displayed from the previous steps in the tutorial. The only tab in the UI is "Settings".

Steps to reproduce:

1. start node ./target/release/node-template --dev

2. start ui via docker: docker run --rm -it --name polkadot-ui -e WS_URL=ws://someip:9944 -p 80:80 chevdor/polkadot-ui:latest

3. browse to http://localhost/#/settings and set the endpoint to ws://127.0.0.1:9944

[update] I noticed the node seems to still be importing...this has been going on for a while so I don't know if that means the node isn't ready to accept connections.

  Imported #2258 (0x2568…a282)

Install prerequisites

Hello,
I am trying to install substrate prerequisites using this command
curl https://getsubstrate.io -sSf | bash -s -- --fast
but I got this error

Package clang is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source

Package libclang-dev:i386 is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source

E: Package 'clang' has no installation candidate
E: Package 'libclang-dev:i386' has no installation candidate

I installed clang
sudo apt install libclang1-7
but it gave the same error.

Website advises that alpha.5 tutorials are current

When I go to an alpha.6 tutorial like this one https://www.substrate.io/tutorials/create-your-first-substrate-chain/v2.0.0-alpha.6 The site tells me that it is not current and advises that alpha.5 is current.

Image missing? [Create your first substrate chain" tut]

On the first page of https://staging.substrate.io/tutorials/create-your-first-substrate-chain

Start a private network tutorial passes secret seed on the command line

https://substrate.dev/docs/en/next/tutorials/start-a-private-network/customchain#option-2-using-cli recommends users to pass their mnemonic phrase on the commandline. This is a security vulnerability because the seed will be retained in eg bash_history. Probably best to remove that section and recommend users use Apps instead.

Tutorial for PoE Front End

The PoE Tutorial gives a detailed explanation about writing the PoE pallet itself. Then it simply gives the learner working code for the front end. This is an appropriate ending to that tutorial because it exposes the learner to the existence of the front-end template, and lets them play with their new pallet immediately.

However, we should also provide a tutorial explaining how to really use the front-end-template and empowering users to build their own custom front ends.

error[E0424]: expected value, found module `self` installing subkey

Tutorial https://substrate.dev/docs/en/tutorials/start-a-private-network/keygen error during subkey compile.

Command:
cargo install --force subkey --git https://github.com/paritytech/substrate --tag v2.0.0-rc2

Error:
Compiling sp-consensus-babe v0.8.0-rc2 (/Users/wlopez/.cargo/git/checkouts/substrate-7e08433d4c370a21/45b9f0a/primitives/consensus/babe)
error[E0424]: expected value, found module self
--> /Users/wlopez/.cargo/git/checkouts/substrate- 7e08433d4c370a21/45b9f0a/frame/support/src/traits.rs:913:11
|
911 | / bitmask! {
912 | | /// Reasons for moving funds out of an account.
913 | | #[derive(Encode, Decode)]
| | ^^^^^^ self value is a keyword only available in methods with a self parameter
914 | | pub mask WithdrawReasons: i8 where
... |
929 | | }
930 | | }
| |_- this function has a self parameter, but a macro invocation can only access identifiers it receives from parameters
|
= note: this error originate

I'll continue using the ui to generate the keys but thought I should report the issue.

Links from tutorials to KB are broken

This issue is moved from https://github.com/paritytech/substrate.io/issues/38

https://staging.substrate.io/tutorials/add-a-pallet/v2.0.0-alpha.5

• "FRAME"
• "Creating Your First Substrate Chain Tutorial"
• "demonstration Substrate node runtime"
• "Genesis Configuration"

@thisisvilla Can you please fix one of these (or explain how to properly write the link) and I'll do the rest of them.

Port or deprecate older tutorials

The following tutorials are all listed in the old substrate.dev tutorial index. They should either be dusted off and ported or deprecated. This issue is about making the decision, not actually updating anything.

• UTXO - @nczhu is overhauling the code presently. I'll leave the decision about the tutorial itself up to her.

• Build a FrontEnd - After discussing with @Tbaut we've decided to deprecate this tutorial and replace it with a new one about building custom frontends starting from the front-end template. Here is a dedicated issue for that work.

• Substrate Collectibles Workshop aka Kitties - Last I heard, @shawntabrizi intends to update this tutorial after Substrate 2.0 is released. I suspect it will remain in its current docsify format, but it is also welcome in this repo, if this format is preferred.

• Verifiable Credentials - This is significantly outdated. My preference is to deprecate.

• TCR - @gautamdhameja and I overhauled the code for this tutorial recently, but not the writeup or the UI. I'm willing to help with updating if Gautam wants to dust this one off. This could also be the combined with the Front End tutorial (see above).