Runtime Upgrade ref docs and Single Block Migration example pallet (#1554)

Closes https://github.com/paritytech/polkadot-sdk-docs/issues/55

- Changes 'current storage version' terminology to less ambiguous
'in-code storage version' (suggestion by @ggwpez)
- Adds a new example pallet `pallet-example-single-block-migrations`
- Adds a new reference doc to replace
https://docs.substrate.io/maintain/runtime-upgrades/ (temporarily living
in the pallet while we wait for developer hub PR to merge)
- Adds documentation for the `storage_alias` macro
- Improves `trait Hooks` docs 
- Improves `trait GetStorageVersion` docs
- Update the suggested patterns for using `VersionedMigration`, so that
version unchecked migrations are never exported
- Prevents accidental usage of version unchecked migrations in runtimes

https://github.com/paritytech/substrate/pull/14421#discussion_r1255467895
- Unversioned migration code is kept inside `mod version_unchecked`,
versioned code is kept in `pub mod versioned`
- It is necessary to use modules to limit visibility because the inner
migration must be `pub`. See
https://github.com/rust-lang/rust/issues/30905 and

https://internals.rust-lang.org/t/lang-team-minutes-private-in-public-rules/4504/40
for more.

### todo

- [x] move to reference docs to proper place within sdk-docs (now that
https://github.com/paritytech/polkadot-sdk/pull/2102 is merged)
- [x] prdoc

---------

Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Juan <juangirini@gmail.com>
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
Co-authored-by: command-bot <>
Co-authored-by: gupnik <nikhilgupta.iitk@gmail.com>
This commit is contained in:
authored and GitHub committed 2024-02-28 07:32:02 +00:00
1 parent 7ec0b8741b
commit 12ce4f7d04
87 files changed
+1222 -369

No files matched your search

+12 -12
View File
@@ -47,7 +47,7 @@ use sp_runtime::{
};
use sp_std::prelude::*;
mod old {
mod v9 {
use super::*;
pub type BalanceOf<T, OldCurrency> = <OldCurrency as frame_support::traits::Currency<
@@ -85,7 +85,7 @@ pub fn store_old_contract_info<T: Config, OldCurrency>(
) where
OldCurrency: ReservableCurrency<<T as frame_system::Config>::AccountId> + 'static,
{
let info = old::ContractInfo {
let info = v9::ContractInfo {
trie_id: info.trie_id,
code_hash: info.code_hash,
storage_bytes: Default::default(),
@@ -94,7 +94,7 @@ pub fn store_old_contract_info<T: Config, OldCurrency>(
storage_item_deposit: Default::default(),
storage_base_deposit: Default::default(),
};
old::ContractInfoOf::<T, OldCurrency>::insert(account, info);
v9::ContractInfoOf::<T, OldCurrency>::insert(account, info);
}
#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebugNoBound, TypeInfo, MaxEncodedLen)]
@@ -120,9 +120,9 @@ where
pub code_hash: CodeHash<T>,
storage_bytes: u32,
storage_items: u32,
pub storage_byte_deposit: old::BalanceOf<T, OldCurrency>,
storage_item_deposit: old::BalanceOf<T, OldCurrency>,
storage_base_deposit: old::BalanceOf<T, OldCurrency>,
pub storage_byte_deposit: v9::BalanceOf<T, OldCurrency>,
storage_item_deposit: v9::BalanceOf<T, OldCurrency>,
storage_base_deposit: v9::BalanceOf<T, OldCurrency>,
}
#[derive(Encode, Decode, MaxEncodedLen, DefaultNoBound)]
@@ -152,7 +152,7 @@ fn deposit_address<T: Config>(
impl<T: Config, OldCurrency: 'static> MigrationStep for Migration<T, OldCurrency>
where
OldCurrency: ReservableCurrency<<T as frame_system::Config>::AccountId>
+ Inspect<<T as frame_system::Config>::AccountId, Balance = old::BalanceOf<T, OldCurrency>>,
+ Inspect<<T as frame_system::Config>::AccountId, Balance = v9::BalanceOf<T, OldCurrency>>,
{
const VERSION: u16 = 10;
@@ -162,11 +162,11 @@ where
fn step(&mut self) -> (IsFinished, Weight) {
let mut iter = if let Some(last_account) = self.last_account.take() {
old::ContractInfoOf::<T, OldCurrency>::iter_from(
old::ContractInfoOf::<T, OldCurrency>::hashed_key_for(last_account),
v9::ContractInfoOf::<T, OldCurrency>::iter_from(
v9::ContractInfoOf::<T, OldCurrency>::hashed_key_for(last_account),
)
} else {
old::ContractInfoOf::<T, OldCurrency>::iter()
v9::ContractInfoOf::<T, OldCurrency>::iter()
};
if let Some((account, contract)) = iter.next() {
@@ -276,7 +276,7 @@ where
#[cfg(feature = "try-runtime")]
fn pre_upgrade_step() -> Result<Vec<u8>, TryRuntimeError> {
let sample: Vec<_> = old::ContractInfoOf::<T, OldCurrency>::iter().take(10).collect();
let sample: Vec<_> = v9::ContractInfoOf::<T, OldCurrency>::iter().take(10).collect();
log::debug!(target: LOG_TARGET, "Taking sample of {} contracts", sample.len());
Ok(sample.encode())
@@ -284,7 +284,7 @@ where
#[cfg(feature = "try-runtime")]
fn post_upgrade_step(state: Vec<u8>) -> Result<(), TryRuntimeError> {
let sample = <Vec<(T::AccountId, old::ContractInfo<T, OldCurrency>)> as Decode>::decode(
let sample = <Vec<(T::AccountId, v9::ContractInfo<T, OldCurrency>)> as Decode>::decode(
&mut &state[..],
)
.expect("pre_upgrade_step provides a valid state; qed");