What is `codeSubstitutes` in the chain spec?

Question

I have seen mention of codeSubstitutes in the chain spec before.

What is this? And when is it applicable?

Answer 1

codeSubstitutes is a really cool and useful feature to upgrade your chain when a runtime upgrade is not possible. This can be useful when your chain is not producing blocks due to a bug. codeSubstitutes replaces the on-chain runtime by specifying the block number and the WASM. When the specified block number is reached the chain will "substitute" the on-chain WASM with the one specified in the codeSubstitutes. Keep in mind though, for a parachain, the relay chain will also have to be updated with the substituted WASM (most likely via governance).

From the source:

//! /// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
//! /// given block number until the `spec_version` on-chain changes. The given `wasm_code` should
//! /// be as close as possible to the on-chain wasm code. A substitute should be used to fix a bug
//! /// that can not be fixed with a runtime upgrade, if for example the runtime is constantly
//! /// panicking. Introducing new runtime apis isn't supported, because the node
//! /// will read the runtime version from the on-chain wasm code. Use this functionality only when
//! /// there is no other way around it and only patch the problematic bug, the rest should be done
//! /// with a on-chain runtime upgrade.

Answer 2

As it has been pointed out already here codeSubstitutes is a good option only when a fix is needed to be included into the runtime because there is no other way to make it through. This is the case when a stalled chain needs some change in the runtime, but as it is stalled, cannot produce any block, and thus, a runtime upgrade is not a possible way.

Usually the steps are:

• Include the fix in the code(branch/release/version) from which the running, and stalled, runtime has been built out from.
• Do not bump the spec version of the runtime. As the documentation reads, this is a code substitution and it will be used until a new runtime with a new spec version is applied.
• Include this new wasm blob in the chain spec of your running chain under the map codeSubstitutes. Its key will be a block number, something recent or even the last block the chain has produced. And as value of this map, the wasm itself.
• Then, the code substitution will be effective once the nodes are running again from the block number specified.
• If a parachain, the next step will be getting this same wasm used in codeSubstitutes into the relay storage for your para. Usually a governance proposal would be needed in order to get this done. E.g. of a call that could be proposed: force_set_current_code(paraId, wasm_used_in_codeSubstitutes).