substrate-developer-hub/docs

Substrate Documentation

(Old) Substrate Developer Hub (ARCHIVED)

THIS SITE IS ARCHIVED.

• New site: https://docs.substrate.io/
• Source available: https://github.com/substrate-developer-hub/substrate-docs/

This repository houses documentation for the Substrate blockchain framework.

The docs are written in markdown, processed by Docusaurus, and hosted at the Substrate Developer Hub.

Contributing

Thank you for your interest in contributing to the Developer Hub and to the larger Substrate community! Please review our contributor guidelines prior to any contribution. If you have any further questions, don't hesitate to reach out on our substrate technical community channel.

Directory Structure

This repository is structured as a Docusaurus project with the markdown files organized in the /docs directory. Images and other assets are in the /docs/assets/ directory. The /website directory is a Yarn Docusaurus project with many helpful scripts (e.g. yarn build, yarn start) for working with this codebase.  In the /website directory you will find sidebars.json and siteConfig.js, which are important Docusaurus files. You will find the source code for some top-level pages in /website/pages/en. Follow our contribution guidelines.

Adding a new document

To add a new markdown document:

• Create your markdown document in a suitable directory inside /docs.
• If you have images in your document, put them in the /docs/assets/ directory.
• Documentation should follow our contribution guidelines.
• If you want your document to appear in the sidebar, add its reference in the /website/sidebar.json file under the   corresponding section.

Rename an existing document

To rename an existing document:

• Change the name or path of the document.
• After the change has been merged, go to the Crowdin project,   make sure the translation is already migrated to the new file automatically for all the target languages.
• Then go to Crowdin project settings, remove the   old source file in Files tab.
• If you don't have access to the Crowdin project, please send email to [email protected] with the   file information you want to remove.

Local Testing

• cd into the /website directory.
• Execute yarn install and then yarn start.

The Substrate Developer Hub website should open in a browser window.

Link Checker

Once the website is running, you should use the included Yarn script (yarn check-links) to ensure that your changes do not introduce any broken links and to check for any links that have broken since the last time the check was executed. Please ensure all links are fixed before submitting any changes; if you have questions about broken links that you did not introduce, please create an Issue.

Once you are done with your changes, feel free to submit a PR.

Updates

There is a helper script that can be used to update substrate.dev/rustdocs links in the docs/knowledgebase directory.

# This examples demonstrates updating links from v2.0.0-rc3 to v2.0.0-rc4
OLD_VERSION=v2.0.0-rc3 NEW_VERSION=v2.0.0-rc4 ./scripts/update-kb-rustdocs

Production Deployment

Our production site is at substrate.dev. To deploy to production, merge your update into the source branch. This triggers the CI to build the website AND also pull in multilingual translation from our Crowdin project. The final built static site is then pushed to the master branch and hosted on GitHub Pages.

Staging Deployment

We have a staging deployment at devhub-maindocs.herokuapp.com, which is hosted on Heroku. Please check with the devhub team for the username and password to access the staging site.

To deploy to staging, you could push to the staging-source branch in the repository. This will trigger the CI to build the website, pull in multilingual translations from crowdin, and have the final built static site being pushed to staging branch. This in turn triggers Heroku to pick up the latest commit from staging branch and deploy to the staging site.

License

Substrate documentation is licenced under the Apache 2 license.

docs's Issues

Event type

Fees Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Internationalization (i18n)

Internationalization of Substrate Dev Hub (not reference docs). Likely target languages are Mandarin, Russian and Spanish.

Config type

Overview & tracking

