snarkos_node_router_messages/
lib.rs

1// Copyright (c) 2019-2025 Provable Inc.
2// This file is part of the snarkOS library.
3
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at:
7
8// http://www.apache.org/licenses/LICENSE-2.0
9
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16#![forbid(unsafe_code)]
17
18#[macro_use]
19extern crate tracing;
20
21pub mod helpers;
22pub use helpers::*;
23
24mod block_request;
25pub use block_request::BlockRequest;
26
27mod block_response;
28pub use block_response::BlockResponse;
29
30mod challenge_request;
31pub use challenge_request::ChallengeRequest;
32
33mod challenge_response;
34pub use challenge_response::ChallengeResponse;
35
36mod disconnect;
37pub use disconnect::Disconnect;
38
39mod peer_request;
40pub use peer_request::PeerRequest;
41
42mod peer_response;
43pub use peer_response::PeerResponse;
44
45mod ping;
46pub use ping::Ping;
47
48mod pong;
49pub use pong::Pong;
50
51mod puzzle_request;
52pub use puzzle_request::PuzzleRequest;
53
54mod puzzle_response;
55pub use puzzle_response::PuzzleResponse;
56
57mod unconfirmed_solution;
58pub use unconfirmed_solution::UnconfirmedSolution;
59
60mod unconfirmed_transaction;
61pub use unconfirmed_transaction::UnconfirmedTransaction;
62
63pub use snarkos_node_bft_events::DataBlocks;
64
65use snarkos_node_sync_locators::BlockLocators;
66use snarkvm::prelude::{
67    Address,
68    ConsensusVersion,
69    FromBytes,
70    Network,
71    Signature,
72    ToBytes,
73    block::{Header, Transaction},
74    error,
75    puzzle::{Solution, SolutionID},
76};
77
78use std::{
79    borrow::Cow,
80    fmt,
81    fmt::{Display, Formatter},
82    io,
83    net::SocketAddr,
84};
85
86pub trait MessageTrait: ToBytes + FromBytes {
87    /// Returns the message name.
88    fn name(&self) -> Cow<'static, str>;
89}
90
91#[derive(Clone, Debug, PartialEq, Eq)]
92pub enum Message<N: Network> {
93    BlockRequest(BlockRequest),
94    BlockResponse(BlockResponse<N>),
95    ChallengeRequest(ChallengeRequest<N>),
96    ChallengeResponse(ChallengeResponse<N>),
97    Disconnect(Disconnect),
98    PeerRequest(PeerRequest),
99    PeerResponse(PeerResponse),
100    Ping(Ping<N>),
101    Pong(Pong),
102    PuzzleRequest(PuzzleRequest),
103    PuzzleResponse(PuzzleResponse<N>),
104    UnconfirmedSolution(UnconfirmedSolution<N>),
105    UnconfirmedTransaction(UnconfirmedTransaction<N>),
106}
107
108impl<N: Network> From<DisconnectReason> for Message<N> {
109    fn from(reason: DisconnectReason) -> Self {
110        Self::Disconnect(Disconnect { reason })
111    }
112}
113
114impl<N: Network> Message<N> {
115    /// The version of the network protocol; this is incremented for breaking changes between migration versions.
116    // Note. This should be incremented for each new `ConsensusVersion` that is added.
117    pub const VERSIONS: [(ConsensusVersion, u32); 5] = [
118        (ConsensusVersion::V5, 17),
119        (ConsensusVersion::V7, 18),
120        (ConsensusVersion::V8, 19),
121        (ConsensusVersion::V9, 20),
122        (ConsensusVersion::V10, 21),
123    ];
124
125    /// Returns the latest message version.
126    pub fn latest_message_version() -> u32 {
127        Self::VERSIONS.last().map(|(_, version)| *version).unwrap_or(0)
128    }
129
130    /// Returns the lowest acceptable message version for the given block height.
131    /// Example scenario:
132    ///     At block height `X`, the protocol upgrades to message version from `Y-1` to `Y`.
133    ///     Client A upgrades and starts using message version `Y`.
134    ///     Client B has not upgraded and still uses message version `Y-1`.
135    ///     Until block `X`, they stay connected and can communicate.
136    ///     After block `X`, Client A will reject messages from Client B.
137    pub fn lowest_accepted_message_version(current_block_height: u32) -> u32 {
138        // Fetch the latest message version.
139        let latest_message_version = Self::latest_message_version();
140
141        // Fetch the versions.
142        let versions = Self::VERSIONS;
143
144        // Determine the minimum accepted message version.
145        N::CONSENSUS_VERSION(current_block_height).map_or(latest_message_version, |seek_version| {
146            // Search the consensus value for the specified version.
147            match versions.binary_search_by(|(version, _)| version.cmp(&seek_version)) {
148                // If a value was found for this consensus version, return it.
149                Ok(index) => versions[index].1,
150                // If the specified version was not found exactly, return the appropriate value belonging to the consensus version *lower* than the sought version.
151                // If the constant is not yet in effect at this consensus version, use the earliest version.
152                Err(index) => versions[index.saturating_sub(1)].1,
153            }
154        })
155    }
156
157    /// Returns the message name.
158    #[inline]
159    pub fn name(&self) -> Cow<'static, str> {
160        match self {
161            Self::BlockRequest(message) => message.name(),
162            Self::BlockResponse(message) => message.name(),
163            Self::ChallengeRequest(message) => message.name(),
164            Self::ChallengeResponse(message) => message.name(),
165            Self::Disconnect(message) => message.name(),
166            Self::PeerRequest(message) => message.name(),
167            Self::PeerResponse(message) => message.name(),
168            Self::Ping(message) => message.name(),
169            Self::Pong(message) => message.name(),
170            Self::PuzzleRequest(message) => message.name(),
171            Self::PuzzleResponse(message) => message.name(),
172            Self::UnconfirmedSolution(message) => message.name(),
173            Self::UnconfirmedTransaction(message) => message.name(),
174        }
175    }
176
177    /// Returns the message ID.
178    #[inline]
179    pub fn id(&self) -> u16 {
180        match self {
181            Self::BlockRequest(..) => 0,
182            Self::BlockResponse(..) => 1,
183            Self::ChallengeRequest(..) => 2,
184            Self::ChallengeResponse(..) => 3,
185            Self::Disconnect(..) => 4,
186            Self::PeerRequest(..) => 5,
187            Self::PeerResponse(..) => 6,
188            Self::Ping(..) => 7,
189            Self::Pong(..) => 8,
190            Self::PuzzleRequest(..) => 9,
191            Self::PuzzleResponse(..) => 10,
192            Self::UnconfirmedSolution(..) => 11,
193            Self::UnconfirmedTransaction(..) => 12,
194        }
195    }
196
197    /// Checks the message byte length. To be used before deserialization.
198    pub fn check_size(bytes: &[u8]) -> io::Result<()> {
199        // Store the length to be checked against the max message size for each variant.
200        let len = bytes.len();
201        if len < 2 {
202            return Err(io::Error::new(io::ErrorKind::InvalidData, "invalid message"));
203        }
204
205        // Check the first two bytes for the message ID.
206        let id_bytes: [u8; 2] = (&bytes[..2])
207            .try_into()
208            .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "id couldn't be deserialized"))?;
209        let id = u16::from_le_bytes(id_bytes);
210
211        // SPECIAL CASE: check the transaction message isn't too large.
212        if id == 12 && len > N::MAX_TRANSACTION_SIZE {
213            return Err(io::Error::new(io::ErrorKind::InvalidData, "transaction is too large"))?;
214        }
215
216        Ok(())
217    }
218}
219
220impl<N: Network> ToBytes for Message<N> {
221    fn write_le<W: io::Write>(&self, mut writer: W) -> io::Result<()> {
222        self.id().write_le(&mut writer)?;
223
224        match self {
225            Self::BlockRequest(message) => message.write_le(writer),
226            Self::BlockResponse(message) => message.write_le(writer),
227            Self::ChallengeRequest(message) => message.write_le(writer),
228            Self::ChallengeResponse(message) => message.write_le(writer),
229            Self::Disconnect(message) => message.write_le(writer),
230            Self::PeerRequest(message) => message.write_le(writer),
231            Self::PeerResponse(message) => message.write_le(writer),
232            Self::Ping(message) => message.write_le(writer),
233            Self::Pong(message) => message.write_le(writer),
234            Self::PuzzleRequest(message) => message.write_le(writer),
235            Self::PuzzleResponse(message) => message.write_le(writer),
236            Self::UnconfirmedSolution(message) => message.write_le(writer),
237            Self::UnconfirmedTransaction(message) => message.write_le(writer),
238        }
239    }
240}
241
242impl<N: Network> FromBytes for Message<N> {
243    fn read_le<R: io::Read>(mut reader: R) -> io::Result<Self> {
244        // Read the event ID.
245        let mut id_bytes = [0u8; 2];
246        reader.read_exact(&mut id_bytes)?;
247        let id = u16::from_le_bytes(id_bytes);
248
249        // Deserialize the data field.
250        let message = match id {
251            0 => Self::BlockRequest(BlockRequest::read_le(&mut reader)?),
252            1 => Self::BlockResponse(BlockResponse::read_le(&mut reader)?),
253            2 => Self::ChallengeRequest(ChallengeRequest::read_le(&mut reader)?),
254            3 => Self::ChallengeResponse(ChallengeResponse::read_le(&mut reader)?),
255            4 => Self::Disconnect(Disconnect::read_le(&mut reader)?),
256            5 => Self::PeerRequest(PeerRequest::read_le(&mut reader)?),
257            6 => Self::PeerResponse(PeerResponse::read_le(&mut reader)?),
258            7 => Self::Ping(Ping::read_le(&mut reader)?),
259            8 => Self::Pong(Pong::read_le(&mut reader)?),
260            9 => Self::PuzzleRequest(PuzzleRequest::read_le(&mut reader)?),
261            10 => Self::PuzzleResponse(PuzzleResponse::read_le(&mut reader)?),
262            11 => Self::UnconfirmedSolution(UnconfirmedSolution::read_le(&mut reader)?),
263            12 => Self::UnconfirmedTransaction(UnconfirmedTransaction::read_le(&mut reader)?),
264            13.. => return Err(error("Unknown message ID {id}")),
265        };
266
267        // Ensure that there are no "dangling" bytes.
268        #[allow(clippy::unbuffered_bytes)]
269        if reader.bytes().next().is_some() {
270            return Err(error("Leftover bytes in a Message"));
271        }
272
273        Ok(message)
274    }
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280    use snarkvm::prelude::{CanaryV0, MainnetV0, TestnetV0};
281
282    /// Ensure that the message versions used at genesis is correct.
283    fn consensus_constants_at_genesis<N: Network>() {
284        let height = 0;
285        let consensus_version = Message::<N>::lowest_accepted_message_version(height);
286        assert_eq!(consensus_version as usize, Message::<N>::VERSIONS.first().unwrap().1 as usize);
287    }
288
289    /// Ensure that the consensus *versions* are unique and incrementing.
290    fn consensus_versions<N: Network>() {
291        let mut previous_version = Message::<N>::VERSIONS.first().unwrap().0;
292        for (version, _) in Message::<N>::VERSIONS.iter().skip(1) {
293            assert!(*version as usize > previous_version as usize);
294            previous_version = *version;
295        }
296    }
297
298    /// Ensure that *message versions* are unique and incrementing by 1.
299    fn consensus_constants_increasing_heights<N: Network>() {
300        let mut previous_message_version = Message::<N>::VERSIONS.first().unwrap().1;
301        for (_, message_version) in Message::<N>::VERSIONS.iter().skip(1) {
302            assert_eq!(*message_version, previous_message_version + 1);
303            previous_message_version = *message_version;
304        }
305    }
306
307    #[test]
308    #[allow(clippy::assertions_on_constants)]
309    fn test_consensus_constants() {
310        consensus_constants_at_genesis::<MainnetV0>();
311        consensus_constants_at_genesis::<TestnetV0>();
312        consensus_constants_at_genesis::<CanaryV0>();
313
314        consensus_versions::<MainnetV0>();
315        consensus_versions::<TestnetV0>();
316        consensus_versions::<CanaryV0>();
317
318        consensus_constants_increasing_heights::<MainnetV0>();
319        consensus_constants_increasing_heights::<TestnetV0>();
320        consensus_constants_increasing_heights::<CanaryV0>();
321    }
322
323    #[test]
324    fn test_latest_consensus_version() {
325        let message_consensus_version = Message::<MainnetV0>::VERSIONS.last().unwrap().0;
326        let expected_consensus_version = MainnetV0::CONSENSUS_VERSION_HEIGHTS().last().unwrap().0;
327        assert_eq!(message_consensus_version, expected_consensus_version);
328
329        let message_consensus_version = Message::<TestnetV0>::VERSIONS.last().unwrap().0;
330        let expected_consensus_version = TestnetV0::CONSENSUS_VERSION_HEIGHTS().last().unwrap().0;
331        assert_eq!(message_consensus_version, expected_consensus_version);
332
333        let message_consensus_version = Message::<CanaryV0>::VERSIONS.last().unwrap().0;
334        let expected_consensus_version = CanaryV0::CONSENSUS_VERSION_HEIGHTS().last().unwrap().0;
335        assert_eq!(message_consensus_version, expected_consensus_version);
336    }
337}
snarkos_node_router_messages/lib.rs

snarkos_node_router_messages/
lib.rs
