Document Runtime Upgrades

[shawntabrizi]

• What are different runtime version types, when should I bump them, when not? (authoring, spec, impl, ...)

• Who can issue runtime upgrades? (sudo, democracy, council, ...)

• When do I have to do runtime upgrades? Anything that modifies the actual runtime?

• How does the technical process look like, how to I correctly build the runtime and how do I push it to my running chain? Does this require a target block number?

• How to get the wasm code? Is cargo build --release enough?

• How to ensure/test that the wasm code does not lead to chain halts, such as unexpected validator set/epoch changes, corrupt storage, etc...?

• Are there limits on what can be upgrated? E. g. can we upgrade things like reward curves, seconds per slot, transition from a PoA to a PoS chain?

• How to upgrade without the sudo module?

• How to schedule a time for the upgrade? Or will it be performed as soon as the democracy module has voted?

[soc1c]

cc @roninkaizen

[joepetrowski]

Useful: https://hackmd.io/mGgNZX0VT4S0UTaq89-_SQ?sync=&type=

Should also include storage migrations.

[danforbes]

This is probably related to #39, particularly the question How to upgrade without the sudo module?

[JoshOrndorff]

I just wrote this in a riot message today.

Here are some sparse docs about runtime upgrades. https://substrate.dev/substrate-beginner-workshop/#/3-upgrading/
The basic idea is:

1. Launch a chain
2. Modify your runtime in some way
   2a. Make double sure you've changed the spec_version. Here's one example of a spec_version from the recipes. Every runtime has this spec_version.
3. recompile your runtime
4. find the ./target/release/wbuild/<name-of-your-runtime>/<name-of-your-runtime>.compact.wasm file
5. Use sudo to call system.set_code with that wasm file