From a64009ae00f954acf907593309af2b1f1797e87d Mon Sep 17 00:00:00 2001 From: eskimor Date: Fri, 12 Apr 2024 12:23:49 +0200 Subject: [PATCH] Improve docs of broker pallet (#3980) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Small adjustments which should make understanding what is going on much easier for future readers. Initialization is a bit messy, the very least we should do is adding documentation to make it harder to use wrongly. I was thinking about calling `request_core_count` right from `start_sales`, but as explained in the docs, this is not necessarily what you want. --------- Co-authored-by: eskimor Co-authored-by: Bastian Köcher Co-authored-by: Dónal Murray --- .../frame/broker/src/dispatchable_impls.rs | 5 +++-- substrate/frame/broker/src/lib.rs | 19 +++++++++++++++---- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/substrate/frame/broker/src/dispatchable_impls.rs b/substrate/frame/broker/src/dispatchable_impls.rs index ef20bc8fb8..c2e731462c 100644 --- a/substrate/frame/broker/src/dispatchable_impls.rs +++ b/substrate/frame/broker/src/dispatchable_impls.rs @@ -81,7 +81,8 @@ impl Pallet { last_timeslice: Self::current_timeslice(), }; let now = frame_system::Pallet::::block_number(); - let new_sale = SaleInfoRecord { + // Imaginary old sale for bootstrapping the first actual sale: + let old_sale = SaleInfoRecord { sale_start: now, leadin_length: Zero::zero(), price, @@ -94,7 +95,7 @@ impl Pallet { cores_sold: 0, }; Self::deposit_event(Event::::SalesStarted { price, core_count }); - Self::rotate_sale(new_sale, &config, &status); + Self::rotate_sale(old_sale, &config, &status); Status::::put(&status); Ok(()) } diff --git a/substrate/frame/broker/src/lib.rs b/substrate/frame/broker/src/lib.rs index a39576b090..330491eb20 100644 --- a/substrate/frame/broker/src/lib.rs +++ b/substrate/frame/broker/src/lib.rs @@ -552,16 +552,27 @@ pub mod pallet { /// /// - `origin`: Must be Root or pass `AdminOrigin`. /// - `initial_price`: The price of Bulk Coretime in the first sale. - /// - `core_count`: The number of cores which can be allocated. + /// - `total_core_count`: This is the total number of cores the relay chain should have + /// after the sale concludes. + /// + /// NOTE: This function does not actually request that new core count from the relay chain. + /// You need to make sure to call `request_core_count` afterwards to bring the relay chain + /// in sync. + /// + /// When to call the function depends on the new core count. If it is larger than what it + /// was before, you can call it immediately or even before `start_sales` as non allocated + /// cores will just be `Idle`. If you are actually reducing the number of cores, you should + /// call `request_core_count`, right before the next sale, to avoid shutting down tasks too + /// early. #[pallet::call_index(4)] - #[pallet::weight(T::WeightInfo::start_sales((*core_count).into()))] + #[pallet::weight(T::WeightInfo::start_sales((*total_core_count).into()))] pub fn start_sales( origin: OriginFor, initial_price: BalanceOf, - core_count: CoreIndex, + total_core_count: CoreIndex, ) -> DispatchResultWithPostInfo { T::AdminOrigin::ensure_origin_or_root(origin)?; - Self::do_start_sales(initial_price, core_count)?; + Self::do_start_sales(initial_price, total_core_count)?; Ok(Pays::No.into()) }