diff --git a/polkadot/Cargo.lock b/polkadot/Cargo.lock index 33218f0d08..f07dd56dda 100644 --- a/polkadot/Cargo.lock +++ b/polkadot/Cargo.lock @@ -5189,6 +5189,7 @@ dependencies = [ "parity-scale-codec", "polkadot-primitives", "polkadot-statement-table", + "sp-consensus-vrf", "sp-core", "sp-runtime", ] diff --git a/polkadot/node/primitives/Cargo.toml b/polkadot/node/primitives/Cargo.toml index b391623703..888b13f0d3 100644 --- a/polkadot/node/primitives/Cargo.toml +++ b/polkadot/node/primitives/Cargo.toml @@ -12,3 +12,4 @@ polkadot-statement-table = { path = "../../statement-table" } parity-scale-codec = { version = "1.3.5", default-features = false, features = ["derive"] } runtime_primitives = { package = "sp-runtime", git = "https://github.com/paritytech/substrate", branch = "master", default-features = false } sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" } +sp-consensus-vrf = { git = "https://github.com/paritytech/substrate", branch = "master" } diff --git a/polkadot/node/primitives/src/approval.rs b/polkadot/node/primitives/src/approval.rs new file mode 100644 index 0000000000..32b4e5af70 --- /dev/null +++ b/polkadot/node/primitives/src/approval.rs @@ -0,0 +1,105 @@ +// Copyright 2017-2020 Parity Technologies (UK) Ltd. +// This file is part of Polkadot. + +// Polkadot is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Polkadot is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Polkadot. If not, see . + +//! Types relevant for approval. + +pub use sp_consensus_vrf::schnorrkel::{VRFOutput, VRFProof}; + +use polkadot_primitives::v1::{ + CandidateHash, Hash, ValidatorIndex, Signed, ValidatorSignature, CoreIndex, +}; +use parity_scale_codec::{Encode, Decode}; + +/// Validators assigning to check a particular candidate are split up into tranches. +/// Earlier tranches of validators check first, with later tranches serving as backup. +pub type DelayTranche = u32; + +/// A static context used for all relay-vrf-modulo VRFs. +pub const RELAY_VRF_MODULO_CONTEXT: &str = "A&V MOD"; + +/// A static context used for all relay-vrf-delay VRFs. +pub const RELAY_VRF_DELAY_CONTEXT: &str = "A&V TRANCHE"; + +/// random bytes derived from the VRF submitted within the block by the +/// block author as a credential and used as input to approval assignment criteria. +#[derive(Debug, Clone, Encode, Decode)] +pub struct RelayVRF(pub [u8; 32]); + +/// Different kinds of input data or criteria that can prove a validator's assignment +/// to check a particular parachain. +#[derive(Debug, Clone, Encode, Decode)] +pub enum AssignmentCertKind { + /// An assignment story based on the VRF that authorized the relay-chain block where the + /// candidate was included combined with a sample number. + /// + /// The context used to produce bytes is [`RELAY_VRF_MODULO_CONTEXT`] + RelayVRFModulo { + /// The sample number used in this cert. + sample: u32, + }, + /// An assignment story based on the VRF that authorized the relay-chain block where the + /// candidate was included combined with the index of a particular core. + /// + /// The context is [`RELAY_VRF_DELAY_CONTEXT`] + RelayVRFDelay { + /// The core index chosen in this cert. + core_index: CoreIndex, + }, +} + +/// A certification of assignment. +#[derive(Debug, Clone, Encode, Decode)] +pub struct AssignmentCert { + /// The criterion which is claimed to be met by this cert. + pub kind: AssignmentCertKind, + /// The VRF showing the criterion is met. + pub vrf: (VRFOutput, VRFProof), +} + +/// An assignment crt which refers to the candidate under which the assignment is +/// relevant by block hash. +#[derive(Debug, Clone, Encode, Decode)] +pub struct IndirectAssignmentCert { + /// A block hash where the candidate appears. + pub block_hash: Hash, + /// The validator index. + pub validator: ValidatorIndex, + /// The cert itself. + pub cert: AssignmentCert, +} + +/// A vote of approval on a candidate. +#[derive(Debug, Clone, Encode, Decode)] +pub struct ApprovalVote(pub CandidateHash); + +/// An approval vote signed by some validator. +pub type SignedApprovalVote = Signed; + +/// A signed approval vote which references the candidate indirectly via the block. +/// +/// In practice, we have a look-up from block hash and candidate index to candidate hash, +/// so this can be transformed into a `SignedApprovalVote`. +#[derive(Debug, Clone, Encode, Decode)] +pub struct IndirectSignedApprovalVote { + /// A block hash where the candidate appears. + pub block_hash: Hash, + /// The index of the candidate in the list of candidates fully included as-of the block. + pub candidate_index: u32, + /// The validator index. + pub validator: ValidatorIndex, + /// The signature by the validator. + pub signature: ValidatorSignature, +} diff --git a/polkadot/node/primitives/src/lib.rs b/polkadot/node/primitives/src/lib.rs index 0ea2799daa..82ac5dd28e 100644 --- a/polkadot/node/primitives/src/lib.rs +++ b/polkadot/node/primitives/src/lib.rs @@ -41,6 +41,8 @@ use std::pin::Pin; pub use sp_core::traits::SpawnNamed; +pub mod approval; + /// A statement, where the candidate receipt is included in the `Seconded` variant. /// /// This is the committed candidate receipt instead of the bare candidate receipt. As such, diff --git a/polkadot/roadmap/implementers-guide/src/types/approval.md b/polkadot/roadmap/implementers-guide/src/types/approval.md index c510137a99..1db305e760 100644 --- a/polkadot/roadmap/implementers-guide/src/types/approval.md +++ b/polkadot/roadmap/implementers-guide/src/types/approval.md @@ -98,40 +98,4 @@ struct CheckedAssignmentCert { ```rust type DelayTranche = u32; -``` - -## RelayVRFStory - -Assignment criteria are based off of possible stories about the relay-chain block that included the candidate. More information on stories is available in [the informational page on approvals.](../protocol-approval.md#stories). - -```rust -/// A story based on the VRF that authorized the relay-chain block where the candidate was -/// included. -/// -/// VRF Context is "A&V RC-VRF" -struct RelayVRFStory(VRFInOut); -``` - -## RelayEquivocationStory - -```rust -/// A story based on the candidate hash itself. Should be used when a candidate is an -/// equivocation: when there are two relay-chain blocks with the same RelayVRFStory, but only -/// one contains the candidate. -/// -/// VRF Context is "A&V RC-EQUIV" -struct RelayEquivocationStory(Hash); -``` - -## ExecutionTimePair - -```rust -struct ExecutionTimePair { - // The absolute time in milliseconds that the validator claims to have taken - // with the block. - absolute: u32, - // The validator's believed ratio in execution time to the average, expressed as a fixed-point - // 16-bit unsigned integer with 8 bits before and after the point. - ratio: FixedU16, -} ``` \ No newline at end of file