1. Under the Module Menu section, I want to include more of the examples in the existing module documentation (the root file for each SRML module)

2. I want to demonstrate implementations for more traits in srml_support to show how to abstract out the SRML logic into stand-alone Substrate runtimes.

(1) and (2) should probably be in the same section.

there's a few links, like the one in intro/motivation to Gautam's TCR tutorial that point to the old substrate website; also advanced/safety recipe links to Gautam's best practices

I am following this tutorial.

./scripts/init.sh works fine.

When I try to run cargo build --release, I get this error.

error: failed to select a version for `substrate-client`.
    ... required by package `super-runtime v2.0.0 (/Users/dhruvinparikh/blockx-labs/recipes/kitchen/runtimes/super-runtime)`
    ... which is depended on by `kitchen-node v2.0.0 (/Users/dhruvinparikh/blockx-labs/recipes/kitchen/node)`
versions that meet the requirements `*` are: 2.0.0

the package `super-runtime` depends on `substrate-client`, with features: `std` but `substrate-client` does not have these features.


failed to select a version for `substrate-client` which could resolve this conflict

Language Accessibility

• Spanish
• Portuguese
• Chinese
• Korean
• Japanese

• start configuring node template in kitchen with permutations of example modules
• show build status (for each module) + a description on the kitchen README

Mechanisms for generating randomness offer varying levels of security/cost. Random seed is inexpensive but not very secure; VRFs are more expensive and more secure. Likewise, a recipe on randomness should guide developers based on the requirements of their application to navigate this tradeoff between runtime cost and security requirements...

• randomness module PR
• wip recipe

NFT Ticket Machine

initially described in #42

Basically, make a prototype of mintbase or kickback using the Substrate Collectables Workshop (kitties v2).

Consider using IPLD data structures in the context of NFT standard fields?

Add to list/Double Map

Then the App pretty much stuck...

I think we can:

1. by default comment out all additional modules, and introduce the necessary type definition to make the module code with polkadot-JS Apps. Have one section teaching readers to add type def. in polkadot-JS Apps

2. Have a big blob of type at the end of ch3 and ask readers to add to the type def. in order to interact with the module code from the Apps.

Gamify to make the recipes more interactive. Probably via a custom mdbook backend?

Rust Quiz

Ethernaut

This topic came up during SCL today.

Some possible example scenarios.

A transaction should only be valid:

• after a certain block height
• before a block height
• after/before a timestamp
• in blocks with an even height
• in blocks with an even hash

This solid OffChain Workers explainer by Gautam has got me thinking about how storage patterns will change as things improve.

I want to eventually do an explainer on optimizing storage by keeping most data off-chain -- and combine this with a tutorial on properly using off-chain workers.

We discussed this once briefly with @shawntabrizi in person.

Briefly said: create a simple runtime which is a collection of

All the things that you should NOT do
All the things that could go wrong, will go wrong.
(bonus) Demonstrate how you reach a corrupt state or fault or exploit etc.

Some ideas quickly:

• float
• vec which is appendable, for free, by user.
• write then check
• panic if corrupted data.
• change data type via an upgrade (not sure how it can be faulty but worth investigating)

PR 3000

Still Researching This...

• start with Shawn's blog post on sudo

In srml/system/src/lib.rs, there is a circular buffer pattern that seems useful. *note that you can also use vec_dequeue

decl_storage {
  /// Series of block headers from the last 81 blocks that acts as random seed material. This is arranged as a
		/// ring buffer with the `i8` prefix being the index into the `Vec` of the oldest hash.
		RandomMaterial get(random_material): (i8, Vec<T::Hash>);
}
...

fn initialize {
<RandomMaterial<T>>::mutate(|&mut(ref mut index, ref mut values)| if values.len() < 81 {
			values.push(parent_hash.clone())
		} else {
			values[*index as usize] = parent_hash.clone();
			*index = (*index + 1) % 81;
		});
}

This is useful when you need to maintain a finite size set that requires replacing old elements with new data as the blockchain grows (which seems like an obviously useful pattern, especially for block explorers).

@JoshOrndorff @4meta5 You will run into an issue very quickly where there is a hard-coded limit of 30 modules in a runtime from Substrate core.

It may make sense to list every module in the construct runtime as "commented out" with instructions for the user to enable the "up to 30 they would want to test"

Originally posted by @shawntabrizi in #52 (comment)

After reading ch4.1, from a new-comer perspective, yes, I would be able to build the module, but then how do I play with the module I have just built? How could I make it run on a chain?

Maybe between ch 3 & 4, add a section documenting how to integrate the module-template into node-template, start up the chain, and then using polkadot UI connecting to our locally-running node, and play with it.

