configuration: Rename validation_upgrade_{frequency -> cooldown} (#4635)

This just renames a member of `HostConfiguration` from
validation_upgrade_frequency to -//-_cooldown.

As was already pointed out in #4460 the existing name is a misnomer, the
member actually represents a minimum time period between upgrades, which
is neatly expressed by a word cooldown.

I've been planning this rename already for some time and the term is
already used in paras module:

https://github.com/paritytech/polkadot/blob/0f1a67114ad4c849223f87fa48c3dd3d9743832c/runtime/parachains/src/paras.rs#L1568-L1574

node/service/src/chain_spec.rs

@@ -179,7 +179,7 @@ fn default_parachains_host_configuration(
 	use polkadot_primitives::v1::{MAX_CODE_SIZE, MAX_POV_SIZE};
 
 	polkadot_runtime_parachains::configuration::HostConfiguration {
-		validation_upgrade_frequency: 2u32,
+		validation_upgrade_cooldown: 2u32,
 		validation_upgrade_delay: 2,
 		code_retention_period: 1200,
 		max_code_size: MAX_CODE_SIZE,

node/test/service/src/chain_spec.rs

@@ -161,7 +161,7 @@ fn polkadot_testnet_genesis(
 		sudo: runtime::SudoConfig { key: Some(root_key) },
 		configuration: runtime::ConfigurationConfig {
 			config: polkadot_runtime_parachains::configuration::HostConfiguration {
-				validation_upgrade_frequency: 10u32,
+				validation_upgrade_cooldown: 10u32,
 				validation_upgrade_delay: 5,
 				code_retention_period: 1200,
 				max_code_size: MAX_CODE_SIZE,

primitives/src/v1/mod.rs

@@ -1031,7 +1031,7 @@ pub struct AbridgedHostConfiguration {
 	/// This parameter affects the upper bound of size of `CandidateCommitments`.
 	pub hrmp_max_message_num_per_candidate: u32,
 	/// The minimum period, in blocks, between which parachains can update their validation code.
-	pub validation_upgrade_frequency: BlockNumber,
+	pub validation_upgrade_cooldown: BlockNumber,
 	/// The delay, in blocks, before a validation upgrade is applied.
 	pub validation_upgrade_delay: BlockNumber,
 }

roadmap/implementers-guide/src/runtime/inclusion.md

@@ -85,7 +85,7 @@ All failed checks should lead to an unrecoverable error making the block invalid
   1. check that each candidate's `validation_data_hash` corresponds to a `PersistedValidationData` computed from the current state.
     > NOTE: With contextual execution in place, validation data will be obtained as of the state of the context block. However, only the state of the current block can be used for such a query.
   1. If the core assignment includes a specific collator, ensure the backed candidate is issued by that collator.
-  1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_frequency` of `Paras::last_code_upgrade(para_id, true)`, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
+  1. Ensure that any code upgrade scheduled by the candidate does not happen within `config.validation_upgrade_cooldown` of `Paras::last_code_upgrade(para_id, true)`, if any, comparing against the value of `Paras::FutureCodeUpgrades` for the given para ID.
   1. Check the collator's signature on the candidate data.
   1. check the backing of the candidate using the signatures and the bitfields, comparing against the validators assigned to the groups, fetched with the `group_validators` lookup.
   1. call `Ump::check_upward_messages(para, commitments.upward_messages)` to check that the upward messages are valid.

roadmap/implementers-guide/src/runtime/paras.md

@@ -258,7 +258,7 @@ CodeByHash: map ValidationCodeHash => Option<ValidationCode>
 * `schedule_parachain_downgrade(ParaId)`: Schedule a parachain to be downgraded to a parathread.
 * `schedule_code_upgrade(ParaId, new_code, relay_parent: BlockNumber, HostConfiguration)`: Schedule a future code
   upgrade of the given parachain. In case the PVF pre-checking is disabled, or the new code is already present in the storage, the upgrade will be applied after inclusion of a block of the same parachain
-  executed in the context of a relay-chain block with number >= `relay_parent + config.validation_upgrade_delay`. If the upgrade is scheduled `UpgradeRestrictionSignal` is set and it will remain set until `relay_parent + config.validation_upgrade_frequency`.
+  executed in the context of a relay-chain block with number >= `relay_parent + config.validation_upgrade_delay`. If the upgrade is scheduled `UpgradeRestrictionSignal` is set and it will remain set until `relay_parent + config.validation_upgrade_cooldown`.
 In case the PVF pre-checking is enabled, or the new code is not already present in the storage, then the PVF pre-checking run will be scheduled for that validation code. If the pre-checking concludes with rejection, then the upgrade is canceled. Otherwise, after pre-checking is concluded the upgrade will be scheduled and be enacted as described above.
 * `note_new_head(ParaId, HeadData, BlockNumber)`: note that a para has progressed to a new head,
   where the new head was executed in the context of a relay-chain block with given number. This will

roadmap/implementers-guide/src/types/README.md

@@ -316,7 +316,7 @@ digraph {
             <tr><td>max_upward_message_size</td><td port="max_upward_message_size">u32</td></tr>
             <tr><td>max_upward_messages_num_per_candidate</td><td port="max_upward_messages_num_per_candidate">u32</td></tr>
             <tr><td>hrmp_max_message_num_per_candidate</td><td port="hrmp_max_message_num_per_candidate">u32</td></tr>
-            <tr><td>validation_upgrade_frequency</td><td port="validation_upgrade_frequency">BlockNumber</td></tr>
+            <tr><td>validation_upgrade_cooldown</td><td port="validation_upgrade_cooldown">BlockNumber</td></tr>
             <tr><td>validation_upgrade_delay</td><td port="validation_upgrade_delay">BlockNumber</td></tr>
         </table>
     >]

roadmap/implementers-guide/src/types/runtime.md

@@ -9,7 +9,7 @@ The internal-to-runtime configuration of the parachain host. This is expected to
 ```rust
 struct HostConfiguration {
 	/// The minimum period, in blocks, between which parachains can update their validation code.
-	pub validation_upgrade_frequency: BlockNumber,
+	pub validation_upgrade_cooldown: BlockNumber,
 	/// The delay, in blocks, before a validation upgrade is applied.
 	pub validation_upgrade_delay: BlockNumber,
 	/// How long to keep code on-chain, in blocks. This should be sufficiently long that disputes

runtime/parachains/src/configuration.rs

@@ -77,7 +77,8 @@ pub struct HostConfiguration<BlockNumber> {
 	/// PVF pre-checking can take. Intuitively, this number should be greater than the duration
 	/// specified by [`pvf_voting_ttl`]. Unlike, [`pvf_voting_ttl`], this parameter uses blocks
 	/// as a unit.
-	pub validation_upgrade_frequency: BlockNumber,
+	#[cfg_attr(feature = "std", serde(alias = "validation_upgrade_frequency"))]
+	pub validation_upgrade_cooldown: BlockNumber,
 	/// The delay, in blocks, before a validation upgrade is applied.
 	pub validation_upgrade_delay: BlockNumber,
 
@@ -218,7 +219,7 @@ impl<BlockNumber: Default + From<u32>> Default for HostConfiguration<BlockNumber
 			chain_availability_period: 1u32.into(),
 			thread_availability_period: 1u32.into(),
 			no_show_slots: 1u32.into(),
-			validation_upgrade_frequency: Default::default(),
+			validation_upgrade_cooldown: Default::default(),
 			validation_upgrade_delay: 2u32.into(),
 			code_retention_period: Default::default(),
 			max_code_size: Default::default(),
@@ -470,18 +471,18 @@ pub mod pallet {
 
 	#[pallet::call]
 	impl<T: Config> Pallet<T> {
-		/// Set the validation upgrade frequency.
+		/// Set the validation upgrade cooldown.
 		#[pallet::weight((
 			T::WeightInfo::set_config_with_block_number(),
 			DispatchClass::Operational,
 		))]
-		pub fn set_validation_upgrade_frequency(
+		pub fn set_validation_upgrade_cooldown(
 			origin: OriginFor<T>,
 			new: T::BlockNumber,
 		) -> DispatchResult {
 			ensure_root(origin)?;
 			Self::schedule_config_update(|config| {
-				config.validation_upgrade_frequency = new;
+				config.validation_upgrade_cooldown = new;
 			})
 		}
 
@@ -1345,11 +1346,11 @@ mod tests {
 			let old_config = Configuration::config();
 			let mut config = old_config.clone();
 			config.validation_upgrade_delay = 100;
-			config.validation_upgrade_frequency = 100;
+			config.validation_upgrade_cooldown = 100;
 			assert!(old_config != config);
 
 			assert_ok!(Configuration::set_validation_upgrade_delay(Origin::root(), 100));
-			assert_ok!(Configuration::set_validation_upgrade_frequency(Origin::root(), 100));
+			assert_ok!(Configuration::set_validation_upgrade_cooldown(Origin::root(), 100));
 			assert_eq!(Configuration::config(), old_config);
 			assert_eq!(<Configuration as Store>::PendingConfigs::get(), vec![(2, config.clone())]);
 
@@ -1373,7 +1374,7 @@ mod tests {
 				HostConfiguration { validation_upgrade_delay: 100, ..initial_config.clone() };
 			let final_config = HostConfiguration {
 				validation_upgrade_delay: 100,
-				validation_upgrade_frequency: 99,
+				validation_upgrade_cooldown: 99,
 				..initial_config.clone()
 			};
 
@@ -1388,7 +1389,7 @@ mod tests {
 
 			// We are still waiting until the pending configuration is applied and we add another
 			// update.
-			assert_ok!(Configuration::set_validation_upgrade_frequency(Origin::root(), 99));
+			assert_ok!(Configuration::set_validation_upgrade_cooldown(Origin::root(), 99));
 
 			// This should result in yet another configiguration change scheduled.
 			assert_eq!(Configuration::config(), initial_config);
@@ -1420,7 +1421,7 @@ mod tests {
 				HostConfiguration { validation_upgrade_delay: 100, ..initial_config.clone() };
 			let final_config = HostConfiguration {
 				validation_upgrade_delay: 100,
-				validation_upgrade_frequency: 99,
+				validation_upgrade_cooldown: 99,
 				code_retention_period: 98,
 				..initial_config.clone()
 			};
@@ -1436,7 +1437,7 @@ mod tests {
 
 			// The second call should fall into the case where we already have a pending config
 			// update for the scheduled_session, but we want to update it once more.
-			assert_ok!(Configuration::set_validation_upgrade_frequency(Origin::root(), 99));
+			assert_ok!(Configuration::set_validation_upgrade_cooldown(Origin::root(), 99));
 			assert_ok!(Configuration::set_code_retention_period(Origin::root(), 98));
 
 			// This should result in yet another configiguration change scheduled.
@@ -1545,7 +1546,7 @@ mod tests {
 	fn setting_pending_config_members() {
 		new_test_ext(Default::default()).execute_with(|| {
 			let new_config = HostConfiguration {
-				validation_upgrade_frequency: 100,
+				validation_upgrade_cooldown: 100,
 				validation_upgrade_delay: 10,
 				code_retention_period: 5,
 				max_code_size: 100_000,
@@ -1592,9 +1593,9 @@ mod tests {
 
 			assert!(<Configuration as Store>::PendingConfig::get(shared::SESSION_DELAY).is_none());
 
-			Configuration::set_validation_upgrade_frequency(
+			Configuration::set_validation_upgrade_cooldown(
 				Origin::root(),
-				new_config.validation_upgrade_frequency,
+				new_config.validation_upgrade_cooldown,
 			)
 			.unwrap();
 			Configuration::set_validation_upgrade_delay(
@@ -1813,7 +1814,7 @@ mod tests {
 						.max_upward_message_num_per_candidate,
 					hrmp_max_message_num_per_candidate: ground_truth
 						.hrmp_max_message_num_per_candidate,
-					validation_upgrade_frequency: ground_truth.validation_upgrade_frequency,
+					validation_upgrade_cooldown: ground_truth.validation_upgrade_cooldown,
 					validation_upgrade_delay: ground_truth.validation_upgrade_delay,
 				},
 			);

runtime/parachains/src/configuration/migration.rs

@@ -156,7 +156,7 @@ max_upward_queue_size                    : pre.max_upward_queue_size,
 max_upward_message_size                  : pre.max_upward_message_size,
 max_upward_message_num_per_candidate     : pre.max_upward_message_num_per_candidate,
 hrmp_max_message_num_per_candidate       : pre.hrmp_max_message_num_per_candidate,
-validation_upgrade_frequency             : pre.validation_upgrade_frequency,
+validation_upgrade_cooldown              : pre.validation_upgrade_frequency,
 validation_upgrade_delay                 : pre.validation_upgrade_delay,
 max_pov_size                             : pre.max_pov_size,
 max_downward_message_size                : pre.max_downward_message_size,
@@ -347,7 +347,7 @@ mod tests {
 			assert_eq!(v1.max_upward_message_size                  , v2.max_upward_message_size);
 			assert_eq!(v1.max_upward_message_num_per_candidate     , v2.max_upward_message_num_per_candidate);
 			assert_eq!(v1.hrmp_max_message_num_per_candidate       , v2.hrmp_max_message_num_per_candidate);
-			assert_eq!(v1.validation_upgrade_frequency             , v2.validation_upgrade_frequency);
+			assert_eq!(v1.validation_upgrade_frequency             , v2.validation_upgrade_cooldown);
 			assert_eq!(v1.validation_upgrade_delay                 , v2.validation_upgrade_delay);
 			assert_eq!(v1.max_pov_size                             , v2.max_pov_size);
 			assert_eq!(v1.max_downward_message_size                , v2.max_downward_message_size);

runtime/parachains/src/paras.rs

@@ -1646,7 +1646,7 @@ impl<T: Config> Pallet<T> {
 		UpgradeRestrictionSignal::<T>::insert(&id, UpgradeRestriction::Present);
 
 		weight += T::DbWeight::get().reads_writes(1, 1);
-		let next_possible_upgrade_at = relay_parent_number + cfg.validation_upgrade_frequency;
+		let next_possible_upgrade_at = relay_parent_number + cfg.validation_upgrade_cooldown;
 		<Self as Store>::UpgradeCooldowns::mutate(|upgrade_cooldowns| {
 			let insert_idx = upgrade_cooldowns
 				.binary_search_by_key(&next_possible_upgrade_at, |&(_, b)| b)
@@ -2268,7 +2268,7 @@ mod tests {
 	fn code_upgrade_applied_after_delay() {
 		let code_retention_period = 10;
 		let validation_upgrade_delay = 5;
-		let validation_upgrade_frequency = 10;
+		let validation_upgrade_cooldown = 10;
 
 		let original_code = ValidationCode(vec![1, 2, 3]);
 		let paras = vec![(
@@ -2286,7 +2286,7 @@ mod tests {
 				config: HostConfiguration {
 					code_retention_period,
 					validation_upgrade_delay,
-					validation_upgrade_frequency,
+					validation_upgrade_cooldown,
 					pvf_checking_enabled: false,
 					..Default::default()
 				},
@@ -2307,7 +2307,7 @@ mod tests {
 			let expected_at = {
 				// this parablock is in the context of block 1.
 				let expected_at = 1 + validation_upgrade_delay;
-				let next_possible_upgrade_at = 1 + validation_upgrade_frequency;
+				let next_possible_upgrade_at = 1 + validation_upgrade_cooldown;
 				Paras::schedule_code_upgrade(
 					para_id,
 					new_code.clone(),
@@ -2376,7 +2376,7 @@ mod tests {
 	fn code_upgrade_applied_after_delay_even_when_late() {
 		let code_retention_period = 10;
 		let validation_upgrade_delay = 5;
-		let validation_upgrade_frequency = 10;
+		let validation_upgrade_cooldown = 10;
 
 		let original_code = ValidationCode(vec![1, 2, 3]);
 		let paras = vec![(
@@ -2394,7 +2394,7 @@ mod tests {
 				config: HostConfiguration {
 					code_retention_period,
 					validation_upgrade_delay,
-					validation_upgrade_frequency,
+					validation_upgrade_cooldown,
 					pvf_checking_enabled: false,
 					..Default::default()
 				},
@@ -2413,7 +2413,7 @@ mod tests {
 			let expected_at = {
 				// this parablock is in the context of block 1.
 				let expected_at = 1 + validation_upgrade_delay;
-				let next_possible_upgrade_at = 1 + validation_upgrade_frequency;
+				let next_possible_upgrade_at = 1 + validation_upgrade_cooldown;
 				Paras::schedule_code_upgrade(
 					para_id,
 					new_code.clone(),
@@ -2467,7 +2467,7 @@ mod tests {
 	fn submit_code_change_when_not_allowed_is_err() {
 		let code_retention_period = 10;
 		let validation_upgrade_delay = 7;
-		let validation_upgrade_frequency = 100;
+		let validation_upgrade_cooldown = 100;
 
 		let paras = vec![(
 			0u32.into(),
@@ -2484,7 +2484,7 @@ mod tests {
 				config: HostConfiguration {
 					code_retention_period,
 					validation_upgrade_delay,
-					validation_upgrade_frequency,
+					validation_upgrade_cooldown,
 					pvf_checking_enabled: false,
 					..Default::default()
 				},