Shawn: Introduction to FRAME and Substrate

[shawntabrizi]

In Progress

This issue will capture my thoughts on the different topics that an introduction to FRAME and Substrate.

I have explicitly not chosen to look at the existing content, and work from my own experience to compile a list of content that I think should be covered.

---

• randomness
• SCALE
• navigating the folder structure
• client vs runtime
• "blockchain state"

---

need to begin with emphasis on what kind of environment we are working with in the runtime / blockchain:

• extremely constrained memory, storage, computation, etc...
• similar to embedded system
• no access to std, etc...
• immense redundancy and workloads because of decentralized system and verification checking of blockchains

---

need to establish wasm, how it is used, why it is good

• should tie in runtime and contracts
• should touch on alternatives, specifically native execution, risc-v, evm.

---

need to establish the wasm / runtime barrier.

Probably not in detail, but have users already start thinking that they are building some internal logic within a native running client.

perhaps there are parallels to wasm web dev that we can lean on.

---

need to establish many of the basics of blockchains. things i see users have problems with:

• fixed point number representation of balances
• understanding what "data" runtime has access to, for example only the current block, and nothing historical (except if you keep it in the data for current block)
• understanding the blockchains keep history! so no need to save stale data!
• runtime running multiple parallel lives within the forks of a chain. perhaps we can tie it into some kind of marvel multiverse example
• "where" the data lives. Data is not on the blockchain itself. blockchain is just transactions which can be executed to generate the state

---

resource constraints of the blockchain:

• computation limits: gas, weights
• storage limits: block size, archive node size, data availability size
• memory limits: runtime memory, parallel execution, in memory db

---

def SCALE if we did not already cover it in Rust sections.

---

• Metadata deep dive
• how it helps with SCALE containing no context
• what it exposes
• why it needs to be updated occasionally etc..

---

students should feel comfortable with the idea and how forkless upgrades work

• why wasm is critical
• how runtime logic is part of the state transition function
• how transactions can be used to update the runtime

---

an overview of the different parts of a blockchain:

• rpc
• tx queue
• storage
• runtime
• p2p
• etc...

should very much be like anatomy, what the part is, what it does, what it connects to.

---

philosophies of substrate

• modularity
• speed
• saftey

levels of developer interaction

• minimal editing (just chain spec)
• adding / removing pre-built modules
• writing custom modules

---

deep dive into chain spec and configuring it

• initial state
• boot nodes
• etc...

how custom modules can add items to the chain spec

---

runtime upgrades, and what you might need to consider

• how state and runtime must work together perfectly and without errors
• when migrations might be needed

---

Philosophies of FRAME

• most opinionated part of the whole stack
• still trying to be as general as possible
• decisions around weight system
• decisions around panic
• decisions around saftey and that runtime developers are inherently non malicious actors
• decisions around freedom and responsibility
• decisions around dust accounts and account cleanup

---

Basics of the Substrate CLI

• --dev flag, and breaking it down
• chain-spec sub commands
• subkey sub-commands
• various important node cli options

---

We don't cover in the academy, but this is an advance topic: reference counters.

not really something that we need users to know, but it would make sense for it to exist in docs or introduced here if we want users to understand it at some point.

---

Pallet features:

• different basic parts of a pallet

  • hooks
  • events, errors
  • calls, etc...

• instantiable pallets, and what that means

---

• Basics of dispatching a call to the runtime
• transaction lifecycle flow

---

• Basic walkthrough of system and executor
• basic walkthrough of frame support
• basic walkthrough of substrate primitives
  • specifically sp arithmetic

---

[CrackTheCode016]

Linking this issue here, as I feel it could add some considerations for us (although it may be out of scope, so feel free to ignore if so): paritytech/polkadot-sdk#5

Particularly, we always emphasize the runtime (which is important), but never anything outside of it, such as the outer node and client implementation (something almost never touched). Is it something we should consider?

[shawntabrizi]

I think it is very much about audience and context.

Normally, we leave the client opaque because we assume that our audience is mostly runtime developers, that wont really touch the client too much, if at all.

Indeed, we also hope this is the case, since as soon as you touch the client, you start to have potential issues with compatibility with being a Parachain on Polkadot.

Understanding the client deeper is important for a core developer role, or building complex / custom solo-chains.

This information is good, but it greatly expands the prerequisite knowledge they need to have about blockchains, designing low level systems, Rust, etc...

I think it would be very hard to create an "introduction to client" course beyond doing small customization of the RPCs, CLIs, etc... Anything deeper to me is "advanced" by definition.

[kianenigma]

Hey Bader and Shawn,

I am looking into this tutorial today as well and will write down some of my thoughts as well.

Substrate Development 101: I like the first section explaining the node and runtime structure. The storage part is also interesting. I would add snippets Ext::execute_with(|| { write_stuff(); read_stuff(); }). I wouldn't mention FRAME storage primitives here, maybe you can link to "if you want a peak at storage primitives provided by FRAME, see ". Finally, I would rename the Pallet section to Runtime. Also, first talk about Runtime, mention that it is mere WASM blob, maybe link to frameless, then mention that you can use FRAME for this, and FRAME has Pallets etc. The section is missing links but it otherwise good.

[kianenigma]

on ensure: I would first actually write the code without ensure! such that I can also hint at what DispatchResult is, then say that ensure is a shorthand.

I am still confused about the categorization. What is the difference between "Building Custom FRAME Pallet" and "Custom FRAME Pallets", and how is events are in one, but dispatchable in another?

I would not mention Currency traits at all.