@4meta5
I was contemplating adding this for a while, but preferred just linking to other tutorials that walk through this process...it would be great to have it in the recipes though in a succinct, generic form so that people could use it as a reference like the rest of the recipes

@shawntabrizi
would you think it is worthwhile to add a section about this?

Res:

• https://substrate.dev/substrate-collectables-workshop/#/0/running-a-custom-node

getting two errors when I compile kitchen/runtimes/super-node-runtime && kitchen/runtimes/super-node-genesis

error[E0432]: unresolved import `babe::SameAuthoritiesForever`
  --> /Users/4meta5/core/recipes/recipes/kitchen/runtimes/super-node-runtime/src/lib.rs:20:35
   |
20 | use babe::{AuthorityId as BabeId, SameAuthoritiesForever};
   |                                   ^^^^^^^^^^^^^^^^^^^^^^ no `SameAuthoritiesForever` in the root

error[E0437]: type `EpochChangeTrigger` is not a member of trait `babe::Trait`
   --> /Users/4meta5/core/recipes/recipes/kitchen/runtimes/super-node-runtime/src/lib.rs:206:2
    |
206 |     type EpochChangeTrigger = SameAuthoritiesForever;
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not a member of trait `babe::Trait`

error: aborting due to 2 previous errors

This type exists and is a member of babe::Trait so I don't know why I'm getting this error. @JoshOrndorff do you know?

EDIT: This is worked around by #64 on master, but it remains a mystery, but the babe code in this module only compiles when it is mismatched with the code on upstream Substrate.

patterns/recipes

• module instancing in collective -- PR 3041 (and balances)
• special origin type in collective => reference polkadot EnsureParachain
• floating point arithmetic in inflation.rs in staking -- PR 3048, 2882

Governance Walk Through (put drafts in book and migrate to substrate.dev/docs)

• kusama genesis config (and genesis configs in general)
• phragmen in staking
• inflation in staking
• treasury => reference parachain para_id "factory"
• collective + elections => council
• scored membership
• generic asset

To strengthen the link between the recipes and the kitchen, I want to place buttons at the top of each recipe with

• link to code in kitchen
• link to build in travis CI

Also,

• place links to all builds at the root of the kitchen

see the hook branch for the fix

https://github.com/substrate-developer-hub/recipes/tree/master/kitchen/random

will close this issue once hook is merged into master

One nice way to experiment with the modules and runtimes in the recipes would be by depending on the from Cargo.toml For example, when I created a node to house the super-node-runtime (drafted here) I used this line in Cargo.toml

[dependencies.node-template-runtime]
path = "../recipes/kitchen/runtimes/super-node-runtime"

It would be nicer to use

[dependencies.node-template-runtime]
git = "https://github.com/substrate-developer-hub/recipes.git"
branch = "master"

I believe this can be achieved through cargo workspaces https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html

@4meta5 Is this something you're interested in having? If not feel free to close this issue.

