Sassafras primitives

Cargo.toml

@@ -29,6 +29,26 @@ frame-support = { path = "frame/support" }
 
 node-cli = { path = "bin/node/cli" }
 
+# Dependencies necessary to optionaly build Sassafras related crates.
+#
+# Sassafras requires to enable `bandersnatch-experimental` feature and this ends up
+# being transitively enabled in:
+#  sp-consensus-sassafras → sp-application-crypto → sp-io → sp-keystore
+# Bandersnatch experimental api is thus exposed in the `Keystore` trait and we require
+# to expose these functions implementations in the client keystore as well.
+# At this stage, by default, we don't want this.
+# We prefer instead to keep sassafras crates (and thus bandersnatch feature) out of
+# workspace and optionally enabled via the `sassafras-experimental` feature.
+sp-consensus-sassafras = { path = "primitives/consensus/sassafras", optional = true }
+sc-keystore = { path = "client/keystore" }
+
+# Feature to unlock "Sassafras" experimental crates
+[features]
+sassafras-experimental = [
+	"sc-keystore/bandersnatch-experimental",
+	"sp-consensus-sassafras",
+]
+
 # Exists here to be backwards compatible and to support `cargo run` in the workspace.
 #
 # Just uses the `node-cli` main binary. `node-cli` itself also again exposes the node as
@@ -312,6 +332,10 @@ members = [
 	"utils/binary-merkle-tree",
 ]
 
+exclude = [
+	"primitives/consensus/sassafras",
+]
+
 # The list of dependencies below (which can be both direct and indirect dependencies) are crates
 # that are suspected to be CPU-intensive, and that are unlikely to require debugging (as some of
 # their debug info might be missing) or to require to be frequently recompiled. We compile these

primitives/consensus/sassafras/Cargo.toml

@@ -0,0 +1,50 @@
+[package]
+name = "sp-consensus-sassafras"
+version = "0.3.4-dev"
+authors = ["Parity Technologies <[email protected]>"]
+description = "Primitives for Sassafras consensus"
+edition = "2021"
+license = "Apache-2.0"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+documentation = "https://docs.rs/sp-consensus-sassafras"
+readme = "README.md"
+publish = false
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+scale-codec = { package = "parity-scale-codec", version = "3.2.2", default-features = false }
+scale-info = { version = "2.5.0", default-features = false, features = ["derive"] }
+serde = { version = "1.0.163", default-features = false, features = ["derive"], optional = true }
+sp-api = { version = "4.0.0-dev", default-features = false, path = "../../api" }
+sp-application-crypto = { version = "23.0.0", default-features = false, path = "../../application-crypto", features = ["bandersnatch-experimental"] }
+sp-consensus-slots = { version = "0.10.0-dev", default-features = false, path = "../slots" }
+sp-core = { version = "21.0.0", default-features = false, path = "../../core", features = ["bandersnatch-experimental"] }
+sp-runtime = { version = "24.0.0", default-features = false, path = "../../runtime" }
+sp-std = { version = "8.0.0", default-features = false, path = "../../std" }
+
+[features]
+default = [ "std" ]
+std = [
+	"scale-codec/std",
+	"scale-info/std",
+	"serde/std",
+	"sp-api/std",
+	"sp-application-crypto/std",
+	"sp-consensus-slots/std",
+	"sp-core/std",
+	"sp-runtime/std",
+	"sp-std/std",
+]
+
+# Serde support without relying on std features.
+serde = [
+	"dep:serde",
+	"scale-info/serde",
+	"sp-application-crypto/serde",
+	"sp-consensus-slots/serde",
+	"sp-core/serde",
+	"sp-runtime/serde",
+]

primitives/consensus/sassafras/README.md

@@ -0,0 +1,12 @@
+Primitives for SASSAFRAS.
+
+# ⚠️ WARNING ⚠️
+
+The crate interfaces and structures are highly experimental and may be subject
+to significant changes.
+
+Depends on upstream experimental feature: `bandersnatch-experimental`.
+
+These structs were mostly extracted from the main SASSAFRAS protocol PR: https://github.com/paritytech/substrate/pull/11879.
+
+Tracking issue: https://github.com/paritytech/substrate/issues/11515.

primitives/consensus/sassafras/src/digests.rs

@@ -0,0 +1,98 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Sassafras digests structures and helpers.
+
+use crate::{
+	ticket::TicketClaim, vrf::VrfSignature, AuthorityId, AuthorityIndex, AuthoritySignature,
+	EpochConfiguration, Randomness, Slot, SASSAFRAS_ENGINE_ID,
+};
+
+use scale_codec::{Decode, Encode, MaxEncodedLen};
+use scale_info::TypeInfo;
+
+use sp_runtime::{DigestItem, RuntimeDebug};
+use sp_std::vec::Vec;
+
+/// Epoch slot claim digest entry.
+///
+/// This is mandatory for each block.
+#[derive(Clone, RuntimeDebug, Encode, Decode, MaxEncodedLen, TypeInfo)]
+pub struct SlotClaim {
+	/// Authority index that claimed the slot.
+	pub authority_idx: AuthorityIndex,
+	/// Corresponding slot number.
+	pub slot: Slot,
+	/// Slot claim VRF signature.
+	pub vrf_signature: VrfSignature,
+	/// Ticket auxiliary information for claim check.
+	pub ticket_claim: Option<TicketClaim>,
+}
+
+/// Information about the next epoch.
+///
+/// This is mandatory in the first block of each epoch.
+#[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)]
+pub struct NextEpochDescriptor {
+	/// Authorities list.
+	pub authorities: Vec<AuthorityId>,
+	/// Epoch randomness.
+	pub randomness: Randomness,
+	/// Epoch configurable parameters.
+	///
+	/// If not present previous epoch parameters are used.
+	pub config: Option<EpochConfiguration>,
+}
+
+/// Runtime digest entries.
+///
+/// Entries which may be generated by on-chain code.
+#[derive(Decode, Encode, Clone, PartialEq, Eq)]
+pub enum ConsensusLog {
+	/// Provides information about the next epoch parameters.
+	#[codec(index = 1)]
+	NextEpochData(NextEpochDescriptor),
+	/// Disable the authority with given index.
+	#[codec(index = 2)]
+	OnDisabled(AuthorityIndex),
+}
+
+impl TryFrom<&DigestItem> for SlotClaim {
+	type Error = ();
+	fn try_from(item: &DigestItem) -> Result<Self, Self::Error> {
+		item.pre_runtime_try_to(&SASSAFRAS_ENGINE_ID).ok_or(())
+	}
+}
+
+impl From<&SlotClaim> for DigestItem {
+	fn from(claim: &SlotClaim) -> Self {
+		DigestItem::PreRuntime(SASSAFRAS_ENGINE_ID, claim.encode())
+	}
+}
+
+impl TryFrom<&DigestItem> for AuthoritySignature {
+	type Error = ();
+	fn try_from(item: &DigestItem) -> Result<Self, Self::Error> {
+		item.seal_try_to(&SASSAFRAS_ENGINE_ID).ok_or(())
+	}
+}
+
+impl From<&AuthoritySignature> for DigestItem {
+	fn from(signature: &AuthoritySignature) -> Self {
+		DigestItem::Seal(SASSAFRAS_ENGINE_ID, signature.encode())
+	}
+}