From 8dbde1f4197df4125dc8f9bc986f263819bb57d5 Mon Sep 17 00:00:00 2001 From: Fabio Lama Date: Fri, 15 Oct 2021 12:28:42 +0200 Subject: [PATCH] Implementers guide: update Collation types (#4084) * Implementers guide: update Collation types * Update roadmap/implementers-guide/src/node/collators/collation-generation.md Co-authored-by: Andronik Ordian * Update roadmap/implementers-guide/src/node/collators/collation-generation.md Co-authored-by: Andronik Ordian * Update roadmap/implementers-guide/src/node/collators/collation-generation.md Co-authored-by: Andronik Ordian * Update roadmap/implementers-guide/src/node/collators/collation-generation.md Co-authored-by: Andronik Ordian * Convert indents to 2 spaces Co-authored-by: Andronik Ordian --- .../node/collators/collation-generation.md | 62 +++++++++++++------ 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/polkadot/roadmap/implementers-guide/src/node/collators/collation-generation.md b/polkadot/roadmap/implementers-guide/src/node/collators/collation-generation.md index 34be8ea7c1..0a17a8619a 100644 --- a/polkadot/roadmap/implementers-guide/src/node/collators/collation-generation.md +++ b/polkadot/roadmap/implementers-guide/src/node/collators/collation-generation.md @@ -21,27 +21,49 @@ Output: `CollationDistributionMessage` The process of generating a collation for a parachain is very parachain-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 Polkadot 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, + /// The horizontal messages sent by the parachain. + pub horizontal_messages: Vec>, /// New validation code. pub new_validation_code: Option, /// The head-data produced as a result of execution. pub head_data: HeadData, /// Proof to verify the state transition of the parachain. 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. - 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 completly okay to just drop it. - /// However, if it is called, it should be called with the signed statement of a parachain validator seconding the - /// collation. - result_sender: Option>, + /// 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 parachain validator seconding the + /// collation. + pub result_sender: Option>, +} + +/// 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. @@ -51,18 +73,22 @@ pub struct CollationResult { /// /// Returns an optional [`CollationResult`]. pub type CollatorFn = Box< - dyn Fn(Hash, &PersistedValidationData) -> Pin> + Send>> - + Send - + Sync, + dyn Fn( + Hash, + &PersistedValidationData, + ) -> Pin> + Send>> + + Send + + Sync, >; -struct CollationGenerationConfig { - key: CollatorPair, - /// Collate will be called with the relay chain hash the parachain should build - /// a block on and the `ValidationData` that provides information about the state - /// of the parachain on the relay chain. - collator: CollatorFn, - para_id: ParaId, +/// 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: CollatorFn, + /// The parachain that this collator collates for + pub para_id: ParaId, } ```