(source)

Table of Contents

• RFC-0013: Prepare Core runtime API for MBMs
  • Summary
  • Motivation
  • Stakeholders
  • Explanation
    • Core::initialize_block
  • Drawbacks
  • Testing, Security, and Privacy
  • Performance, Ergonomics, and Compatibility
    • Performance
    • Ergonomics
    • Compatibility
  • Prior Art and References
  • Unresolved Questions
  • Future Directions and Related Material

RFC-0013: Prepare Core runtime API for MBMs

Summary

Introduces breaking changes to the Core runtime API by letting Core::initialize_block return an enum. The versions of Core is bumped from 4 to 5.

Motivation

The main feature that motivates this RFC are Multi-Block-Migrations (MBM); these make it possible to split a migration over multiple blocks.
Further it would be nice to not hinder the possibility of implementing a new hook poll, that runs at the beginning of the block when there are no MBMs and has access to AllPalletsWithSystem. This hook can then be used to replace the use of on_initialize and on_finalize for non-deadline critical logic.
In a similar fashion, it should not hinder the future addition of a System::PostInherents callback that always runs after all inherents were applied.

Stakeholders

• Substrate Maintainers: They have to implement this, including tests, audit and maintenance burden.
• Polkadot Runtime developers: They will have to adapt the runtime files to this breaking change.
• Polkadot Parachain Teams: They have to adapt to the breaking changes but then eventually have multi-block migrations available.

Explanation

Core::initialize_block

This runtime API function is changed from returning () to ExtrinsicInclusionMode:

fn initialize_block(header: &<Block as BlockT>::Header)
+  -> ExtrinsicInclusionMode;

With ExtrinsicInclusionMode is defined as:

#![allow(unused)]
fn main() {
enum ExtrinsicInclusionMode {
  /// All extrinsics are allowed in this block.
  AllExtrinsics,
  /// Only inherents are allowed in this block.
  OnlyInherents,
}
}

A block author MUST respect the ExtrinsicInclusionMode that is returned by initialize_block. The runtime MUST reject blocks that have non-inherent extrinsics in them while OnlyInherents was returned.

Coming back to the motivations and how they can be implemented with this runtime API change:

1. Multi-Block-Migrations: The runtime is being put into lock-down mode for the duration of the migration process by returning OnlyInherents from initialize_block. This ensures that no user provided transaction can interfere with the migration process. It is absolutely necessary to ensure this, otherwise a transaction could call into un-migrated storage and violate storage invariants.

2. poll is possible by using apply_extrinsic as entry-point and not hindered by this approach. It would not be possible to use a pallet inherent like System::last_inherent to achieve this for two reasons: First is that pallets do not have access to AllPalletsWithSystem which is required to invoke the poll hook on all pallets. Second is that the runtime does currently not enforce an order of inherents.

3. System::PostInherents can be done in the same manner as poll.

Drawbacks

The previous drawback of cementing the order of inherents has been addressed and removed by redesigning the approach. No further drawbacks have been identified thus far.

Testing, Security, and Privacy

The new logic of initialize_block can be tested by checking that the block-builder will skip transactions when OnlyInherents is returned.

Security: n/a

Privacy: n/a

Performance, Ergonomics, and Compatibility

Performance

The performance overhead is minimal in the sense that no clutter was added after fulfilling the requirements. The only performance difference is that initialize_block also returns an enum that needs to be passed through the WASM boundary. This should be negligible.

Ergonomics

The new interface allows for more extensible runtime logic. In the future, this will be utilized for multi-block-migrations which should be a huge ergonomic advantage for parachain developers.

Compatibility

The advice here is OPTIONAL and outside of the RFC. To not degrade user experience, it is recommended to ensure that an updated node can still import historic blocks.

Prior Art and References

The RFC is currently being implemented in polkadot-sdk#1781 (formerly substrate#14275). Related issues and merge requests:

• Simple multi block migrations
• Execute a hook after inherent but before transactions
• There is no module hook after inherents and before transactions

Unresolved Questions

Please suggest a better name for BlockExecutiveMode. We already tried: RuntimeExecutiveMode, ExtrinsicInclusionMode. The names of the modes Normal and Minimal were also called AllExtrinsics and OnlyInherents, so if you have naming preferences; please post them.
=> renamed to ExtrinsicInclusionMode

Is post_inherents more consistent instead of last_inherent? Then we should change it.
=> renamed to last_inherent

Future Directions and Related Material

The long-term future here is to move the block building logic into the runtime. Currently there is a tight dance between the block author and the runtime; the author has to call into different runtime functions in quick succession and exact order. Any misstep causes the block to be invalid.
This can be unified and simplified by moving both parts into the runtime.