feat: initialize Kurdistan SDK - independent fork of Polkadot SDK

pezkuwi/roadmap/implementers-guide/src/runtime/configuration.md

@@ -0,0 +1,72 @@
+# Configuration Pallet
+
+This module is responsible for managing all configuration of the teyrchain host in-flight. It provides a central point
+for configuration updates to prevent races between configuration changes and teyrchain-processing logic. Configuration
+can only change during the session change routine, and as this module handles the session change notification first it
+provides an invariant that the configuration does not change throughout the entire session. Both the
+[scheduler](scheduler.md) and [inclusion](inclusion.md) modules rely on this invariant to ensure proper behavior of the
+scheduler.
+
+The configuration that we will be tracking is the [`HostConfiguration`](../types/runtime.md#host-configuration) struct.
+
+## Storage
+
+The configuration module is responsible for two main pieces of storage.
+
+```rust
+/// The current configuration to be used.
+Configuration: HostConfiguration;
+/// A pending configuration to be applied on session change.
+PendingConfigs: Vec<(SessionIndex, HostConfiguration)>;
+/// A flag that says if the consistency checks should be omitted.
+BypassConsistencyCheck: bool;
+```
+
+## Session change
+
+The session change routine works as follows:
+
+- If there is no pending configurations, then return early.
+- Take all pending configurations that are less than or equal to the current session index.
+  - Get the pending configuration with the highest session index and apply it to the current configuration. Discard the
+    earlier ones if any.
+
+## Routines
+
+```rust
+enum InconsistentError {
+  // ...
+}
+
+impl HostConfiguration {
+  fn check_consistency(&self) -> Result<(), InconsistentError> { /* ... */ }
+}
+
+/// Get the host configuration.
+pub fn configuration() -> HostConfiguration {
+  Configuration::get()
+}
+
+/// Schedules updating the host configuration. The update is given by the `updater` closure. The
+/// closure takes the current version of the configuration and returns the new version.
+/// Returns an `Err` if the closure returns a broken configuration. However, there are a couple of
+/// exceptions:
+///
+/// - if the configuration that was passed in the closure is already broken, then it will pass the
+/// update: you cannot break something that is already broken.
+/// - If the `BypassConsistencyCheck` flag is set, then the checks will be skipped.
+///
+/// The changes made by this function will always be scheduled at session X, where X is the current session index + 2.
+/// If there is already a pending update for X, then the closure will receive the already pending configuration for
+/// session X.
+///
+/// If there is already a pending update for the current session index + 1, then it won't be touched. Otherwise,
+/// that would violate the promise of this function that changes will be applied on the second session change (cur + 2).
+fn schedule_config_update(updater: impl FnOnce(&mut HostConfiguration<BlockNumberFor<T>>)) -> DispatchResult
+```
+
+## Entry-points
+
+The Configuration module exposes an entry point for each configuration member. These entry-points accept calls only from
+governance origins. These entry-points will use the `update_configuration` routine to update the specific configuration
+field.