hotshot_types/
message.rs

1// Copyright (c) 2021-2024 Espresso Systems (espressosys.com)
2// This file is part of the HotShot repository.
3
4// You should have received a copy of the MIT License
5// along with the HotShot repository. If not, see <https://mit-license.org/>.
6
7//! Network message types
8//!
9//! This module contains types used to represent the various types of messages that
10//! `HotShot` nodes can send among themselves.
11
12use std::{
13    fmt::{self, Debug},
14    marker::PhantomData,
15    sync::Arc,
16};
17
18use committable::Committable;
19use hotshot_utils::anytrace::*;
20use parking_lot::RwLock;
21use serde::{Deserialize, Serialize, de::DeserializeOwned};
22use vbs::version::Version;
23use versions::{DRB_AND_HEADER_UPGRADE_VERSION, EPOCH_VERSION, NEW_PROTOCOL_VERSION, Upgrade};
24
25/// The version we should expect for external messages
26pub const EXTERNAL_MESSAGE_VERSION: Version = Version { major: 0, minor: 0 };
27
28use crate::{
29    data::{
30        DaProposal, DaProposal2, EpochNumber, Leaf, Leaf2, QuorumProposal, QuorumProposal2,
31        QuorumProposal2Legacy, QuorumProposalWrapper, UpgradeProposal, VidDisperseShare0,
32        VidDisperseShare1, VidDisperseShare2, ViewNumber,
33    },
34    epoch_membership::{EpochMembership, EpochMembershipCoordinator},
35    request_response::ProposalRequestPayload,
36    simple_certificate::{
37        DaCertificate, DaCertificate2, EpochRootQuorumCertificateV1, EpochRootQuorumCertificateV2,
38        NextEpochQuorumCertificate2, QuorumCertificate2, UpgradeCertificate,
39        ViewSyncCommitCertificate, ViewSyncCommitCertificate2, ViewSyncFinalizeCertificate,
40        ViewSyncFinalizeCertificate2, ViewSyncPreCommitCertificate, ViewSyncPreCommitCertificate2,
41    },
42    simple_vote::{
43        DaVote, DaVote2, EpochRootQuorumVote, EpochRootQuorumVote2, HasEpoch, QuorumVote,
44        QuorumVote2, TimeoutVote, TimeoutVote2, UpgradeVote, ViewSyncCommitVote,
45        ViewSyncCommitVote2, ViewSyncFinalizeVote, ViewSyncFinalizeVote2, ViewSyncPreCommitVote,
46        ViewSyncPreCommitVote2,
47    },
48    traits::{
49        election::{Membership, NonEpochMembershipSnapshot},
50        network::{DataRequest, ResponseMessage, ViewMessage},
51        node_implementation::NodeType,
52        signature_key::SignatureKey,
53    },
54    utils::mnemonic,
55    vote::HasViewNumber,
56};
57
58/// Incoming message
59#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash)]
60#[serde(bound(deserialize = "", serialize = ""))]
61pub struct Message<TYPES: NodeType> {
62    /// The sender of this message
63    pub sender: TYPES::SignatureKey,
64
65    /// The message kind
66    pub kind: MessageKind<TYPES>,
67}
68
69impl<TYPES: NodeType> fmt::Debug for Message<TYPES> {
70    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
71        fmt.debug_struct("Message")
72            .field("sender", &mnemonic(&self.sender))
73            .field("kind", &self.kind)
74            .finish()
75    }
76}
77
78impl<TYPES: NodeType> HasViewNumber for Message<TYPES> {
79    /// get the view number out of a message
80    fn view_number(&self) -> ViewNumber {
81        self.kind.view_number()
82    }
83}
84
85/// A wrapper type for implementing `PassType` on a vector of `Message`.
86#[derive(Clone, Debug)]
87pub struct Messages<TYPES: NodeType>(pub Vec<Message<TYPES>>);
88
89/// A message type agnostic description of a message's purpose
90#[derive(PartialEq, Copy, Clone)]
91pub enum MessagePurpose {
92    /// Message with a [quorum/DA] proposal.
93    Proposal,
94    /// Message with most recent [quorum/DA] proposal the server has
95    LatestProposal,
96    /// Message with most recent view sync certificate the server has
97    LatestViewSyncCertificate,
98    /// Message with a quorum vote.
99    Vote,
100    /// Message with a view sync vote.
101    ViewSyncVote,
102    /// Message with a view sync certificate.
103    ViewSyncCertificate,
104    /// Message with a DAC.
105    DaCertificate,
106    /// Message for internal use
107    Internal,
108    /// Data message
109    Data,
110    /// VID disperse, like [`Proposal`].
111    VidDisperse,
112    /// Message with an upgrade proposal.
113    UpgradeProposal,
114    /// Upgrade vote.
115    UpgradeVote,
116    /// A message to be passed through to external listeners
117    External,
118}
119
120// TODO (da) make it more customized to the consensus layer, maybe separating the specific message
121// data from the kind enum.
122/// Enum representation of any message type
123#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Hash, Eq)]
124#[serde(bound(deserialize = "", serialize = ""))]
125pub enum MessageKind<TYPES: NodeType> {
126    /// Messages related to the consensus protocol
127    Consensus(SequencingMessage<TYPES>),
128    /// Messages relating to sharing data between nodes
129    Data(DataMessage<TYPES>),
130    /// A (still serialized) message to be passed through to external listeners
131    External(#[serde(with = "serde_bytes")] Vec<u8>),
132}
133
134/// List of keys to send a message to, or broadcast to all known keys
135pub enum RecipientList<K: SignatureKey> {
136    /// Broadcast to all
137    Broadcast,
138    /// Send a message directly to a key
139    Direct(K),
140    /// Send a message directly to many keys
141    Many(Vec<K>),
142}
143
144impl<TYPES: NodeType> MessageKind<TYPES> {
145    // Can't implement `From<I::ConsensusMessage>` directly due to potential conflict with
146    // `From<DataMessage>`.
147    /// Construct a [`MessageKind`] from [`SequencingMessage`].
148    pub fn from_consensus_message(m: SequencingMessage<TYPES>) -> Self {
149        Self::Consensus(m)
150    }
151}
152
153impl<TYPES: NodeType> From<DataMessage<TYPES>> for MessageKind<TYPES> {
154    fn from(m: DataMessage<TYPES>) -> Self {
155        Self::Data(m)
156    }
157}
158
159impl<TYPES: NodeType> ViewMessage<TYPES> for MessageKind<TYPES> {
160    fn view_number(&self) -> ViewNumber {
161        match &self {
162            MessageKind::Consensus(message) => message.view_number(),
163            MessageKind::Data(DataMessage::SubmitTransaction(_, v)) => *v,
164            MessageKind::Data(DataMessage::RequestData(msg)) => msg.view,
165            MessageKind::Data(DataMessage::DataResponse(msg)) => match msg {
166                ResponseMessage::Found(m) => m.view_number(),
167                ResponseMessage::NotFound | ResponseMessage::Denied => ViewNumber::new(1),
168            },
169            MessageKind::External(_) => ViewNumber::new(1),
170        }
171    }
172}
173
174impl<TYPES: NodeType> HasEpoch for MessageKind<TYPES> {
175    fn epoch(&self) -> Option<EpochNumber> {
176        match &self {
177            MessageKind::Consensus(message) => message.epoch_number(),
178            MessageKind::Data(DataMessage::SubmitTransaction(..) | DataMessage::RequestData(_))
179            | MessageKind::External(_) => None,
180            MessageKind::Data(DataMessage::DataResponse(msg)) => match msg {
181                ResponseMessage::Found(m) => m.epoch_number(),
182                ResponseMessage::NotFound | ResponseMessage::Denied => None,
183            },
184        }
185    }
186}
187
188#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)]
189#[serde(bound(deserialize = "", serialize = ""))]
190/// Messages related to both validating and sequencing consensus.
191pub enum GeneralConsensusMessage<TYPES: NodeType> {
192    /// Message with a quorum proposal.
193    Proposal(Proposal<TYPES, QuorumProposal<TYPES>>),
194
195    /// Message with a quorum vote.
196    Vote(QuorumVote<TYPES>),
197
198    /// Message with a view sync pre-commit vote
199    ViewSyncPreCommitVote(ViewSyncPreCommitVote<TYPES>),
200
201    /// Message with a view sync commit vote
202    ViewSyncCommitVote(ViewSyncCommitVote<TYPES>),
203
204    /// Message with a view sync finalize vote
205    ViewSyncFinalizeVote(ViewSyncFinalizeVote<TYPES>),
206
207    /// Message with a view sync pre-commit certificate
208    ViewSyncPreCommitCertificate(ViewSyncPreCommitCertificate<TYPES>),
209
210    /// Message with a view sync commit certificate
211    ViewSyncCommitCertificate(ViewSyncCommitCertificate<TYPES>),
212
213    /// Message with a view sync finalize certificate
214    ViewSyncFinalizeCertificate(ViewSyncFinalizeCertificate<TYPES>),
215
216    /// Message with a Timeout vote
217    TimeoutVote(TimeoutVote<TYPES>),
218
219    /// Message with an upgrade proposal
220    UpgradeProposal(Proposal<TYPES, UpgradeProposal>),
221
222    /// Message with an upgrade vote
223    UpgradeVote(UpgradeVote<TYPES>),
224
225    /// A peer node needs a proposal from the leader.
226    ProposalRequested(
227        ProposalRequestPayload<TYPES>,
228        <TYPES::SignatureKey as SignatureKey>::PureAssembledSignatureType,
229    ),
230
231    /// A replica has responded with a valid proposal.
232    ProposalResponse(Proposal<TYPES, QuorumProposal<TYPES>>),
233
234    /// Message with a quorum proposal.
235    Proposal2Legacy(Proposal<TYPES, QuorumProposal2Legacy<TYPES>>),
236
237    /// Message with a quorum vote.
238    Vote2(QuorumVote2<TYPES>),
239
240    /// Message with an epoch root quorum vote.
241    EpochRootQuorumVote(EpochRootQuorumVote<TYPES>),
242
243    /// A replica has responded with a valid proposal.
244    ProposalResponse2Legacy(Proposal<TYPES, QuorumProposal2Legacy<TYPES>>),
245
246    /// Message for the next leader containing our highest QC
247    HighQc(
248        QuorumCertificate2<TYPES>,
249        Option<NextEpochQuorumCertificate2<TYPES>>,
250    ),
251
252    /// Message containing the highest QC and the next epoch QC
253    ExtendedQc(
254        QuorumCertificate2<TYPES>,
255        NextEpochQuorumCertificate2<TYPES>,
256    ),
257
258    /// Message for the next leader containing the epoch root QC from older consensus version.
259    EpochRootQcV1(EpochRootQuorumCertificateV1<TYPES>),
260
261    /// Message with a view sync pre-commit vote
262    ViewSyncPreCommitVote2(ViewSyncPreCommitVote2<TYPES>),
263
264    /// Message with a view sync commit vote
265    ViewSyncCommitVote2(ViewSyncCommitVote2<TYPES>),
266
267    /// Message with a view sync finalize vote
268    ViewSyncFinalizeVote2(ViewSyncFinalizeVote2<TYPES>),
269
270    /// Message with a view sync pre-commit certificate
271    ViewSyncPreCommitCertificate2(ViewSyncPreCommitCertificate2<TYPES>),
272
273    /// Message with a view sync commit certificate
274    ViewSyncCommitCertificate2(ViewSyncCommitCertificate2<TYPES>),
275
276    /// Message with a view sync finalize certificate
277    ViewSyncFinalizeCertificate2(ViewSyncFinalizeCertificate2<TYPES>),
278
279    /// Message with a Timeout vote
280    TimeoutVote2(TimeoutVote2<TYPES>),
281
282    /// Message for the next leader containing the epoch root QC
283    EpochRootQc(EpochRootQuorumCertificateV2<TYPES>),
284
285    /// Message with a quorum proposal.
286    Proposal2(Proposal<TYPES, QuorumProposal2<TYPES>>),
287
288    /// A replica has responded with a valid proposal.
289    ProposalResponse2(Proposal<TYPES, QuorumProposal2<TYPES>>),
290
291    /// Message with an epoch root quorum vote.
292    EpochRootQuorumVote2(EpochRootQuorumVote2<TYPES>),
293}
294
295#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Hash, Eq)]
296#[serde(bound(deserialize = "", serialize = ""))]
297/// Messages related to the sequencing consensus protocol for the DA committee.
298pub enum DaConsensusMessage<TYPES: NodeType> {
299    /// Proposal for data availability committee
300    DaProposal(Proposal<TYPES, DaProposal<TYPES>>),
301
302    /// vote for data availability committee
303    DaVote(DaVote<TYPES>),
304
305    /// Certificate data is available
306    DaCertificate(DaCertificate<TYPES>),
307
308    /// Initiate VID dispersal.
309    ///
310    /// Like [`DaProposal`]. Use `Msg` suffix to distinguish from `VidDisperse`.
311    VidDisperseMsg(Proposal<TYPES, VidDisperseShare0<TYPES>>),
312
313    /// Proposal for data availability committee
314    DaProposal2(Proposal<TYPES, DaProposal2<TYPES>>),
315
316    /// vote for data availability committee
317    DaVote2(DaVote2<TYPES>),
318
319    /// Certificate data is available
320    DaCertificate2(DaCertificate2<TYPES>),
321
322    /// VID dispersal for AvidM Scheme.
323    VidDisperseMsg1(Proposal<TYPES, VidDisperseShare1<TYPES>>),
324
325    /// VID dispersal for AvidmGf2 Scheme.
326    VidDisperseMsg2(Proposal<TYPES, VidDisperseShare2<TYPES>>),
327}
328
329/// Messages for sequencing consensus.
330#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
331#[serde(bound(deserialize = "", serialize = ""))]
332#[allow(clippy::large_enum_variant)]
333pub enum SequencingMessage<TYPES: NodeType> {
334    /// Messages related to validating and sequencing consensus
335    General(GeneralConsensusMessage<TYPES>),
336
337    /// Messages related to the sequencing consensus protocol for the DA committee.
338    Da(DaConsensusMessage<TYPES>),
339}
340
341impl<TYPES: NodeType> SequencingMessage<TYPES> {
342    /// Get the view number this message relates to
343    fn view_number(&self) -> ViewNumber {
344        match &self {
345            SequencingMessage::General(general_message) => {
346                match general_message {
347                    GeneralConsensusMessage::Proposal(p) => {
348                        // view of leader in the leaf when proposal
349                        // this should match replica upon receipt
350                        p.data.view_number()
351                    },
352                    GeneralConsensusMessage::Proposal2Legacy(p) => {
353                        // view of leader in the leaf when proposal
354                        // this should match replica upon receipt
355                        p.data.view_number()
356                    },
357                    GeneralConsensusMessage::Proposal2(p) => {
358                        // view of leader in the leaf when proposal
359                        // this should match replica upon receipt
360                        p.data.view_number()
361                    },
362                    GeneralConsensusMessage::ProposalRequested(req, _) => req.view_number,
363                    GeneralConsensusMessage::ProposalResponse(proposal) => {
364                        proposal.data.view_number()
365                    },
366                    GeneralConsensusMessage::ProposalResponse2Legacy(proposal) => {
367                        proposal.data.view_number()
368                    },
369                    GeneralConsensusMessage::ProposalResponse2(proposal) => {
370                        proposal.data.view_number()
371                    },
372                    GeneralConsensusMessage::Vote(vote_message) => vote_message.view_number(),
373                    GeneralConsensusMessage::Vote2(vote_message) => vote_message.view_number(),
374                    GeneralConsensusMessage::TimeoutVote(message) => message.view_number(),
375                    GeneralConsensusMessage::ViewSyncPreCommitVote(message) => {
376                        message.view_number()
377                    },
378                    GeneralConsensusMessage::ViewSyncCommitVote(message) => message.view_number(),
379                    GeneralConsensusMessage::ViewSyncFinalizeVote(message) => message.view_number(),
380                    GeneralConsensusMessage::ViewSyncPreCommitCertificate(message) => {
381                        message.view_number()
382                    },
383                    GeneralConsensusMessage::ViewSyncCommitCertificate(message) => {
384                        message.view_number()
385                    },
386                    GeneralConsensusMessage::ViewSyncFinalizeCertificate(message) => {
387                        message.view_number()
388                    },
389                    GeneralConsensusMessage::TimeoutVote2(message) => message.view_number(),
390                    GeneralConsensusMessage::ViewSyncPreCommitVote2(message) => {
391                        message.view_number()
392                    },
393                    GeneralConsensusMessage::ViewSyncCommitVote2(message) => message.view_number(),
394                    GeneralConsensusMessage::ViewSyncFinalizeVote2(message) => {
395                        message.view_number()
396                    },
397                    GeneralConsensusMessage::ViewSyncPreCommitCertificate2(message) => {
398                        message.view_number()
399                    },
400                    GeneralConsensusMessage::ViewSyncCommitCertificate2(message) => {
401                        message.view_number()
402                    },
403                    GeneralConsensusMessage::ViewSyncFinalizeCertificate2(message) => {
404                        message.view_number()
405                    },
406                    GeneralConsensusMessage::UpgradeProposal(message) => message.data.view_number(),
407                    GeneralConsensusMessage::UpgradeVote(message) => message.view_number(),
408                    GeneralConsensusMessage::HighQc(qc, _)
409                    | GeneralConsensusMessage::ExtendedQc(qc, _) => qc.view_number(),
410                    GeneralConsensusMessage::EpochRootQuorumVote(vote) => vote.view_number(),
411                    GeneralConsensusMessage::EpochRootQuorumVote2(vote) => vote.view_number(),
412                    GeneralConsensusMessage::EpochRootQc(root_qc) => root_qc.view_number(),
413                    GeneralConsensusMessage::EpochRootQcV1(root_qc) => root_qc.view_number(),
414                }
415            },
416            SequencingMessage::Da(da_message) => {
417                match da_message {
418                    DaConsensusMessage::DaProposal(p) => {
419                        // view of leader in the leaf when proposal
420                        // this should match replica upon receipt
421                        p.data.view_number()
422                    },
423                    DaConsensusMessage::DaVote(vote_message) => vote_message.view_number(),
424                    DaConsensusMessage::DaCertificate(cert) => cert.view_number,
425                    DaConsensusMessage::VidDisperseMsg(disperse) => disperse.data.view_number(),
426                    DaConsensusMessage::DaProposal2(p) => {
427                        // view of leader in the leaf when proposal
428                        // this should match replica upon receipt
429                        p.data.view_number()
430                    },
431                    DaConsensusMessage::DaVote2(vote_message) => vote_message.view_number(),
432                    DaConsensusMessage::DaCertificate2(cert) => cert.view_number,
433                    DaConsensusMessage::VidDisperseMsg1(disperse) => disperse.data.view_number(),
434                    DaConsensusMessage::VidDisperseMsg2(disperse) => disperse.data.view_number(),
435                }
436            },
437        }
438    }
439
440    /// Get the epoch number this message relates to, if applicable
441    fn epoch_number(&self) -> Option<EpochNumber> {
442        match &self {
443            SequencingMessage::General(general_message) => {
444                match general_message {
445                    GeneralConsensusMessage::Proposal(p) => {
446                        // view of leader in the leaf when proposal
447                        // this should match replica upon receipt
448                        p.data.epoch()
449                    },
450                    GeneralConsensusMessage::Proposal2Legacy(p) => {
451                        // view of leader in the leaf when proposal
452                        // this should match replica upon receipt
453                        p.data.epoch()
454                    },
455                    GeneralConsensusMessage::Proposal2(p) => {
456                        // view of leader in the leaf when proposal
457                        // this should match replica upon receipt
458                        p.data.epoch()
459                    },
460                    GeneralConsensusMessage::ProposalRequested(..) => None,
461                    GeneralConsensusMessage::ProposalResponse(proposal) => proposal.data.epoch(),
462                    GeneralConsensusMessage::ProposalResponse2Legacy(proposal) => {
463                        proposal.data.epoch()
464                    },
465                    GeneralConsensusMessage::ProposalResponse2(proposal) => proposal.data.epoch(),
466                    GeneralConsensusMessage::Vote(vote_message) => vote_message.epoch(),
467                    GeneralConsensusMessage::Vote2(vote_message) => vote_message.epoch(),
468                    GeneralConsensusMessage::TimeoutVote(message) => message.epoch(),
469                    GeneralConsensusMessage::ViewSyncPreCommitVote(message) => message.epoch(),
470                    GeneralConsensusMessage::ViewSyncCommitVote(message) => message.epoch(),
471                    GeneralConsensusMessage::ViewSyncFinalizeVote(message) => message.epoch(),
472                    GeneralConsensusMessage::ViewSyncPreCommitCertificate(message) => {
473                        message.epoch()
474                    },
475                    GeneralConsensusMessage::ViewSyncCommitCertificate(message) => message.epoch(),
476                    GeneralConsensusMessage::ViewSyncFinalizeCertificate(message) => {
477                        message.epoch()
478                    },
479                    GeneralConsensusMessage::TimeoutVote2(message) => message.epoch(),
480                    GeneralConsensusMessage::ViewSyncPreCommitVote2(message) => message.epoch(),
481                    GeneralConsensusMessage::ViewSyncCommitVote2(message) => message.epoch(),
482                    GeneralConsensusMessage::ViewSyncFinalizeVote2(message) => message.epoch(),
483                    GeneralConsensusMessage::ViewSyncPreCommitCertificate2(message) => {
484                        message.epoch()
485                    },
486                    GeneralConsensusMessage::ViewSyncCommitCertificate2(message) => message.epoch(),
487                    GeneralConsensusMessage::ViewSyncFinalizeCertificate2(message) => {
488                        message.epoch()
489                    },
490                    GeneralConsensusMessage::UpgradeProposal(message) => message.data.epoch(),
491                    GeneralConsensusMessage::UpgradeVote(message) => message.epoch(),
492                    GeneralConsensusMessage::HighQc(qc, _)
493                    | GeneralConsensusMessage::ExtendedQc(qc, _) => qc.epoch(),
494                    GeneralConsensusMessage::EpochRootQuorumVote(vote) => vote.epoch(),
495                    GeneralConsensusMessage::EpochRootQuorumVote2(vote) => vote.epoch(),
496                    GeneralConsensusMessage::EpochRootQc(root_qc) => root_qc.epoch(),
497                    GeneralConsensusMessage::EpochRootQcV1(root_qc) => root_qc.epoch(),
498                }
499            },
500            SequencingMessage::Da(da_message) => {
501                match da_message {
502                    DaConsensusMessage::DaProposal(p) => {
503                        // view of leader in the leaf when proposal
504                        // this should match replica upon receipt
505                        p.data.epoch()
506                    },
507                    DaConsensusMessage::DaVote(vote_message) => vote_message.epoch(),
508                    DaConsensusMessage::DaCertificate(cert) => cert.epoch(),
509                    DaConsensusMessage::VidDisperseMsg(disperse) => disperse.data.epoch(),
510                    DaConsensusMessage::VidDisperseMsg1(disperse) => disperse.data.epoch(),
511                    DaConsensusMessage::VidDisperseMsg2(disperse) => disperse.data.epoch(),
512                    DaConsensusMessage::DaProposal2(p) => {
513                        // view of leader in the leaf when proposal
514                        // this should match replica upon receipt
515                        p.data.epoch()
516                    },
517                    DaConsensusMessage::DaVote2(vote_message) => vote_message.epoch(),
518                    DaConsensusMessage::DaCertificate2(cert) => cert.epoch(),
519                }
520            },
521        }
522    }
523}
524
525#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)]
526#[serde(bound(deserialize = ""))]
527#[allow(clippy::large_enum_variant)]
528/// TODO: Put `DataResponse` content in a `Box` to make enum smaller
529/// Messages related to sending data between nodes
530pub enum DataMessage<TYPES: NodeType> {
531    /// Contains a transaction to be submitted
532    /// TODO rethink this when we start to send these messages
533    /// we only need the view number for broadcast
534    SubmitTransaction(TYPES::Transaction, ViewNumber),
535    /// A request for data
536    RequestData(DataRequest<TYPES>),
537    /// A response to a data request
538    DataResponse(ResponseMessage<TYPES>),
539}
540
541#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)]
542#[serde(bound(deserialize = ""))]
543/// Prepare qc from the leader
544pub struct Proposal<TYPES: NodeType, PROPOSAL: HasViewNumber + HasEpoch + DeserializeOwned> {
545    // NOTE: optimization could include view number to help look up parent leaf
546    // could even do 16 bit numbers if we want
547    /// The data being proposed.
548    pub data: PROPOSAL,
549    /// The proposal must be signed by the view leader
550    pub signature: <TYPES::SignatureKey as SignatureKey>::PureAssembledSignatureType,
551    /// Phantom for TYPES
552    pub _pd: PhantomData<TYPES>,
553}
554
555impl<TYPES: NodeType, PROPOSAL: HasViewNumber + HasEpoch + DeserializeOwned>
556    Proposal<TYPES, PROPOSAL>
557{
558    pub fn new(
559        data: PROPOSAL,
560        signature: <TYPES::SignatureKey as SignatureKey>::PureAssembledSignatureType,
561    ) -> Self {
562        Self {
563            data,
564            signature,
565            _pd: PhantomData,
566        }
567    }
568}
569
570/// Convert a `Proposal` by converting the underlying proposal type
571pub fn convert_proposal<TYPES, PROPOSAL, PROPOSAL2>(
572    proposal: Proposal<TYPES, PROPOSAL>,
573) -> Proposal<TYPES, PROPOSAL2>
574where
575    TYPES: NodeType,
576    PROPOSAL: HasViewNumber + HasEpoch + DeserializeOwned,
577    PROPOSAL2: HasViewNumber + HasEpoch + DeserializeOwned + From<PROPOSAL>,
578{
579    Proposal {
580        data: proposal.data.into(),
581        signature: proposal.signature,
582        _pd: proposal._pd,
583    }
584}
585
586impl<TYPES> Proposal<TYPES, QuorumProposal<TYPES>>
587where
588    TYPES: NodeType,
589{
590    /// Checks that the signature of the quorum proposal is valid.
591    /// # Errors
592    /// Returns an error when the proposal signature is invalid.
593    pub fn validate_signature(
594        &self,
595        membership: &TYPES::Membership,
596        _epoch_height: u64,
597        upgrade_lock: &UpgradeLock<TYPES>,
598    ) -> Result<()> {
599        let view_number = self.data.view_number();
600        let view_leader_key = membership.non_epoch_snapshot().leader(view_number)?;
601        let proposed_leaf = Leaf::from_quorum_proposal(&self.data);
602
603        ensure!(
604            view_leader_key.validate(&self.signature, proposed_leaf.commit(upgrade_lock).as_ref()),
605            "Proposal signature is invalid."
606        );
607
608        Ok(())
609    }
610}
611
612impl<TYPES> Proposal<TYPES, QuorumProposalWrapper<TYPES>>
613where
614    TYPES: NodeType,
615{
616    /// Checks that the signature of the quorum proposal is valid.
617    /// # Errors
618    /// Returns an error when the proposal signature is invalid.
619    pub fn validate_signature(&self, membership: &EpochMembership<TYPES>) -> Result<()> {
620        let view_number = self.data.proposal.view_number();
621        let view_leader_key = membership.leader(view_number)?;
622        let proposed_leaf = Leaf2::from_quorum_proposal(&self.data);
623
624        ensure!(
625            view_leader_key.validate(&self.signature, proposed_leaf.commit().as_ref()),
626            "Proposal signature is invalid."
627        );
628
629        Ok(())
630    }
631}
632
633impl<TYPES> Proposal<TYPES, QuorumProposal2<TYPES>>
634where
635    TYPES: NodeType,
636{
637    pub fn validate_signature(
638        &self,
639        membership_coordinator: &EpochMembershipCoordinator<TYPES>,
640    ) -> Result<()> {
641        let view_number = self.data.view_number();
642        let epoch = self.data.epoch().ok_or(error!("Epoch is not set"))?;
643        let membership = membership_coordinator.membership_for_epoch(Some(epoch))?;
644        let view_leader_key = membership.leader(view_number)?;
645        let proposed_leaf =
646            Leaf2::from_quorum_proposal(&QuorumProposalWrapper::from(self.data.clone()));
647
648        ensure!(
649            view_leader_key.validate(&self.signature, proposed_leaf.commit().as_ref()),
650            "Proposal signature is invalid."
651        );
652
653        Ok(())
654    }
655}
656
657/// A lock for an upgrade certificate decided by HotShot.
658#[derive(Clone, Debug)]
659pub struct UpgradeLock<TYPES: NodeType> {
660    decided_upgrade_certificate: Arc<RwLock<Option<UpgradeCertificate<TYPES>>>>,
661    upgrade: Upgrade,
662}
663
664impl<TYPES: NodeType> UpgradeLock<TYPES> {
665    /// Create a new `UpgradeLock` for a fresh instance of HotShot
666    pub fn new(upgrade: Upgrade) -> Self {
667        Self {
668            decided_upgrade_certificate: Arc::new(RwLock::new(None)),
669            upgrade,
670        }
671    }
672
673    /// Create a new `UpgradeLock` from an optional upgrade certificate
674    pub fn from_certificate(
675        upgrade: Upgrade,
676        certificate: &Option<UpgradeCertificate<TYPES>>,
677    ) -> Self {
678        Self {
679            decided_upgrade_certificate: Arc::new(RwLock::new(certificate.clone())),
680            upgrade,
681        }
682    }
683
684    pub fn upgrade(&self) -> Upgrade {
685        self.upgrade
686    }
687
688    pub fn upgrade_view(&self) -> Option<ViewNumber> {
689        self.decided_upgrade_certificate
690            .read()
691            .as_ref()
692            .map(|cert| cert.data.new_version_first_view)
693    }
694
695    pub fn decided_upgrade_cert(&self) -> Option<UpgradeCertificate<TYPES>> {
696        self.decided_upgrade_certificate.read().clone()
697    }
698
699    pub fn set_decided_upgrade_cert<C>(&self, cert: C)
700    where
701        C: Into<Option<UpgradeCertificate<TYPES>>>,
702    {
703        *self.decided_upgrade_certificate.write() = cert.into()
704    }
705
706    /// Apply a function to the upgrade certificate.
707    pub fn apply<F>(&self, f: F)
708    where
709        F: FnOnce(&mut Option<UpgradeCertificate<TYPES>>),
710    {
711        let mut guard = self.decided_upgrade_certificate.write();
712        f(&mut *guard)
713    }
714
715    /// Calculate the version applied in a view, based on the provided upgrade lock.
716    ///
717    /// # Errors
718    /// Returns an error if we do not support the version required by the decided upgrade certificate.
719    pub fn version(&self, view: ViewNumber) -> Result<Version> {
720        if let Some(cert) = &*self.decided_upgrade_certificate.read() {
721            if view >= cert.data.new_version_first_view {
722                if cert.data.new_version == self.upgrade.target {
723                    Ok(self.upgrade.target)
724                } else {
725                    bail!("The network has upgraded to a new version that we do not support!");
726                }
727            } else {
728                Ok(self.upgrade.base)
729            }
730        } else {
731            Ok(self.upgrade.base)
732        }
733    }
734
735    /// Calculate the version applied in a view, based on the provided upgrade lock.
736    ///
737    /// This function does not fail, since it does not check that the version is supported.
738    pub fn version_infallible(&self, view: ViewNumber) -> Version {
739        if let Some(cert) = &*self.decided_upgrade_certificate.read() {
740            if view >= cert.data.new_version_first_view {
741                cert.data.new_version
742            } else {
743                cert.data.old_version
744            }
745        } else {
746            self.upgrade.base
747        }
748    }
749
750    /// Return whether epochs are enabled in the given view
751    pub fn epochs_enabled(&self, view: ViewNumber) -> bool {
752        self.version_infallible(view) >= EPOCH_VERSION
753    }
754
755    /// Return whether `QuorumProposal2Legacy` is the correct message type for the given view
756    pub fn proposal2_legacy_version(&self, view: ViewNumber) -> bool {
757        let version = self.version_infallible(view);
758        version >= EPOCH_VERSION && version < DRB_AND_HEADER_UPGRADE_VERSION
759    }
760
761    /// Return whether `QuorumProposal2` is the correct message type for the given view
762    pub fn proposal2_version(&self, view: ViewNumber) -> bool {
763        let version = self.version_infallible(view);
764        version >= EPOCH_VERSION && version >= DRB_AND_HEADER_UPGRADE_VERSION
765    }
766
767    /// Return whether epochs are enabled in the given view
768    pub fn upgraded_drb_and_header(&self, view: ViewNumber) -> bool {
769        self.version_infallible(view) >= DRB_AND_HEADER_UPGRADE_VERSION
770    }
771
772    pub fn upgraded_vid2(&self, view: ViewNumber) -> bool {
773        self.version_infallible(view) >= NEW_PROTOCOL_VERSION
774    }
775
776    /// Return whether the new protocol (HotShot 0.8) is active for the given view.
777    ///
778    /// Once true for any view, all consensus messages tagged with versions strictly
779    /// less than `NEW_PROTOCOL_VERSION` should be ignored at the legacy task layer
780    /// for that view onward. The wire-level deserialize already rejects
781    /// version-mismatched messages via [`Self::version`].
782    pub fn new_protocol_active(&self, view: ViewNumber) -> bool {
783        self.version_infallible(view) >= NEW_PROTOCOL_VERSION
784    }
785
786    /// Serialize a message with a version number, using `message.view_number()`
787    /// and an optional decided upgrade certificate to determine the message's
788    /// version.
789    ///
790    /// # Errors
791    ///
792    /// Errors if serialization fails.
793    pub fn serialize<M: HasViewNumber + Serialize>(&self, message: &M) -> Result<Vec<u8>> {
794        let view = message.view_number();
795
796        let version = self.version(view)?;
797
798        let serialized_message = if version == self.upgrade.base || version == self.upgrade.target {
799            versions::encode(version, message)
800        } else {
801            bail!(
802                "Attempted to serialize with version {version}, which is incompatible. This \
803                 should be impossible."
804            );
805        };
806
807        serialized_message
808            .wrap()
809            .context(info!("Failed to serialize message!"))
810    }
811
812    /// Deserialize a message with a version number, using `message.view_number()`
813    /// to determine the message's version. This function will fail on improperly
814    /// versioned messages.
815    ///
816    /// Returns both the deserialized message and the version of the message
817    ///
818    /// # Errors
819    ///
820    /// Errors if deserialization fails.
821    pub fn deserialize<M: Debug + HasViewNumber + DeserializeOwned>(
822        &self,
823        message: &[u8],
824    ) -> Result<(M, Version)> {
825        let (version, deserialized_message) = versions::decode::<M>(message)
826            .wrap()
827            .context(info!("Failed to read version and message!"))?;
828
829        if EXTERNAL_MESSAGE_VERSION != version
830            && self.upgrade.base != version
831            && self.upgrade.target != version
832        {
833            bail!(warn!(
834                "Received a message with state version {version} which is invalid for its view: \
835                 {:?}",
836                deserialized_message
837            ));
838        }
839
840        // If the message is version 0.0, just return the deserialized message and the version.
841        // We don't care about it matching the expected version for the view number.
842        if version == EXTERNAL_MESSAGE_VERSION {
843            return Ok((deserialized_message, version));
844        }
845
846        // Get the view number associated with the message
847        let view = deserialized_message.view_number();
848
849        // Get the expected version for the message based on the view number
850        let expected_version = self.version(view)?;
851
852        // Check that the actual version matches the expected version
853        if version != expected_version {
854            return Err(error!(format!(
855                "Message has invalid version number for its view. Expected: {expected_version}, \
856                 Actual: {version}, View: {view:?}\n\n{deserialized_message:?}"
857            )));
858        };
859
860        Ok((deserialized_message, version))
861    }
862}
hotshot_types/message.rs

hotshot_types/
message.rs