On the Storage Recipes/Single Value section (https://substrate.dev/recipes/storage/value.html), at the very bottom, there's a paragraph about Substrate Specific Types. It only says that "to access the Substrate types Hash, AccountId, and Balance, it is sufficient to inherit the balances module". Ideally, it should demonstrate how to access these types using the system module, instead of requiring users to use the balances module.

• mem::replace to change enum values in place

I'm keen to experiment with OSS incentives beyond just listing github handles on the README (though that might be sufficient; I acknowledge that overdoing it with incentives is worse than basic recognition)

Brainstorming

1. Gitcoin or Bounties Network, but I don't really have the funds ATM...
2. Harberger Ad board with rent issued according to contributions; this could be attractive to projects working on Substrate -- they abstract out patterns from their project, PR them here, and then achieve temporary advertising to attract OSS contributions to their project
3. Establishing an Aragon DAO to manage this repo with voting rights issued according to contributions

For (1), I could set up a DAO like MolochDAO (or soon SunshineDAO) to accept donations, issue proportional voting rights, and fund grants for specific recipes. As a reminder, grant funding is voted on by the donors that choose to request shares (and shares provide the voting rights).

The problem with (2) and (3) is that weighting the value-add of contributions is extremely subjective. I still don't think this means we can't experiment!

• similar to this recipe but explain spend_funds method in context of T::SpendPeriod::get()
• use of Imbalances type
• use of OnDilution type

more?

extending treasury to accept grant applications (based on this)

Resources:

• https://stackoverflow.com/questions/57410932/
• open-web3-stack/open-runtime-module-library@3d0a8a2

Just tried following instructions to run a kitchen node.
https://substrate.dev/recipes/base/runnode.html

However seem to get the following error when running cargo build --release

Error:

araa@MAC127 ~/Desktop/recipes/kitchen/node (master) (₿) cargo build --release
    Updating git repository `https://github.com/paritytech/substrate.git`
    Updating crates.io index
error: no matching package named `srml-babe` found
location searched: https://github.com/paritytech/substrate.git
required by package `super-runtime v2.0.0 (/Users/araa/Desktop/recipes/kitchen/runtimes/super-runtime)`
    ... which is depended on by `kitchen-node v2.0.0 (/Users/araa/Desktop/recipes/kitchen/node)`

This is a subtle difficulty when working with computers. Floating point arithmetic is nondeterminisic so the basic approach is to use a wrapper type that represents either 1_000_000 (Permill) or 1_000_000_000 (Perbill) times the given floating point value.

I've learned recently that this can get messy. I think it's worth doing a recipe on this.

• Permill in docs

• StackOverflow Question

• Fixed64

loosely coupled module examples in kitchen/runtime/; the super-runtime from #52 does the job at the moment (#29) so this isn't a priority unless someone wants to add it

Something like @JoshOrndorff 's state-changer or marketplace would be useful for demonstrating runtime configuration in practice with only a few modules.

The justification is that developers might start with one module for an MVP and then gradually abstract certain behavior out into separate modules which still need to be configured in one runtime.

The current testing section is lacking...create separate issues for each of these ideas once I actually decide to pursue them individually.

Soon

• Alternative Test Scaffolding Pattern(s)
• Unit Testing

In the Pipeline

• Error Handling::{error_chain, failure}
• Model-Based Testing::{model, proptest, quickcheck}
• Fuzzing
• Benchmarking

Resources

Follow progress on substrate-developer-hub/substrate-developer-hub.github.io#81

using conditional compilation to reduce code duplication

Possibly Bundle With...

• procedural macros:: {when is it appropriate to use #[compact], #[derive(Encode, Decode)]}
• if_std! macro for debugging even if code doesn't compile with no_std
• customization of ensure_signed (systems)

We've agreed in riot that running CI over the modules (and eventually the runtimes and the node) is a good idea. Even before runtime tests are written for the modules, we can at least use CI to ensure they build.

Options for CI pipeline and their strengths are
Travis -- Already used for mdbook portion of recipes
Circle -- Already used by this team for devhub and frontend template
Github actions -- No 3rd party service needed. All stays here in github.

• stop abusing clone with put_ref from PR 3041
• append and len from PR 3071

Runtime configuration is something that the book ignores thus far, but module development only makes sense in the context of a Substrate runtime. So, it is necessary to add a new section called Runtime.

• super runtime (kitchen/runtimes/super-runtime)
• node for runtimes (kitchen/node)

• shawn's blog post

• block action quota in proportion to posted collateral and the action in question (see transaction weight macro)

storage/list/linked_map heading

WHAT ARE THE RECIPES? I envision the recipes as similar to Rust by Example, but for Substrate. The purpose is to provide examples of Substrate runtime patterns through minimal samples. Each sample might only take up a single page in the book, but the point is to demonstrate common patterns and application in the context of an example.

TLDR; each recipe should fulfill two objectives:

• demonstrate Substrate runtime best practices (full code should be tested and placed in kitchen/)
• show the usefulness of the pattern in the context of an example

motivation:

While some developers complete tutorials chronologically, many prefer to skim tutorials for usage examples and apply patterns to build a personal project. For these developers, it is useful to have something like Rust by Example to reference while building. By not requiring the developer to read previous sections for continuity, this format is convenient in the context of fast prototyping based on common design patterns.

If done well, this format can

1. provide high signal to noise for mature developers building on Substrate
2. reduce the friction to publish high-level explanations for code in the SRML

The 2nd objective is especially relevant. I want to minimize the friction for converting personal notes into recipes for teaching others. Moreover, I want to target the creation of specific content pertaining to the most well-vetted code that uses the Substrate Runtime API, the SRML.

srml-tour

With @JoshOrndorff 's blessing, I want to create a section similar to srml-tour for the recipes. I think this fits what I view as the purpose of the recipes: a space to share high-level explanations of SRML code and API usage examples for building runtimes.

criteria

The structure of each recipe should be oriented around the patterns and use cases it exposes. Even so, in general, each recipe should be a single page explainer to communicate how the code in certain module(s) maps to the web3 research specs. Each post should do the following

• motivate study of the chosen module(s) (possibly in the context of Polkadot)
• explain how objects/relationships are modeled and how this influences the implementation
• extract any useful patterns and discuss examples for usage in other runtime samples

priorities

• treasury, especially because of this
• democracy, already partly finished by @JoshOrndorff

• collective + elections as the council
• support/phragmen => elections + staking
• staking because it contains inflation which is interesting paired with treasury and demonstrates fixed point arithmetic

future recipes/sections?

lots of V2 patterns to be covered...

• fixed point arithmetic, see 3456, 3189
• runtime module configuration, see 29
• testing and error handling => not lengthy docs, but succinct tips and short examples of scaffolding (3433 and 3479)

all getter functions now are preferred to be pub Foo get(fn fee): u32 = 10u32;

The context of the off-chain workers API is after finalize for block X, but before initialize for block X+1; run in the context of the last block untouched.

archaeology

• https://substrate.dev/docs/en/next/overview/off-chain-workers#docsNav
• oracle (motivating) issue - pr 1942
• api stubs - pr 2615
• capabilities filtering for off-chain runtime calls - pr 3454
• example
• move delegation voting off-chain: pr 1827

paritytech/polkadot#309

To deal with a subtraction overflow, Kian used an interesting pattern in the calculation of a transaction fee multiplier; it is worth reviewing for other people that may come across the same problem. The naive solution would be to use a signed integer instead of an unsigned one, but this is even cleaner:

let diff = match ideal.checked_sub(all) {
			Some(d) => d,
			None => { positive = true; all - ideal }
};

Basically, if it didn't work, we reversed the order of computation, then subtracted the term instead of added it. We could tell if it needed to be substracted by the value of positive = all > ideal.

make a separate issue for each of these if/when pursued

• proof of existence (shawn's example)
• off-chain storage section in Storage (could include caching, database interaction, etc)
• cryptography (2phase commit, blind auctions, hashing data, zk stuff, extra layers of encryption e.g. PRE)
• private network setup (by Josh and Gautam)
• rust-unofficial patterns in the context of Substrate samples?

Demonstrate usage of trie storage structure in the context of a minimal example

Rob: "What we're doing there is storing the root of another trie under a key in the main trie. Since keys are typically hashed in the main trie, it's a fairly convenient (although not the only) way to make sure that inserting many elements under a single mapping does not make your typical lookup path for unrelated elements longer."

• might reference specialized usage in crowdfund
• dependent on paritytech/substrate#2209
• paritytech/substrate#3421
• substrate-developer-hub/substrate-developer-hub.github.io#255

cc @shawntabrizi

High-level overview of how srml-democracy coordinates the public referenda for Substrate-based governance. Might be useful to discuss conviction voting and the Approved trait for setting vote thresholds.

• original srml-tour democracy

Feel free to discuss how we could edit the VoteThreshold struct and still match on it to add more thresholds and, therefore, change the number of outcomes or the weighting of the voting algorithm itself. Then, how could the network be elegantly governed through this upgrade?

criteria from #32

The structure of each recipe should be oriented around the patterns and use cases it exposes. Even so, in general, each recipe should be a single page explainer to communicate how the code in certain module(s) maps to the web3 research specs. Each post should do the following

• motivate study of the chosen module(s) (possibly in the context of Polkadot)
• explain how objects/relationships are modeled and how this influences the implementation
• extract any useful patterns and discuss examples for usage in other runtime samples

how to choose which hash function to use for double_map and/or other things in the srml

• what are the options
• when is each option preferred (associated tradeoffs)

I will live stream the creation of all the recipes using v2.0 of Substrate.

Here is a starting list of ideas to create; organization TBD:

• type-conversions

  • Balance to u64
  • Moment to u64
  • AccountId to Hex/Public Key
  • more?

• Custom Types (multiple projects)

  • enum
  • struct

• Limiting Vec input size

• Two Modules Interacting

• Static Getters (rather than using storage) and exposing it in metadata

• All storage types

  • StorageValue
  • StorageMap
  • LinkedMap
  • DoubleMap

• Creating Origins, using all origins

• Runtime Hooks

• [ ]

• [ ]

As a suggestion, it may be useful to explicitly mention the necessary changes to lib.rs for each recipe. That way, readers can follow along personally with the code snippets.

Example: In this page (https://substrate.dev/recipes/storage/constants.html), it could show something like:

parameter_types! {
	pub const Number: u32 = 5;
}

/// Used for the module template in `./template.rs`
impl template::Trait for Runtime {
	type Event = Event;
	type Number = Number;
}

This is just a suggestion, but it may make sense to have this content migrated to Docusaurus.

@4meta5, are there advantages to using RustDoc for these recipes?