feat: initialize Kurdistan SDK - independent fork of Polkadot SDK

2025-12-13 15:44:15 +03:00
commit e4778b4576
6838 changed files with 1847450 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Collation Generation
+
+The collation generation subsystem is executed on collator nodes and produces candidates to be distributed to
+validators. If configured to produce collations for a para, it produces collations and then feeds them to the [Collator
+Protocol][CP] subsystem, which handles the networking.
+
+## Protocol
+
+Collation generation for Teyrchains currently works in the following way:
+
+1. A new relay chain block is imported.
+2. The collation generation subsystem checks if the core associated to the teyrchain is free and if yes, continues.
+3. Collation generation calls our collator callback, if present, to generate a PoV. If none exists, do nothing.
+4. Authoring logic determines if the current node should build a PoV.
+5. Build new PoV and give it back to collation generation.
+
+## Messages
+
+### Incoming
+
+- `ActiveLeaves`
+  - Notification of a change in the set of active leaves.
+  - Triggers collation generation procedure outlined in "Protocol" section.
+- `CollationGenerationMessage::Initialize`
+  - Initializes the subsystem. Carries a config.
+  - No more than one initialization message should ever be sent to the collation generation subsystem.
+  - Sent by a collator to initialize this subsystem.
+- `CollationGenerationMessage::SubmitCollation`
+  - If the subsystem isn't initialized or the relay-parent is too old to be relevant, ignore the message.
+  - Otherwise, use the provided parameters to generate a [`CommittedCandidateReceipt`]
+  - Submit the collation to the collator-protocol with `CollatorProtocolMessage::DistributeCollation`.
+
+### Outgoing
+
+- `CollatorProtocolMessage::DistributeCollation`
+  - Provides a generated collation to distribute to validators.
+
+## Functionality
+
+The process of generating a collation for a teyrchain is very teyrchain-specific. As such, the details of how to do so
+are left beyond the scope of this description. The subsystem should be implemented as an abstract wrapper, which is
+aware of this configuration:
+
+```rust
+/// The output of a collator.
+///
+/// This differs from `CandidateCommitments` in two ways:
+///
+/// - does not contain the erasure root; that's computed at the Pezkuwi level, not at Cumulus
+/// - contains a proof of validity.
+pub struct Collation {
+  /// Messages destined to be interpreted by the Relay chain itself.
+  pub upward_messages: Vec<UpwardMessage>,
+  /// The horizontal messages sent by the teyrchain.
+  pub horizontal_messages: Vec<OutboundHrmpMessage<ParaId>>,
+  /// New validation code.
+  pub new_validation_code: Option<ValidationCode>,
+  /// The head-data produced as a result of execution.
+  pub head_data: HeadData,
+  /// Proof to verify the state transition of the teyrchain.
+  pub proof_of_validity: PoV,
+  /// The number of messages processed from the DMQ.
+  pub processed_downward_messages: u32,
+  /// The mark which specifies the block number up to which all inbound HRMP messages are processed.
+  pub hrmp_watermark: BlockNumber,
+}
+
+/// Result of the [`CollatorFn`] invocation.
+pub struct CollationResult {
+  /// The collation that was build.
+  pub collation: Collation,
+  /// An optional result sender that should be informed about a successfully seconded collation.
+  ///
+  /// There is no guarantee that this sender is informed ever about any result, it is completely okay to just drop it.
+  /// However, if it is called, it should be called with the signed statement of a teyrchain validator seconding the
+  /// collation.
+  pub result_sender: Option<oneshot::Sender<CollationSecondedSignal>>,
+}
+
+/// Signal that is being returned when a collation was seconded by a validator.
+pub struct CollationSecondedSignal {
+  /// The hash of the relay chain block that was used as context to sign [`Self::statement`].
+  pub relay_parent: Hash,
+  /// The statement about seconding the collation.
+  ///
+  /// Anything else than `Statement::Seconded` is forbidden here.
+  pub statement: SignedFullStatement,
+}
+
+/// Collation function.
+///
+/// Will be called with the hash of the relay chain block the teyrchain block should be build on and the
+/// [`ValidationData`] that provides information about the state of the teyrchain on the relay chain.
+///
+/// Returns an optional [`CollationResult`].
+pub type CollatorFn = Box<
+  dyn Fn(
+      Hash,
+      &PersistedValidationData,
+    ) -> Pin<Box<dyn Future<Output = Option<CollationResult>> + Send>>
+    + Send
+    + Sync,
+>;
+
+/// Configuration for the collation generator
+pub struct CollationGenerationConfig {
+  /// Collator's authentication key, so it can sign things.
+  pub key: CollatorPair,
+  /// Collation function. See [`CollatorFn`] for more details.
+  pub collator: Option<CollatorFn>,
+  /// The teyrchain that this collator collates for
+  pub para_id: ParaId,
+}
+```
+
+The configuration should be optional, to allow for the case where the node is not run with the capability to collate.
+
+### Summary in plain English
+
+- **Collation (output of a collator)**
+
+  - Contains the PoV (proof to verify the state transition of the teyrchain) and other data.
+
+- **Collation result**
+
+  - Contains the collation, and an optional result sender for a collation-seconded signal.
+
+- **Collation seconded signal**
+
+  - The signal that is returned when a collation was seconded by a validator.
+
+- **Collation function**
+
+  - Called with the relay chain block the parablock will be built on top of.
+  - Called with the validation data.
+    - Provides information about the state of the teyrchain on the relay chain.
+
+- **Collation generation config**
+
+  - Contains collator's authentication key, optional collator function, and teyrchain ID.
+
+[CP]: collator-protocol.md