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

hotshot_types/
message.rs
