From 095f4bd9ae6ed691b19768f7daac9e6833f425ed Mon Sep 17 00:00:00 2001 From: Davide Galassi Date: Fri, 1 Dec 2023 16:39:07 +0100 Subject: [PATCH] Sassafras Consensus Pallet (#1577) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR introduces the pallet for Sassafras consensus. ## Non Goals The pallet delivers only the bare-bones and doesn't deliver support for auxiliary functionalities such as equivocation report and support for epoch change via session pallet. These functionalities were drafted in the [main PR](/~https://github.com/paritytech/polkadot-sdk/pull/1336), but IMO is better to introduce this auxiliary stuff in a follow up PR and after client code. ## Potential follow ups /~https://github.com/paritytech/polkadot-sdk/issues/2364 --------- Co-authored-by: Sebastian Kunert Co-authored-by: Koute Co-authored-by: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com> Co-authored-by: André Silva <123550+andresilva@users.noreply.github.com> Co-authored-by: Bastian Köcher --- Cargo.lock | 50 +- Cargo.toml | 1 + substrate/frame/sassafras/Cargo.toml | 59 + substrate/frame/sassafras/README.md | 8 + substrate/frame/sassafras/src/benchmarking.rs | 272 +++++ .../src/data/25_tickets_100_auths.bin | Bin 0 -> 24728 bytes .../sassafras/src/data/benchmark-results.md | 99 ++ .../frame/sassafras/src/data/tickets-sort.md | 274 +++++ .../frame/sassafras/src/data/tickets-sort.png | Bin 0 -> 33919 bytes substrate/frame/sassafras/src/lib.rs | 1081 +++++++++++++++++ substrate/frame/sassafras/src/mock.rs | 343 ++++++ substrate/frame/sassafras/src/tests.rs | 874 +++++++++++++ substrate/frame/sassafras/src/weights.rs | 425 +++++++ .../primitives/consensus/sassafras/Cargo.toml | 12 +- .../primitives/consensus/sassafras/README.md | 12 +- .../consensus/sassafras/src/digests.rs | 6 +- .../primitives/consensus/sassafras/src/lib.rs | 38 +- .../consensus/sassafras/src/ticket.rs | 43 +- .../primitives/consensus/sassafras/src/vrf.rs | 2 +- substrate/primitives/core/Cargo.toml | 2 +- substrate/primitives/core/src/bandersnatch.rs | 289 +++-- 21 files changed, 3763 insertions(+), 127 deletions(-) create mode 100644 substrate/frame/sassafras/Cargo.toml create mode 100644 substrate/frame/sassafras/README.md create mode 100644 substrate/frame/sassafras/src/benchmarking.rs create mode 100644 substrate/frame/sassafras/src/data/25_tickets_100_auths.bin create mode 100644 substrate/frame/sassafras/src/data/benchmark-results.md create mode 100644 substrate/frame/sassafras/src/data/tickets-sort.md create mode 100644 substrate/frame/sassafras/src/data/tickets-sort.png create mode 100644 substrate/frame/sassafras/src/lib.rs create mode 100644 substrate/frame/sassafras/src/mock.rs create mode 100644 substrate/frame/sassafras/src/tests.rs create mode 100644 substrate/frame/sassafras/src/weights.rs diff --git a/Cargo.lock b/Cargo.lock index 9c5a2c57da00..241a2fd3d158 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -544,7 +544,7 @@ dependencies = [ [[package]] name = "ark-secret-scalar" version = "0.0.2" -source = "git+/~https://github.com/w3f/ring-vrf?rev=3ddc205#3ddc2051066c4b3f0eadd0ba5700df12500d9754" +source = "git+/~https://github.com/w3f/ring-vrf?rev=2019248#2019248785389b3246d55b1c3b0e9bdef4454cb7" dependencies = [ "ark-ec", "ark-ff", @@ -552,7 +552,7 @@ dependencies = [ "ark-std", "ark-transcript", "digest 0.10.7", - "rand_core 0.6.4", + "getrandom_or_panic", "zeroize", ] @@ -593,7 +593,7 @@ dependencies = [ [[package]] name = "ark-transcript" version = "0.0.2" -source = "git+/~https://github.com/w3f/ring-vrf?rev=3ddc205#3ddc2051066c4b3f0eadd0ba5700df12500d9754" +source = "git+/~https://github.com/w3f/ring-vrf?rev=2019248#2019248785389b3246d55b1c3b0e9bdef4454cb7" dependencies = [ "ark-ff", "ark-serialize", @@ -1225,7 +1225,7 @@ dependencies = [ [[package]] name = "bandersnatch_vrfs" version = "0.0.4" -source = "git+/~https://github.com/w3f/ring-vrf?rev=3ddc205#3ddc2051066c4b3f0eadd0ba5700df12500d9754" +source = "git+/~https://github.com/w3f/ring-vrf?rev=2019248#2019248785389b3246d55b1c3b0e9bdef4454cb7" dependencies = [ "ark-bls12-381", "ark-ec", @@ -2716,7 +2716,7 @@ dependencies = [ [[package]] name = "common" version = "0.1.0" -source = "git+/~https://github.com/burdges/ring-proof?branch=patch-1#05a756076cb20f981a52afea3a620168de49f95f" +source = "git+/~https://github.com/w3f/ring-proof#61e7b528bc0170d6bf541be32440d569b784425d" dependencies = [ "ark-ec", "ark-ff", @@ -2724,6 +2724,7 @@ dependencies = [ "ark-serialize", "ark-std", "fflonk", + "getrandom_or_panic", "merlin 3.0.0", "rand_chacha 0.3.1", ] @@ -4525,7 +4526,7 @@ checksum = "86e3bdc80eee6e16b2b6b0f87fbc98c04bee3455e35174c0de1a125d0688c632" [[package]] name = "dleq_vrf" version = "0.0.2" -source = "git+/~https://github.com/w3f/ring-vrf?rev=3ddc205#3ddc2051066c4b3f0eadd0ba5700df12500d9754" +source = "git+/~https://github.com/w3f/ring-vrf?rev=2019248#2019248785389b3246d55b1c3b0e9bdef4454cb7" dependencies = [ "ark-ec", "ark-ff", @@ -4535,7 +4536,6 @@ dependencies = [ "ark-std", "ark-transcript", "arrayvec 0.7.4", - "rand_core 0.6.4", "zeroize", ] @@ -4869,9 +4869,9 @@ dependencies = [ [[package]] name = "env_logger" -version = "0.10.0" +version = "0.10.1" source = "registry+/~https://github.com/rust-lang/crates.io-index" -checksum = "85cdab6a89accf66733ad5a1693a4dcced6aeff64602b634530dd73c1f3ee9f0" +checksum = "95b3f3e67048839cb0d0781f445682a35113da7121f7c949db0e2be96a4fbece" dependencies = [ "humantime", "is-terminal", @@ -5132,7 +5132,7 @@ version = "0.1.6" source = "registry+/~https://github.com/rust-lang/crates.io-index" checksum = "84f2e425d9790201ba4af4630191feac6dcc98765b118d4d18e91d23c2353866" dependencies = [ - "env_logger 0.10.0", + "env_logger 0.10.1", "log", ] @@ -5912,6 +5912,16 @@ dependencies = [ "wasi 0.11.0+wasi-snapshot-preview1", ] +[[package]] +name = "getrandom_or_panic" +version = "0.0.3" +source = "registry+/~https://github.com/rust-lang/crates.io-index" +checksum = "6ea1015b5a70616b688dc230cfe50c8af89d972cb132d5a622814d29773b10b9" +dependencies = [ + "rand 0.8.5", + "rand_core 0.6.4", +] + [[package]] name = "ghash" version = "0.4.4" @@ -10509,6 +10519,24 @@ dependencies = [ "sp-std 8.0.0", ] +[[package]] +name = "pallet-sassafras" +version = "0.3.5-dev" +dependencies = [ + "array-bytes 6.1.0", + "frame-benchmarking", + "frame-support", + "frame-system", + "log", + "parity-scale-codec", + "scale-info", + "sp-consensus-sassafras", + "sp-core", + "sp-io", + "sp-runtime", + "sp-std 8.0.0", +] + [[package]] name = "pallet-scheduler" version = "4.0.0-dev" @@ -14164,7 +14192,7 @@ dependencies = [ [[package]] name = "ring" version = "0.1.0" -source = "git+/~https://github.com/burdges/ring-proof?branch=patch-1#05a756076cb20f981a52afea3a620168de49f95f" +source = "git+/~https://github.com/w3f/ring-proof#61e7b528bc0170d6bf541be32440d569b784425d" dependencies = [ "ark-ec", "ark-ff", diff --git a/Cargo.toml b/Cargo.toml index 0a7bf912e48a..5fb7c0f2315b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -346,6 +346,7 @@ members = [ "substrate/frame/root-testing", "substrate/frame/safe-mode", "substrate/frame/salary", + "substrate/frame/sassafras", "substrate/frame/scheduler", "substrate/frame/scored-pool", "substrate/frame/session", diff --git a/substrate/frame/sassafras/Cargo.toml b/substrate/frame/sassafras/Cargo.toml new file mode 100644 index 000000000000..7ab2e2e17702 --- /dev/null +++ b/substrate/frame/sassafras/Cargo.toml @@ -0,0 +1,59 @@ +[package] +name = "pallet-sassafras" +version = "0.3.5-dev" +authors = ["Parity Technologies "] +edition = "2021" +license = "Apache-2.0" +homepage = "https://substrate.io" +repository = "/~https://github.com/paritytech/substrate/" +description = "Consensus extension module for Sassafras consensus." +readme = "README.md" +publish = false + +[package.metadata.docs.rs] +targets = ["x86_64-unknown-linux-gnu"] + +[dependencies] +scale-codec = { package = "parity-scale-codec", version = "3.6.1", default-features = false, features = ["derive"] } +scale-info = { version = "2.5.0", default-features = false, features = ["derive"] } +frame-benchmarking = { path = "../benchmarking", default-features = false, optional = true } +frame-support = { path = "../support", default-features = false } +frame-system = { path = "../system", default-features = false } +log = { version = "0.4.17", default-features = false } +sp-consensus-sassafras = { path = "../../primitives/consensus/sassafras", default-features = false, features = ["serde"] } +sp-io = { path = "../../primitives/io", default-features = false } +sp-runtime = { path = "../../primitives/runtime", default-features = false } +sp-std = { path = "../../primitives/std", default-features = false } + +[dev-dependencies] +array-bytes = "6.1" +sp-core = { path = "../../primitives/core" } + +[features] +default = [ "std" ] +std = [ + "frame-benchmarking?/std", + "frame-support/std", + "frame-system/std", + "log/std", + "scale-codec/std", + "scale-info/std", + "sp-consensus-sassafras/std", + "sp-io/std", + "sp-runtime/std", + "sp-std/std", +] +runtime-benchmarks = [ + "frame-benchmarking/runtime-benchmarks", + "frame-support/runtime-benchmarks", + "frame-system/runtime-benchmarks", + "sp-runtime/runtime-benchmarks", +] +try-runtime = [ + "frame-support/try-runtime", + "frame-system/try-runtime", + "sp-runtime/try-runtime", +] +# Construct dummy ring context on genesis. +# Mostly used for testing and development. +construct-dummy-ring-context = [] diff --git a/substrate/frame/sassafras/README.md b/substrate/frame/sassafras/README.md new file mode 100644 index 000000000000..f0e24a053557 --- /dev/null +++ b/substrate/frame/sassafras/README.md @@ -0,0 +1,8 @@ +Runtime module for SASSAFRAS consensus. + +- Tracking issue: /~https://github.com/paritytech/polkadot-sdk/issues/41 +- Protocol RFC proposal: /~https://github.com/polkadot-fellows/RFCs/pull/26 + +# ⚠️ WARNING ⚠️ + +The crate interfaces and structures are experimental and may be subject to changes. diff --git a/substrate/frame/sassafras/src/benchmarking.rs b/substrate/frame/sassafras/src/benchmarking.rs new file mode 100644 index 000000000000..95a2b4bbce4e --- /dev/null +++ b/substrate/frame/sassafras/src/benchmarking.rs @@ -0,0 +1,272 @@ +// 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. + +//! Benchmarks for the Sassafras pallet. + +use crate::*; +use sp_consensus_sassafras::{vrf::VrfSignature, EphemeralPublic, EpochConfiguration}; + +use frame_benchmarking::v2::*; +use frame_support::traits::Hooks; +use frame_system::RawOrigin; + +const LOG_TARGET: &str = "sassafras::benchmark"; + +const TICKETS_DATA: &[u8] = include_bytes!("data/25_tickets_100_auths.bin"); + +fn make_dummy_vrf_signature() -> VrfSignature { + // This leverages our knowledge about serialized vrf signature structure. + // Mostly to avoid to import all the bandersnatch primitive just for this test. + let buf = [ + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, 0x00, 0x00, 0x04, 0xb5, 0x5f, 0x8e, 0xc7, 0x68, 0xf5, 0x05, 0x3f, 0xa9, + 0x18, 0xca, 0x07, 0x13, 0xc7, 0x4b, 0xa3, 0x9a, 0x97, 0xd3, 0x76, 0x8f, 0x0c, 0xbf, 0x2e, + 0xd4, 0xf9, 0x3a, 0xae, 0xc1, 0x96, 0x2a, 0x64, 0x80, + ]; + VrfSignature::decode(&mut &buf[..]).unwrap() +} + +#[benchmarks] +mod benchmarks { + use super::*; + + // For first block (#1) we do some extra operation. + // But is a one shot operation, so we don't account for it here. + // We use 0, as it will be the path used by all the blocks with n != 1 + #[benchmark] + fn on_initialize() { + let block_num = BlockNumberFor::::from(0u32); + + let slot_claim = SlotClaim { + authority_idx: 0, + slot: Default::default(), + vrf_signature: make_dummy_vrf_signature(), + ticket_claim: None, + }; + frame_system::Pallet::::deposit_log((&slot_claim).into()); + + // We currently don't account for the potential weight added by the `on_finalize` + // incremental sorting of the tickets. + + #[block] + { + // According to `Hooks` trait docs, `on_finalize` `Weight` should be bundled + // together with `on_initialize` `Weight`. + Pallet::::on_initialize(block_num); + Pallet::::on_finalize(block_num) + } + } + + // Weight for the default internal epoch change trigger. + // + // Parameters: + // - `x`: number of authorities (1:100). + // - `y`: epoch length in slots (1000:5000) + // + // This accounts for the worst case which includes: + // - load the full ring context. + // - recompute the ring verifier. + // - sorting the epoch tickets in one shot + // (here we account for the very unluky scenario where we haven't done any sort work yet) + // - pending epoch change config. + // + // For this bench we assume a redundancy factor of 2 (suggested value to be used in prod). + #[benchmark] + fn enact_epoch_change(x: Linear<1, 100>, y: Linear<1000, 5000>) { + let authorities_count = x as usize; + let epoch_length = y as u32; + let redundancy_factor = 2; + + let unsorted_tickets_count = epoch_length * redundancy_factor; + + let mut meta = TicketsMetadata { unsorted_tickets_count, tickets_count: [0, 0] }; + let config = EpochConfiguration { redundancy_factor, attempts_number: 32 }; + + // Triggers ring verifier computation for `x` authorities + let mut raw_data = TICKETS_DATA; + let (authorities, _): (Vec, Vec) = + Decode::decode(&mut raw_data).expect("Failed to decode tickets buffer"); + let next_authorities: Vec<_> = authorities[..authorities_count].to_vec(); + let next_authorities = WeakBoundedVec::force_from(next_authorities, None); + NextAuthorities::::set(next_authorities); + + // Triggers JIT sorting tickets + (0..meta.unsorted_tickets_count) + .collect::>() + .chunks(SEGMENT_MAX_SIZE as usize) + .enumerate() + .for_each(|(segment_id, chunk)| { + let segment = chunk + .iter() + .map(|i| { + let id_bytes = crate::hashing::blake2_128(&i.to_le_bytes()); + TicketId::from_le_bytes(id_bytes) + }) + .collect::>(); + UnsortedSegments::::insert( + segment_id as u32, + BoundedVec::truncate_from(segment), + ); + }); + + // Triggers some code related to config change (dummy values) + NextEpochConfig::::set(Some(config)); + PendingEpochConfigChange::::set(Some(config)); + + // Triggers the cleanup of the "just elapsed" epoch tickets (i.e. the current one) + let epoch_tag = EpochIndex::::get() & 1; + meta.tickets_count[epoch_tag as usize] = epoch_length; + (0..epoch_length).for_each(|i| { + let id_bytes = crate::hashing::blake2_128(&i.to_le_bytes()); + let id = TicketId::from_le_bytes(id_bytes); + TicketsIds::::insert((epoch_tag as u8, i), id); + let body = TicketBody { + attempt_idx: i, + erased_public: EphemeralPublic([i as u8; 32]), + revealed_public: EphemeralPublic([i as u8; 32]), + }; + TicketsData::::set(id, Some(body)); + }); + + TicketsMeta::::set(meta); + + #[block] + { + Pallet::::should_end_epoch(BlockNumberFor::::from(3u32)); + let next_authorities = Pallet::::next_authorities(); + // Using a different set of authorities triggers the recomputation of ring verifier. + Pallet::::enact_epoch_change(Default::default(), next_authorities); + } + } + + #[benchmark] + fn submit_tickets(x: Linear<1, 25>) { + let tickets_count = x as usize; + + let mut raw_data = TICKETS_DATA; + let (authorities, tickets): (Vec, Vec) = + Decode::decode(&mut raw_data).expect("Failed to decode tickets buffer"); + + log::debug!(target: LOG_TARGET, "PreBuiltTickets: {} tickets, {} authorities", tickets.len(), authorities.len()); + + // Set `NextRandomness` to the same value used for pre-built tickets + // (see `make_tickets_data` test). + NextRandomness::::set([0; 32]); + + Pallet::::update_ring_verifier(&authorities); + + // Set next epoch config to accept all the tickets + let next_config = EpochConfiguration { attempts_number: 1, redundancy_factor: u32::MAX }; + NextEpochConfig::::set(Some(next_config)); + + // Use the authorities in the pre-build tickets + let authorities = WeakBoundedVec::force_from(authorities, None); + NextAuthorities::::set(authorities); + + let tickets = tickets[..tickets_count].to_vec(); + let tickets = BoundedVec::truncate_from(tickets); + + log::debug!(target: LOG_TARGET, "Submitting {} tickets", tickets_count); + + #[extrinsic_call] + submit_tickets(RawOrigin::None, tickets); + } + + #[benchmark] + fn plan_config_change() { + let config = EpochConfiguration { redundancy_factor: 1, attempts_number: 10 }; + + #[extrinsic_call] + plan_config_change(RawOrigin::Root, config); + } + + // Construction of ring verifier + #[benchmark] + fn update_ring_verifier(x: Linear<1, 100>) { + let authorities_count = x as usize; + + let mut raw_data = TICKETS_DATA; + let (authorities, _): (Vec, Vec) = + Decode::decode(&mut raw_data).expect("Failed to decode tickets buffer"); + let authorities: Vec<_> = authorities[..authorities_count].to_vec(); + + #[block] + { + Pallet::::update_ring_verifier(&authorities); + } + } + + // Bare loading of ring context. + // + // It is interesting to see how this compares to 'update_ring_verifier', which + // also recomputes and stores the new verifier. + #[benchmark] + fn load_ring_context() { + #[block] + { + let _ring_ctx = RingContext::::get().unwrap(); + } + } + + // Tickets segments sorting function benchmark. + #[benchmark] + fn sort_segments(x: Linear<1, 100>) { + let segments_count = x as u32; + let tickets_count = segments_count * SEGMENT_MAX_SIZE; + + // Construct a bunch of dummy tickets + let tickets: Vec<_> = (0..tickets_count) + .map(|i| { + let body = TicketBody { + attempt_idx: i, + erased_public: EphemeralPublic([i as u8; 32]), + revealed_public: EphemeralPublic([i as u8; 32]), + }; + let id_bytes = crate::hashing::blake2_128(&i.to_le_bytes()); + let id = TicketId::from_le_bytes(id_bytes); + (id, body) + }) + .collect(); + + for (chunk_id, chunk) in tickets.chunks(SEGMENT_MAX_SIZE as usize).enumerate() { + let segment: Vec = chunk + .iter() + .map(|(id, body)| { + TicketsData::::set(id, Some(body.clone())); + *id + }) + .collect(); + let segment = BoundedVec::truncate_from(segment); + UnsortedSegments::::insert(chunk_id as u32, segment); + } + + // Update metadata + let mut meta = TicketsMeta::::get(); + meta.unsorted_tickets_count = tickets_count; + TicketsMeta::::set(meta.clone()); + + log::debug!(target: LOG_TARGET, "Before sort: {:?}", meta); + #[block] + { + Pallet::::sort_segments(u32::MAX, 0, &mut meta); + } + log::debug!(target: LOG_TARGET, "After sort: {:?}", meta); + } +} diff --git a/substrate/frame/sassafras/src/data/25_tickets_100_auths.bin b/substrate/frame/sassafras/src/data/25_tickets_100_auths.bin new file mode 100644 index 0000000000000000000000000000000000000000..6e81f216455ae9dc61be31a9edef583a652721a8 GIT binary patch literal 24728 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 k^`E)Px# literal 0 HcmV?d00001 diff --git a/substrate/frame/sassafras/src/lib.rs b/substrate/frame/sassafras/src/lib.rs new file mode 100644 index 000000000000..b6f405f56549 --- /dev/null +++ b/substrate/frame/sassafras/src/lib.rs @@ -0,0 +1,1081 @@ +// 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. + +//! Extension module for Sassafras consensus. +//! +//! [Sassafras](https://research.web3.foundation/Polkadot/protocols/block-production/SASSAFRAS) +//! is a constant-time block production protocol that aims to ensure that there is +//! exactly one block produced with constant time intervals rather than multiple or none. +//! +//! We run a lottery to distribute block production slots in an epoch and to fix the +//! order validators produce blocks in, by the beginning of an epoch. +//! +//! Each validator signs the same VRF input and publishes the output on-chain. This +//! value is their lottery ticket that can be validated against their public key. +//! +//! We want to keep lottery winners secret, i.e. do not publish their public keys. +//! At the beginning of the epoch all the validators tickets are published but not +//! their public keys. +//! +//! A valid tickets is validated when an honest validator reclaims it on block +//! production. +//! +//! To prevent submission of fake tickets, resulting in empty slots, the validator +//! when submitting the ticket accompanies it with a SNARK of the statement: "Here's +//! my VRF output that has been generated using the given VRF input and my secret +//! key. I'm not telling you my keys, but my public key is among those of the +//! nominated validators", that is validated before the lottery. +//! +//! To anonymously publish the ticket to the chain a validator sends their tickets +//! to a random validator who later puts it on-chain as a transaction. + +#![deny(warnings)] +#![warn(unused_must_use, unsafe_code, unused_variables, unused_imports, missing_docs)] +#![cfg_attr(not(feature = "std"), no_std)] + +use log::{debug, error, trace, warn}; +use scale_codec::{Decode, Encode, MaxEncodedLen}; +use scale_info::TypeInfo; + +use frame_support::{ + dispatch::{DispatchResultWithPostInfo, Pays}, + traits::{Defensive, Get}, + weights::Weight, + BoundedVec, WeakBoundedVec, +}; +use frame_system::{ + offchain::{SendTransactionTypes, SubmitTransaction}, + pallet_prelude::BlockNumberFor, +}; +use sp_consensus_sassafras::{ + digests::{ConsensusLog, NextEpochDescriptor, SlotClaim}, + vrf, AuthorityId, Epoch, EpochConfiguration, Randomness, Slot, TicketBody, TicketEnvelope, + TicketId, RANDOMNESS_LENGTH, SASSAFRAS_ENGINE_ID, +}; +use sp_io::hashing; +use sp_runtime::{ + generic::DigestItem, + traits::{One, Zero}, + BoundToRuntimeAppPublic, +}; +use sp_std::prelude::Vec; + +#[cfg(feature = "runtime-benchmarks")] +mod benchmarking; +#[cfg(all(feature = "std", test))] +mod mock; +#[cfg(all(feature = "std", test))] +mod tests; + +pub mod weights; +pub use weights::WeightInfo; + +pub use pallet::*; + +const LOG_TARGET: &str = "sassafras::runtime"; + +// Contextual string used by the VRF to generate per-block randomness. +const RANDOMNESS_VRF_CONTEXT: &[u8] = b"SassafrasOnChainRandomness"; + +// Max length for segments holding unsorted tickets. +const SEGMENT_MAX_SIZE: u32 = 128; + +/// Authorities bounded vector convenience type. +pub type AuthoritiesVec = WeakBoundedVec::MaxAuthorities>; + +/// Epoch length defined by the configuration. +pub type EpochLengthFor = ::EpochLength; + +/// Tickets metadata. +#[derive(Debug, Default, PartialEq, Encode, Decode, TypeInfo, MaxEncodedLen, Clone, Copy)] +pub struct TicketsMetadata { + /// Number of outstanding next epoch tickets requiring to be sorted. + /// + /// These tickets are held by the [`UnsortedSegments`] storage map in segments + /// containing at most `SEGMENT_MAX_SIZE` items. + pub unsorted_tickets_count: u32, + + /// Number of tickets available for current and next epoch. + /// + /// These tickets are held by the [`TicketsIds`] storage map. + /// + /// The array entry to be used for the current epoch is computed as epoch index modulo 2. + pub tickets_count: [u32; 2], +} + +#[frame_support::pallet] +pub mod pallet { + use super::*; + use frame_support::pallet_prelude::*; + use frame_system::pallet_prelude::*; + + /// The Sassafras pallet. + #[pallet::pallet] + pub struct Pallet(_); + + /// Configuration parameters. + #[pallet::config] + pub trait Config: frame_system::Config + SendTransactionTypes> { + /// Amount of slots that each epoch should last. + #[pallet::constant] + type EpochLength: Get; + + /// Max number of authorities allowed. + #[pallet::constant] + type MaxAuthorities: Get; + + /// Epoch change trigger. + /// + /// Logic to be triggered on every block to query for whether an epoch has ended + /// and to perform the transition to the next epoch. + type EpochChangeTrigger: EpochChangeTrigger; + + /// Weight information for all calls of this pallet. + type WeightInfo: WeightInfo; + } + + /// Sassafras runtime errors. + #[pallet::error] + pub enum Error { + /// Submitted configuration is invalid. + InvalidConfiguration, + } + + /// Current epoch index. + #[pallet::storage] + #[pallet::getter(fn epoch_index)] + pub type EpochIndex = StorageValue<_, u64, ValueQuery>; + + /// Current epoch authorities. + #[pallet::storage] + #[pallet::getter(fn authorities)] + pub type Authorities = StorageValue<_, AuthoritiesVec, ValueQuery>; + + /// Next epoch authorities. + #[pallet::storage] + #[pallet::getter(fn next_authorities)] + pub type NextAuthorities = StorageValue<_, AuthoritiesVec, ValueQuery>; + + /// First block slot number. + /// + /// As the slots may not be zero-based, we record the slot value for the fist block. + /// This allows to always compute relative indices for epochs and slots. + #[pallet::storage] + #[pallet::getter(fn genesis_slot)] + pub type GenesisSlot = StorageValue<_, Slot, ValueQuery>; + + /// Current block slot number. + #[pallet::storage] + #[pallet::getter(fn current_slot)] + pub type CurrentSlot = StorageValue<_, Slot, ValueQuery>; + + /// Current epoch randomness. + #[pallet::storage] + #[pallet::getter(fn randomness)] + pub type CurrentRandomness = StorageValue<_, Randomness, ValueQuery>; + + /// Next epoch randomness. + #[pallet::storage] + #[pallet::getter(fn next_randomness)] + pub type NextRandomness = StorageValue<_, Randomness, ValueQuery>; + + /// Randomness accumulator. + /// + /// Excluded the first imported block, its value is updated on block finalization. + #[pallet::storage] + #[pallet::getter(fn randomness_accumulator)] + pub(crate) type RandomnessAccumulator = StorageValue<_, Randomness, ValueQuery>; + + /// The configuration for the current epoch. + #[pallet::storage] + #[pallet::getter(fn config)] + pub type EpochConfig = StorageValue<_, EpochConfiguration, ValueQuery>; + + /// The configuration for the next epoch. + #[pallet::storage] + #[pallet::getter(fn next_config)] + pub type NextEpochConfig = StorageValue<_, EpochConfiguration>; + + /// Pending epoch configuration change that will be set as `NextEpochConfig` when the next + /// epoch is enacted. + /// + /// In other words, a configuration change submitted during epoch N will be enacted on epoch + /// N+2. This is to maintain coherence for already submitted tickets for epoch N+1 that where + /// computed using configuration parameters stored for epoch N+1. + #[pallet::storage] + pub type PendingEpochConfigChange = StorageValue<_, EpochConfiguration>; + + /// Stored tickets metadata. + #[pallet::storage] + pub type TicketsMeta = StorageValue<_, TicketsMetadata, ValueQuery>; + + /// Tickets identifiers map. + /// + /// The map holds tickets ids for the current and next epoch. + /// + /// The key is a tuple composed by: + /// - `u8` equal to epoch's index modulo 2; + /// - `u32` equal to the ticket's index in a sorted list of epoch's tickets. + /// + /// Epoch X first N-th ticket has key (X mod 2, N) + /// + /// Note that the ticket's index doesn't directly correspond to the slot index within the epoch. + /// The assigment is computed dynamically using an *outside-in* strategy. + /// + /// Be aware that entries within this map are never removed, only overwritten. + /// Last element index should be fetched from the [`TicketsMeta`] value. + #[pallet::storage] + pub type TicketsIds = StorageMap<_, Identity, (u8, u32), TicketId>; + + /// Tickets to be used for current and next epoch. + #[pallet::storage] + pub type TicketsData = StorageMap<_, Identity, TicketId, TicketBody>; + + /// Next epoch tickets unsorted segments. + /// + /// Contains lists of tickets where each list represents a batch of tickets + /// received via the `submit_tickets` extrinsic. + /// + /// Each segment has max length [`SEGMENT_MAX_SIZE`]. + #[pallet::storage] + pub type UnsortedSegments = + StorageMap<_, Identity, u32, BoundedVec>, ValueQuery>; + + /// The most recently set of tickets which are candidates to become the next + /// epoch tickets. + #[pallet::storage] + pub type SortedCandidates = + StorageValue<_, BoundedVec>, ValueQuery>; + + /// Parameters used to construct the epoch's ring verifier. + /// + /// In practice: Updatable Universal Reference String and the seed. + #[pallet::storage] + #[pallet::getter(fn ring_context)] + pub type RingContext = StorageValue<_, vrf::RingContext>; + + /// Ring verifier data for the current epoch. + #[pallet::storage] + pub type RingVerifierData = StorageValue<_, vrf::RingVerifierData>; + + /// Slot claim vrf-preoutput used to generate per-slot randomness. + /// + /// The value is ephemeral and is cleared on block finalization. + #[pallet::storage] + pub(crate) type ClaimTemporaryData = StorageValue<_, vrf::VrfOutput>; + + /// Genesis configuration for Sassafras protocol. + #[pallet::genesis_config] + #[derive(frame_support::DefaultNoBound)] + pub struct GenesisConfig { + /// Genesis authorities. + pub authorities: Vec, + /// Genesis epoch configuration. + pub epoch_config: EpochConfiguration, + /// Phantom config + #[serde(skip)] + pub _phantom: sp_std::marker::PhantomData, + } + + #[pallet::genesis_build] + impl BuildGenesisConfig for GenesisConfig { + fn build(&self) { + EpochConfig::::put(self.epoch_config); + Pallet::::genesis_authorities_initialize(&self.authorities); + + #[cfg(feature = "construct-dummy-ring-context")] + { + debug!(target: LOG_TARGET, "Constructing dummy ring context"); + let ring_ctx = vrf::RingContext::new_testing(); + RingContext::::put(ring_ctx); + Pallet::::update_ring_verifier(&self.authorities); + } + } + } + + #[pallet::hooks] + impl Hooks> for Pallet { + fn on_initialize(block_num: BlockNumberFor) -> Weight { + debug_assert_eq!(block_num, frame_system::Pallet::::block_number()); + + let claim = >::digest() + .logs + .iter() + .find_map(|item| item.pre_runtime_try_to::(&SASSAFRAS_ENGINE_ID)) + .expect("Valid block must have a slot claim. qed"); + + CurrentSlot::::put(claim.slot); + + if block_num == One::one() { + Self::post_genesis_initialize(claim.slot); + } + + let randomness_output = claim + .vrf_signature + .outputs + .get(0) + .expect("Valid claim must have vrf signature; qed"); + ClaimTemporaryData::::put(randomness_output); + + let trigger_weight = T::EpochChangeTrigger::trigger::(block_num); + + T::WeightInfo::on_initialize() + trigger_weight + } + + fn on_finalize(_: BlockNumberFor) { + // At the end of the block, we can safely include the current slot randomness + // to the accumulator. If we've determined that this block was the first in + // a new epoch, the changeover logic has already occurred at this point + // (i.e. `enact_epoch_change` has already been called). + let randomness_input = vrf::slot_claim_input( + &Self::randomness(), + CurrentSlot::::get(), + EpochIndex::::get(), + ); + let randomness_output = ClaimTemporaryData::::take() + .expect("Unconditionally populated in `on_initialize`; `on_finalize` is always called after; qed"); + let randomness = randomness_output + .make_bytes::(RANDOMNESS_VRF_CONTEXT, &randomness_input); + Self::deposit_slot_randomness(&randomness); + + // Check if we are in the epoch's second half. + // If so, start sorting the next epoch tickets. + let epoch_length = T::EpochLength::get(); + let current_slot_idx = Self::current_slot_index(); + if current_slot_idx >= epoch_length / 2 { + let mut metadata = TicketsMeta::::get(); + if metadata.unsorted_tickets_count != 0 { + let next_epoch_idx = EpochIndex::::get() + 1; + let next_epoch_tag = (next_epoch_idx & 1) as u8; + let slots_left = epoch_length.checked_sub(current_slot_idx).unwrap_or(1); + Self::sort_segments( + metadata + .unsorted_tickets_count + .div_ceil(SEGMENT_MAX_SIZE * slots_left as u32), + next_epoch_tag, + &mut metadata, + ); + TicketsMeta::::set(metadata); + } + } + } + } + + #[pallet::call] + impl Pallet { + /// Submit next epoch tickets candidates. + /// + /// The number of tickets allowed to be submitted in one call is equal to the epoch length. + #[pallet::call_index(0)] + #[pallet::weight(T::WeightInfo::submit_tickets(tickets.len() as u32))] + pub fn submit_tickets( + origin: OriginFor, + tickets: BoundedVec>, + ) -> DispatchResultWithPostInfo { + ensure_none(origin)?; + + debug!(target: LOG_TARGET, "Received {} tickets", tickets.len()); + + let epoch_length = T::EpochLength::get(); + let current_slot_idx = Self::current_slot_index(); + if current_slot_idx > epoch_length / 2 { + warn!(target: LOG_TARGET, "Tickets shall be submitted in the first epoch half",); + return Err("Tickets shall be submitted in the first epoch half".into()) + } + + let Some(verifier) = RingVerifierData::::get().map(|v| v.into()) else { + warn!(target: LOG_TARGET, "Ring verifier key not initialized"); + return Err("Ring verifier key not initialized".into()) + }; + + let next_authorities = Self::next_authorities(); + + // Compute tickets threshold + let next_config = Self::next_config().unwrap_or_else(|| Self::config()); + let ticket_threshold = sp_consensus_sassafras::ticket_id_threshold( + next_config.redundancy_factor, + epoch_length as u32, + next_config.attempts_number, + next_authorities.len() as u32, + ); + + // Get next epoch params + let randomness = NextRandomness::::get(); + let epoch_idx = EpochIndex::::get() + 1; + + let mut valid_tickets = BoundedVec::with_bounded_capacity(tickets.len()); + + for ticket in tickets { + debug!(target: LOG_TARGET, "Checking ring proof"); + + let Some(ticket_id_output) = ticket.signature.outputs.get(0) else { + debug!(target: LOG_TARGET, "Missing ticket vrf output from ring signature"); + continue + }; + let ticket_id_input = + vrf::ticket_id_input(&randomness, ticket.body.attempt_idx, epoch_idx); + + // Check threshold constraint + let ticket_id = vrf::make_ticket_id(&ticket_id_input, &ticket_id_output); + if ticket_id >= ticket_threshold { + debug!(target: LOG_TARGET, "Ignoring ticket over threshold ({:032x} >= {:032x})", ticket_id, ticket_threshold); + continue + } + + // Check for duplicates + if TicketsData::::contains_key(ticket_id) { + debug!(target: LOG_TARGET, "Ignoring duplicate ticket ({:032x})", ticket_id); + continue + } + + // Check ring signature + let sign_data = vrf::ticket_body_sign_data(&ticket.body, ticket_id_input); + if !ticket.signature.ring_vrf_verify(&sign_data, &verifier) { + debug!(target: LOG_TARGET, "Proof verification failure for ticket ({:032x})", ticket_id); + continue + } + + if let Ok(_) = valid_tickets.try_push(ticket_id).defensive_proof( + "Input segment has same length as bounded destination vector; qed", + ) { + TicketsData::::set(ticket_id, Some(ticket.body)); + } + } + + if !valid_tickets.is_empty() { + Self::append_tickets(valid_tickets); + } + + Ok(Pays::No.into()) + } + + /// Plan an epoch configuration change. + /// + /// The epoch configuration change is recorded and will be announced at the begining + /// of the next epoch together with next epoch authorities information. + /// In other words, the configuration will be enacted one epoch later. + /// + /// Multiple calls to this method will replace any existing planned config change + /// that has not been enacted yet. + #[pallet::call_index(1)] + #[pallet::weight(T::WeightInfo::plan_config_change())] + pub fn plan_config_change( + origin: OriginFor, + config: EpochConfiguration, + ) -> DispatchResult { + ensure_root(origin)?; + + ensure!( + config.redundancy_factor != 0 && config.attempts_number != 0, + Error::::InvalidConfiguration + ); + PendingEpochConfigChange::::put(config); + Ok(()) + } + } + + #[pallet::validate_unsigned] + impl ValidateUnsigned for Pallet { + type Call = Call; + + fn validate_unsigned(source: TransactionSource, call: &Self::Call) -> TransactionValidity { + let Call::submit_tickets { tickets } = call else { + return InvalidTransaction::Call.into() + }; + + // Discard tickets not coming from the local node or that are not included in a block + if source == TransactionSource::External { + warn!( + target: LOG_TARGET, + "Rejecting unsigned `submit_tickets` transaction from external source", + ); + return InvalidTransaction::BadSigner.into() + } + + // Current slot should be less than half of epoch length. + let epoch_length = T::EpochLength::get(); + let current_slot_idx = Self::current_slot_index(); + if current_slot_idx > epoch_length / 2 { + warn!(target: LOG_TARGET, "Tickets shall be proposed in the first epoch half",); + return InvalidTransaction::Stale.into() + } + + // This should be set such that it is discarded after the first epoch half + let tickets_longevity = epoch_length / 2 - current_slot_idx; + let tickets_tag = tickets.using_encoded(|bytes| hashing::blake2_256(bytes)); + + ValidTransaction::with_tag_prefix("Sassafras") + .priority(TransactionPriority::max_value()) + .longevity(tickets_longevity as u64) + .and_provides(tickets_tag) + .propagate(true) + .build() + } + } +} + +// Inherent methods +impl Pallet { + /// Determine whether an epoch change should take place at this block. + /// + /// Assumes that initialization has already taken place. + pub(crate) fn should_end_epoch(block_num: BlockNumberFor) -> bool { + // The epoch has technically ended during the passage of time between this block and the + // last, but we have to "end" the epoch now, since there is no earlier possible block we + // could have done it. + // + // The exception is for block 1: the genesis has slot 0, so we treat epoch 0 as having + // started at the slot of block 1. We want to use the same randomness and validator set as + // signalled in the genesis, so we don't rotate the epoch. + block_num > One::one() && Self::current_slot_index() >= T::EpochLength::get() + } + + /// Current slot index relative to the current epoch. + fn current_slot_index() -> u32 { + Self::slot_index(CurrentSlot::::get()) + } + + /// Slot index relative to the current epoch. + fn slot_index(slot: Slot) -> u32 { + slot.checked_sub(*Self::current_epoch_start()) + .and_then(|v| v.try_into().ok()) + .unwrap_or(u32::MAX) + } + + /// Finds the start slot of the current epoch. + /// + /// Only guaranteed to give correct results after `initialize` of the first + /// block in the chain (as its result is based off of `GenesisSlot`). + fn current_epoch_start() -> Slot { + Self::epoch_start(EpochIndex::::get()) + } + + /// Get the epoch's first slot. + fn epoch_start(epoch_index: u64) -> Slot { + const PROOF: &str = "slot number is u64; it should relate in some way to wall clock time; \ + if u64 is not enough we should crash for safety; qed."; + + let epoch_start = epoch_index.checked_mul(T::EpochLength::get() as u64).expect(PROOF); + GenesisSlot::::get().checked_add(epoch_start).expect(PROOF).into() + } + + pub(crate) fn update_ring_verifier(authorities: &[AuthorityId]) { + debug!(target: LOG_TARGET, "Loading ring context"); + let Some(ring_ctx) = RingContext::::get() else { + debug!(target: LOG_TARGET, "Ring context not initialized"); + return + }; + + let pks: Vec<_> = authorities.iter().map(|auth| *auth.as_ref()).collect(); + + debug!(target: LOG_TARGET, "Building ring verifier (ring size: {})", pks.len()); + let verifier_data = ring_ctx + .verifier_data(&pks) + .expect("Failed to build ring verifier. This is a bug"); + + RingVerifierData::::put(verifier_data); + } + + /// Enact an epoch change. + /// + /// WARNING: Should be called on every block once and if and only if [`should_end_epoch`] + /// has returned `true`. + /// + /// If we detect one or more skipped epochs the policy is to use the authorities and values + /// from the first skipped epoch. The tickets data is invalidated. + pub(crate) fn enact_epoch_change( + authorities: WeakBoundedVec, + next_authorities: WeakBoundedVec, + ) { + if next_authorities != authorities { + Self::update_ring_verifier(&next_authorities); + } + + // Update authorities + Authorities::::put(&authorities); + NextAuthorities::::put(&next_authorities); + + // Update epoch index + let mut epoch_idx = EpochIndex::::get() + 1; + + let slot_idx = CurrentSlot::::get().saturating_sub(Self::epoch_start(epoch_idx)); + if slot_idx >= T::EpochLength::get() { + // Detected one or more skipped epochs, clear tickets data and recompute epoch index. + Self::reset_tickets_data(); + let skipped_epochs = *slot_idx / T::EpochLength::get() as u64; + epoch_idx += skipped_epochs; + warn!( + target: LOG_TARGET, + "Detected {} skipped epochs, resuming from epoch {}", + skipped_epochs, + epoch_idx + ); + } + + let mut metadata = TicketsMeta::::get(); + let mut metadata_dirty = false; + + EpochIndex::::put(epoch_idx); + + let next_epoch_idx = epoch_idx + 1; + + // Updates current epoch randomness and computes the *next* epoch randomness. + let next_randomness = Self::update_epoch_randomness(next_epoch_idx); + + if let Some(config) = NextEpochConfig::::take() { + EpochConfig::::put(config); + } + + let next_config = PendingEpochConfigChange::::take(); + if let Some(next_config) = next_config { + NextEpochConfig::::put(next_config); + } + + // After we update the current epoch, we signal the *next* epoch change + // so that nodes can track changes. + let next_epoch = NextEpochDescriptor { + randomness: next_randomness, + authorities: next_authorities.into_inner(), + config: next_config, + }; + Self::deposit_next_epoch_descriptor_digest(next_epoch); + + let epoch_tag = (epoch_idx & 1) as u8; + + // Optionally finish sorting + if metadata.unsorted_tickets_count != 0 { + Self::sort_segments(u32::MAX, epoch_tag, &mut metadata); + metadata_dirty = true; + } + + // Clear the "prev ≡ next (mod 2)" epoch tickets counter and bodies. + // Ids are left since are just cyclically overwritten on-the-go. + let prev_epoch_tag = epoch_tag ^ 1; + let prev_epoch_tickets_count = &mut metadata.tickets_count[prev_epoch_tag as usize]; + if *prev_epoch_tickets_count != 0 { + for idx in 0..*prev_epoch_tickets_count { + if let Some(ticket_id) = TicketsIds::::get((prev_epoch_tag, idx)) { + TicketsData::::remove(ticket_id); + } + } + *prev_epoch_tickets_count = 0; + metadata_dirty = true; + } + + if metadata_dirty { + TicketsMeta::::set(metadata); + } + } + + // Call this function on epoch change to enact current epoch randomness. + // + // Returns the next epoch randomness. + fn update_epoch_randomness(next_epoch_index: u64) -> Randomness { + let curr_epoch_randomness = NextRandomness::::get(); + CurrentRandomness::::put(curr_epoch_randomness); + + let accumulator = RandomnessAccumulator::::get(); + + let mut buf = [0; RANDOMNESS_LENGTH + 8]; + buf[..RANDOMNESS_LENGTH].copy_from_slice(&accumulator[..]); + buf[RANDOMNESS_LENGTH..].copy_from_slice(&next_epoch_index.to_le_bytes()); + + let next_randomness = hashing::blake2_256(&buf); + NextRandomness::::put(&next_randomness); + + next_randomness + } + + // Deposit per-slot randomness. + fn deposit_slot_randomness(randomness: &Randomness) { + let accumulator = RandomnessAccumulator::::get(); + + let mut buf = [0; 2 * RANDOMNESS_LENGTH]; + buf[..RANDOMNESS_LENGTH].copy_from_slice(&accumulator[..]); + buf[RANDOMNESS_LENGTH..].copy_from_slice(&randomness[..]); + + let accumulator = hashing::blake2_256(&buf); + RandomnessAccumulator::::put(accumulator); + } + + // Deposit next epoch descriptor in the block header digest. + fn deposit_next_epoch_descriptor_digest(desc: NextEpochDescriptor) { + let item = ConsensusLog::NextEpochData(desc); + let log = DigestItem::Consensus(SASSAFRAS_ENGINE_ID, item.encode()); + >::deposit_log(log) + } + + // Initialize authorities on genesis phase. + // + // Genesis authorities may have been initialized via other means (e.g. via session pallet). + // + // If this function has already been called with some authorities, then the new list + // should match the previously set one. + fn genesis_authorities_initialize(authorities: &[AuthorityId]) { + let prev_authorities = Authorities::::get(); + + if !prev_authorities.is_empty() { + // This function has already been called. + if prev_authorities.as_slice() == authorities { + return + } else { + panic!("Authorities were already initialized"); + } + } + + let authorities = WeakBoundedVec::try_from(authorities.to_vec()) + .expect("Initial number of authorities should be lower than T::MaxAuthorities"); + Authorities::::put(&authorities); + NextAuthorities::::put(&authorities); + } + + // Method to be called on first block `on_initialize` to properly populate some key parameters. + fn post_genesis_initialize(slot: Slot) { + // Keep track of the actual first slot used (may not be zero based). + GenesisSlot::::put(slot); + + // Properly initialize randomness using genesis hash and current slot. + // This is important to guarantee that a different set of tickets are produced for: + // - different chains which share the same ring parameters and + // - same chain started with a different slot base. + let genesis_hash = frame_system::Pallet::::parent_hash(); + let mut buf = genesis_hash.as_ref().to_vec(); + buf.extend_from_slice(&slot.to_le_bytes()); + let randomness = hashing::blake2_256(buf.as_slice()); + RandomnessAccumulator::::put(randomness); + + let next_randoness = Self::update_epoch_randomness(1); + + // Deposit a log as this is the first block in first epoch. + let next_epoch = NextEpochDescriptor { + randomness: next_randoness, + authorities: Self::next_authorities().into_inner(), + config: None, + }; + Self::deposit_next_epoch_descriptor_digest(next_epoch); + } + + /// Current epoch information. + pub fn current_epoch() -> Epoch { + let index = EpochIndex::::get(); + Epoch { + index, + start: Self::epoch_start(index), + length: T::EpochLength::get(), + authorities: Self::authorities().into_inner(), + randomness: Self::randomness(), + config: Self::config(), + } + } + + /// Next epoch information. + pub fn next_epoch() -> Epoch { + let index = EpochIndex::::get() + 1; + Epoch { + index, + start: Self::epoch_start(index), + length: T::EpochLength::get(), + authorities: Self::next_authorities().into_inner(), + randomness: Self::next_randomness(), + config: Self::next_config().unwrap_or_else(|| Self::config()), + } + } + + /// Fetch expected ticket-id for the given slot according to an "outside-in" sorting strategy. + /// + /// Given an ordered sequence of tickets [t0, t1, t2, ..., tk] to be assigned to n slots, + /// with n >= k, then the tickets are assigned to the slots according to the following + /// strategy: + /// + /// slot-index : [ 0, 1, 2, ............ , n ] + /// tickets : [ t1, t3, t5, ... , t4, t2, t0 ]. + /// + /// With slot-index computed as `epoch_start() - slot`. + /// + /// If `slot` value falls within the current epoch then we fetch tickets from the current epoch + /// tickets list. + /// + /// If `slot` value falls within the next epoch then we fetch tickets from the next epoch + /// tickets ids list. Note that in this case we may have not finished receiving all the tickets + /// for that epoch yet. The next epoch tickets should be considered "stable" only after the + /// current epoch first half slots were elapsed (see `submit_tickets_unsigned_extrinsic`). + /// + /// Returns `None` if, according to the sorting strategy, there is no ticket associated to the + /// specified slot-index (happens if a ticket falls in the middle of an epoch and n > k), + /// or if the slot falls beyond the next epoch. + /// + /// Before importing the first block this returns `None`. + pub fn slot_ticket_id(slot: Slot) -> Option { + if frame_system::Pallet::::block_number().is_zero() { + return None + } + let epoch_idx = EpochIndex::::get(); + let epoch_len = T::EpochLength::get(); + let mut slot_idx = Self::slot_index(slot); + let mut metadata = TicketsMeta::::get(); + + let get_ticket_idx = |slot_idx| { + let ticket_idx = if slot_idx < epoch_len / 2 { + 2 * slot_idx + 1 + } else { + 2 * (epoch_len - (slot_idx + 1)) + }; + debug!( + target: LOG_TARGET, + "slot-idx {} <-> ticket-idx {}", + slot_idx, + ticket_idx + ); + ticket_idx as u32 + }; + + let mut epoch_tag = (epoch_idx & 1) as u8; + + if epoch_len <= slot_idx && slot_idx < 2 * epoch_len { + // Try to get a ticket for the next epoch. Since its state values were not enacted yet, + // we may have to finish sorting the tickets. + epoch_tag ^= 1; + slot_idx -= epoch_len; + if metadata.unsorted_tickets_count != 0 { + Self::sort_segments(u32::MAX, epoch_tag, &mut metadata); + TicketsMeta::::set(metadata); + } + } else if slot_idx >= 2 * epoch_len { + return None + } + + let ticket_idx = get_ticket_idx(slot_idx); + if ticket_idx < metadata.tickets_count[epoch_tag as usize] { + TicketsIds::::get((epoch_tag, ticket_idx)) + } else { + None + } + } + + /// Returns ticket id and data associated with the given `slot`. + /// + /// Refer to the `slot_ticket_id` documentation for the slot-ticket association + /// criteria. + pub fn slot_ticket(slot: Slot) -> Option<(TicketId, TicketBody)> { + Self::slot_ticket_id(slot).and_then(|id| TicketsData::::get(id).map(|body| (id, body))) + } + + // Sort and truncate candidate tickets, cleanup storage. + fn sort_and_truncate(candidates: &mut Vec, max_tickets: usize) -> u128 { + candidates.sort_unstable(); + candidates.drain(max_tickets..).for_each(TicketsData::::remove); + candidates[max_tickets - 1] + } + + /// Sort the tickets which belong to the epoch with the specified `epoch_tag`. + /// + /// At most `max_segments` are taken from the `UnsortedSegments` structure. + /// + /// The tickets of the removed segments are merged with the tickets on the `SortedCandidates` + /// which is then sorted an truncated to contain at most `MaxTickets` entries. + /// + /// If all the entries in `UnsortedSegments` are consumed, then `SortedCandidates` is elected + /// as the next epoch tickets, else it is saved to be used by next calls of this function. + pub(crate) fn sort_segments(max_segments: u32, epoch_tag: u8, metadata: &mut TicketsMetadata) { + let unsorted_segments_count = metadata.unsorted_tickets_count.div_ceil(SEGMENT_MAX_SIZE); + let max_segments = max_segments.min(unsorted_segments_count); + let max_tickets = Self::epoch_length() as usize; + + // Fetch the sorted candidates (if any). + let mut candidates = SortedCandidates::::take().into_inner(); + + // There is an upper bound to check only if we already sorted the max number + // of allowed tickets. + let mut upper_bound = *candidates.get(max_tickets - 1).unwrap_or(&TicketId::MAX); + + let mut require_sort = false; + + // Consume at most `max_segments` segments. + // During the process remove every stale ticket from `TicketsData` storage. + for segment_idx in (0..unsorted_segments_count).rev().take(max_segments as usize) { + let segment = UnsortedSegments::::take(segment_idx); + metadata.unsorted_tickets_count -= segment.len() as u32; + + // Push only ids with a value less than the current `upper_bound`. + let prev_len = candidates.len(); + for ticket_id in segment { + if ticket_id < upper_bound { + candidates.push(ticket_id); + } else { + TicketsData::::remove(ticket_id); + } + } + require_sort = candidates.len() != prev_len; + + // As we approach the tail of the segments buffer the `upper_bound` value is expected + // to decrease (fast). We thus expect the number of tickets pushed into the + // `candidates` vector to follow an exponential drop. + // + // Given this, sorting and truncating after processing each segment may be an overkill + // as we may find pushing few tickets more and more often. Is preferable to perform + // the sort and truncation operations only when we reach some bigger threshold + // (currently set as twice the capacity of `SortCandidate`). + // + // The more is the protocol's redundancy factor (i.e. the ratio between tickets allowed + // to be submitted and the epoch length) the more this check becomes relevant. + if candidates.len() > 2 * max_tickets { + upper_bound = Self::sort_and_truncate(&mut candidates, max_tickets); + require_sort = false; + } + } + + if candidates.len() > max_tickets { + Self::sort_and_truncate(&mut candidates, max_tickets); + } else if require_sort { + candidates.sort_unstable(); + } + + if metadata.unsorted_tickets_count == 0 { + // Sorting is over, write to next epoch map. + candidates.iter().enumerate().for_each(|(i, id)| { + TicketsIds::::insert((epoch_tag, i as u32), id); + }); + metadata.tickets_count[epoch_tag as usize] = candidates.len() as u32; + } else { + // Keep the partial result for the next calls. + SortedCandidates::::set(BoundedVec::truncate_from(candidates)); + } + } + + /// Append a set of tickets to the segments map. + pub(crate) fn append_tickets(mut tickets: BoundedVec>) { + debug!(target: LOG_TARGET, "Appending batch with {} tickets", tickets.len()); + tickets.iter().for_each(|t| trace!(target: LOG_TARGET, " + {t:032x}")); + + let mut metadata = TicketsMeta::::get(); + let mut segment_idx = metadata.unsorted_tickets_count / SEGMENT_MAX_SIZE; + + while !tickets.is_empty() { + let rem = metadata.unsorted_tickets_count % SEGMENT_MAX_SIZE; + let to_be_added = tickets.len().min((SEGMENT_MAX_SIZE - rem) as usize); + + let mut segment = UnsortedSegments::::get(segment_idx); + let _ = segment + .try_extend(tickets.drain(..to_be_added)) + .defensive_proof("We don't add more than `SEGMENT_MAX_SIZE` and this is the maximum bound for the vector."); + UnsortedSegments::::insert(segment_idx, segment); + + metadata.unsorted_tickets_count += to_be_added as u32; + segment_idx += 1; + } + + TicketsMeta::::set(metadata); + } + + /// Remove all tickets related data. + /// + /// May not be efficient as the calling places may repeat some of this operations + /// but is a very extraordinary operation (hopefully never happens in production) + /// and better safe than sorry. + fn reset_tickets_data() { + let metadata = TicketsMeta::::get(); + + // Remove even/odd-epoch data. + for epoch_tag in 0..=1 { + for idx in 0..metadata.tickets_count[epoch_tag] { + if let Some(id) = TicketsIds::::get((epoch_tag as u8, idx)) { + TicketsData::::remove(id); + } + } + } + + // Remove all unsorted tickets segments. + let segments_count = metadata.unsorted_tickets_count.div_ceil(SEGMENT_MAX_SIZE); + (0..segments_count).for_each(UnsortedSegments::::remove); + + // Reset sorted candidates + SortedCandidates::::kill(); + + // Reset tickets metadata + TicketsMeta::::kill(); + } + + /// Submit next epoch validator tickets via an unsigned extrinsic constructed with a call to + /// `submit_unsigned_transaction`. + /// + /// The submitted tickets are added to the next epoch outstanding tickets as long as the + /// extrinsic is called within the first half of the epoch. Tickets received during the + /// second half are dropped. + pub fn submit_tickets_unsigned_extrinsic(tickets: Vec) -> bool { + let tickets = BoundedVec::truncate_from(tickets); + let call = Call::submit_tickets { tickets }; + match SubmitTransaction::>::submit_unsigned_transaction(call.into()) { + Ok(_) => true, + Err(e) => { + error!(target: LOG_TARGET, "Error submitting tickets {:?}", e); + false + }, + } + } + + /// Epoch length + pub fn epoch_length() -> u32 { + T::EpochLength::get() + } +} + +/// Trigger an epoch change, if any should take place. +pub trait EpochChangeTrigger { + /// May trigger an epoch change, if any should take place. + /// + /// Returns an optional `Weight` if epoch change has been triggered. + /// + /// This should be called during every block, after initialization is done. + fn trigger(_: BlockNumberFor) -> Weight; +} + +/// An `EpochChangeTrigger` which does nothing. +/// +/// In practice this means that the epoch change logic is left to some external component +/// (e.g. pallet-session). +pub struct EpochChangeExternalTrigger; + +impl EpochChangeTrigger for EpochChangeExternalTrigger { + fn trigger(_: BlockNumberFor) -> Weight { + // nothing - trigger is external. + Weight::zero() + } +} + +/// An `EpochChangeTrigger` which recycle the same authorities set forever. +/// +/// The internal trigger should only be used when no other module is responsible for +/// changing authority set. +pub struct EpochChangeInternalTrigger; + +impl EpochChangeTrigger for EpochChangeInternalTrigger { + fn trigger(block_num: BlockNumberFor) -> Weight { + if Pallet::::should_end_epoch(block_num) { + let authorities = Pallet::::next_authorities(); + let next_authorities = authorities.clone(); + let len = next_authorities.len() as u32; + Pallet::::enact_epoch_change(authorities, next_authorities); + T::WeightInfo::enact_epoch_change(len, T::EpochLength::get()) + } else { + Weight::zero() + } + } +} + +impl BoundToRuntimeAppPublic for Pallet { + type Public = AuthorityId; +} diff --git a/substrate/frame/sassafras/src/mock.rs b/substrate/frame/sassafras/src/mock.rs new file mode 100644 index 000000000000..b700207c4991 --- /dev/null +++ b/substrate/frame/sassafras/src/mock.rs @@ -0,0 +1,343 @@ +// 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. + +//! Test utilities for Sassafras pallet. + +use crate::{self as pallet_sassafras, EpochChangeInternalTrigger, *}; + +use frame_support::{ + derive_impl, + traits::{ConstU32, OnFinalize, OnInitialize}, +}; +use sp_consensus_sassafras::{ + digests::SlotClaim, + vrf::{RingProver, VrfSignature}, + AuthorityIndex, AuthorityPair, EpochConfiguration, Slot, TicketBody, TicketEnvelope, TicketId, +}; +use sp_core::{ + crypto::{ByteArray, Pair, UncheckedFrom, VrfSecret, Wraps}, + ed25519::Public as EphemeralPublic, + H256, U256, +}; +use sp_runtime::{ + testing::{Digest, DigestItem, Header, TestXt}, + BuildStorage, +}; + +const LOG_TARGET: &str = "sassafras::tests"; + +const EPOCH_LENGTH: u32 = 10; +const MAX_AUTHORITIES: u32 = 100; + +#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)] +impl frame_system::Config for Test { + type Block = frame_system::mocking::MockBlock; +} + +impl frame_system::offchain::SendTransactionTypes for Test +where + RuntimeCall: From, +{ + type OverarchingCall = RuntimeCall; + type Extrinsic = TestXt; +} + +impl pallet_sassafras::Config for Test { + type EpochLength = ConstU32; + type MaxAuthorities = ConstU32; + type EpochChangeTrigger = EpochChangeInternalTrigger; + type WeightInfo = (); +} + +frame_support::construct_runtime!( + pub enum Test { + System: frame_system, + Sassafras: pallet_sassafras, + } +); + +// Default used for most of the tests. +// +// The redundancy factor has been set to max value to accept all submitted +// tickets without worrying about the threshold. +pub const TEST_EPOCH_CONFIGURATION: EpochConfiguration = + EpochConfiguration { redundancy_factor: u32::MAX, attempts_number: 5 }; + +/// Build and returns test storage externalities +pub fn new_test_ext(authorities_len: usize) -> sp_io::TestExternalities { + new_test_ext_with_pairs(authorities_len, false).1 +} + +/// Build and returns test storage externalities and authority set pairs used +/// by Sassafras genesis configuration. +pub fn new_test_ext_with_pairs( + authorities_len: usize, + with_ring_context: bool, +) -> (Vec, sp_io::TestExternalities) { + let pairs = (0..authorities_len) + .map(|i| AuthorityPair::from_seed(&U256::from(i).into())) + .collect::>(); + + let authorities: Vec<_> = pairs.iter().map(|p| p.public()).collect(); + + let mut storage = frame_system::GenesisConfig::::default().build_storage().unwrap(); + + pallet_sassafras::GenesisConfig:: { + authorities: authorities.clone(), + epoch_config: TEST_EPOCH_CONFIGURATION, + _phantom: sp_std::marker::PhantomData, + } + .assimilate_storage(&mut storage) + .unwrap(); + + let mut ext: sp_io::TestExternalities = storage.into(); + + if with_ring_context { + ext.execute_with(|| { + log::debug!(target: LOG_TARGET, "Building testing ring context"); + let ring_ctx = vrf::RingContext::new_testing(); + RingContext::::set(Some(ring_ctx.clone())); + Sassafras::update_ring_verifier(&authorities); + }); + } + + (pairs, ext) +} + +fn make_ticket_with_prover( + attempt: u32, + pair: &AuthorityPair, + prover: &RingProver, +) -> TicketEnvelope { + log::debug!("attempt: {}", attempt); + + // Values are referring to the next epoch + let epoch = Sassafras::epoch_index() + 1; + let randomness = Sassafras::next_randomness(); + + // Make a dummy ephemeral public that hopefully is unique within one test instance. + // In the tests, the values within the erased public are just used to compare + // ticket bodies, so it is not important to be a valid key. + let mut raw: [u8; 32] = [0; 32]; + raw.copy_from_slice(&pair.public().as_slice()[0..32]); + let erased_public = EphemeralPublic::unchecked_from(raw); + let revealed_public = erased_public; + + let ticket_id_input = vrf::ticket_id_input(&randomness, attempt, epoch); + + let body = TicketBody { attempt_idx: attempt, erased_public, revealed_public }; + let sign_data = vrf::ticket_body_sign_data(&body, ticket_id_input); + + let signature = pair.as_ref().ring_vrf_sign(&sign_data, &prover); + + // Ticket-id can be generated via vrf-preout. + // We don't care that much about its value here. + TicketEnvelope { body, signature } +} + +pub fn make_prover(pair: &AuthorityPair) -> RingProver { + let public = pair.public(); + let mut prover_idx = None; + + let ring_ctx = Sassafras::ring_context().unwrap(); + + let pks: Vec = Sassafras::authorities() + .iter() + .enumerate() + .map(|(idx, auth)| { + if public == *auth { + prover_idx = Some(idx); + } + *auth.as_ref() + }) + .collect(); + + log::debug!("Building prover. Ring size: {}", pks.len()); + let prover = ring_ctx.prover(&pks, prover_idx.unwrap()).unwrap(); + log::debug!("Done"); + + prover +} + +/// Construct `attempts` tickets envelopes for the next epoch. +/// +/// E.g. by passing an optional threshold +pub fn make_tickets(attempts: u32, pair: &AuthorityPair) -> Vec { + let prover = make_prover(pair); + (0..attempts) + .into_iter() + .map(|attempt| make_ticket_with_prover(attempt, pair, &prover)) + .collect() +} + +pub fn make_ticket_body(attempt_idx: u32, pair: &AuthorityPair) -> (TicketId, TicketBody) { + // Values are referring to the next epoch + let epoch = Sassafras::epoch_index() + 1; + let randomness = Sassafras::next_randomness(); + + let ticket_id_input = vrf::ticket_id_input(&randomness, attempt_idx, epoch); + let ticket_id_output = pair.as_inner_ref().vrf_output(&ticket_id_input); + + let id = vrf::make_ticket_id(&ticket_id_input, &ticket_id_output); + + // Make a dummy ephemeral public that hopefully is unique within one test instance. + // In the tests, the values within the erased public are just used to compare + // ticket bodies, so it is not important to be a valid key. + let mut raw: [u8; 32] = [0; 32]; + raw[..16].copy_from_slice(&pair.public().as_slice()[0..16]); + raw[16..].copy_from_slice(&id.to_le_bytes()); + let erased_public = EphemeralPublic::unchecked_from(raw); + let revealed_public = erased_public; + + let body = TicketBody { attempt_idx, erased_public, revealed_public }; + + (id, body) +} + +pub fn make_dummy_ticket_body(attempt_idx: u32) -> (TicketId, TicketBody) { + let hash = sp_core::hashing::blake2_256(&attempt_idx.to_le_bytes()); + + let erased_public = EphemeralPublic::unchecked_from(hash); + let revealed_public = erased_public; + + let body = TicketBody { attempt_idx, erased_public, revealed_public }; + + let mut bytes = [0u8; 16]; + bytes.copy_from_slice(&hash[..16]); + let id = TicketId::from_le_bytes(bytes); + + (id, body) +} + +pub fn make_ticket_bodies( + number: u32, + pair: Option<&AuthorityPair>, +) -> Vec<(TicketId, TicketBody)> { + (0..number) + .into_iter() + .map(|i| match pair { + Some(pair) => make_ticket_body(i, pair), + None => make_dummy_ticket_body(i), + }) + .collect() +} + +/// Persist the given tickets in the unsorted segments buffer. +/// +/// This function skips all the checks performed by the `submit_tickets` extrinsic and +/// directly appends the tickets to the `UnsortedSegments` structure. +pub fn persist_next_epoch_tickets_as_segments(tickets: &[(TicketId, TicketBody)]) { + let mut ids = Vec::with_capacity(tickets.len()); + tickets.iter().for_each(|(id, body)| { + TicketsData::::set(id, Some(body.clone())); + ids.push(*id); + }); + let max_chunk_size = Sassafras::epoch_length() as usize; + ids.chunks(max_chunk_size).for_each(|chunk| { + Sassafras::append_tickets(BoundedVec::truncate_from(chunk.to_vec())); + }) +} + +/// Calls the [`persist_next_epoch_tickets_as_segments`] and then proceeds to the +/// sorting of the candidates. +/// +/// Only "winning" tickets are left. +pub fn persist_next_epoch_tickets(tickets: &[(TicketId, TicketBody)]) { + persist_next_epoch_tickets_as_segments(tickets); + // Force sorting of next epoch tickets (enactment) by explicitly querying the first of them. + let next_epoch = Sassafras::next_epoch(); + assert_eq!(TicketsMeta::::get().unsorted_tickets_count, tickets.len() as u32); + Sassafras::slot_ticket(next_epoch.start).unwrap(); + assert_eq!(TicketsMeta::::get().unsorted_tickets_count, 0); +} + +fn slot_claim_vrf_signature(slot: Slot, pair: &AuthorityPair) -> VrfSignature { + let mut epoch = Sassafras::epoch_index(); + let mut randomness = Sassafras::randomness(); + + // Check if epoch is going to change on initialization. + let epoch_start = Sassafras::current_epoch_start(); + let epoch_length = EPOCH_LENGTH.into(); + if epoch_start != 0_u64 && slot >= epoch_start + epoch_length { + epoch += slot.saturating_sub(epoch_start).saturating_div(epoch_length); + randomness = crate::NextRandomness::::get(); + } + + let data = vrf::slot_claim_sign_data(&randomness, slot, epoch); + pair.as_ref().vrf_sign(&data) +} + +/// Construct a `PreDigest` instance for the given parameters. +pub fn make_slot_claim( + authority_idx: AuthorityIndex, + slot: Slot, + pair: &AuthorityPair, +) -> SlotClaim { + let vrf_signature = slot_claim_vrf_signature(slot, pair); + SlotClaim { authority_idx, slot, vrf_signature, ticket_claim: None } +} + +/// Construct a `Digest` with a `SlotClaim` item. +pub fn make_digest(authority_idx: AuthorityIndex, slot: Slot, pair: &AuthorityPair) -> Digest { + let claim = make_slot_claim(authority_idx, slot, pair); + Digest { logs: vec![DigestItem::from(&claim)] } +} + +pub fn initialize_block( + number: u64, + slot: Slot, + parent_hash: H256, + pair: &AuthorityPair, +) -> Digest { + let digest = make_digest(0, slot, pair); + System::reset_events(); + System::initialize(&number, &parent_hash, &digest); + Sassafras::on_initialize(number); + digest +} + +pub fn finalize_block(number: u64) -> Header { + Sassafras::on_finalize(number); + System::finalize() +} + +/// Progress the pallet state up to the given block `number` and `slot`. +pub fn go_to_block(number: u64, slot: Slot, pair: &AuthorityPair) -> Digest { + Sassafras::on_finalize(System::block_number()); + let parent_hash = System::finalize().hash(); + + let digest = make_digest(0, slot, pair); + + System::reset_events(); + System::initialize(&number, &parent_hash, &digest); + Sassafras::on_initialize(number); + + digest +} + +/// Progress the pallet state up to the given block `number`. +/// Slots will grow linearly accordingly to blocks. +pub fn progress_to_block(number: u64, pair: &AuthorityPair) -> Option { + let mut slot = Sassafras::current_slot() + 1; + let mut digest = None; + for i in System::block_number() + 1..=number { + let dig = go_to_block(i, slot, pair); + digest = Some(dig); + slot = slot + 1; + } + digest +} diff --git a/substrate/frame/sassafras/src/tests.rs b/substrate/frame/sassafras/src/tests.rs new file mode 100644 index 000000000000..ec3425cce7bf --- /dev/null +++ b/substrate/frame/sassafras/src/tests.rs @@ -0,0 +1,874 @@ +// 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. + +//! Tests for Sassafras pallet. + +use crate::*; +use mock::*; + +use sp_consensus_sassafras::Slot; + +fn h2b(hex: &str) -> [u8; N] { + array_bytes::hex2array_unchecked(hex) +} + +fn b2h(bytes: [u8; N]) -> String { + array_bytes::bytes2hex("", &bytes) +} + +#[test] +fn genesis_values_assumptions_check() { + new_test_ext(3).execute_with(|| { + assert_eq!(Sassafras::authorities().len(), 3); + assert_eq!(Sassafras::config(), TEST_EPOCH_CONFIGURATION); + }); +} + +#[test] +fn post_genesis_randomness_initialization() { + let (pairs, mut ext) = new_test_ext_with_pairs(1, false); + let pair = &pairs[0]; + + ext.execute_with(|| { + assert_eq!(Sassafras::randomness(), [0; 32]); + assert_eq!(Sassafras::next_randomness(), [0; 32]); + assert_eq!(Sassafras::randomness_accumulator(), [0; 32]); + + // Test the values with a zero genesis block hash + let _ = initialize_block(1, 123.into(), [0x00; 32].into(), pair); + + assert_eq!(Sassafras::randomness(), [0; 32]); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("b9497550deeeb4adc134555930de61968a0558f8947041eb515b2f5fa68ffaf7") + ); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("febcc7fe9539fe17ed29f525831394edfb30b301755dc9bd91584a1f065faf87") + ); + let (id1, _) = make_ticket_bodies(1, Some(pair))[0]; + + // Reset what is relevant + NextRandomness::::set([0; 32]); + RandomnessAccumulator::::set([0; 32]); + + // Test the values with a non-zero genesis block hash + let _ = initialize_block(1, 123.into(), [0xff; 32].into(), pair); + + assert_eq!(Sassafras::randomness(), [0; 32]); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("51c1e3b3a73d2043b3cabae98ff27bdd4aad8967c21ecda7b9465afaa0e70f37") + ); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("466bf3007f2e17bffee0b3c42c90f33d654f5ff61eff28b0cc650825960abd52") + ); + let (id2, _) = make_ticket_bodies(1, Some(pair))[0]; + + // Ticket ids should be different when next epoch randomness is different + assert_ne!(id1, id2); + + // Reset what is relevant + NextRandomness::::set([0; 32]); + RandomnessAccumulator::::set([0; 32]); + + // Test the values with a non-zero genesis block hash + let _ = initialize_block(1, 321.into(), [0x00; 32].into(), pair); + + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("d85d84a54f79453000eb62e8a17b30149bd728d3232bc2787a89d51dc9a36008") + ); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("8a035eed02b5b8642b1515ed19752df8df156627aea45c4ef6e3efa88be9a74d") + ); + let (id2, _) = make_ticket_bodies(1, Some(pair))[0]; + + // Ticket ids should be different when next epoch randomness is different + assert_ne!(id1, id2); + }); +} + +// Tests if the sorted tickets are assigned to each slot outside-in. +#[test] +fn slot_ticket_id_outside_in_fetch() { + let genesis_slot = Slot::from(100); + let tickets_count = 6; + + // Current epoch tickets + let curr_tickets: Vec = (0..tickets_count).map(|i| i as TicketId).collect(); + + // Next epoch tickets + let next_tickets: Vec = + (0..tickets_count - 1).map(|i| (i + tickets_count) as TicketId).collect(); + + new_test_ext(0).execute_with(|| { + // Some corner cases + TicketsIds::::insert((0, 0_u32), 1_u128); + + // Cleanup + (0..3).for_each(|i| TicketsIds::::remove((0, i as u32))); + + curr_tickets + .iter() + .enumerate() + .for_each(|(i, id)| TicketsIds::::insert((0, i as u32), id)); + + next_tickets + .iter() + .enumerate() + .for_each(|(i, id)| TicketsIds::::insert((1, i as u32), id)); + + TicketsMeta::::set(TicketsMetadata { + tickets_count: [curr_tickets.len() as u32, next_tickets.len() as u32], + unsorted_tickets_count: 0, + }); + + // Before importing the first block the pallet always return `None` + // This is a kind of special hardcoded case that should never happen in practice + // as the first thing the pallet does is to initialize the genesis slot. + + assert_eq!(Sassafras::slot_ticket_id(0.into()), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 0), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 1), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 100), None); + + // Initialize genesis slot.. + GenesisSlot::::set(genesis_slot); + frame_system::Pallet::::set_block_number(One::one()); + + // Try to fetch a ticket for a slot before current epoch. + assert_eq!(Sassafras::slot_ticket_id(0.into()), None); + + // Current epoch tickets. + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 0), Some(curr_tickets[1])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 1), Some(curr_tickets[3])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 2), Some(curr_tickets[5])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 3), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 4), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 5), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 6), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 7), Some(curr_tickets[4])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 8), Some(curr_tickets[2])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 9), Some(curr_tickets[0])); + + // Next epoch tickets (note that only 5 tickets are available) + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 10), Some(next_tickets[1])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 11), Some(next_tickets[3])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 12), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 13), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 14), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 15), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 16), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 17), Some(next_tickets[4])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 18), Some(next_tickets[2])); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 19), Some(next_tickets[0])); + + // Try to fetch the tickets for slots beyond the next epoch. + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 20), None); + assert_eq!(Sassafras::slot_ticket_id(genesis_slot + 42), None); + }); +} + +// Different test for outside-in test with more focus on corner case correctness. +#[test] +fn slot_ticket_id_outside_in_fetch_corner_cases() { + new_test_ext(0).execute_with(|| { + frame_system::Pallet::::set_block_number(One::one()); + + let mut meta = TicketsMetadata { tickets_count: [0, 0], unsorted_tickets_count: 0 }; + let curr_epoch_idx = EpochIndex::::get(); + + let mut epoch_test = |epoch_idx| { + let tag = (epoch_idx & 1) as u8; + let epoch_start = Sassafras::epoch_start(epoch_idx); + + // cleanup + meta.tickets_count = [0, 0]; + TicketsMeta::::set(meta); + assert!((0..10).all(|i| Sassafras::slot_ticket_id((epoch_start + i).into()).is_none())); + + meta.tickets_count[tag as usize] += 1; + TicketsMeta::::set(meta); + TicketsIds::::insert((tag, 0_u32), 1_u128); + assert_eq!(Sassafras::slot_ticket_id((epoch_start + 9).into()), Some(1_u128)); + assert!((0..9).all(|i| Sassafras::slot_ticket_id((epoch_start + i).into()).is_none())); + + meta.tickets_count[tag as usize] += 1; + TicketsMeta::::set(meta); + TicketsIds::::insert((tag, 1_u32), 2_u128); + assert_eq!(Sassafras::slot_ticket_id((epoch_start + 0).into()), Some(2_u128)); + assert!((1..9).all(|i| Sassafras::slot_ticket_id((epoch_start + i).into()).is_none())); + + meta.tickets_count[tag as usize] += 2; + TicketsMeta::::set(meta); + TicketsIds::::insert((tag, 2_u32), 3_u128); + assert_eq!(Sassafras::slot_ticket_id((epoch_start + 8).into()), Some(3_u128)); + assert!((1..8).all(|i| Sassafras::slot_ticket_id((epoch_start + i).into()).is_none())); + }; + + // Even epoch + epoch_test(curr_epoch_idx); + epoch_test(curr_epoch_idx + 1); + }); +} + +#[test] +fn on_first_block_after_genesis() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + + ext.execute_with(|| { + let start_slot = Slot::from(100); + let start_block = 1; + + let digest = initialize_block(start_block, start_slot, Default::default(), &pairs[0]); + + let common_assertions = || { + assert_eq!(Sassafras::genesis_slot(), start_slot); + assert_eq!(Sassafras::current_slot(), start_slot); + assert_eq!(Sassafras::epoch_index(), 0); + assert_eq!(Sassafras::current_epoch_start(), start_slot); + assert_eq!(Sassafras::current_slot_index(), 0); + assert_eq!(Sassafras::randomness(), [0; 32]); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("a49592ef190b96f3eb87bde4c8355e33df28c75006156e8c81998158de2ed49e") + ); + }; + + // Post-initialization status + + assert!(ClaimTemporaryData::::exists()); + common_assertions(); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("f0d42f6b7c0d157ecbd788be44847b80a96c290c04b5dfa5d1d40c98aa0c04ed") + ); + + let header = finalize_block(start_block); + + // Post-finalization status + + assert!(!ClaimTemporaryData::::exists()); + common_assertions(); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("9f2b9fd19a772c34d437dcd8b84a927e73a5cb43d3d1cd00093223d60d2b4843"), + ); + + // Header data check + + assert_eq!(header.digest.logs.len(), 2); + assert_eq!(header.digest.logs[0], digest.logs[0]); + + // Genesis epoch start deposits consensus + let consensus_log = sp_consensus_sassafras::digests::ConsensusLog::NextEpochData( + sp_consensus_sassafras::digests::NextEpochDescriptor { + authorities: Sassafras::next_authorities().into_inner(), + randomness: Sassafras::next_randomness(), + config: None, + }, + ); + let consensus_digest = DigestItem::Consensus(SASSAFRAS_ENGINE_ID, consensus_log.encode()); + assert_eq!(header.digest.logs[1], consensus_digest) + }) +} + +#[test] +fn on_normal_block() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + let start_slot = Slot::from(100); + let start_block = 1; + let end_block = start_block + 1; + + ext.execute_with(|| { + initialize_block(start_block, start_slot, Default::default(), &pairs[0]); + + // We don't want to trigger an epoch change in this test. + let epoch_length = Sassafras::epoch_length() as u64; + assert!(epoch_length > end_block); + + // Progress to block 2 + let digest = progress_to_block(end_block, &pairs[0]).unwrap(); + + let common_assertions = || { + assert_eq!(Sassafras::genesis_slot(), start_slot); + assert_eq!(Sassafras::current_slot(), start_slot + 1); + assert_eq!(Sassafras::epoch_index(), 0); + assert_eq!(Sassafras::current_epoch_start(), start_slot); + assert_eq!(Sassafras::current_slot_index(), 1); + assert_eq!(Sassafras::randomness(), [0; 32]); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("a49592ef190b96f3eb87bde4c8355e33df28c75006156e8c81998158de2ed49e") + ); + }; + + // Post-initialization status + + assert!(ClaimTemporaryData::::exists()); + common_assertions(); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("9f2b9fd19a772c34d437dcd8b84a927e73a5cb43d3d1cd00093223d60d2b4843"), + ); + + let header = finalize_block(end_block); + + // Post-finalization status + + assert!(!ClaimTemporaryData::::exists()); + common_assertions(); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("be9261adb9686dfd3f23f8a276b7acc7f4beb3137070beb64c282ac22d84cbf0"), + ); + + // Header data check + + assert_eq!(header.digest.logs.len(), 1); + assert_eq!(header.digest.logs[0], digest.logs[0]); + }); +} + +#[test] +fn produce_epoch_change_digest_no_config() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + + ext.execute_with(|| { + let start_slot = Slot::from(100); + let start_block = 1; + + initialize_block(start_block, start_slot, Default::default(), &pairs[0]); + + // We want to trigger an epoch change in this test. + let epoch_length = Sassafras::epoch_length() as u64; + let end_block = start_block + epoch_length; + + let digest = progress_to_block(end_block, &pairs[0]).unwrap(); + + let common_assertions = || { + assert_eq!(Sassafras::genesis_slot(), start_slot); + assert_eq!(Sassafras::current_slot(), start_slot + epoch_length); + assert_eq!(Sassafras::epoch_index(), 1); + assert_eq!(Sassafras::current_epoch_start(), start_slot + epoch_length); + assert_eq!(Sassafras::current_slot_index(), 0); + println!("[DEBUG] {}", b2h(Sassafras::randomness())); + assert_eq!( + Sassafras::randomness(), + h2b("a49592ef190b96f3eb87bde4c8355e33df28c75006156e8c81998158de2ed49e") + ); + }; + + // Post-initialization status + + assert!(ClaimTemporaryData::::exists()); + common_assertions(); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("d3a18b857af6ecc7b52f047107e684fff0058b5722d540a296d727e37eaa55b3"), + ); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("bf0f1228f4ff953c8c1bda2cceb668bf86ea05d7ae93e26d021c9690995d5279"), + ); + + let header = finalize_block(end_block); + + // Post-finalization status + + assert!(!ClaimTemporaryData::::exists()); + common_assertions(); + println!("[DEBUG] {}", b2h(Sassafras::next_randomness())); + assert_eq!( + Sassafras::next_randomness(), + h2b("d3a18b857af6ecc7b52f047107e684fff0058b5722d540a296d727e37eaa55b3"), + ); + println!("[DEBUG] {}", b2h(Sassafras::randomness_accumulator())); + assert_eq!( + Sassafras::randomness_accumulator(), + h2b("8a1ceb346036c386d021264b10912c8b656799668004c4a487222462b394cd89"), + ); + + // Header data check + + assert_eq!(header.digest.logs.len(), 2); + assert_eq!(header.digest.logs[0], digest.logs[0]); + // Deposits consensus log on epoch change + let consensus_log = sp_consensus_sassafras::digests::ConsensusLog::NextEpochData( + sp_consensus_sassafras::digests::NextEpochDescriptor { + authorities: Sassafras::next_authorities().into_inner(), + randomness: Sassafras::next_randomness(), + config: None, + }, + ); + let consensus_digest = DigestItem::Consensus(SASSAFRAS_ENGINE_ID, consensus_log.encode()); + assert_eq!(header.digest.logs[1], consensus_digest) + }) +} + +#[test] +fn produce_epoch_change_digest_with_config() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + + ext.execute_with(|| { + let start_slot = Slot::from(100); + let start_block = 1; + + initialize_block(start_block, start_slot, Default::default(), &pairs[0]); + + let config = EpochConfiguration { redundancy_factor: 1, attempts_number: 123 }; + Sassafras::plan_config_change(RuntimeOrigin::root(), config).unwrap(); + + // We want to trigger an epoch change in this test. + let epoch_length = Sassafras::epoch_length() as u64; + let end_block = start_block + epoch_length; + + let digest = progress_to_block(end_block, &pairs[0]).unwrap(); + + let header = finalize_block(end_block); + + // Header data check. + // Skip pallet status checks that were already performed by other tests. + + assert_eq!(header.digest.logs.len(), 2); + assert_eq!(header.digest.logs[0], digest.logs[0]); + // Deposits consensus log on epoch change + let consensus_log = sp_consensus_sassafras::digests::ConsensusLog::NextEpochData( + sp_consensus_sassafras::digests::NextEpochDescriptor { + authorities: Sassafras::next_authorities().into_inner(), + randomness: Sassafras::next_randomness(), + config: Some(config), + }, + ); + let consensus_digest = DigestItem::Consensus(SASSAFRAS_ENGINE_ID, consensus_log.encode()); + assert_eq!(header.digest.logs[1], consensus_digest) + }) +} + +#[test] +fn segments_incremental_sort_works() { + let (pairs, mut ext) = new_test_ext_with_pairs(1, false); + let pair = &pairs[0]; + let segments_count = 14; + let start_slot = Slot::from(100); + let start_block = 1; + + ext.execute_with(|| { + let epoch_length = Sassafras::epoch_length() as u64; + // -3 just to have the last segment not full... + let submitted_tickets_count = segments_count * SEGMENT_MAX_SIZE - 3; + + initialize_block(start_block, start_slot, Default::default(), pair); + + // Manually populate the segments to skip the threshold check + let mut tickets = make_ticket_bodies(submitted_tickets_count, None); + persist_next_epoch_tickets_as_segments(&tickets); + + // Proceed to half of the epoch (sortition should not have been started yet) + let half_epoch_block = start_block + epoch_length / 2; + progress_to_block(half_epoch_block, pair); + + let mut unsorted_tickets_count = submitted_tickets_count; + + // Check that next epoch tickets sortition is not started yet + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count); + assert_eq!(meta.tickets_count, [0, 0]); + + // Follow the incremental sortition block by block + + progress_to_block(half_epoch_block + 1, pair); + unsorted_tickets_count -= 3 * SEGMENT_MAX_SIZE - 3; + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count,); + assert_eq!(meta.tickets_count, [0, 0]); + + progress_to_block(half_epoch_block + 2, pair); + unsorted_tickets_count -= 3 * SEGMENT_MAX_SIZE; + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count); + assert_eq!(meta.tickets_count, [0, 0]); + + progress_to_block(half_epoch_block + 3, pair); + unsorted_tickets_count -= 3 * SEGMENT_MAX_SIZE; + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count); + assert_eq!(meta.tickets_count, [0, 0]); + + progress_to_block(half_epoch_block + 4, pair); + unsorted_tickets_count -= 3 * SEGMENT_MAX_SIZE; + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count); + assert_eq!(meta.tickets_count, [0, 0]); + + let header = finalize_block(half_epoch_block + 4); + + // Sort should be finished now. + // Check that next epoch tickets count have the correct value. + // Bigger ticket ids were discarded during sortition. + unsorted_tickets_count -= 2 * SEGMENT_MAX_SIZE; + assert_eq!(unsorted_tickets_count, 0); + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, unsorted_tickets_count); + assert_eq!(meta.tickets_count, [0, epoch_length as u32]); + // Epoch change log should have been pushed as well + assert_eq!(header.digest.logs.len(), 1); + // No tickets for the current epoch + assert_eq!(TicketsIds::::get((0, 0)), None); + + // Check persistence of "winning" tickets + tickets.sort_by_key(|t| t.0); + (0..epoch_length as usize).into_iter().for_each(|i| { + let id = TicketsIds::::get((1, i as u32)).unwrap(); + let body = TicketsData::::get(id).unwrap(); + assert_eq!((id, body), tickets[i]); + }); + // Check removal of "loosing" tickets + (epoch_length as usize..tickets.len()).into_iter().for_each(|i| { + assert!(TicketsIds::::get((1, i as u32)).is_none()); + assert!(TicketsData::::get(tickets[i].0).is_none()); + }); + + // The next block will be the first produced on the new epoch. + // At this point the tickets are found already sorted and ready to be used. + let slot = Sassafras::current_slot() + 1; + let number = System::block_number() + 1; + initialize_block(number, slot, header.hash(), pair); + let header = finalize_block(number); + // Epoch changes digest is also produced + assert_eq!(header.digest.logs.len(), 2); + }); +} + +#[test] +fn tickets_fetch_works_after_epoch_change() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + let pair = &pairs[0]; + let start_slot = Slot::from(100); + let start_block = 1; + let submitted_tickets = 300; + + ext.execute_with(|| { + initialize_block(start_block, start_slot, Default::default(), pair); + + // We don't want to trigger an epoch change in this test. + let epoch_length = Sassafras::epoch_length() as u64; + assert!(epoch_length > 2); + progress_to_block(2, &pairs[0]).unwrap(); + + // Persist tickets as three different segments. + let tickets = make_ticket_bodies(submitted_tickets, None); + persist_next_epoch_tickets_as_segments(&tickets); + + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, submitted_tickets); + assert_eq!(meta.tickets_count, [0, 0]); + + // Progress up to the last epoch slot (do not enact epoch change) + progress_to_block(epoch_length, &pairs[0]).unwrap(); + + // At this point next epoch tickets should have been sorted and ready to be used + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, 0); + assert_eq!(meta.tickets_count, [0, epoch_length as u32]); + + // Compute and sort the tickets ids (aka tickets scores) + let mut expected_ids: Vec<_> = tickets.into_iter().map(|(id, _)| id).collect(); + expected_ids.sort(); + expected_ids.truncate(epoch_length as usize); + + // Check if we can fetch next epoch tickets ids (outside-in). + let slot = Sassafras::current_slot(); + assert_eq!(Sassafras::slot_ticket_id(slot + 1).unwrap(), expected_ids[1]); + assert_eq!(Sassafras::slot_ticket_id(slot + 2).unwrap(), expected_ids[3]); + assert_eq!(Sassafras::slot_ticket_id(slot + 3).unwrap(), expected_ids[5]); + assert_eq!(Sassafras::slot_ticket_id(slot + 4).unwrap(), expected_ids[7]); + assert_eq!(Sassafras::slot_ticket_id(slot + 7).unwrap(), expected_ids[6]); + assert_eq!(Sassafras::slot_ticket_id(slot + 8).unwrap(), expected_ids[4]); + assert_eq!(Sassafras::slot_ticket_id(slot + 9).unwrap(), expected_ids[2]); + assert_eq!(Sassafras::slot_ticket_id(slot + 10).unwrap(), expected_ids[0]); + assert!(Sassafras::slot_ticket_id(slot + 11).is_none()); + + // Enact epoch change by progressing one more block + + progress_to_block(epoch_length + 1, &pairs[0]).unwrap(); + + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, 0); + assert_eq!(meta.tickets_count, [0, 10]); + + // Check if we can fetch current epoch tickets ids (outside-in). + let slot = Sassafras::current_slot(); + assert_eq!(Sassafras::slot_ticket_id(slot).unwrap(), expected_ids[1]); + assert_eq!(Sassafras::slot_ticket_id(slot + 1).unwrap(), expected_ids[3]); + assert_eq!(Sassafras::slot_ticket_id(slot + 2).unwrap(), expected_ids[5]); + assert_eq!(Sassafras::slot_ticket_id(slot + 3).unwrap(), expected_ids[7]); + assert_eq!(Sassafras::slot_ticket_id(slot + 6).unwrap(), expected_ids[6]); + assert_eq!(Sassafras::slot_ticket_id(slot + 7).unwrap(), expected_ids[4]); + assert_eq!(Sassafras::slot_ticket_id(slot + 8).unwrap(), expected_ids[2]); + assert_eq!(Sassafras::slot_ticket_id(slot + 9).unwrap(), expected_ids[0]); + assert!(Sassafras::slot_ticket_id(slot + 10).is_none()); + + // Enact another epoch change, for which we don't have any ticket + progress_to_block(2 * epoch_length + 1, &pairs[0]).unwrap(); + let meta = TicketsMeta::::get(); + assert_eq!(meta.unsorted_tickets_count, 0); + assert_eq!(meta.tickets_count, [0, 0]); + }); +} + +#[test] +fn block_allowed_to_skip_epochs() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + let pair = &pairs[0]; + let start_slot = Slot::from(100); + let start_block = 1; + + ext.execute_with(|| { + let epoch_length = Sassafras::epoch_length() as u64; + + initialize_block(start_block, start_slot, Default::default(), pair); + + let tickets = make_ticket_bodies(3, Some(pair)); + persist_next_epoch_tickets(&tickets); + + let next_random = Sassafras::next_randomness(); + + // We want to skip 3 epochs in this test. + let offset = 4 * epoch_length; + go_to_block(start_block + offset, start_slot + offset, &pairs[0]); + + // Post-initialization status + + assert!(ClaimTemporaryData::::exists()); + assert_eq!(Sassafras::genesis_slot(), start_slot); + assert_eq!(Sassafras::current_slot(), start_slot + offset); + assert_eq!(Sassafras::epoch_index(), 4); + assert_eq!(Sassafras::current_epoch_start(), start_slot + offset); + assert_eq!(Sassafras::current_slot_index(), 0); + + // Tickets data has been discarded + assert_eq!(TicketsMeta::::get(), TicketsMetadata::default()); + assert!(tickets.iter().all(|(id, _)| TicketsData::::get(id).is_none())); + assert_eq!(SortedCandidates::::get().len(), 0); + + // We used the last known next epoch randomness as a fallback + assert_eq!(next_random, Sassafras::randomness()); + }); +} + +#[test] +fn obsolete_tickets_are_removed_on_epoch_change() { + let (pairs, mut ext) = new_test_ext_with_pairs(4, false); + let pair = &pairs[0]; + let start_slot = Slot::from(100); + let start_block = 1; + + ext.execute_with(|| { + let epoch_length = Sassafras::epoch_length() as u64; + + initialize_block(start_block, start_slot, Default::default(), pair); + + let tickets = make_ticket_bodies(10, Some(pair)); + let mut epoch1_tickets = tickets[..4].to_vec(); + let mut epoch2_tickets = tickets[4..].to_vec(); + + // Persist some tickets for next epoch (N) + persist_next_epoch_tickets(&epoch1_tickets); + assert_eq!(TicketsMeta::::get().tickets_count, [0, 4]); + // Check next epoch tickets presence + epoch1_tickets.sort_by_key(|t| t.0); + (0..epoch1_tickets.len()).into_iter().for_each(|i| { + let id = TicketsIds::::get((1, i as u32)).unwrap(); + let body = TicketsData::::get(id).unwrap(); + assert_eq!((id, body), epoch1_tickets[i]); + }); + + // Advance one epoch to enact the tickets + go_to_block(start_block + epoch_length, start_slot + epoch_length, pair); + assert_eq!(TicketsMeta::::get().tickets_count, [0, 4]); + + // Persist some tickets for next epoch (N+1) + persist_next_epoch_tickets(&epoch2_tickets); + assert_eq!(TicketsMeta::::get().tickets_count, [6, 4]); + epoch2_tickets.sort_by_key(|t| t.0); + // Check for this epoch and next epoch tickets presence + (0..epoch1_tickets.len()).into_iter().for_each(|i| { + let id = TicketsIds::::get((1, i as u32)).unwrap(); + let body = TicketsData::::get(id).unwrap(); + assert_eq!((id, body), epoch1_tickets[i]); + }); + (0..epoch2_tickets.len()).into_iter().for_each(|i| { + let id = TicketsIds::::get((0, i as u32)).unwrap(); + let body = TicketsData::::get(id).unwrap(); + assert_eq!((id, body), epoch2_tickets[i]); + }); + + // Advance to epoch 2 and check for cleanup + + go_to_block(start_block + 2 * epoch_length, start_slot + 2 * epoch_length, pair); + assert_eq!(TicketsMeta::::get().tickets_count, [6, 0]); + + (0..epoch1_tickets.len()).into_iter().for_each(|i| { + let id = TicketsIds::::get((1, i as u32)).unwrap(); + assert!(TicketsData::::get(id).is_none()); + }); + (0..epoch2_tickets.len()).into_iter().for_each(|i| { + let id = TicketsIds::::get((0, i as u32)).unwrap(); + let body = TicketsData::::get(id).unwrap(); + assert_eq!((id, body), epoch2_tickets[i]); + }); + }) +} + +const TICKETS_FILE: &str = "src/data/25_tickets_100_auths.bin"; + +fn data_read(filename: &str) -> T { + use std::{fs::File, io::Read}; + let mut file = File::open(filename).unwrap(); + let mut buf = Vec::new(); + file.read_to_end(&mut buf).unwrap(); + T::decode(&mut &buf[..]).unwrap() +} + +fn data_write(filename: &str, data: T) { + use std::{fs::File, io::Write}; + let mut file = File::create(filename).unwrap(); + let buf = data.encode(); + file.write_all(&buf).unwrap(); +} + +// We don't want to implement anything secure here. +// Just a trivial shuffle for the tests. +fn trivial_fisher_yates_shuffle(vector: &mut Vec, random_seed: u64) { + let mut rng = random_seed as usize; + for i in (1..vector.len()).rev() { + let j = rng % (i + 1); + vector.swap(i, j); + rng = (rng.wrapping_mul(6364793005) + 1) as usize; // Some random number generation + } +} + +// For this test we use a set of pre-constructed tickets from a file. +// Creating a large set of tickets on the fly takes time, and may be annoying +// for test execution. +// +// A valid ring-context is required for this test since we are passing through the +// `submit_ticket` call which tests for ticket validity. +#[test] +fn submit_tickets_with_ring_proof_check_works() { + use sp_core::Pair as _; + // env_logger::init(); + + let (authorities, mut tickets): (Vec, Vec) = + data_read(TICKETS_FILE); + + // Also checks that duplicates are discarded + tickets.extend(tickets.clone()); + trivial_fisher_yates_shuffle(&mut tickets, 321); + + let (pairs, mut ext) = new_test_ext_with_pairs(authorities.len(), true); + let pair = &pairs[0]; + // Check if deserialized data has been generated for the correct set of authorities... + assert!(authorities.iter().zip(pairs.iter()).all(|(auth, pair)| auth == &pair.public())); + + ext.execute_with(|| { + let start_slot = Slot::from(0); + let start_block = 1; + + // Tweak the config to discard ~half of the tickets. + let mut config = EpochConfig::::get(); + config.redundancy_factor = 25; + EpochConfig::::set(config); + + initialize_block(start_block, start_slot, Default::default(), pair); + NextRandomness::::set([0; 32]); + + // Check state before tickets submission + assert_eq!( + TicketsMeta::::get(), + TicketsMetadata { unsorted_tickets_count: 0, tickets_count: [0, 0] }, + ); + + // Submit the tickets + let max_tickets_per_call = Sassafras::epoch_length() as usize; + tickets.chunks(max_tickets_per_call).for_each(|chunk| { + let chunk = BoundedVec::truncate_from(chunk.to_vec()); + Sassafras::submit_tickets(RuntimeOrigin::none(), chunk).unwrap(); + }); + + // Check state after submission + assert_eq!( + TicketsMeta::::get(), + TicketsMetadata { unsorted_tickets_count: 16, tickets_count: [0, 0] }, + ); + assert_eq!(UnsortedSegments::::get(0).len(), 16); + assert_eq!(UnsortedSegments::::get(1).len(), 0); + + finalize_block(start_block); + }) +} + +#[test] +#[ignore = "test tickets data generator"] +fn make_tickets_data() { + use super::*; + use sp_core::crypto::Pair; + + // Number of authorities who produces tickets (for the sake of this test) + let tickets_authors_count = 5; + // Total number of authorities (the ring) + let authorities_count = 100; + let (pairs, mut ext) = new_test_ext_with_pairs(authorities_count, true); + + let authorities: Vec<_> = pairs.iter().map(|sk| sk.public()).collect(); + + ext.execute_with(|| { + let config = EpochConfig::::get(); + + let tickets_count = tickets_authors_count * config.attempts_number as usize; + let mut tickets = Vec::with_capacity(tickets_count); + + // Construct pre-built tickets with a well known `NextRandomness` value. + NextRandomness::::set([0; 32]); + + println!("Constructing {} tickets", tickets_count); + pairs.iter().take(tickets_authors_count).enumerate().for_each(|(i, pair)| { + let t = make_tickets(config.attempts_number, pair); + tickets.extend(t); + println!("{:.2}%", 100f32 * ((i + 1) as f32 / tickets_authors_count as f32)); + }); + + data_write(TICKETS_FILE, (authorities, tickets)); + }); +} diff --git a/substrate/frame/sassafras/src/weights.rs b/substrate/frame/sassafras/src/weights.rs new file mode 100644 index 000000000000..32ea2d29a180 --- /dev/null +++ b/substrate/frame/sassafras/src/weights.rs @@ -0,0 +1,425 @@ +// 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. + +//! Autogenerated weights for `pallet_sassafras` +//! +//! THIS FILE WAS AUTO-GENERATED USING THE SUBSTRATE BENCHMARK CLI VERSION 4.0.0-dev +//! DATE: 2023-11-16, STEPS: `20`, REPEAT: `3`, LOW RANGE: `[]`, HIGH RANGE: `[]` +//! WORST CASE MAP SIZE: `1000000` +//! HOSTNAME: `behemoth`, CPU: `AMD Ryzen Threadripper 3970X 32-Core Processor` +//! WASM-EXECUTION: `Compiled`, CHAIN: `Some("dev")`, DB CACHE: `1024` + +// Executed Command: +// ./target/release/node-template +// benchmark +// pallet +// --chain +// dev +// --pallet +// pallet_sassafras +// --extrinsic +// * +// --steps +// 20 +// --repeat +// 3 +// --output +// weights.rs +// --template +// substrate/.maintain/frame-weight-template.hbs + +#![cfg_attr(rustfmt, rustfmt_skip)] +#![allow(unused_parens)] +#![allow(unused_imports)] +#![allow(missing_docs)] + +use frame_support::{traits::Get, weights::{Weight, constants::RocksDbWeight}}; +use core::marker::PhantomData; + +/// Weight functions needed for `pallet_sassafras`. +pub trait WeightInfo { + fn on_initialize() -> Weight; + fn enact_epoch_change(x: u32, y: u32, ) -> Weight; + fn submit_tickets(x: u32, ) -> Weight; + fn plan_config_change() -> Weight; + fn update_ring_verifier(x: u32, ) -> Weight; + fn load_ring_context() -> Weight; + fn sort_segments(x: u32, ) -> Weight; +} + +/// Weights for `pallet_sassafras` using the Substrate node and recommended hardware. +pub struct SubstrateWeight(PhantomData); +impl WeightInfo for SubstrateWeight { + /// Storage: `System::Digest` (r:1 w:1) + /// Proof: `System::Digest` (`max_values`: Some(1), `max_size`: None, mode: `Measured`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:0) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:0) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentRandomness` (r:1 w:0) + /// Proof: `Sassafras::CurrentRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:0) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RandomnessAccumulator` (r:1 w:1) + /// Proof: `Sassafras::RandomnessAccumulator` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentSlot` (r:0 w:1) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::ClaimTemporaryData` (r:0 w:1) + /// Proof: `Sassafras::ClaimTemporaryData` (`max_values`: Some(1), `max_size`: Some(33), added: 528, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:0 w:1) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + fn on_initialize() -> Weight { + // Proof Size summary in bytes: + // Measured: `302` + // Estimated: `4787` + // Minimum execution time: 438_039_000 picoseconds. + Weight::from_parts(439_302_000, 4787) + .saturating_add(T::DbWeight::get().reads(6_u64)) + .saturating_add(T::DbWeight::get().writes(5_u64)) + } + /// Storage: `Sassafras::CurrentSlot` (r:1 w:0) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:1) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:1 w:0) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:1) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsMeta` (r:1 w:1) + /// Proof: `Sassafras::TicketsMeta` (`max_values`: Some(1), `max_size`: Some(12), added: 507, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:1) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RandomnessAccumulator` (r:1 w:0) + /// Proof: `Sassafras::RandomnessAccumulator` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextEpochConfig` (r:1 w:1) + /// Proof: `Sassafras::NextEpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::PendingEpochConfigChange` (r:1 w:1) + /// Proof: `Sassafras::PendingEpochConfigChange` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `System::Digest` (r:1 w:1) + /// Proof: `System::Digest` (`max_values`: Some(1), `max_size`: None, mode: `Measured`) + /// Storage: `Sassafras::SortedCandidates` (r:1 w:0) + /// Proof: `Sassafras::SortedCandidates` (`max_values`: Some(1), `max_size`: Some(3202), added: 3697, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:79 w:79) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsIds` (r:5000 w:200) + /// Proof: `Sassafras::TicketsIds` (`max_values`: None, `max_size`: Some(21), added: 2496, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::Authorities` (r:0 w:1) + /// Proof: `Sassafras::Authorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:0 w:9896) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:0 w:1) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochConfig` (r:0 w:1) + /// Proof: `Sassafras::EpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentRandomness` (r:0 w:1) + /// Proof: `Sassafras::CurrentRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + /// The range of component `y` is `[1000, 5000]`. + fn enact_epoch_change(x: u32, y: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `594909 + x * (33 ±0) + y * (53 ±0)` + // Estimated: `593350 + x * (24 ±1) + y * (2496 ±0)` + // Minimum execution time: 121_279_846_000 picoseconds. + Weight::from_parts(94_454_851_972, 593350) + // Standard Error: 24_177_301 + .saturating_add(Weight::from_parts(8_086_191, 0).saturating_mul(x.into())) + // Standard Error: 601_053 + .saturating_add(Weight::from_parts(15_578_413, 0).saturating_mul(y.into())) + .saturating_add(T::DbWeight::get().reads(13_u64)) + .saturating_add(T::DbWeight::get().reads((1_u64).saturating_mul(y.into()))) + .saturating_add(T::DbWeight::get().writes(112_u64)) + .saturating_add(T::DbWeight::get().writes((2_u64).saturating_mul(y.into()))) + .saturating_add(Weight::from_parts(0, 24).saturating_mul(x.into())) + .saturating_add(Weight::from_parts(0, 2496).saturating_mul(y.into())) + } + /// Storage: `Sassafras::CurrentSlot` (r:1 w:0) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:0) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:1 w:0) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:1 w:0) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:0) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextEpochConfig` (r:1 w:0) + /// Proof: `Sassafras::NextEpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:0) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:25 w:25) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsMeta` (r:1 w:1) + /// Proof: `Sassafras::TicketsMeta` (`max_values`: Some(1), `max_size`: Some(12), added: 507, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:1 w:1) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 25]`. + fn submit_tickets(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `3869` + // Estimated: `5519 + x * (2559 ±0)` + // Minimum execution time: 36_904_934_000 picoseconds. + Weight::from_parts(25_822_957_295, 5519) + // Standard Error: 11_047_832 + .saturating_add(Weight::from_parts(11_338_353_299, 0).saturating_mul(x.into())) + .saturating_add(T::DbWeight::get().reads(9_u64)) + .saturating_add(T::DbWeight::get().reads((1_u64).saturating_mul(x.into()))) + .saturating_add(T::DbWeight::get().writes(2_u64)) + .saturating_add(T::DbWeight::get().writes((1_u64).saturating_mul(x.into()))) + .saturating_add(Weight::from_parts(0, 2559).saturating_mul(x.into())) + } + /// Storage: `Sassafras::PendingEpochConfigChange` (r:0 w:1) + /// Proof: `Sassafras::PendingEpochConfigChange` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + fn plan_config_change() -> Weight { + // Proof Size summary in bytes: + // Measured: `0` + // Estimated: `0` + // Minimum execution time: 4_038_000 picoseconds. + Weight::from_parts(4_499_000, 0) + .saturating_add(T::DbWeight::get().writes(1_u64)) + } + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:0 w:1) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + fn update_ring_verifier(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `590485` + // Estimated: `591809` + // Minimum execution time: 105_121_424_000 picoseconds. + Weight::from_parts(105_527_334_385, 591809) + // Standard Error: 2_933_910 + .saturating_add(Weight::from_parts(96_136_261, 0).saturating_mul(x.into())) + .saturating_add(T::DbWeight::get().reads(1_u64)) + .saturating_add(T::DbWeight::get().writes(1_u64)) + } + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + fn load_ring_context() -> Weight { + // Proof Size summary in bytes: + // Measured: `590485` + // Estimated: `591809` + // Minimum execution time: 44_005_681_000 picoseconds. + Weight::from_parts(44_312_079_000, 591809) + .saturating_add(T::DbWeight::get().reads(1_u64)) + } + /// Storage: `Sassafras::SortedCandidates` (r:1 w:0) + /// Proof: `Sassafras::SortedCandidates` (`max_values`: Some(1), `max_size`: Some(3202), added: 3697, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:100 w:100) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsIds` (r:0 w:200) + /// Proof: `Sassafras::TicketsIds` (`max_values`: None, `max_size`: Some(21), added: 2496, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:0 w:12600) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + fn sort_segments(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `222 + x * (2060 ±0)` + // Estimated: `4687 + x * (4529 ±0)` + // Minimum execution time: 183_501_000 picoseconds. + Weight::from_parts(183_501_000, 4687) + // Standard Error: 1_426_363 + .saturating_add(Weight::from_parts(169_156_241, 0).saturating_mul(x.into())) + .saturating_add(T::DbWeight::get().reads(1_u64)) + .saturating_add(T::DbWeight::get().reads((1_u64).saturating_mul(x.into()))) + .saturating_add(T::DbWeight::get().writes((129_u64).saturating_mul(x.into()))) + .saturating_add(Weight::from_parts(0, 4529).saturating_mul(x.into())) + } +} + +// For backwards compatibility and tests. +impl WeightInfo for () { + /// Storage: `System::Digest` (r:1 w:1) + /// Proof: `System::Digest` (`max_values`: Some(1), `max_size`: None, mode: `Measured`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:0) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:0) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentRandomness` (r:1 w:0) + /// Proof: `Sassafras::CurrentRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:0) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RandomnessAccumulator` (r:1 w:1) + /// Proof: `Sassafras::RandomnessAccumulator` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentSlot` (r:0 w:1) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::ClaimTemporaryData` (r:0 w:1) + /// Proof: `Sassafras::ClaimTemporaryData` (`max_values`: Some(1), `max_size`: Some(33), added: 528, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:0 w:1) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + fn on_initialize() -> Weight { + // Proof Size summary in bytes: + // Measured: `302` + // Estimated: `4787` + // Minimum execution time: 438_039_000 picoseconds. + Weight::from_parts(439_302_000, 4787) + .saturating_add(RocksDbWeight::get().reads(6_u64)) + .saturating_add(RocksDbWeight::get().writes(5_u64)) + } + /// Storage: `Sassafras::CurrentSlot` (r:1 w:0) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:1) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:1 w:0) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:1) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsMeta` (r:1 w:1) + /// Proof: `Sassafras::TicketsMeta` (`max_values`: Some(1), `max_size`: Some(12), added: 507, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:1) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RandomnessAccumulator` (r:1 w:0) + /// Proof: `Sassafras::RandomnessAccumulator` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextEpochConfig` (r:1 w:1) + /// Proof: `Sassafras::NextEpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::PendingEpochConfigChange` (r:1 w:1) + /// Proof: `Sassafras::PendingEpochConfigChange` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `System::Digest` (r:1 w:1) + /// Proof: `System::Digest` (`max_values`: Some(1), `max_size`: None, mode: `Measured`) + /// Storage: `Sassafras::SortedCandidates` (r:1 w:0) + /// Proof: `Sassafras::SortedCandidates` (`max_values`: Some(1), `max_size`: Some(3202), added: 3697, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:79 w:79) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsIds` (r:5000 w:200) + /// Proof: `Sassafras::TicketsIds` (`max_values`: None, `max_size`: Some(21), added: 2496, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::Authorities` (r:0 w:1) + /// Proof: `Sassafras::Authorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:0 w:9896) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:0 w:1) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochConfig` (r:0 w:1) + /// Proof: `Sassafras::EpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::CurrentRandomness` (r:0 w:1) + /// Proof: `Sassafras::CurrentRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + /// The range of component `y` is `[1000, 5000]`. + fn enact_epoch_change(x: u32, y: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `594909 + x * (33 ±0) + y * (53 ±0)` + // Estimated: `593350 + x * (24 ±1) + y * (2496 ±0)` + // Minimum execution time: 121_279_846_000 picoseconds. + Weight::from_parts(94_454_851_972, 593350) + // Standard Error: 24_177_301 + .saturating_add(Weight::from_parts(8_086_191, 0).saturating_mul(x.into())) + // Standard Error: 601_053 + .saturating_add(Weight::from_parts(15_578_413, 0).saturating_mul(y.into())) + .saturating_add(RocksDbWeight::get().reads(13_u64)) + .saturating_add(RocksDbWeight::get().reads((1_u64).saturating_mul(y.into()))) + .saturating_add(RocksDbWeight::get().writes(112_u64)) + .saturating_add(RocksDbWeight::get().writes((2_u64).saturating_mul(y.into()))) + .saturating_add(Weight::from_parts(0, 24).saturating_mul(x.into())) + .saturating_add(Weight::from_parts(0, 2496).saturating_mul(y.into())) + } + /// Storage: `Sassafras::CurrentSlot` (r:1 w:0) + /// Proof: `Sassafras::CurrentSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::EpochIndex` (r:1 w:0) + /// Proof: `Sassafras::EpochIndex` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::GenesisSlot` (r:1 w:0) + /// Proof: `Sassafras::GenesisSlot` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:1 w:0) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextAuthorities` (r:1 w:0) + /// Proof: `Sassafras::NextAuthorities` (`max_values`: Some(1), `max_size`: Some(3302), added: 3797, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextEpochConfig` (r:1 w:0) + /// Proof: `Sassafras::NextEpochConfig` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::NextRandomness` (r:1 w:0) + /// Proof: `Sassafras::NextRandomness` (`max_values`: Some(1), `max_size`: Some(32), added: 527, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:25 w:25) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsMeta` (r:1 w:1) + /// Proof: `Sassafras::TicketsMeta` (`max_values`: Some(1), `max_size`: Some(12), added: 507, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:1 w:1) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 25]`. + fn submit_tickets(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `3869` + // Estimated: `5519 + x * (2559 ±0)` + // Minimum execution time: 36_904_934_000 picoseconds. + Weight::from_parts(25_822_957_295, 5519) + // Standard Error: 11_047_832 + .saturating_add(Weight::from_parts(11_338_353_299, 0).saturating_mul(x.into())) + .saturating_add(RocksDbWeight::get().reads(9_u64)) + .saturating_add(RocksDbWeight::get().reads((1_u64).saturating_mul(x.into()))) + .saturating_add(RocksDbWeight::get().writes(2_u64)) + .saturating_add(RocksDbWeight::get().writes((1_u64).saturating_mul(x.into()))) + .saturating_add(Weight::from_parts(0, 2559).saturating_mul(x.into())) + } + /// Storage: `Sassafras::PendingEpochConfigChange` (r:0 w:1) + /// Proof: `Sassafras::PendingEpochConfigChange` (`max_values`: Some(1), `max_size`: Some(8), added: 503, mode: `MaxEncodedLen`) + fn plan_config_change() -> Weight { + // Proof Size summary in bytes: + // Measured: `0` + // Estimated: `0` + // Minimum execution time: 4_038_000 picoseconds. + Weight::from_parts(4_499_000, 0) + .saturating_add(RocksDbWeight::get().writes(1_u64)) + } + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::RingVerifierData` (r:0 w:1) + /// Proof: `Sassafras::RingVerifierData` (`max_values`: Some(1), `max_size`: Some(388), added: 883, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + fn update_ring_verifier(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `590485` + // Estimated: `591809` + // Minimum execution time: 105_121_424_000 picoseconds. + Weight::from_parts(105_527_334_385, 591809) + // Standard Error: 2_933_910 + .saturating_add(Weight::from_parts(96_136_261, 0).saturating_mul(x.into())) + .saturating_add(RocksDbWeight::get().reads(1_u64)) + .saturating_add(RocksDbWeight::get().writes(1_u64)) + } + /// Storage: `Sassafras::RingContext` (r:1 w:0) + /// Proof: `Sassafras::RingContext` (`max_values`: Some(1), `max_size`: Some(590324), added: 590819, mode: `MaxEncodedLen`) + fn load_ring_context() -> Weight { + // Proof Size summary in bytes: + // Measured: `590485` + // Estimated: `591809` + // Minimum execution time: 44_005_681_000 picoseconds. + Weight::from_parts(44_312_079_000, 591809) + .saturating_add(RocksDbWeight::get().reads(1_u64)) + } + /// Storage: `Sassafras::SortedCandidates` (r:1 w:0) + /// Proof: `Sassafras::SortedCandidates` (`max_values`: Some(1), `max_size`: Some(3202), added: 3697, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::UnsortedSegments` (r:100 w:100) + /// Proof: `Sassafras::UnsortedSegments` (`max_values`: None, `max_size`: Some(2054), added: 4529, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsIds` (r:0 w:200) + /// Proof: `Sassafras::TicketsIds` (`max_values`: None, `max_size`: Some(21), added: 2496, mode: `MaxEncodedLen`) + /// Storage: `Sassafras::TicketsData` (r:0 w:12600) + /// Proof: `Sassafras::TicketsData` (`max_values`: None, `max_size`: Some(84), added: 2559, mode: `MaxEncodedLen`) + /// The range of component `x` is `[1, 100]`. + fn sort_segments(x: u32, ) -> Weight { + // Proof Size summary in bytes: + // Measured: `222 + x * (2060 ±0)` + // Estimated: `4687 + x * (4529 ±0)` + // Minimum execution time: 183_501_000 picoseconds. + Weight::from_parts(183_501_000, 4687) + // Standard Error: 1_426_363 + .saturating_add(Weight::from_parts(169_156_241, 0).saturating_mul(x.into())) + .saturating_add(RocksDbWeight::get().reads(1_u64)) + .saturating_add(RocksDbWeight::get().reads((1_u64).saturating_mul(x.into()))) + .saturating_add(RocksDbWeight::get().writes((129_u64).saturating_mul(x.into()))) + .saturating_add(Weight::from_parts(0, 4529).saturating_mul(x.into())) + } +} diff --git a/substrate/primitives/consensus/sassafras/Cargo.toml b/substrate/primitives/consensus/sassafras/Cargo.toml index 67f09e2b9041..e71f82b4382f 100644 --- a/substrate/primitives/consensus/sassafras/Cargo.toml +++ b/substrate/primitives/consensus/sassafras/Cargo.toml @@ -18,12 +18,12 @@ targets = ["x86_64-unknown-linux-gnu"] scale-codec = { package = "parity-scale-codec", version = "3.2.2", default-features = false } scale-info = { version = "2.10.0", default-features = false, features = ["derive"] } serde = { version = "1.0.193", default-features = false, features = ["derive"], optional = true } -sp-api = { default-features = false, path = "../../api" } -sp-application-crypto = { default-features = false, path = "../../application-crypto", features = ["bandersnatch-experimental"] } -sp-consensus-slots = { default-features = false, path = "../slots" } -sp-core = { default-features = false, path = "../../core", features = ["bandersnatch-experimental"] } -sp-runtime = { default-features = false, path = "../../runtime" } -sp-std = { default-features = false, path = "../../std" } +sp-api = { path = "../../api", default-features = false } +sp-application-crypto = { path = "../../application-crypto", default-features = false, features = ["bandersnatch-experimental"] } +sp-consensus-slots = { path = "../slots", default-features = false } +sp-core = { path = "../../core", default-features = false, features = ["bandersnatch-experimental"] } +sp-runtime = { path = "../../runtime", default-features = false } +sp-std = { path = "../../std", default-features = false } [features] default = ["std"] diff --git a/substrate/primitives/consensus/sassafras/README.md b/substrate/primitives/consensus/sassafras/README.md index b0f3685494e4..d6251940a496 100644 --- a/substrate/primitives/consensus/sassafras/README.md +++ b/substrate/primitives/consensus/sassafras/README.md @@ -1,12 +1,6 @@ Primitives for SASSAFRAS. -# ⚠️ WARNING ⚠️ +- Tracking issue: /~https://github.com/paritytech/polkadot-sdk/issues/41 +- RFC proposal: /~https://github.com/polkadot-fellows/RFCs/pull/26 -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/polkadot-sdk/pull/1336. - -Tracking issue: /~https://github.com/paritytech/polkadot-sdk/issues/41 +Depends on `sp-core` feature: `bandersnatch-experimental`. diff --git a/substrate/primitives/consensus/sassafras/src/digests.rs b/substrate/primitives/consensus/sassafras/src/digests.rs index 95a305099de5..5274f1309d82 100644 --- a/substrate/primitives/consensus/sassafras/src/digests.rs +++ b/substrate/primitives/consensus/sassafras/src/digests.rs @@ -48,11 +48,11 @@ pub struct SlotClaim { /// This is mandatory in the first block of each epoch. #[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)] pub struct NextEpochDescriptor { + /// Randomness value. + pub randomness: Randomness, /// Authorities list. pub authorities: Vec, - /// Epoch randomness. - pub randomness: Randomness, - /// Epoch configurable parameters. + /// Epoch configuration. /// /// If not present previous epoch parameters are used. pub config: Option, diff --git a/substrate/primitives/consensus/sassafras/src/lib.rs b/substrate/primitives/consensus/sassafras/src/lib.rs index e421e771d406..1752f7658863 100644 --- a/substrate/primitives/consensus/sassafras/src/lib.rs +++ b/substrate/primitives/consensus/sassafras/src/lib.rs @@ -80,33 +80,43 @@ pub type EquivocationProof = sp_consensus_slots::EquivocationProof, - /// Randomness for the epoch. + /// Epoch index. + pub index: u64, + /// Starting slot of the epoch. + pub start: Slot, + /// Number of slots in the epoch. + pub length: u32, + /// Randomness value. pub randomness: Randomness, + /// Authorities list. + pub authorities: Vec, /// Epoch configuration. pub config: EpochConfiguration, } diff --git a/substrate/primitives/consensus/sassafras/src/ticket.rs b/substrate/primitives/consensus/sassafras/src/ticket.rs index d81770c96d9b..dc0a61990d3e 100644 --- a/substrate/primitives/consensus/sassafras/src/ticket.rs +++ b/substrate/primitives/consensus/sassafras/src/ticket.rs @@ -62,10 +62,10 @@ pub struct TicketClaim { pub erased_signature: EphemeralSignature, } -/// Computes ticket-id maximum allowed value for a given epoch. +/// Computes a boundary for [`TicketId`] maximum allowed value for a given epoch. /// -/// Only ticket identifiers below this threshold should be considered for slot -/// assignment. +/// Only ticket identifiers below this threshold should be considered as candidates +/// for slot assignment. /// /// The value is computed as `TicketId::MAX*(redundancy*slots)/(attempts*validators)` /// @@ -76,16 +76,51 @@ pub struct TicketClaim { /// - `validators`: number of validators in epoch. /// /// If `attempts * validators = 0` then we return 0. +/// +/// For details about the formula and implications refer to +/// [*probabilities an parameters*](https://research.web3.foundation/Polkadot/protocols/block-production/SASSAFRAS#probabilities-and-parameters) +/// paragraph of the w3f introduction to the protocol. +// TODO: replace with [RFC-26](/~https://github.com/polkadot-fellows/RFCs/pull/26) +// "Tickets Threshold" paragraph once is merged pub fn ticket_id_threshold( redundancy: u32, slots: u32, attempts: u32, validators: u32, ) -> TicketId { - let den = attempts as u64 * validators as u64; let num = redundancy as u64 * slots as u64; + let den = attempts as u64 * validators as u64; TicketId::max_value() .checked_div(den.into()) .unwrap_or_default() .saturating_mul(num.into()) } + +#[cfg(test)] +mod tests { + use super::*; + + // This is a trivial example/check which just better explain explains the rationale + // behind the threshold. + // + // After this reading the formula should become obvious. + #[test] + fn ticket_id_threshold_trivial_check() { + // For an epoch with `s` slots we want to accept a number of tickets equal to ~s·r + let redundancy = 2; + let slots = 1000; + let attempts = 100; + let validators = 500; + + let threshold = ticket_id_threshold(redundancy, slots, attempts, validators); + let threshold = threshold as f64 / TicketId::MAX as f64; + + // We expect that the total number of tickets allowed to be submited + // is slots*redundancy + let avt = ((attempts * validators) as f64 * threshold) as u32; + assert_eq!(avt, slots * redundancy); + + println!("threshold: {}", threshold); + println!("avt = {}", avt); + } +} diff --git a/substrate/primitives/consensus/sassafras/src/vrf.rs b/substrate/primitives/consensus/sassafras/src/vrf.rs index d25a656f9508..bdbac0aae037 100644 --- a/substrate/primitives/consensus/sassafras/src/vrf.rs +++ b/substrate/primitives/consensus/sassafras/src/vrf.rs @@ -23,7 +23,7 @@ use sp_consensus_slots::Slot; use sp_std::vec::Vec; pub use sp_core::bandersnatch::{ - ring_vrf::{RingContext, RingProver, RingVerifier, RingVrfSignature}, + ring_vrf::{RingContext, RingProver, RingVerifier, RingVerifierData, RingVrfSignature}, vrf::{VrfInput, VrfOutput, VrfSignData, VrfSignature}, }; diff --git a/substrate/primitives/core/Cargo.toml b/substrate/primitives/core/Cargo.toml index 9c556c07736d..331d762e0d7b 100644 --- a/substrate/primitives/core/Cargo.toml +++ b/substrate/primitives/core/Cargo.toml @@ -56,7 +56,7 @@ sp-runtime-interface = { path = "../runtime-interface", default-features = false # bls crypto w3f-bls = { version = "0.1.3", default-features = false, optional = true } # bandersnatch crypto -bandersnatch_vrfs = { git = "/~https://github.com/w3f/ring-vrf", rev = "3ddc205", default-features = false, optional = true } +bandersnatch_vrfs = { git = "/~https://github.com/w3f/ring-vrf", rev = "2019248", default-features = false, features = ["substrate-curves"], optional = true } [dev-dependencies] criterion = "0.4.0" diff --git a/substrate/primitives/core/src/bandersnatch.rs b/substrate/primitives/core/src/bandersnatch.rs index 78b7f12f9ffd..1d666f13b627 100644 --- a/substrate/primitives/core/src/bandersnatch.rs +++ b/substrate/primitives/core/src/bandersnatch.rs @@ -20,13 +20,17 @@ //! //! The primitive can operate both as a regular VRF or as an anonymized Ring VRF. -#[cfg(feature = "std")] +#[cfg(feature = "serde")] use crate::crypto::Ss58Codec; use crate::crypto::{ ByteArray, CryptoType, CryptoTypeId, Derive, Public as TraitPublic, UncheckedFrom, VrfPublic, }; #[cfg(feature = "full_crypto")] use crate::crypto::{DeriveError, DeriveJunction, Pair as TraitPair, SecretStringError, VrfSecret}; +#[cfg(feature = "serde")] +use serde::{de, Deserialize, Deserializer, Serialize, Serializer}; +#[cfg(all(not(feature = "std"), feature = "serde"))] +use sp_std::alloc::{format, string::String}; use bandersnatch_vrfs::CanonicalSerialize; #[cfg(feature = "full_crypto")] @@ -44,23 +48,12 @@ pub const CRYPTO_ID: CryptoTypeId = CryptoTypeId(*b"band"); #[cfg(feature = "full_crypto")] pub const SIGNING_CTX: &[u8] = b"BandersnatchSigningContext"; -// Max ring domain size. -const RING_DOMAIN_SIZE: usize = 1024; - #[cfg(feature = "full_crypto")] -const SEED_SERIALIZED_LEN: usize = 32; - -// Short-Weierstrass form serialized sizes. -const PUBLIC_SERIALIZED_LEN: usize = 33; -const SIGNATURE_SERIALIZED_LEN: usize = 65; -const RING_SIGNATURE_SERIALIZED_LEN: usize = 755; -const PREOUT_SERIALIZED_LEN: usize = 33; +const SEED_SERIALIZED_SIZE: usize = 32; -// Max size of serialized ring-vrf context params. -// -// This size is dependent on the ring domain size and the actual value -// is equal to the SCALE encoded size of the `KZG` backend. -const RING_CONTEXT_SERIALIZED_LEN: usize = 147716; +const PUBLIC_SERIALIZED_SIZE: usize = 33; +const SIGNATURE_SERIALIZED_SIZE: usize = 65; +const PREOUT_SERIALIZED_SIZE: usize = 33; /// Bandersnatch public key. #[cfg_attr(feature = "full_crypto", derive(Hash))] @@ -77,16 +70,16 @@ const RING_CONTEXT_SERIALIZED_LEN: usize = 147716; MaxEncodedLen, TypeInfo, )] -pub struct Public(pub [u8; PUBLIC_SERIALIZED_LEN]); +pub struct Public(pub [u8; PUBLIC_SERIALIZED_SIZE]); -impl UncheckedFrom<[u8; PUBLIC_SERIALIZED_LEN]> for Public { - fn unchecked_from(raw: [u8; PUBLIC_SERIALIZED_LEN]) -> Self { +impl UncheckedFrom<[u8; PUBLIC_SERIALIZED_SIZE]> for Public { + fn unchecked_from(raw: [u8; PUBLIC_SERIALIZED_SIZE]) -> Self { Public(raw) } } -impl AsRef<[u8; PUBLIC_SERIALIZED_LEN]> for Public { - fn as_ref(&self) -> &[u8; PUBLIC_SERIALIZED_LEN] { +impl AsRef<[u8; PUBLIC_SERIALIZED_SIZE]> for Public { + fn as_ref(&self) -> &[u8; PUBLIC_SERIALIZED_SIZE] { &self.0 } } @@ -107,17 +100,17 @@ impl TryFrom<&[u8]> for Public { type Error = (); fn try_from(data: &[u8]) -> Result { - if data.len() != PUBLIC_SERIALIZED_LEN { + if data.len() != PUBLIC_SERIALIZED_SIZE { return Err(()) } - let mut r = [0u8; PUBLIC_SERIALIZED_LEN]; + let mut r = [0u8; PUBLIC_SERIALIZED_SIZE]; r.copy_from_slice(data); Ok(Self::unchecked_from(r)) } } impl ByteArray for Public { - const LEN: usize = PUBLIC_SERIALIZED_LEN; + const LEN: usize = PUBLIC_SERIALIZED_SIZE; } impl TraitPublic for Public {} @@ -142,16 +135,31 @@ impl sp_std::fmt::Debug for Public { } } +#[cfg(feature = "serde")] +impl Serialize for Public { + fn serialize(&self, serializer: S) -> Result { + serializer.serialize_str(&self.to_ss58check()) + } +} + +#[cfg(feature = "serde")] +impl<'de> Deserialize<'de> for Public { + fn deserialize>(deserializer: D) -> Result { + Public::from_ss58check(&String::deserialize(deserializer)?) + .map_err(|e| de::Error::custom(format!("{:?}", e))) + } +} + /// Bandersnatch signature. /// /// The signature is created via the [`VrfSecret::vrf_sign`] using [`SIGNING_CTX`] as transcript /// `label`. #[cfg_attr(feature = "full_crypto", derive(Hash))] #[derive(Clone, Copy, PartialEq, Eq, Encode, Decode, PassByInner, MaxEncodedLen, TypeInfo)] -pub struct Signature([u8; SIGNATURE_SERIALIZED_LEN]); +pub struct Signature([u8; SIGNATURE_SERIALIZED_SIZE]); -impl UncheckedFrom<[u8; SIGNATURE_SERIALIZED_LEN]> for Signature { - fn unchecked_from(raw: [u8; SIGNATURE_SERIALIZED_LEN]) -> Self { +impl UncheckedFrom<[u8; SIGNATURE_SERIALIZED_SIZE]> for Signature { + fn unchecked_from(raw: [u8; SIGNATURE_SERIALIZED_SIZE]) -> Self { Signature(raw) } } @@ -172,17 +180,17 @@ impl TryFrom<&[u8]> for Signature { type Error = (); fn try_from(data: &[u8]) -> Result { - if data.len() != SIGNATURE_SERIALIZED_LEN { + if data.len() != SIGNATURE_SERIALIZED_SIZE { return Err(()) } - let mut r = [0u8; SIGNATURE_SERIALIZED_LEN]; + let mut r = [0u8; SIGNATURE_SERIALIZED_SIZE]; r.copy_from_slice(data); Ok(Self::unchecked_from(r)) } } impl ByteArray for Signature { - const LEN: usize = SIGNATURE_SERIALIZED_LEN; + const LEN: usize = SIGNATURE_SERIALIZED_SIZE; } impl CryptoType for Signature { @@ -204,7 +212,7 @@ impl sp_std::fmt::Debug for Signature { /// The raw secret seed, which can be used to reconstruct the secret [`Pair`]. #[cfg(feature = "full_crypto")] -type Seed = [u8; SEED_SERIALIZED_LEN]; +type Seed = [u8; SEED_SERIALIZED_SIZE]; /// Bandersnatch secret key. #[cfg(feature = "full_crypto")] @@ -232,10 +240,10 @@ impl TraitPair for Pair { /// /// The slice must be 32 bytes long or it will return an error. fn from_seed_slice(seed_slice: &[u8]) -> Result { - if seed_slice.len() != SEED_SERIALIZED_LEN { + if seed_slice.len() != SEED_SERIALIZED_SIZE { return Err(SecretStringError::InvalidSeedLength) } - let mut seed = [0; SEED_SERIALIZED_LEN]; + let mut seed = [0; SEED_SERIALIZED_SIZE]; seed.copy_from_slice(seed_slice); let secret = SecretKey::from_seed(&seed); Ok(Pair { secret, seed }) @@ -266,7 +274,7 @@ impl TraitPair for Pair { fn public(&self) -> Public { let public = self.secret.to_public(); - let mut raw = [0; PUBLIC_SERIALIZED_LEN]; + let mut raw = [0; PUBLIC_SERIALIZED_SIZE]; public .serialize_compressed(raw.as_mut_slice()) .expect("serialization length is constant and checked by test; qed"); @@ -344,7 +352,7 @@ pub mod vrf { impl Encode for VrfOutput { fn encode(&self) -> Vec { - let mut bytes = [0; PREOUT_SERIALIZED_LEN]; + let mut bytes = [0; PREOUT_SERIALIZED_SIZE]; self.0 .serialize_compressed(bytes.as_mut_slice()) .expect("serialization length is constant and checked by test; qed"); @@ -354,21 +362,24 @@ pub mod vrf { impl Decode for VrfOutput { fn decode(i: &mut R) -> Result { - let buf = <[u8; PREOUT_SERIALIZED_LEN]>::decode(i)?; - let preout = bandersnatch_vrfs::VrfPreOut::deserialize_compressed(buf.as_slice()) - .map_err(|_| "vrf-preout decode error: bad preout")?; + let buf = <[u8; PREOUT_SERIALIZED_SIZE]>::decode(i)?; + let preout = + bandersnatch_vrfs::VrfPreOut::deserialize_compressed_unchecked(buf.as_slice()) + .map_err(|_| "vrf-preout decode error: bad preout")?; Ok(VrfOutput(preout)) } } + impl EncodeLike for VrfOutput {} + impl MaxEncodedLen for VrfOutput { fn max_encoded_len() -> usize { - <[u8; PREOUT_SERIALIZED_LEN]>::max_encoded_len() + <[u8; PREOUT_SERIALIZED_SIZE]>::max_encoded_len() } } impl TypeInfo for VrfOutput { - type Identity = [u8; PREOUT_SERIALIZED_LEN]; + type Identity = [u8; PREOUT_SERIALIZED_SIZE]; fn type_info() -> scale_info::Type { Self::Identity::type_info() @@ -395,10 +406,10 @@ pub mod vrf { /// will contribute to the signature as well. #[derive(Clone)] pub struct VrfSignData { - /// VRF inputs to be signed. - pub inputs: VrfIosVec, /// Associated protocol transcript. pub transcript: Transcript, + /// VRF inputs to be signed. + pub inputs: VrfIosVec, } impl VrfSignData { @@ -468,10 +479,10 @@ pub mod vrf { /// Refer to [`VrfSignData`] for more details. #[derive(Clone, Debug, PartialEq, Eq, Encode, Decode, MaxEncodedLen, TypeInfo)] pub struct VrfSignature { - /// VRF (pre)outputs. - pub outputs: VrfIosVec, /// Transcript signature. pub signature: Signature, + /// VRF (pre)outputs. + pub outputs: VrfIosVec, } #[cfg(feature = "full_crypto")] @@ -539,7 +550,7 @@ pub mod vrf { let outputs = VrfIosVec::truncate_from(outputs); let mut signature = - VrfSignature { signature: Signature([0; SIGNATURE_SERIALIZED_LEN]), outputs }; + VrfSignature { signature: Signature([0; SIGNATURE_SERIALIZED_SIZE]), outputs }; thin_signature .proof @@ -567,7 +578,7 @@ pub mod vrf { data: &VrfSignData, signature: &VrfSignature, ) -> bool { - let Ok(public) = PublicKey::deserialize_compressed(self.as_slice()) else { + let Ok(public) = PublicKey::deserialize_compressed_unchecked(self.as_slice()) else { return false }; @@ -577,10 +588,10 @@ pub mod vrf { // Deserialize only the proof, the rest has already been deserialized // This is another hack used because backend signature type is generic over // the number of ios. - let Ok(proof) = - ThinVrfSignature::<0>::deserialize_compressed(signature.signature.as_ref()) - .map(|s| s.proof) - else { + let Ok(proof) = ThinVrfSignature::<0>::deserialize_compressed_unchecked( + signature.signature.as_ref(), + ) + .map(|s| s.proof) else { return false }; let signature = ThinVrfSignature { proof, preouts }; @@ -609,16 +620,100 @@ pub mod vrf { pub mod ring_vrf { use super::{vrf::*, *}; pub use bandersnatch_vrfs::ring::{RingProof, RingProver, RingVerifier, KZG}; - use bandersnatch_vrfs::{CanonicalDeserialize, PublicKey}; + use bandersnatch_vrfs::{ring::VerifierKey, CanonicalDeserialize, PublicKey}; + + /// Ring max size (keyset max size). + pub const RING_MAX_SIZE: u32 = RING_DOMAIN_MAX_SIZE - RING_DOMAIN_OVERHEAD; + + /// Ring domain max size. + pub const RING_DOMAIN_MAX_SIZE: u32 = 2048; + + /// Overhead in the domain size over the max ring size. + /// + /// Some bits of the domain are reserved for the zk proof to work. + pub(crate) const RING_DOMAIN_OVERHEAD: u32 = 257; + + // Max size of serialized ring-vrf context params. + // + // The actual size is dependent on the ring domain size and this value + // has been computed for `RING_DOMAIN_MAX_SIZE` with compression disabled + // for performance reasons. + // + // 1024 uncompressed + // pub(crate) const RING_CONTEXT_SERIALIZED_MAX_SIZE: usize = 295412; + // 1024 compressed + // pub(crate) const RING_CONTEXT_SERIALIZED_MAX_SIZE: usize = 147716; + // 2048 uncompressed + pub(crate) const RING_CONTEXT_SERIALIZED_MAX_SIZE: usize = 590324; + // 2048 compressed + // pub(crate) const RING_CONTEXT_SERIALIZED_MAX_SIZE: usize = 295172; + + pub(crate) const RING_VERIFIER_DATA_SERIALIZED_SIZE: usize = 388; + pub(crate) const RING_SIGNATURE_SERIALIZED_SIZE: usize = 755; + + /// remove as soon as soon as serialization is implemented by the backend + pub struct RingVerifierData { + /// Domain size. + pub domain_size: u32, + /// Verifier key. + pub verifier_key: VerifierKey, + } + + impl From for RingVerifier { + fn from(vd: RingVerifierData) -> RingVerifier { + bandersnatch_vrfs::ring::make_ring_verifier(vd.verifier_key, vd.domain_size as usize) + } + } + + impl Encode for RingVerifierData { + fn encode(&self) -> Vec { + const ERR_STR: &str = "serialization length is constant and checked by test; qed"; + let mut buf = [0; RING_VERIFIER_DATA_SERIALIZED_SIZE]; + self.domain_size.serialize_compressed(&mut buf[..4]).expect(ERR_STR); + self.verifier_key.serialize_compressed(&mut buf[4..]).expect(ERR_STR); + buf.encode() + } + } + + impl Decode for RingVerifierData { + fn decode(i: &mut R) -> Result { + const ERR_STR: &str = "serialization length is constant and checked by test; qed"; + let buf = <[u8; RING_VERIFIER_DATA_SERIALIZED_SIZE]>::decode(i)?; + let domain_size = + ::deserialize_compressed_unchecked(&mut &buf[..4]) + .expect(ERR_STR); + let verifier_key = ::deserialize_compressed_unchecked(&mut &buf[4..]).expect(ERR_STR); + + Ok(RingVerifierData { domain_size, verifier_key }) + } + } - /// Context used to produce ring signatures. + impl EncodeLike for RingVerifierData {} + + impl MaxEncodedLen for RingVerifierData { + fn max_encoded_len() -> usize { + <[u8; RING_VERIFIER_DATA_SERIALIZED_SIZE]>::max_encoded_len() + } + } + + impl TypeInfo for RingVerifierData { + type Identity = [u8; RING_VERIFIER_DATA_SERIALIZED_SIZE]; + + fn type_info() -> scale_info::Type { + Self::Identity::type_info() + } + } + + /// Context used to construct ring prover and verifier. #[derive(Clone)] pub struct RingContext(KZG); impl RingContext { - /// Build an dummy instance used for testing purposes. + /// Build an dummy instance for testing purposes. + /// + /// `domain_size` is set to `RING_DOMAIN_MAX_SIZE`. pub fn new_testing() -> Self { - Self(KZG::testing_kzg_setup([0; 32], RING_DOMAIN_SIZE as u32)) + Self(KZG::testing_kzg_setup([0; 32], RING_DOMAIN_MAX_SIZE)) } /// Get the keyset max size. @@ -630,7 +725,7 @@ pub mod ring_vrf { pub fn prover(&self, public_keys: &[Public], public_idx: usize) -> Option { let mut pks = Vec::with_capacity(public_keys.len()); for public_key in public_keys { - let pk = PublicKey::deserialize_compressed(public_key.as_slice()).ok()?; + let pk = PublicKey::deserialize_compressed_unchecked(public_key.as_slice()).ok()?; pks.push(pk.0.into()); } @@ -643,7 +738,7 @@ pub mod ring_vrf { pub fn verifier(&self, public_keys: &[Public]) -> Option { let mut pks = Vec::with_capacity(public_keys.len()); for public_key in public_keys { - let pk = PublicKey::deserialize_compressed(public_key.as_slice()).ok()?; + let pk = PublicKey::deserialize_compressed_unchecked(public_key.as_slice()).ok()?; pks.push(pk.0.into()); } @@ -651,13 +746,26 @@ pub mod ring_vrf { let ring_verifier = self.0.init_ring_verifier(verifier_key); Some(ring_verifier) } + + /// Information required for a lazy construction of a ring verifier. + pub fn verifier_data(&self, public_keys: &[Public]) -> Option { + let mut pks = Vec::with_capacity(public_keys.len()); + for public_key in public_keys { + let pk = PublicKey::deserialize_compressed_unchecked(public_key.as_slice()).ok()?; + pks.push(pk.0.into()); + } + Some(RingVerifierData { + verifier_key: self.0.verifier_key(pks), + domain_size: self.0.domain_size, + }) + } } impl Encode for RingContext { fn encode(&self) -> Vec { - let mut buf = Box::new([0; RING_CONTEXT_SERIALIZED_LEN]); + let mut buf = Box::new([0; RING_CONTEXT_SERIALIZED_MAX_SIZE]); self.0 - .serialize_compressed(buf.as_mut_slice()) + .serialize_uncompressed(buf.as_mut_slice()) .expect("serialization length is constant and checked by test; qed"); buf.encode() } @@ -665,9 +773,9 @@ pub mod ring_vrf { impl Decode for RingContext { fn decode(i: &mut R) -> Result { - let buf = >::decode(i)?; - let kzg = - KZG::deserialize_compressed(buf.as_slice()).map_err(|_| "KZG decode error")?; + let buf = >::decode(i)?; + let kzg = KZG::deserialize_uncompressed_unchecked(buf.as_slice()) + .map_err(|_| "KZG decode error")?; Ok(RingContext(kzg)) } } @@ -676,12 +784,12 @@ pub mod ring_vrf { impl MaxEncodedLen for RingContext { fn max_encoded_len() -> usize { - <[u8; RING_CONTEXT_SERIALIZED_LEN]>::max_encoded_len() + <[u8; RING_CONTEXT_SERIALIZED_MAX_SIZE]>::max_encoded_len() } } impl TypeInfo for RingContext { - type Identity = [u8; RING_CONTEXT_SERIALIZED_LEN]; + type Identity = [u8; RING_CONTEXT_SERIALIZED_MAX_SIZE]; fn type_info() -> scale_info::Type { Self::Identity::type_info() @@ -691,10 +799,10 @@ pub mod ring_vrf { /// Ring VRF signature. #[derive(Clone, Debug, PartialEq, Eq, Encode, Decode, MaxEncodedLen, TypeInfo)] pub struct RingVrfSignature { + /// Ring signature. + pub signature: [u8; RING_SIGNATURE_SERIALIZED_SIZE], /// VRF (pre)outputs. pub outputs: VrfIosVec, - /// Ring signature. - pub signature: [u8; RING_SIGNATURE_SERIALIZED_LEN], } #[cfg(feature = "full_crypto")] @@ -731,7 +839,7 @@ pub mod ring_vrf { let outputs = VrfIosVec::truncate_from(outputs); let mut signature = - RingVrfSignature { outputs, signature: [0; RING_SIGNATURE_SERIALIZED_LEN] }; + RingVrfSignature { outputs, signature: [0; RING_SIGNATURE_SERIALIZED_SIZE] }; ring_signature .proof @@ -769,7 +877,7 @@ pub mod ring_vrf { verifier: &RingVerifier, ) -> bool { let Ok(vrf_signature) = - bandersnatch_vrfs::RingVrfSignature::<0>::deserialize_compressed( + bandersnatch_vrfs::RingVrfSignature::<0>::deserialize_compressed_unchecked( self.signature.as_slice(), ) else { @@ -795,7 +903,7 @@ pub mod ring_vrf { mod tests { use super::{ring_vrf::*, vrf::*, *}; use crate::crypto::{VrfPublic, VrfSecret, DEV_PHRASE}; - const DEV_SEED: &[u8; SEED_SERIALIZED_LEN] = &[0xcb; SEED_SERIALIZED_LEN]; + const DEV_SEED: &[u8; SEED_SERIALIZED_SIZE] = &[0xcb; SEED_SERIALIZED_SIZE]; #[allow(unused)] fn b2h(bytes: &[u8]) -> String { @@ -808,9 +916,10 @@ mod tests { #[test] fn backend_assumptions_sanity_check() { - let kzg = KZG::testing_kzg_setup([0; 32], RING_DOMAIN_SIZE as u32); - assert_eq!(kzg.max_keyset_size(), RING_DOMAIN_SIZE - 257); - assert_eq!(kzg.compressed_size(), RING_CONTEXT_SERIALIZED_LEN); + let kzg = KZG::testing_kzg_setup([0; 32], RING_DOMAIN_MAX_SIZE); + assert_eq!(kzg.max_keyset_size() as u32, RING_MAX_SIZE); + + assert_eq!(kzg.uncompressed_size(), RING_CONTEXT_SERIALIZED_MAX_SIZE); let pks: Vec<_> = (0..16) .map(|i| SecretKey::from_seed(&[i as u8; 32]).to_public().0.into()) @@ -819,11 +928,14 @@ mod tests { let secret = SecretKey::from_seed(&[0u8; 32]); let public = secret.to_public(); - assert_eq!(public.compressed_size(), PUBLIC_SERIALIZED_LEN); + assert_eq!(public.compressed_size(), PUBLIC_SERIALIZED_SIZE); let input = VrfInput::new(b"foo", &[]); let preout = secret.vrf_preout(&input.0); - assert_eq!(preout.compressed_size(), PREOUT_SERIALIZED_LEN); + assert_eq!(preout.compressed_size(), PREOUT_SERIALIZED_SIZE); + + let verifier_key = kzg.verifier_key(pks.clone()); + assert_eq!(verifier_key.compressed_size() + 4, RING_VERIFIER_DATA_SERIALIZED_SIZE); let prover_key = kzg.prover_key(pks); let ring_prover = kzg.init_ring_prover(prover_key, 0); @@ -832,12 +944,12 @@ mod tests { let thin_signature: bandersnatch_vrfs::ThinVrfSignature<0> = secret.sign_thin_vrf(data.transcript.clone(), &[]); - assert_eq!(thin_signature.compressed_size(), SIGNATURE_SERIALIZED_LEN); + assert_eq!(thin_signature.compressed_size(), SIGNATURE_SERIALIZED_SIZE); let ring_signature: bandersnatch_vrfs::RingVrfSignature<0> = bandersnatch_vrfs::RingProver { ring_prover: &ring_prover, secret: &secret } .sign_ring_vrf(data.transcript.clone(), &[]); - assert_eq!(ring_signature.compressed_size(), RING_SIGNATURE_SERIALIZED_LEN); + assert_eq!(ring_signature.compressed_size(), RING_SIGNATURE_SERIALIZED_SIZE); } #[test] @@ -941,7 +1053,8 @@ mod tests { let bytes = expected.encode(); - let expected_len = data.inputs.len() * PREOUT_SERIALIZED_LEN + SIGNATURE_SERIALIZED_LEN + 1; + let expected_len = + data.inputs.len() * PREOUT_SERIALIZED_SIZE + SIGNATURE_SERIALIZED_SIZE + 1; assert_eq!(bytes.len(), expected_len); let decoded = VrfSignature::decode(&mut bytes.as_slice()).unwrap(); @@ -1055,7 +1168,7 @@ mod tests { let bytes = expected.encode(); let expected_len = - data.inputs.len() * PREOUT_SERIALIZED_LEN + RING_SIGNATURE_SERIALIZED_LEN + 1; + data.inputs.len() * PREOUT_SERIALIZED_SIZE + RING_SIGNATURE_SERIALIZED_SIZE + 1; assert_eq!(bytes.len(), expected_len); let decoded = RingVrfSignature::decode(&mut bytes.as_slice()).unwrap(); @@ -1067,11 +1180,31 @@ mod tests { let ctx1 = RingContext::new_testing(); let enc1 = ctx1.encode(); - assert_eq!(enc1.len(), RingContext::max_encoded_len()); + assert_eq!(enc1.len(), RING_CONTEXT_SERIALIZED_MAX_SIZE); + assert_eq!(RingContext::max_encoded_len(), RING_CONTEXT_SERIALIZED_MAX_SIZE); let ctx2 = RingContext::decode(&mut enc1.as_slice()).unwrap(); let enc2 = ctx2.encode(); assert_eq!(enc1, enc2); } + + #[test] + fn encode_decode_verifier_data() { + let ring_ctx = RingContext::new_testing(); + + let pks: Vec<_> = (0..16).map(|i| Pair::from_seed(&[i as u8; 32]).public()).collect(); + assert!(pks.len() <= ring_ctx.max_keyset_size()); + + let verifier_data = ring_ctx.verifier_data(&pks).unwrap(); + let enc1 = verifier_data.encode(); + + assert_eq!(enc1.len(), RING_VERIFIER_DATA_SERIALIZED_SIZE); + assert_eq!(RingVerifierData::max_encoded_len(), RING_VERIFIER_DATA_SERIALIZED_SIZE); + + let vd2 = RingVerifierData::decode(&mut enc1.as_slice()).unwrap(); + let enc2 = vd2.encode(); + + assert_eq!(enc1, enc2); + } }