linking better to existing docs/tutorials

.gitignore

@@ -1,8 +1,7 @@
 # todos are scattered in these files
 k.md
 # to be made into a larger PR for Substrate soon
-vision.md
-todo.md
+v002.md
 **/*/drafts/
 **/*/*/drafts/
 

CONTRIBUTING.md

@@ -1,23 +1,38 @@
 # Contributing Guidelines
 
-**Recipes are not entire tutorials -- they are small patterns that may be extracted from tutorials**. The purpose of Substrate Cookbook is to identify best practices in Substrate runtime code and extract patterns that are useful outside of the context of the specific use case.
-
-1. isolate specific pattern
-2. walk through logic in piecewise steps
-3. show/link to the full file in the used codebase
+The **purpose** of [Substrate Recipes](https://substrate.dev/recipes/) is to identify best practices in Substrate runtime code and extract useful patterns.
 
-If you want to get involved, feel free to open an [issue](https://github.com/substrate-developer-hub/recipes/issues/new) with any ideas/comments/questions.**The markdown for each recipe can be found by following the paths set in [SUMMARY.md](./src/SUMMARY.md)**.
+* [Scope and Structure](#scope)
+* [Getting Involved](#involve)
+* [Mdbook Local Build Instructions](#instructions)
+* [Etiquette](#etiquette)
 
-I'm going to spend more time working on samples over the next few weeks, but I'm in the process of improving this project as well.
+## Scope and Structure <a name = "scope"></a>
 
-## Common Etiquette
+At the moment, the recipes onboards developers by focusing primarily on **module development** patterns before reusing these patterns in the context of **runtime configuration** (runtime section is *in-progress*).
 
-* try to not use "we" or "our" because it often is conducive to unnecessary language
-* frequently link to outside content ie original code, blog/tutorial references, documentation for a specific method/trait/etc
+The **[kitchen](./kitchen)** contains code from the recipes in the context of modules/runtimes, while **[src](./src)** houses the commentary for related explanations and references. The structure of the `src` can be found in [src/SUMMARY.md](./src/SUMMARY.md).
+
+In practice, the recipes supplements existing resources by providing usage examples, demonstrating best practices in context, and extending simple samples/tutorials. Likewise, it is necessary to **frequently link to/from [reference docs](https://crates.parity.io/substrate_service/index.html?search=srml), [tutorials](https://github.com/substrate-developer-hub/), and [high-level docs](https://substrate.dev/)**.
+
+The recipes do NOT cover:
+* module testing
+* rpc, cli, and other [`node/`](https://github.com/paritytech/substrate/tree/master/node) stuff outside the runtime
+* frontend UI
+* protocol engineering (consensus, networking, etc.)
+
+If you're interested in adding new chapters for any of these sections, [create an issue](https://github.com/substrate-developer-hub/recipes/issues/new) and convince us :)
+
+## Getting Involved <a name = "involve"></a>
 
-## Local Build Instructions
+1. isolate useful pattern (in [`issues`](https://github.com/substrate-developer-hub/recipes/issues))
+2. build a module/runtime example with context (in [`kitchen`](https://github.com/substrate-developer-hub/recipes/tree/master/kitchen))
+3. walk through logic of useful pattern in piecewise steps (in [`src/`](https://github.com/substrate-developer-hub/recipes/tree/master/src))
+4. link `src` and `kitchen` (in [`src/`](https://github.com/substrate-developer-hub/recipes/tree/master/src)) 
 
-Stage locally before making a PR. Don't forget to switch to a new branch before you make edits.
+## Local Build Instructions <a name = "instructions"></a>
+
+**Stage locally before making a PR.** Don't forget to switch to a new branch before you make edits.
 
 1. install [`mdbook`](https://github.com/rust-lang-nursery/mdBook)
 
@@ -31,4 +46,11 @@ $ cargo install mdbook
 $ mdbook build --open
 ```
 
-3. If everything looks good, open a [Pull Request](https://github.com/substrate-developer-hub/recipes/compare)
+3. If everything looks good, open a [Pull Request](https://github.com/substrate-developer-hub/recipes/compare)
+
+## Etiquette <a name = "etiquette"></a>
+
+* don't use "we" or "our" because it often is conducive to unnecessary language
+* use active voice (instead of passive voice ie "you may want to use active voice")
+* frequently link to outside content ie original code, blog/tutorial references, documentation for a specific method/trait/etc
+* **be nice, abide by the [Rust CoC](https://www.rust-lang.org/policies/code-of-conduct)**

kitchen/random/src/lib.rs

@@ -1,9 +1,15 @@
+/// Generating randomness with weak entropy
 #![cfg_attr(not(feature = "std"), no_std)]
+#![recursion_limit = "128"]
 
 use primitives::{ed25519, Blake2Hasher, Hasher, H256};
+use primitives::{Blake2Hasher, Hasher};
 /// Generating Randomness example(s)
 use support::{decl_event, decl_module, decl_storage, dispatch::Result, ensure, StorageValue};
 use system::ensure_signed;
+use parity_scale_codec::{Encode, Decode};
+use support::{decl_event, decl_module, decl_storage, StorageValue, dispatch::Result};
+use system::{self, ensure_signed};
 
 pub trait Trait: system::Trait {
     type Event: From<Event> + Into<<Self as system::Trait>::Event>;
@@ -20,21 +26,36 @@ decl_module! {
         fn deposit_event() = default;
 
         fn weak_entropy(origin) -> u32{
+        fn use_weak_entropy(origin) -> Result {
+            let _ = ensure_signed(origin)?;
+
+            let random_seed = <system::Module<T>>::random_seed();
             let nonce = <Nonce>::get();
             let new_random = (<system::Module<T>>::random_seed(), nonce)
+            let new_random = (random_seed, nonce)
                 .using_encoded(|b| Blake2Hasher::hash(b))
                 .using_encoded(|mut b| u64::decode(&mut b))
                 .expect("Hash must be bigger than 8 bytes; Qed");
             let new_nonce = <Nonce>::get() + 1;
             <Nonce>::put(new_nonce);
             Self::deposit_event(RawEvent::RNGenerate(new_random));
             new_random
+            Self::deposit_event(Event::WeakEntropy(new_random));
+            <Nonce>::put(nonce + 1);
+            Ok(())
         }
     }
 }
 
 decl_event!(
     pub enum Event {
         RNGenerate(u32),
+        WeakEntropy(u64),
     }
 );
+
+decl_storage! {
+    trait Store for Module<T: Trait> as Ranodom {
+        Nonce get(nonce): u64;
+    }
+} 

src/README.md

@@ -1,29 +1,27 @@
 # Summary
 
-- [Introduction](./misc/README.md)
-- [Getting Started](./misc/setup.md)
-- [Events](./event/README.md)
-    - [Adding Machine](./event/adder.md)
-- [Storage](./storage/README.md)
-    - [Single Value](./storage/value.md)
-    - [Maps](./storage/list.md)
-    - [Configurable Constants](./storage/constants.md)
+- [Introduction](./base/README.md)
+- [Set Up Substrate](./base/setup.md)
+- [Rust Review](./base/rust.md)
+- [Module Fundamentals](./basics/README.md)
+    - [Adding Machine](./basics/adder.md)
+    - [Single Value Storage](./basics/value.md)
+    - [Maps](./basics/list.md)
+    - [Configurable Constants](./basics/constants.md)
 - [Types and Traits](./types/README.md)
-    - [Collateral Management](./types/collateral.md)
-    - [Nested Structs](./types/structs.md)
-- [Design Patterns](./common/README.md)
-    - [Permissioned Methods](./common/permissioned.md)
-    - [Blockchain Event Loop](./common/loop.md)
-- [Recipes](./recipes/README.md)
-    - [Token Transfer](./recipes/token.md)
-    - [Social Network](./recipes/social.md)
+    - [Currency Type Usage](./types/collateral.md)
+    - [Safety First](./safety/README.md)
+    - [Robust Path Handling](./safety/paths.md)
+    - [Fixed Point Arithmetic](./safety/safemath.md)
+- [Examples](./examples/README.md)
+    - [Permissioned Methods](./examples/permissioned.md)
+    - [Scheduling Runtime Tasks](./examples/loop.md)
+    - [Automated Token Issuance](./examples/token.md)
+    - [Social Network](./examples/social.md)
 - [SRML Tour](./tour/README.md)
     - [Treasury](./tour/treasury.md)
-- [Advanced](./safety/README.md)
-    - [Declarative Programming](./safety/cop.md)
-    - [Optimizations](./safety/optimizations.md)
-- [Featured Tutorials](./misc/dessert.md)
+- [Featured Tutorials](./base/dessert.md)
 
 -----------
 
-[More Resources](./misc/resource.md)
+[More Resources](./base/resource.md)

src/SUMMARY.md

@@ -1,29 +1,27 @@
 # Summary
 
-- [Introduction](./misc/README.md)
-- [Getting Started](./misc/setup.md)
-- [Events](./event/README.md)
-    - [Adding Machine](./event/adder.md)
-- [Storage](./storage/README.md)
-    - [Single Value](./storage/value.md)
-    - [Maps](./storage/list.md)
-    - [Configurable Constants](./storage/constants.md)
+- [Introduction](./base/README.md)
+- [Set Up Substrate](./base/setup.md)
+- [Rust Review](./base/rust.md)
+- [Module Fundamentals](./basics/README.md)
+    - [Adding Machine](./basics/adder.md)
+    - [Single Value Storage](./basics/value.md)
+    - [Maps](./basics/list.md)
+    - [Configurable Constants](./basics/constants.md)
 - [Types and Traits](./types/README.md)
-    - [Collateral Management](./types/collateral.md)
-    - [Nested Structs](./types/structs.md)
-- [Design Patterns](./common/README.md)
-    - [Permissioned Methods](./common/permissioned.md)
-    - [Blockchain Event Loop](./common/loop.md)
-- [Recipes](./recipes/README.md)
-    - [Token Transfer](./recipes/token.md)
-    - [Social Network](./recipes/social.md)
+    - [Currency Type Usage](./types/collateral.md)
+    - [Safety First](./safety/README.md)
+    - [Robust Path Handling](./safety/paths.md)
+    - [Fixed Point Arithmetic](./safety/safemath.md)
+- [Examples](./examples/README.md)
+    - [Permissioned Methods](./examples/permissioned.md)
+    - [Scheduling Runtime Tasks](./examples/loop.md)
+    - [Automated Token Issuance](./examples/token.md)
+    - [Social Network](./examples/social.md)
 - [SRML Tour](./tour/README.md)
     - [Treasury](./tour/treasury.md)
-- [Advanced](./safety/README.md)
-    - [Declarative Programming](./safety/cop.md)
-    - [Optimizations](./safety/optimizations.md)
-- [Featured Tutorials](./misc/dessert.md)
+- [Featured Tutorials](./base/dessert.md)
 
 -----------
 
-[More Resources](./misc/resource.md)
+[More Resources](./base/resource.md)

src/advanced/random.md

@@ -0,0 +1,24 @@
+# Generating Randomness
+
+Substrate uses a safe mixing algorithm to generate randomness using the entropy of previous blocks. Because it is dependent on previous blocks, it can take many blocks for the seed to change. 
+
+```rust
+let random_seed = <system::Module<T>>::random_seed();
+```
+
+**To increase entropy**, we can introduce a nonce and a user-specified property. This provides us with a basic RNG on Substrate: 
+```rust
+let nonce = <Nonce>::get();
+let new_random = (<system::Module<T>>::random_seed(), nonce)
+    .using_encoded(|b| Blake2Hasher::hash(b))
+    .using_encoded(|mut b| u64::decode(&mut b))
+    .expect("Hash must be bigger than 8 bytes; Qed");
+<Nonce<T>>::mutate(|n| *n += 1);
+<Nonce<T>>::put(nonce + 1);
+```
+
+**also see...**
+* [code in kitchen](https://github.com/substrate-developer-hub/recipes/blob/master/kitchen/random/src/lib.rs)
+* https://github.com/paritytech/ink/issues/57
+
+**[Back to Recipes](https://substrate.dev/recipes/)**

src/misc/README.md → src/base/README.md

@@ -1,6 +1,6 @@
 # Substrate Recipes 🍴😋🍴
 
-Substrate Recipes is a collection of simple code patterns that demonstrate best practices when building blockchains with **[Substrate](https://github.com/paritytech/substrate)**. The repo used to build this book is [open source](https://github.com/substrate-developer-hub/recipes) and [open for contributions](https://github.com/substrate-developer-hub/recipes/blob/master/CONTRIBUTING.md).
+Substrate Recipes is a collection of simple code patterns that demonstrate best practices when building blockchains with **[Substrate](https://github.com/paritytech/substrate)**. The repo used to build this book is [open source](https://github.com/substrate-developer-hub/recipes). Check out the [contributions guidelines](https://github.com/substrate-developer-hub/recipes/blob/master/CONTRIBUTING.md) for an overview of the structure and directions for getting involved.
 
 ## What is Substrate?
 

src/base/rust.md

@@ -0,0 +1,3 @@
+# Intro to Rust
+
+* TODO

src/safety/README.md

@@ -1,4 +1,4 @@
-# Safety and Optimization
+# Safety First
 
 Unlike conventional software development kits that abstract away low-level decisions, Substrate grants developers fine-grain control over the underlying implementation. This approach fosters high-performance, modular applications. At the same time, it also demands increased attention from developers. To quote the [late Uncle Ben](https://knowyourmeme.com/memes/with-great-power-comes-great-responsibility), **with great power comes great responsibility**.
 

src/safety/safemath.md

@@ -1,7 +1,8 @@
-# Safe Arithmetic
+# Fixed Point Arithmetic
 
-* computers are notoriously bad with precision with small numbers
-* link to the inflation section wherein I will discuss some of this stuff
+*computers are notoriously bad with precision with small numbers*
+
+see https://github.com/substrate-developer-hub/recipes/issues/12 for links
 
 ## Perbill and Permill Usage