(data merged with #578) cc/ @0x7CFE

Priority: P1, P2, P3

TOPBAR

Ask a question [either links to on-hub discussion section or [stackoverflow](https://stackoverflow.com/questions/ask?tags=substrate]
Chat with us

Home P2

• How to get Substrate
• 10,000ft view on Substrate
• Link to parity.io/substrate
• How to Contribute: github.com/paritytech/substrate#contributing
• How to report an issue or provide feedback: github.com/paritytech/substrate/issues
• Discuss your project on Parity's Forum
• Bug Bounty Program: https://www.parity.io/bug-bounty
• Missing a Feature? Check out our roadmap on GH/ announcements (parity.io/blog)
• Community:
  • StackOverflow // Ask a question
  • Follow us: Twitter, Reddit, Github

Introduction P1/P2

1. What is Substrate -> condense https://medium.com/paritytech/what-is-substrate-29af4231d7e0 P1
2. How it works - wasm runtime + rust environment P1
3. When to use and not use Substrate? P2
   • How to decide, what should be implemented in runtime and what not
   • What parts are optional and what parts are expected to be implemented by the user
4. What parts are optional and what parts are expected to be implemented by the user

Examples P1

1. Recipes (reorganize)

2. Sample Apps & Runtimes

   • ERC20 - @gautamdhameja
   • ERC721 - @shawntabrizi
   • TCR - @gautamdhameja
   • CryptoKitties - @shawntabrizi

3. UI Interaction Patterns

Concepts P2

1. Architecture
   • How runtime interacts with the outer code
   • Asynchronous model, futures, tasks, etc as it is used in the Substrate
   • Lifecycle of a transaction from network to storage, how a block is imported - @joepetrowski
   • entry points
   • consensus
   • executor
   • network
   • runtime
   • service
2. Substrate primitives & core data types
3. Layers of abstraction - bare bones, runtime modules (SRML), Node
   a. Core (including consensus)
   b. SRML (brief overview of what is SRML)
   c. Substrate Node
4. Compilation - WASM (without std) and rust (with std)
5. Macros & Entry points(Full in-depth coverage of Substrate macros and module entry points)
   • impl_stubs!
   • construct_runtime! - @shawntabrizi - #1288
   • decl_apis!
   • decl_module! (WIP by @0x7CFE) - @shawntabrizi - #1288
   • decl_event!
   • decl_storage! - @shawntabrizi - #1288
   • impl_outer_origin!
   • impl_outer_dispatch!
   • impl_outer_event!
   • impl_outer_inherent!
   • impl_outer_config!
   • impl_outer_log!
   • Call (module level)
   • PrivCall (module level)
   • Call (dispatch level)
   • PrivCall (dispatch level)
   • aux

Runtime Tutorials P1

1. Quick start (we already have one)
2. Usage
3. Guides
4. Bonds UI
   • When should I use this vs Polkadot UI?
5. Polkadot API + Apps UI
6. Macros
7. Rust Playground
8. Local Node detection, kitty image generation before them creating ui
9. Advanced UTXO Tutorial
10. Production Deployment
11. IPFS
12. Storage Upgrade
13. Node Configuration
14. Dedicated Front End
15. Upgrade Single Page

Tutorials for Polkadot P3

1. Prerequisites to make your Substrate chain compatible with Polkadot
2. Porting your Substrate chain to Polkadot (parachain)
3. Bridging your Substrate chain to Polkadot
4. Inter-chain communication

Reference P2

API

Overview of Substrate API.

CLI

Overview of the Substrate CLI (commands and scripts)

SRML

In-depth overview of each SRML module that ships with Substrate

• example (see this first)
• assets - @ltfschoen
• balances
• consensus
• contract
• council - @ltfschoen
• democracy - @ltfschoen
• session - @ltfschoen
• staking - @ltfschoen
• timestamp
• treasury
• How to build your own SRML module

Primitives (Types and Traits)

• *::Trait
• *::Service
• HasPublicAux
• bft::Environment
• bft::Proposer
• BlockBuilder
• Specialization<B>
• Encode / Decode (Codec)
• Executive

Glossary

• Glossary

Documentation from code-comments (RUSTDOCS) wait for release on docs.rs

Not-released yet: https://crates.parity.io/substrate_service/index.html

FAQ

Generated from questions in the discussion section or custom FAQ
https://substrate.readme.io/discuss?isFAQ=true

Changelog/Release notes P2

• initially just link to GH release page

Storage type

Democracy Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Architecture of a Runtime Overview

decl_event

construct_runtime

documentation: transaction lifetime sequence diagram

I propose a documentation diagram to understand what happens with a transaction within substrate.

After a discussion below #1789 I'll be adding single diagrams per issue over here.

please consider using this diagram for substrate docs.

Support tools for SRML

In modules folder there is a support folder which needs documention

SRML Documentation Template

We need to create a markdown template for SRML documentation

MUST: Include all of these sections/subsections

Overview

• short description of module purpose
• links to [Traits], [Call], [Module]

standard format (example):

The timestamp module provides functionality to get and set the on-chain time.

See also: [Trait] [Call] [Module]

Interface

Dispatchable

MUST: Have link to Call enum
MUST: Have origin information included in function doc
CAN: Have more info up to the user

Public

up to writer for respective module (wrt how much information to provide)

Usage

Prerequisites

necessary imports

Simple Code Snippet

Example from SRML

Genesis Config

Related Modules

bulleted list to other modules (maybe one sentence)

References

Bonded Token Tutorial

As per the call earlier today I'm opening an issue to track the tutorial I wrote about bonding curve tokens as a Substrate runtime module. All the code compiles and is complete through a minimal token which is minted / burned from a bonding curve. The implementation could be expanded and the tutorial leaves off before describing the UI portion (the UI code is available in the repo and should be able to be started by following the quickstart). Right now, I don't have any definite plans to finish the UI part but if it turns out to be a priority, can definitely do that.

Another idea was to possibly include the code into the party-samples organization, which is something we could do too.

Link to code repository

Link to tutorial

Vision for Substrate 1.0 Docs

I believe effective documentation tells a story, and makes it clear to the user the story we are telling. Documentation which tells a story tends to be concise and has limited redundancy, whereas individual pages on different topics may repeat the same shared content over and over. Finally, if a user understand the story we are trying to tell, they should be better able to navigate through our docs on their own "mental table of contents", allowing them to find content more quickly.

The Story

For the Substrate 1.0 release we should be loud and proud of what seems to be the most accessible and well established part of Substrate: Runtime Development.

Hypothesis: The largest audience of users to use Substrate will not be looking to make changes to Substrate Core, rather they will keep most things the same, and only change the Blockchain Runtime, either by adding/removing SRML elements or creating their own custom runtime modules.

With that in mind our documentation should tell two stories:

• How to build a Runtime Module
• How do the SRML modules work and work together

How to build a Runtime Module

To build a runtime module the user may need to understand the following:

• Architecture of a Runtime

  • Based on something like this needs to be worked on a lot:
  • 

• Best Practices for Runtime Module Development

  • How is it different than smart contract development
  • Dos and Do Nots

• High Level Macros Used

  • decl_module
  • decl_storage
  • decl_event
  • construct_runtime

• High Level Types Used

  • Module, Call, Origin, Inherent, Storage, Config, Event, Log

• Common Patterns/Recipes

How do the SRML Modules Work and Work Together

A user will need to understand how the individual SRML modules work and work together in order to correctly use them in their runtime.

At a high level, each module should have a document explaining:

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Our goal should be to present the information needed so that if a user wants to just pick from an available set of modules, they can make the correct decisions for their needs, and understand what decisions they have made for their blockchain. Furthermore, if a user wants to modify a subset of modules, they will be able to do so without adversely affecting untouched modules.

For example: Introduce a modified Balances module, without hurting Staking, Fees, etc...

Lower Priority Docs

We should, for the purposes of achieving these goals, avoid too much effort on other topics which do not directly contribute to these two goals.

Topics which we may be able to write about, but may be a more "advance" topic are good examples of things we probably can focus on after the v1 release date.

For example:

• Consensus and Consensus Upgrades
• Transaction Queue
• Database Stuff
• Networking Stuff
• Smart Contracts
• Polkadot Parachain details
• etc...

Upgrade Key Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Consensus Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Organize, Refactor, and Add Runtime Recipes

This item should be broken down into multiple new issues.

• Needs someone to think about whether we should have all recipes on the same page as it is now, or start to break things up and organize them

• Need to make sure that all recipes are consistent and self-sufficient to run

• Need to think about other recipes which should be included

Metadata in SRML

Metadata in the SRML is the final layer between the blockchain node and the underlying JavaScript APIs allowing you to call into the Runtime.

Users who want to learn more about the SRML will probably want answers to the following:

• How is the metadata generated?
• What is the general structure of the metadata, and what information can I find in it?
• How can I fetch the metadata via a raw RPC call (metadata endpoint)? (or something low level)
• How is the result of the metadata endpoint encoded, and how do I decode it?
• Can I add additional information to the metadata using Substrate?
• (Edit to add other questions we should answer)

These questions should be indirectly answered via two forms of documentation:

• Reference documentation for the srml-metadata crate in the srml folder of Substrate.

  • These are low level docs for the crate. First check if they exist already. If they do not, you should try your best to write the docs if you understand the code, otherwise, leave it to the developers who wrote the code and ping them that we need to update the docs.

• Substrate Developer Hub Docs

  • This doc should wrap together the various docs around Substrate types, which all point to generating some information for the metadata.
  • This doc should also update the architecture of a runtime doc to add a layer between construct_runtime and the JavaScript APIs.

decl_storage

Example Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Session Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Call type

Assets Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Indices Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Staking Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Origin type

Executive in SRML

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Sudo Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

documentation: full client components

The following draw.io diagram shall give an overview over full client components and the usage of native/wasm

improves #578

Runtime architecture

Create table of contents for a developer story.

Treasury Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Improve UX when navigating between docusaurus, rustdocs, recipes, kitties, etc

• What will it feel like to have a user jump to a different page to see documentation that we are keeping with the source code
• Are there things we can do to minimize confusion and maximize discoverability
• Is there some format we need to follow with our direct links so that redirects do not break and do not become stale with updates

Aura Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Contract Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Balances Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

decl_module

Substrate VSCode/Sublime snippets plugin

With the current rush on docs this is no priority but something that has been on my mind for a while:

• Assuming that VSCode is the editor of choice for most rust devs:
• VSCode + RLS has relatively good support for rust projects with auto-imports, Intellisense, and inline error report. If the project is huge it takes a while to compile under the hood and get the errors but no complaints here.
• All of this breaks the minute you start working on any sort of SRML/macro-generated code. All that you get is the fuzzy auto-completion that just comes from inspecting the file and guessing.
• The least we can do here is to create a snippet plugin for edits to make some of the SRML syntax which is eccentric auto-generated.
• Ideally, the rest of the features (intellisense, auto-import, peek definition, peek function signature etc.) might also be fixable.
• I assume since the scope here is SRML-specific syntax (macro magic as @shawntabrizi calls it), RLS or any rust related tool will never help.

Council Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

rustdoc docs generator for master & all Substrate versions released on crates.io

docs.rs (https://github.com/rust-lang/docs.rs) has a nice UI and supports versioning, unfortunately they don't host docs for master (only for versions released on crates.io).

Log type

Update all documentation to use `decl_dispatch`

Substrate has renamed the decl_module macro to decl_dispatch:
paritytech/substrate#1960

We need to update all documentation accordingly.

Process for adding documentation

JOE EDIT:

I propose the following review process to improve and speed up the review process:

1. Get review from person who wrote the code. Make sure the documentation is accurate.
2. Get review from another person in the docs team. This person should (a) get a clear understanding of the module by reading your documentation and (b) review the code to ensure that the code matches his or her interpretation of the doc.
3. Get review from me for style and grammar. This will keep our docs consistent.
4. Get review from Gav. Before this step it should be ready to merge.

---

SHAWN EDIT:

I have created the following documentation types. They should represent the kind of document that should be produced:

• T0 - Overview
• T1 - Reference
• T2 - Page
• T3 - Sample
• T4 - Tutorial
• T5 - Planning (Not a real doc, just planning internally)

I have created the following documentation subjects which should represent the material in the documentation produced:

• S0 - Concept
• S1 - Macro
• S2 - Types and Primatives
• S3 - SRML
• S4 - Smart Contracts
• S5 - Polkadot
• S6 - API
• S7 - CLI

We can of course add more and modify them if needed, but I think this pattern should be good. Nearly every issue in this developer hub should have one of each tag type

---

ORIGINAL POST:

I would like to propose the following process for adding documentation in this repo,

• Create an issue with the documentation item title and a brief description. Ideally, choose a high priority one from the Overview and Tracking list.

• Add one or more of the following tags to the issue,

Tags for content categories

Core, SRML, Tutorial, Sample, Overview, Polkadot, Reference

The content category tags can have sub-tags for specific topics, for example,
(the following list is not exhaustive)

Macros, API, CLI, Types and Primitives, Smart Contracts

Primarily, the idea of adding tags and sub tags is to help identify the content for the potential reviewers so that they can review as per their focus areas.

Tags for status

Todo, InProgress, ContentComplete, InReview, Reviewed, Published

• Write your documentation in markdown using any of your favourite editors/tools (eg: hackmd.io).
• Update the issue with the documentation link and add the tag ContentComplete once you have finished writing your document.

Add link to parity-samples repo

Timestamp Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

System Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Grandpa Module

Custom Documentation:

• The purpose of the module
• Explanation of the real world users and their role/interactions with the module
• Key logic, processes, or assumptions that happen within the module
• Details on how a module easily integrates with other associated modules

Rust Docs:

• Available storage items and what they hold
• Public Functions
• Internal Functions

Module type

Inherent type

Dos and Do Nots of Runtime Module Development

This might need to be more than one page, and would need someone to come up with a larger plan on what content will be here, and how we will present it