cumulus_primitives_spec_messaging/
lib.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Cumulus.
3// SPDX-License-Identifier: Apache-2.0
4
5// Licensed under the Apache License, Version 2.0 (the "License");
6// you may not use this file except in compliance with the License.
7// You may obtain a copy of the License at
8//
9// 	http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the License for the specific language governing permissions and
15// limitations under the License.
16
17//! Primitives for the Speculative Messaging protocol.
18//!
19//! A sender parachain keeps each outgoing stream as an MMR and commits all stream roots as one
20//! `StreamsRoot` (a keyed trie). Messages travel between collators; the relay chain only checks
21//! that each receiver's `Requires` matches a sender's `Provides`.
22//!
23//! The relay-visible types (`StreamsRoot`, `RequiresSet`) are in `polkadot-primitives`. This crate
24//! has the parachain-side types and the off-chain wire format.
25
26#![cfg_attr(not(feature = "std"), no_std)]
27
28extern crate alloc;
29
30pub mod channel;
31pub mod flow_control;
32pub mod inherent;
33pub mod lift;
34pub mod message;
35pub mod mmr;
36pub mod stream;
37pub mod streams_root;
38
39#[cfg(test)]
40mod adversarial_tests;
41#[cfg(test)]
42mod test_utils;
43
44pub use channel::{ChannelId, ChannelPhase, InChannelState, OutChannelState, RegisterRead};
45pub use flow_control::{Register, SpecMsgKind, SpecMsgSignal, WindowGrant};
46pub use inherent::{
47	ConsumeItem, ConsumedStream, MessagingInherentData, Payload, INHERENT_IDENTIFIER,
48};
49pub use lift::{
50	build_requires, build_requires_entry, stitch, ConsumptionRecord, Interval, LiftError,
51	LiftsBySource, MMRExtensionProof, MmrInclusionProof, ProofError, RequiresLift, SourceStreams,
52	TreeInclusionProof,
53};
54pub use message::{
55	leaf_hash, verify_event, verify_exchange, verify_messages, EventRequest, EventResponse,
56	ExchangeRequest, ExchangeResponse, ExchangeVerified, MessagesRequest, MessagesResponse,
57	VerifiedEvent, VerifyError, MAX_MESSAGES_PER_RESPONSE, MAX_SPECULATIVE_MESSAGE_LEN,
58};
59pub use mmr::{FrontierFull, MessagePosition, MmrFrontier, MmrRoot};
60pub use stream::{PrivateKind, StreamId, STREAM_ID_LEN};
61pub use streams_root::{StreamProof, StreamsRoot};
62
63/// The hash function for all of speculative messaging: leaves, MMR merges, stream and
64/// commitment-tree roots. A protocol constant. Changing it is a consensus break, so nothing here
65/// is generic over it.
66pub type SpecHasher = sp_runtime::traits::BlakeTwo256;
67
68// Domain tags. Each hash preimage starts with one, so a node in one role can never collide with a
69// node in another.
70
71/// MMR leaf.
72pub const LEAF_TAG: u8 = 0x1;
73
74/// MMR inner node.
75pub const INNER_TAG: u8 = 0x2;
76
77/// MMR peak bagging.
78pub const PEAK_TAG: u8 = 0x3;
79
80/// Stream root: `H(ROOT_TAG ++ leaf_count[8, LE] ++ bag(peaks)[32])` ([`mmr::MmrRoot::from_bag`]).
81/// Binding the count stops a peer from presenting the same peaks at a forged position. The empty
82/// MMR has no peaks to bag; its root is the count-0 case, with a zero bag ([`mmr::empty_root`]).
83pub const ROOT_TAG: u8 = 0x4;
84
85/// Commitment-tree leaf: `H(TREE_LEAF_TAG ++ key[8] ++ stream_root[32])`.
86pub const TREE_LEAF_TAG: u8 = 0x5;
87
88/// Commitment-tree inner node: `H(TREE_INNER_TAG ++ split_bit ++ left[32] ++ right[32])`.
89pub const TREE_INNER_TAG: u8 = 0x6;
90
91/// Leaf preimage version. Versions are hash-disjoint, so the layout can change without old leaves
92/// colliding with new ones.
93pub const LEAF_VERSION: u8 = 0x0;
94
95/// Engine id of the header digest carrying a block's `StreamsRoot`, deposited only by blocks that
96/// send.
97pub const SPMS_ENGINE_ID: sp_runtime::ConsensusEngineId = *b"SPMS";
cumulus_primitives_spec_messaging/lib.rs

cumulus_primitives_spec_messaging/
lib.rs
