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

What is this? And when is it applicable?

2 Answers 2


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.

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).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.