pallet_broker/
coretime_interface.rs

Help
1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18#![deny(missing_docs)]
19
20use alloc::vec::Vec;
21use codec::{Decode, DecodeWithMemTracking, Encode, MaxEncodedLen};
22use core::fmt::Debug;
23use frame_support::Parameter;
24use scale_info::TypeInfo;
25use sp_arithmetic::traits::AtLeast32BitUnsigned;
26use sp_core::RuntimeDebug;
27use sp_runtime::traits::BlockNumberProvider;
28
29use crate::Timeslice;
30
31/// Index of a Polkadot Core.
32pub type CoreIndex = u16;
33
34/// A Task Id. In general this is called a ParachainId.
35pub type TaskId = u32;
36
37/// Fraction expressed as a nominator with an assumed denominator of 57,600.
38pub type PartsOf57600 = u16;
39
40/// An element to which a core can be assigned.
41#[derive(
42	Encode,
43	Decode,
44	DecodeWithMemTracking,
45	Clone,
46	Eq,
47	PartialEq,
48	Ord,
49	PartialOrd,
50	RuntimeDebug,
51	TypeInfo,
52	MaxEncodedLen,
53)]
54pub enum CoreAssignment {
55	/// Core need not be used for anything.
56	Idle,
57	/// Core should be used for the Instantaneous Coretime Pool.
58	Pool,
59	/// Core should be used to process the given task.
60	Task(TaskId),
61}
62
63/// Relay chain block number of `T` that implements [`CoretimeInterface`].
64pub type RCBlockNumberOf<T> = <RCBlockNumberProviderOf<T> as BlockNumberProvider>::BlockNumber;
65
66/// Relay chain block number provider of `T` that implements [`CoretimeInterface`].
67pub type RCBlockNumberProviderOf<T> = <T as CoretimeInterface>::RelayChainBlockNumberProvider;
68
69/// Type able to accept Coretime scheduling instructions and provide certain usage information.
70/// Generally implemented by the Relay-chain or some means of communicating with it.
71///
72/// The trait representation of RFC#5 `<https://github.com/polkadot-fellows/RFCs/pull/5>`.
73pub trait CoretimeInterface {
74	/// A (Relay-chain-side) account ID.
75	type AccountId: Parameter;
76
77	/// A (Relay-chain-side) balance.
78	type Balance: AtLeast32BitUnsigned + Encode + Decode + MaxEncodedLen + TypeInfo + Debug;
79
80	/// A provider for the relay chain block number.
81	type RelayChainBlockNumberProvider: BlockNumberProvider;
82
83	/// Requests the Relay-chain to alter the number of schedulable cores to `count`. Under normal
84	/// operation, the Relay-chain SHOULD send a `notify_core_count(count)` message back.
85	fn request_core_count(count: CoreIndex);
86
87	/// Requests that the Relay-chain send a `notify_revenue` message back at or soon after
88	/// Relay-chain block number `when` whose `until` parameter is equal to `when`.
89	///
90	/// `when` may never be greater than the result of `Self::latest()`.
91	/// The period in to the past which `when` is allowed to be may be limited; if so the limit
92	/// should be understood on a channel outside of this proposal. In the case that the request
93	/// cannot be serviced because `when` is too old a block then a `notify_revenue` message must
94	/// still be returned, but its `revenue` field may be `None`.
95	fn request_revenue_info_at(when: RCBlockNumberOf<Self>);
96
97	/// Instructs the Relay-chain to add the `amount` of DOT to the Instantaneous Coretime Market
98	/// Credit account of `who`.
99	///
100	/// It is expected that Instantaneous Coretime Market Credit on the Relay-chain is NOT
101	/// transferable and only redeemable when used to assign cores in the Instantaneous Coretime
102	/// Pool.
103	fn credit_account(who: Self::AccountId, amount: Self::Balance);
104
105	/// Instructs the Relay-chain to ensure that the core indexed as `core` is utilised for a number
106	/// of assignments in specific ratios given by `assignment` starting as soon after `begin` as
107	/// possible. Core assignments take the form of a `CoreAssignment` value which can either task
108	/// the core to a `ParaId` value or indicate that the core should be used in the Instantaneous
109	/// Pool. Each assignment comes with a ratio value, represented as the numerator of the fraction
110	/// with a denominator of 57,600.
111	///
112	/// If `end_hint` is `Some` and the inner is greater than the current block number, then the
113	/// Relay-chain should optimize in the expectation of receiving a new `assign_core(core, ...)`
114	/// message at or prior to the block number of the inner value. Specific functionality should
115	/// remain unchanged regardless of the `end_hint` value.
116	fn assign_core(
117		core: CoreIndex,
118		begin: RCBlockNumberOf<Self>,
119		assignment: Vec<(CoreAssignment, PartsOf57600)>,
120		end_hint: Option<RCBlockNumberOf<Self>>,
121	);
122
123	/// A hook supposed to be called right after a new timeslice has begun. Likely to be used for
124	/// batching different matters happened during the timeslice that may benefit from batched
125	/// processing.
126	fn on_new_timeslice(_timeslice: Timeslice) {}
127}
128
129impl CoretimeInterface for () {
130	type AccountId = ();
131	type Balance = u64;
132	type RelayChainBlockNumberProvider = ();
133
134	fn request_core_count(_count: CoreIndex) {}
135	fn request_revenue_info_at(_when: RCBlockNumberOf<Self>) {}
136	fn credit_account(_who: Self::AccountId, _amount: Self::Balance) {}
137	fn assign_core(
138		_core: CoreIndex,
139		_begin: RCBlockNumberOf<Self>,
140		_assignment: Vec<(CoreAssignment, PartsOf57600)>,
141		_end_hint: Option<RCBlockNumberOf<Self>>,
142	) {
143	}
144}
pallet_broker/coretime_interface.rs

pallet_broker/
coretime_interface.rs
