1#![forbid(unsafe_code)]
10#![allow(
11 clippy::doc_markdown,
12 clippy::missing_errors_doc,
13 clippy::module_name_repetitions,
14 reason = "HNS, P2P, HSD, and HIP are protocol names"
15)]
16
17use std::collections::VecDeque;
18use std::io::{Read, Write};
19use std::net::{Shutdown, SocketAddr, TcpStream};
20use std::time::Duration;
21
22use hns_header_consensus::Header;
23use hns_p2p_wire::{
24 Frame, FrameDecoder, GetProofPacket, Inventory, LocatorPacket, NetAddress, NetworkMagic,
25 Packet, PacketType, ProofPacket, RejectPacket, SERVICE_BLOOM, SERVICE_NETWORK, VersionPacket,
26 WireError,
27};
28use hns_primitives::{BlockHash, NameHash, TreeRoot};
29use hns_transaction::Transaction;
30use thiserror::Error;
31
32pub const DEFAULT_HANDSHAKE_TIMEOUT_SECONDS: u64 = 10;
34pub const DEFAULT_REQUEST_TIMEOUT_SECONDS: u64 = 15;
36pub const DEFAULT_MAX_CLOCK_SKEW_SECONDS: u64 = 2 * 60 * 60;
38pub const PEER_READ_BUFFER_SIZE: usize = 8 * 1_024;
40pub const MAX_PENDING_PEER_FRAMES: usize = 1_024;
42
43#[derive(Clone, Copy, Debug, Eq, PartialEq)]
45pub struct PeerConfig {
46 pub network: NetworkMagic,
48 pub required_services: u64,
50 pub handshake_timeout_seconds: u64,
52 pub request_timeout_seconds: u64,
54 pub max_clock_skew_seconds: u64,
56}
57
58impl PeerConfig {
59 #[must_use]
61 pub const fn for_network(network: NetworkMagic) -> Self {
62 Self {
63 network,
64 required_services: SERVICE_NETWORK,
65 handshake_timeout_seconds: DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
66 request_timeout_seconds: DEFAULT_REQUEST_TIMEOUT_SECONDS,
67 max_clock_skew_seconds: DEFAULT_MAX_CLOCK_SKEW_SECONDS,
68 }
69 }
70
71 #[must_use]
73 pub const fn for_wallet_network(network: NetworkMagic) -> Self {
74 Self {
75 network,
76 required_services: SERVICE_NETWORK | SERVICE_BLOOM,
77 handshake_timeout_seconds: DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
78 request_timeout_seconds: DEFAULT_REQUEST_TIMEOUT_SECONDS,
79 max_clock_skew_seconds: DEFAULT_MAX_CLOCK_SKEW_SECONDS,
80 }
81 }
82
83 fn validate(self) -> Result<Self, PeerError> {
84 if self.required_services & SERVICE_NETWORK == 0
85 || self.handshake_timeout_seconds == 0
86 || self.handshake_timeout_seconds > 60
87 || self.request_timeout_seconds == 0
88 || self.request_timeout_seconds > 300
89 || self.max_clock_skew_seconds > 24 * 60 * 60
90 {
91 return Err(PeerError::InvalidConfig);
92 }
93 Ok(self)
94 }
95}
96
97#[derive(Clone, Copy, Debug, Eq, PartialEq)]
99pub enum PeerState {
100 AwaitingVersion,
102 AwaitingVerack,
104 Ready,
106 Closed,
108}
109
110#[derive(Clone, Debug, Eq, PartialEq)]
112pub struct PeerMetadata {
113 pub version: u32,
115 pub services: u64,
117 pub time: u64,
119 pub agent: String,
121 pub height: u32,
123}
124
125#[derive(Clone, Debug, Eq, PartialEq)]
131pub enum WalletPeerEvent {
132 Inventory(Vec<Inventory>),
134 DataRequest(Vec<Inventory>),
136 NotFound(Vec<Inventory>),
138 Transaction(Transaction),
140 MerkleBlock(Vec<u8>),
142 FeeFilter(i64),
144}
145
146#[repr(u8)]
148#[derive(Clone, Copy, Debug, Eq, PartialEq)]
149pub enum RequestKind {
150 Headers = 0,
152 Proof = 1,
154 Ping = 2,
156}
157
158#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
160pub struct ExpiredRequests {
161 pub headers: bool,
163 pub proof: bool,
165 pub ping: bool,
167}
168
169impl ExpiredRequests {
170 #[must_use]
172 pub const fn any(self) -> bool {
173 self.headers || self.proof || self.ping
174 }
175}
176
177#[derive(Clone, Debug, Eq, PartialEq)]
179pub enum PeerEvent {
180 Send(Frame),
182 Ready(PeerMetadata),
184 Headers(Vec<Header>),
186 Proof(ProofPacket),
188 Addresses(Vec<NetAddress>),
190 GetAddresses,
194 GetBlocks(LocatorPacket),
198 GetHeaders(LocatorPacket),
202 Pong([u8; 8]),
204 Rejected(RejectPacket),
206 Wallet(WalletPeerEvent),
208 Experimental {
213 packet_type: u8,
215 payload: Vec<u8>,
217 },
218 Ignored(PacketType),
220}
221
222#[derive(Clone, Copy, Debug, Eq, PartialEq)]
223struct Pending {
224 deadline: u64,
225}
226
227#[derive(Clone, Copy, Debug, Eq, PartialEq)]
228struct PendingProof {
229 root: TreeRoot,
230 key: NameHash,
231 deadline: u64,
232}
233
234#[derive(Clone, Copy, Debug, Eq, PartialEq)]
235struct PendingPing {
236 nonce: [u8; 8],
237 deadline: u64,
238}
239
240#[derive(Clone, Debug)]
242pub struct PeerSession {
243 config: PeerConfig,
244 state: PeerState,
245 local_nonce: [u8; 8],
246 handshake_deadline: u64,
247 peer_verack_received: bool,
251 ready_after_response: bool,
256 metadata: Option<PeerMetadata>,
257 pending_headers: Option<Pending>,
258 pending_proof: Option<PendingProof>,
259 pending_ping: Option<PendingPing>,
260}
261
262#[derive(Debug)]
268pub struct PeerConnection<T> {
269 transport: T,
270 session: PeerSession,
271 decoder: FrameDecoder,
272 pending: VecDeque<Frame>,
273}
274
275impl PeerSession {
276 pub fn start(
278 config: PeerConfig,
279 local_version: &VersionPacket,
280 now: u64,
281 ) -> Result<(Self, Frame), PeerError> {
282 let config = config.validate()?;
283 if local_version.nonce == [0; 8]
284 || local_version.version < hns_p2p_wire::MIN_PROTOCOL_VERSION
285 || local_version.time.abs_diff(now) > config.max_clock_skew_seconds
286 {
287 return Err(PeerError::InvalidLocalVersion);
288 }
289 let handshake_deadline = now
290 .checked_add(config.handshake_timeout_seconds)
291 .ok_or(PeerError::TimeOverflow)?;
292 let frame = Frame::from_packet(&Packet::Version(local_version.clone()))?;
293 Ok((
294 Self {
295 config,
296 state: PeerState::AwaitingVersion,
297 local_nonce: local_version.nonce,
298 handshake_deadline,
299 peer_verack_received: false,
300 ready_after_response: false,
301 metadata: None,
302 pending_headers: None,
303 pending_proof: None,
304 pending_ping: None,
305 },
306 frame,
307 ))
308 }
309
310 #[must_use]
312 pub const fn network(&self) -> NetworkMagic {
313 self.config.network
314 }
315
316 #[must_use]
318 pub const fn state(&self) -> PeerState {
319 self.state
320 }
321
322 #[must_use]
324 pub const fn metadata(&self) -> Option<&PeerMetadata> {
325 self.metadata.as_ref()
326 }
327
328 pub fn close(&mut self) {
330 self.state = PeerState::Closed;
331 self.pending_headers = None;
332 self.pending_proof = None;
333 self.pending_ping = None;
334 }
335
336 pub fn handle_frame(&mut self, frame: &Frame, now: u64) -> Result<PeerEvent, PeerError> {
338 if self.state == PeerState::Closed {
339 return Err(PeerError::Closed);
340 }
341 if self.state != PeerState::Ready && now > self.handshake_deadline {
342 self.close();
343 return Err(PeerError::HandshakeTimeout);
344 }
345 let packet = frame.decode_packet()?;
346 match self.state {
347 PeerState::AwaitingVersion if packet == Packet::Verack => {
352 self.peer_verack_received = true;
353 Ok(PeerEvent::Ignored(PacketType::Verack))
354 }
355 PeerState::AwaitingVersion => self.handle_version(packet, now),
356 PeerState::AwaitingVerack => {
357 if packet != Packet::Verack {
358 return Err(PeerError::ExpectedVerack);
359 }
360 self.state = PeerState::Ready;
361 Ok(PeerEvent::Ready(
362 self.metadata.clone().ok_or(PeerError::InternalInvariant)?,
363 ))
364 }
365 PeerState::Ready => self.handle_ready(packet, now),
366 PeerState::Closed => Err(PeerError::Closed),
367 }
368 }
369
370 pub fn request_headers(
372 &mut self,
373 locator: Vec<BlockHash>,
374 stop: BlockHash,
375 now: u64,
376 ) -> Result<Frame, PeerError> {
377 self.require_ready()?;
378 if locator.is_empty() {
379 return Err(PeerError::EmptyLocator);
380 }
381 if self.pending_headers.is_some() {
382 return Err(PeerError::DuplicateRequest(RequestKind::Headers));
383 }
384 let deadline = self.request_deadline(now)?;
385 let frame = Frame::from_packet(&Packet::GetHeaders(LocatorPacket { locator, stop }))?;
386 self.pending_headers = Some(Pending { deadline });
387 Ok(frame)
388 }
389
390 pub fn request_proof(
392 &mut self,
393 root: TreeRoot,
394 key: NameHash,
395 now: u64,
396 ) -> Result<Frame, PeerError> {
397 self.require_ready()?;
398 if self.pending_proof.is_some() {
399 return Err(PeerError::DuplicateRequest(RequestKind::Proof));
400 }
401 let deadline = self.request_deadline(now)?;
402 let frame = Frame::from_packet(&Packet::GetProof(GetProofPacket { root, key }))?;
403 self.pending_proof = Some(PendingProof {
404 root,
405 key,
406 deadline,
407 });
408 Ok(frame)
409 }
410
411 pub fn wallet_frame(&self, packet: &Packet) -> Result<Frame, PeerError> {
419 self.require_ready()?;
420 if self
421 .metadata
422 .as_ref()
423 .is_none_or(|metadata| metadata.services & SERVICE_BLOOM == 0)
424 {
425 return Err(PeerError::MissingBloomService);
426 }
427 if !matches!(
428 packet,
429 Packet::Inv(_)
430 | Packet::GetData(_)
431 | Packet::Tx(_)
432 | Packet::Mempool
433 | Packet::FilterLoad(_)
434 | Packet::FilterAdd(_)
435 | Packet::FilterClear
436 ) {
437 return Err(PeerError::UnsupportedWalletPacket(packet.packet_type()));
438 }
439 Ok(Frame::from_packet(packet)?)
440 }
441
442 pub fn address_request(&self) -> Result<Frame, PeerError> {
444 self.require_ready()?;
445 Ok(Frame::from_packet(&Packet::GetAddr)?)
446 }
447
448 pub fn ping(&mut self, nonce: [u8; 8], now: u64) -> Result<Frame, PeerError> {
450 self.require_ready()?;
451 if nonce == [0; 8] {
452 return Err(PeerError::ZeroPingNonce);
453 }
454 if self.pending_ping.is_some() {
455 return Err(PeerError::DuplicateRequest(RequestKind::Ping));
456 }
457 let deadline = self.request_deadline(now)?;
458 let frame = Frame::from_packet(&Packet::Ping(nonce))?;
459 self.pending_ping = Some(PendingPing { nonce, deadline });
460 Ok(frame)
461 }
462
463 pub fn expire(&mut self, now: u64) -> Result<ExpiredRequests, PeerError> {
465 if self.state != PeerState::Ready {
466 if self.state != PeerState::Closed && now > self.handshake_deadline {
467 self.close();
468 return Err(PeerError::HandshakeTimeout);
469 }
470 return Ok(ExpiredRequests::default());
471 }
472 let expired = ExpiredRequests {
473 headers: self
474 .pending_headers
475 .is_some_and(|pending| now > pending.deadline),
476 proof: self
477 .pending_proof
478 .is_some_and(|pending| now > pending.deadline),
479 ping: self
480 .pending_ping
481 .is_some_and(|pending| now > pending.deadline),
482 };
483 if expired.headers {
484 self.pending_headers = None;
485 }
486 if expired.proof {
487 self.pending_proof = None;
488 }
489 if expired.ping {
490 self.pending_ping = None;
491 }
492 Ok(expired)
493 }
494
495 fn handle_version(&mut self, packet: Packet, now: u64) -> Result<PeerEvent, PeerError> {
496 let Packet::Version(version) = packet else {
497 return Err(PeerError::ExpectedVersion);
498 };
499 if version.version < hns_p2p_wire::MIN_PROTOCOL_VERSION {
500 return Err(PeerError::ObsoleteVersion);
501 }
502 if version.services & self.config.required_services != self.config.required_services {
503 return Err(PeerError::MissingService);
504 }
505 if version.nonce == self.local_nonce {
506 return Err(PeerError::SelfConnection);
507 }
508 if version.time.abs_diff(now) > self.config.max_clock_skew_seconds {
509 return Err(PeerError::ClockSkew);
510 }
511 self.metadata = Some(PeerMetadata {
512 version: version.version.min(hns_p2p_wire::PROTOCOL_VERSION),
513 services: version.services,
514 time: version.time,
515 agent: version.agent,
516 height: version.height,
517 });
518 if self.peer_verack_received {
519 self.state = PeerState::Ready;
520 self.ready_after_response = true;
521 } else {
522 self.state = PeerState::AwaitingVerack;
523 }
524 Ok(PeerEvent::Send(Frame::from_packet(&Packet::Verack)?))
525 }
526
527 fn handle_ready(&mut self, packet: Packet, now: u64) -> Result<PeerEvent, PeerError> {
528 match packet {
529 Packet::Version(_) | Packet::Verack => Err(PeerError::DuplicateHandshake),
530 Packet::Ping(nonce) => Ok(PeerEvent::Send(Frame::from_packet(&Packet::Pong(nonce))?)),
531 Packet::Pong(nonce) => {
532 let pending = self.pending_ping.ok_or(PeerError::UnsolicitedPong)?;
533 if now > pending.deadline {
534 self.pending_ping = None;
535 return Err(PeerError::RequestTimeout(RequestKind::Ping));
536 }
537 if pending.nonce != nonce {
538 return Err(PeerError::WrongPong);
539 }
540 self.pending_ping = None;
541 Ok(PeerEvent::Pong(nonce))
542 }
543 Packet::Headers(headers) => {
544 let pending = self
545 .pending_headers
546 .take()
547 .ok_or(PeerError::UnsolicitedHeaders)?;
548 if now > pending.deadline {
549 return Err(PeerError::RequestTimeout(RequestKind::Headers));
550 }
551 Ok(PeerEvent::Headers(headers))
552 }
553 Packet::Proof(proof) => {
554 let pending = self
555 .pending_proof
556 .take()
557 .ok_or(PeerError::UnsolicitedProof)?;
558 if now > pending.deadline {
559 return Err(PeerError::RequestTimeout(RequestKind::Proof));
560 }
561 if proof.root != pending.root || proof.key != pending.key {
562 return Err(PeerError::WrongProof);
563 }
564 Ok(PeerEvent::Proof(proof))
565 }
566 Packet::Addr(addresses) => Ok(PeerEvent::Addresses(addresses)),
567 Packet::GetAddr => Ok(PeerEvent::GetAddresses),
568 Packet::GetBlocks(locator) => Ok(PeerEvent::GetBlocks(locator)),
569 Packet::GetHeaders(locator) => Ok(PeerEvent::GetHeaders(locator)),
570 Packet::Reject(reject) => Ok(PeerEvent::Rejected(reject)),
571 Packet::Inv(inventory) => Ok(PeerEvent::Wallet(WalletPeerEvent::Inventory(inventory))),
572 Packet::GetData(inventory) => {
573 Ok(PeerEvent::Wallet(WalletPeerEvent::DataRequest(inventory)))
574 }
575 Packet::NotFound(inventory) => {
576 Ok(PeerEvent::Wallet(WalletPeerEvent::NotFound(inventory)))
577 }
578 Packet::Tx(transaction) => {
579 Ok(PeerEvent::Wallet(WalletPeerEvent::Transaction(transaction)))
580 }
581 Packet::MerkleBlock(payload) => {
582 Ok(PeerEvent::Wallet(WalletPeerEvent::MerkleBlock(payload)))
583 }
584 Packet::FeeFilter(rate) => Ok(PeerEvent::Wallet(WalletPeerEvent::FeeFilter(rate))),
585 Packet::Unknown {
586 packet_type,
587 payload,
588 } => Ok(PeerEvent::Experimental {
589 packet_type,
590 payload,
591 }),
592 packet => Ok(PeerEvent::Ignored(packet.packet_type())),
593 }
594 }
595
596 fn require_ready(&self) -> Result<(), PeerError> {
597 match self.state {
598 PeerState::Ready => Ok(()),
599 PeerState::Closed => Err(PeerError::Closed),
600 PeerState::AwaitingVersion | PeerState::AwaitingVerack => Err(PeerError::NotReady),
601 }
602 }
603
604 fn request_deadline(&self, now: u64) -> Result<u64, PeerError> {
605 now.checked_add(self.config.request_timeout_seconds)
606 .ok_or(PeerError::TimeOverflow)
607 }
608
609 fn take_ready_after_response(&mut self) -> Result<Option<PeerMetadata>, PeerError> {
610 if !self.ready_after_response {
611 return Ok(None);
612 }
613 self.ready_after_response = false;
614 self.metadata
615 .clone()
616 .map(Some)
617 .ok_or(PeerError::InternalInvariant)
618 }
619}
620
621impl<T: Read + Write> PeerConnection<T> {
622 pub fn start(
624 transport: T,
625 config: PeerConfig,
626 local_version: &VersionPacket,
627 now: u64,
628 ) -> Result<Self, PeerError> {
629 let (session, version) = PeerSession::start(config, local_version, now)?;
630 let decoder = FrameDecoder::new(session.network());
631 let mut connection = Self {
632 transport,
633 session,
634 decoder,
635 pending: VecDeque::new(),
636 };
637 connection.send_frame(&version)?;
638 Ok(connection)
639 }
640
641 #[must_use]
643 pub const fn session(&self) -> &PeerSession {
644 &self.session
645 }
646
647 #[must_use]
649 pub const fn session_mut(&mut self) -> &mut PeerSession {
650 &mut self.session
651 }
652
653 #[must_use]
655 pub const fn transport(&self) -> &T {
656 &self.transport
657 }
658
659 #[must_use]
661 pub const fn transport_mut(&mut self) -> &mut T {
662 &mut self.transport
663 }
664
665 pub fn into_inner(self) -> T {
667 self.transport
668 }
669
670 pub fn complete_handshake(
673 &mut self,
674 mut now_unix: impl FnMut() -> u64,
675 ) -> Result<PeerMetadata, PeerError> {
676 if self.session.state() == PeerState::Ready {
677 return self
678 .session
679 .metadata()
680 .cloned()
681 .ok_or(PeerError::InternalInvariant);
682 }
683 loop {
684 match self.receive_event(now_unix())? {
685 PeerEvent::Ready(metadata) => return Ok(metadata),
686 PeerEvent::Ignored(_) | PeerEvent::Addresses(_) => {}
687 PeerEvent::Send(_)
688 | PeerEvent::GetAddresses
689 | PeerEvent::GetBlocks(_)
690 | PeerEvent::GetHeaders(_)
691 | PeerEvent::Headers(_)
692 | PeerEvent::Proof(_)
693 | PeerEvent::Pong(_)
694 | PeerEvent::Rejected(_)
695 | PeerEvent::Wallet(_)
696 | PeerEvent::Experimental { .. } => {
697 return Err(PeerError::UnexpectedHandshakeEvent);
698 }
699 }
700 }
701 }
702
703 pub fn send_frame(&mut self, frame: &Frame) -> Result<(), PeerError> {
705 let encoded = frame.encode(self.session.network())?;
706 self.transport
707 .write_all(&encoded)
708 .map_err(|error| peer_io_error(&error))?;
709 self.transport
710 .flush()
711 .map_err(|error| peer_io_error(&error))
712 }
713
714 pub fn request_headers(
716 &mut self,
717 locator: Vec<BlockHash>,
718 stop: BlockHash,
719 now: u64,
720 ) -> Result<(), PeerError> {
721 let frame = self.session.request_headers(locator, stop, now)?;
722 self.send_frame(&frame)
723 }
724
725 pub fn request_proof(
727 &mut self,
728 root: TreeRoot,
729 key: NameHash,
730 now: u64,
731 ) -> Result<(), PeerError> {
732 let frame = self.session.request_proof(root, key, now)?;
733 self.send_frame(&frame)
734 }
735
736 pub fn send_wallet_packet(&mut self, packet: &Packet) -> Result<(), PeerError> {
738 let frame = self.session.wallet_frame(packet)?;
739 self.send_frame(&frame)
740 }
741
742 pub fn send_experimental_packet(
746 &mut self,
747 packet_type: u8,
748 payload: Vec<u8>,
749 ) -> Result<(), PeerError> {
750 self.session.require_ready()?;
751 let frame = Frame::new(PacketType::Unknown(packet_type), payload)?;
752 self.send_frame(&frame)
753 }
754
755 pub fn request_addresses(&mut self) -> Result<(), PeerError> {
757 let frame = self.session.address_request()?;
758 self.send_frame(&frame)
759 }
760
761 pub fn ping(&mut self, nonce: [u8; 8], now: u64) -> Result<(), PeerError> {
763 let frame = self.session.ping(nonce, now)?;
764 self.send_frame(&frame)
765 }
766
767 pub fn receive_event(&mut self, now: u64) -> Result<PeerEvent, PeerError> {
770 loop {
771 let frame = self.receive_frame()?;
772 match self.session.handle_frame(&frame, now)? {
773 PeerEvent::Send(response) => {
774 self.send_frame(&response)?;
775 if let Some(metadata) = self.session.take_ready_after_response()? {
776 return Ok(PeerEvent::Ready(metadata));
777 }
778 }
779 event => return Ok(event),
780 }
781 }
782 }
783
784 pub fn close(&mut self) {
787 self.session.close();
788 self.pending.clear();
789 }
790
791 fn receive_frame(&mut self) -> Result<Frame, PeerError> {
792 if let Some(frame) = self.pending.pop_front() {
793 return Ok(frame);
794 }
795 let mut input = [0_u8; PEER_READ_BUFFER_SIZE];
796 loop {
797 let read = self
798 .transport
799 .read(&mut input)
800 .map_err(|error| peer_io_error(&error))?;
801 if read == 0 {
802 return Err(PeerError::ConnectionClosed);
803 }
804 let bytes = input.get(..read).ok_or(PeerError::InternalInvariant)?;
805 let frames = self.decoder.push(bytes)?;
806 if self.pending.len().saturating_add(frames.len()) > MAX_PENDING_PEER_FRAMES {
807 return Err(PeerError::FrameQueueLimit);
808 }
809 self.pending.extend(frames);
810 if let Some(frame) = self.pending.pop_front() {
811 return Ok(frame);
812 }
813 }
814 }
815}
816
817impl PeerConnection<TcpStream> {
818 pub fn connect(
821 address: SocketAddr,
822 config: PeerConfig,
823 local_version: &VersionPacket,
824 now: u64,
825 connect_timeout: Duration,
826 ) -> Result<Self, PeerError> {
827 if connect_timeout.is_zero() || connect_timeout > Duration::from_secs(300) {
828 return Err(PeerError::InvalidConnectTimeout);
829 }
830 let config = config.validate()?;
831 let stream = TcpStream::connect_timeout(&address, connect_timeout)
832 .map_err(|error| peer_io_error(&error))?;
833 configure_native_stream(&stream, config)?;
834 Self::start(stream, config, local_version, now)
835 }
836
837 pub fn accept(
844 stream: TcpStream,
845 config: PeerConfig,
846 local_version: &VersionPacket,
847 now: u64,
848 ) -> Result<Self, PeerError> {
849 let config = config.validate()?;
850 configure_native_stream(&stream, config)?;
851 Self::start(stream, config, local_version, now)
852 }
853
854 pub fn shutdown(&mut self) -> Result<(), PeerError> {
856 self.close();
857 self.transport
858 .shutdown(Shutdown::Both)
859 .map_err(|error| peer_io_error(&error))
860 }
861}
862
863fn configure_native_stream(stream: &TcpStream, config: PeerConfig) -> Result<(), PeerError> {
864 let io_timeout = Duration::from_secs(
865 config
866 .handshake_timeout_seconds
867 .max(config.request_timeout_seconds),
868 );
869 stream
870 .set_read_timeout(Some(io_timeout))
871 .map_err(|error| peer_io_error(&error))?;
872 stream
873 .set_write_timeout(Some(io_timeout))
874 .map_err(|error| peer_io_error(&error))?;
875 stream
876 .set_nodelay(true)
877 .map_err(|error| peer_io_error(&error))
878}
879
880#[must_use]
882pub fn light_wallet_version(
883 remote: SocketAddr,
884 nonce: [u8; 8],
885 height: u32,
886 now: u64,
887) -> VersionPacket {
888 VersionPacket {
889 version: hns_p2p_wire::PROTOCOL_VERSION,
890 services: 0,
891 time: now,
892 remote: NetAddress::from_socket_addr(remote, now, 0),
893 nonce,
894 agent: concat!("/hns-light-wallet:", env!("CARGO_PKG_VERSION"), "/").to_owned(),
895 height,
896 no_relay: false,
897 }
898}
899
900fn peer_io_error(error: &std::io::Error) -> PeerError {
901 PeerError::Io(error.kind())
902}
903
904#[derive(Debug, Error)]
906#[non_exhaustive]
907pub enum PeerError {
908 #[error("standard Handshake wire failure: {0}")]
910 Wire(#[from] WireError),
911 #[error("standard Handshake peer I/O failed: {0:?}")]
913 Io(std::io::ErrorKind),
914 #[error("standard Handshake peer closed the connection")]
916 ConnectionClosed,
917 #[error("standard Handshake peer frame queue exceeded its bound")]
919 FrameQueueLimit,
920 #[error("invalid light-peer configuration")]
922 InvalidConfig,
923 #[error("invalid native peer connection timeout")]
925 InvalidConnectTimeout,
926 #[error("invalid local version packet")]
928 InvalidLocalVersion,
929 #[error("peer deadline overflow")]
931 TimeOverflow,
932 #[error("peer handshake timed out")]
934 HandshakeTimeout,
935 #[error("expected remote version packet")]
937 ExpectedVersion,
938 #[error("expected remote verack packet")]
940 ExpectedVerack,
941 #[error("remote Handshake protocol version is obsolete")]
943 ObsoleteVersion,
944 #[error("remote peer omitted a required service")]
946 MissingService,
947 #[error("remote peer omitted the standard bloom-filter service")]
949 MissingBloomService,
950 #[error("remote version nonce matches local nonce")]
952 SelfConnection,
953 #[error("remote version timestamp exceeds clock-skew policy")]
955 ClockSkew,
956 #[error("duplicate version or verack")]
958 DuplicateHandshake,
959 #[error("peer session is not ready")]
961 NotReady,
962 #[error("peer session is closed")]
964 Closed,
965 #[error("header locator is empty")]
967 EmptyLocator,
968 #[error("duplicate outstanding {0:?} request")]
970 DuplicateRequest(RequestKind),
971 #[error("{0:?} response arrived after its request deadline")]
973 RequestTimeout(RequestKind),
974 #[error("unsolicited headers packet")]
976 UnsolicitedHeaders,
977 #[error("unsolicited proof packet")]
979 UnsolicitedProof,
980 #[error("proof response does not match requested root and key")]
982 WrongProof,
983 #[error("unsolicited pong")]
985 UnsolicitedPong,
986 #[error("pong nonce mismatch")]
988 WrongPong,
989 #[error("ping nonce must be nonzero")]
991 ZeroPingNonce,
992 #[error("unsupported outbound wallet packet: {0:?}")]
994 UnsupportedWalletPacket(PacketType),
995 #[error("peer session internal invariant failed")]
997 InternalInvariant,
998 #[error("unexpected event during standard peer handshake")]
1000 UnexpectedHandshakeEvent,
1001}
1002
1003#[cfg(test)]
1004#[allow(
1005 clippy::unwrap_used,
1006 reason = "tests fail immediately on invalid local peer fixtures"
1007)]
1008mod tests {
1009 use std::collections::VecDeque;
1010 use std::io::{Read, Write};
1011 use std::net::{IpAddr, Ipv4Addr, SocketAddr, TcpListener};
1012 use std::thread;
1013
1014 use hns_p2p_wire::{InventoryKind, NetAddress, Packet};
1015
1016 use super::*;
1017
1018 #[derive(Debug)]
1019 struct ScriptedIo {
1020 inbound: VecDeque<u8>,
1021 outbound: Vec<u8>,
1022 read_chunk: usize,
1023 }
1024
1025 impl ScriptedIo {
1026 fn new(inbound: Vec<u8>, read_chunk: usize) -> Self {
1027 Self {
1028 inbound: inbound.into(),
1029 outbound: Vec::new(),
1030 read_chunk,
1031 }
1032 }
1033 }
1034
1035 impl Read for ScriptedIo {
1036 fn read(&mut self, output: &mut [u8]) -> std::io::Result<usize> {
1037 let length = output.len().min(self.read_chunk).min(self.inbound.len());
1038 for byte in output.iter_mut().take(length) {
1039 *byte = self.inbound.pop_front().unwrap();
1040 }
1041 Ok(length)
1042 }
1043 }
1044
1045 impl Write for ScriptedIo {
1046 fn write(&mut self, input: &[u8]) -> std::io::Result<usize> {
1047 self.outbound.extend_from_slice(input);
1048 Ok(input.len())
1049 }
1050
1051 fn flush(&mut self) -> std::io::Result<()> {
1052 Ok(())
1053 }
1054 }
1055
1056 fn version(nonce: [u8; 8], now: u64) -> VersionPacket {
1057 VersionPacket {
1058 version: hns_p2p_wire::PROTOCOL_VERSION,
1059 services: SERVICE_NETWORK,
1060 time: now,
1061 remote: NetAddress::from_socket_addr(
1062 SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 12_038),
1063 now,
1064 SERVICE_NETWORK,
1065 ),
1066 nonce,
1067 agent: "/hns-light-p2p:test/".to_owned(),
1068 height: 100,
1069 no_relay: true,
1070 }
1071 }
1072
1073 fn test_nonce(label: u64) -> [u8; 8] {
1078 label.to_le_bytes()
1079 }
1080
1081 fn ready(now: u64) -> PeerSession {
1082 let (mut session, local) = PeerSession::start(
1083 PeerConfig::for_network(NetworkMagic::Regtest),
1084 &version([1; 8], now),
1085 now,
1086 )
1087 .unwrap();
1088 assert!(matches!(local.decode_packet().unwrap(), Packet::Version(_)));
1089 let remote = Frame::from_packet(&Packet::Version(version([2; 8], now))).unwrap();
1090 assert!(matches!(
1091 session.handle_frame(&remote, now).unwrap(),
1092 PeerEvent::Send(_)
1093 ));
1094 let verack = Frame::from_packet(&Packet::Verack).unwrap();
1095 assert!(matches!(
1096 session.handle_frame(&verack, now).unwrap(),
1097 PeerEvent::Ready(_)
1098 ));
1099 session
1100 }
1101
1102 fn ready_wallet(now: u64) -> PeerSession {
1103 let mut local_version = version([3; 8], now);
1104 local_version.services = 0;
1105 let (mut session, _) = PeerSession::start(
1106 PeerConfig::for_wallet_network(NetworkMagic::Regtest),
1107 &local_version,
1108 now,
1109 )
1110 .unwrap();
1111 let mut remote_version = version([4; 8], now);
1112 remote_version.services |= SERVICE_BLOOM;
1113 let remote = Frame::from_packet(&Packet::Version(remote_version)).unwrap();
1114 assert!(matches!(
1115 session.handle_frame(&remote, now).unwrap(),
1116 PeerEvent::Send(_)
1117 ));
1118 let verack = Frame::from_packet(&Packet::Verack).unwrap();
1119 assert!(matches!(
1120 session.handle_frame(&verack, now).unwrap(),
1121 PeerEvent::Ready(_)
1122 ));
1123 session
1124 }
1125
1126 #[test]
1127 fn accepted_native_socket_completes_the_standard_handshake() {
1128 let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).unwrap();
1129 let address = listener.local_addr().unwrap();
1130 let now = 1_700_000_000;
1131 let server = thread::spawn(move || {
1132 let (stream, _) = listener.accept().unwrap();
1133 let mut connection = PeerConnection::accept(
1134 stream,
1135 PeerConfig::for_network(NetworkMagic::Regtest),
1136 &version([2; 8], now),
1137 now,
1138 )
1139 .unwrap();
1140 connection.complete_handshake(|| now).unwrap()
1141 });
1142
1143 let mut client = PeerConnection::connect(
1144 address,
1145 PeerConfig::for_network(NetworkMagic::Regtest),
1146 &version([1; 8], now),
1147 now,
1148 Duration::from_secs(1),
1149 )
1150 .unwrap();
1151 let client_metadata = client.complete_handshake(|| now).unwrap();
1152 let server_metadata = server.join().unwrap();
1153
1154 assert_eq!(client_metadata.services, SERVICE_NETWORK);
1155 assert_eq!(server_metadata.services, SERVICE_NETWORK);
1156 }
1157
1158 #[test]
1159 fn completes_standard_handshake_and_rejects_invalid_versions() {
1160 let now = 1_700_000_000;
1161 let session = ready(now);
1162 assert_eq!(session.state(), PeerState::Ready);
1163 assert_eq!(session.metadata().unwrap().height, 100);
1164
1165 let mut local_light_client = version([9; 8], now);
1166 local_light_client.services = 0;
1167 assert!(
1168 PeerSession::start(
1169 PeerConfig::for_network(NetworkMagic::Mainnet),
1170 &local_light_client,
1171 now
1172 )
1173 .is_ok()
1174 );
1175
1176 let (mut self_peer, _) = PeerSession::start(
1177 PeerConfig::for_network(NetworkMagic::Mainnet),
1178 &version([3; 8], now),
1179 now,
1180 )
1181 .unwrap();
1182 let frame = Frame::from_packet(&Packet::Version(version([3; 8], now))).unwrap();
1183 assert!(matches!(
1184 self_peer.handle_frame(&frame, now),
1185 Err(PeerError::SelfConnection)
1186 ));
1187
1188 let (mut missing_service, _) = PeerSession::start(
1189 PeerConfig::for_network(NetworkMagic::Mainnet),
1190 &version([4; 8], now),
1191 now,
1192 )
1193 .unwrap();
1194 let mut remote = version([5; 8], now);
1195 remote.services = 0;
1196 let frame = Frame::from_packet(&Packet::Version(remote)).unwrap();
1197 assert!(matches!(
1198 missing_service.handle_frame(&frame, now),
1199 Err(PeerError::MissingService)
1200 ));
1201 }
1202
1203 #[test]
1204 fn admits_hsd_verack_before_remote_version() {
1205 let now = 1_700_000_000;
1206 let (mut session, _) = PeerSession::start(
1207 PeerConfig::for_network(NetworkMagic::Mainnet),
1208 &version(test_nonce(6), now),
1209 now,
1210 )
1211 .unwrap();
1212 let verack = Frame::from_packet(&Packet::Verack).unwrap();
1213 assert_eq!(
1214 session.handle_frame(&verack, now).unwrap(),
1215 PeerEvent::Ignored(PacketType::Verack)
1216 );
1217 assert_eq!(session.state(), PeerState::AwaitingVersion);
1218
1219 let remote = Frame::from_packet(&Packet::Version(version(test_nonce(7), now))).unwrap();
1220 assert!(matches!(
1221 session.handle_frame(&remote, now).unwrap(),
1222 PeerEvent::Send(_)
1223 ));
1224 assert_eq!(session.state(), PeerState::Ready);
1225 assert_eq!(session.metadata().unwrap().height, 100);
1226 }
1227
1228 #[test]
1229 fn correlates_one_header_request_and_expires_duplicates() {
1230 let now = 1_700_000_000;
1231 let mut session = ready(now);
1232 let request = session
1233 .request_headers(vec![BlockHash::new([1; 32])], BlockHash::default(), now)
1234 .unwrap();
1235 assert!(matches!(
1236 request.decode_packet().unwrap(),
1237 Packet::GetHeaders(_)
1238 ));
1239 assert!(matches!(
1240 session.request_headers(vec![BlockHash::new([1; 32])], BlockHash::default(), now,),
1241 Err(PeerError::DuplicateRequest(RequestKind::Headers))
1242 ));
1243 let headers = Frame::from_packet(&Packet::Headers(Vec::new())).unwrap();
1244 assert_eq!(
1245 session.handle_frame(&headers, now).unwrap(),
1246 PeerEvent::Headers(Vec::new())
1247 );
1248 assert!(matches!(
1249 session.handle_frame(&headers, now),
1250 Err(PeerError::UnsolicitedHeaders)
1251 ));
1252
1253 session
1254 .request_headers(vec![BlockHash::new([2; 32])], BlockHash::default(), now)
1255 .unwrap();
1256 let expired = session
1257 .expire(now + DEFAULT_REQUEST_TIMEOUT_SECONDS + 1)
1258 .unwrap();
1259 assert!(expired.headers);
1260 assert!(matches!(
1261 session.handle_frame(&headers, now + DEFAULT_REQUEST_TIMEOUT_SECONDS + 1),
1262 Err(PeerError::UnsolicitedHeaders)
1263 ));
1264
1265 session
1266 .request_headers(vec![BlockHash::new([3; 32])], BlockHash::default(), now)
1267 .unwrap();
1268 assert!(matches!(
1269 session.handle_frame(&headers, now + DEFAULT_REQUEST_TIMEOUT_SECONDS + 1),
1270 Err(PeerError::RequestTimeout(RequestKind::Headers))
1271 ));
1272 assert!(matches!(
1273 session.handle_frame(&headers, now + DEFAULT_REQUEST_TIMEOUT_SECONDS + 1),
1274 Err(PeerError::UnsolicitedHeaders)
1275 ));
1276 }
1277
1278 #[test]
1279 fn serving_requests_preserve_locators_and_getaddr() {
1280 let now = 1_700_000_000;
1281 let mut session = ready(now);
1282 let request = LocatorPacket {
1283 locator: vec![BlockHash::new([9; 32])],
1284 stop: BlockHash::new([8; 32]),
1285 };
1286 let get_headers = Frame::from_packet(&Packet::GetHeaders(request.clone())).unwrap();
1287 assert_eq!(
1288 session.handle_frame(&get_headers, now).unwrap(),
1289 PeerEvent::GetHeaders(request.clone())
1290 );
1291 let get_blocks = Frame::from_packet(&Packet::GetBlocks(request.clone())).unwrap();
1292 assert_eq!(
1293 session.handle_frame(&get_blocks, now).unwrap(),
1294 PeerEvent::GetBlocks(request)
1295 );
1296 let get_addr = Frame::from_packet(&Packet::GetAddr).unwrap();
1297 assert_eq!(
1298 session.handle_frame(&get_addr, now).unwrap(),
1299 PeerEvent::GetAddresses
1300 );
1301 }
1302
1303 #[test]
1304 fn proof_root_key_and_ping_nonce_are_exactly_correlated() {
1305 let now = 1_700_000_000;
1306 let mut session = ready(now);
1307 let root = TreeRoot::new([7; 32]);
1308 let key = NameHash::new([8; 32]);
1309 session.request_proof(root, key, now).unwrap();
1310
1311 let mut payload = Vec::new();
1312 payload.extend_from_slice(root.as_bytes());
1313 payload.extend_from_slice(NameHash::new([9; 32]).as_bytes());
1314 payload.extend_from_slice(&[0, 0, 0, 0]);
1315 let wrong = Frame::new(PacketType::Proof, payload).unwrap();
1316 assert!(matches!(
1317 session.handle_frame(&wrong, now),
1318 Err(PeerError::WrongProof)
1319 ));
1320
1321 session.request_proof(root, key, now).unwrap();
1322 let mut payload = Vec::new();
1323 payload.extend_from_slice(root.as_bytes());
1324 payload.extend_from_slice(key.as_bytes());
1325 payload.extend_from_slice(&[0, 0, 0, 0]);
1326 let proof = Frame::new(PacketType::Proof, payload).unwrap();
1327 assert!(matches!(
1328 session.handle_frame(&proof, now).unwrap(),
1329 PeerEvent::Proof(_)
1330 ));
1331
1332 let request_frame = session.ping([4; 8], now).unwrap();
1333 assert!(matches!(
1334 request_frame.decode_packet().unwrap(),
1335 Packet::Ping(_)
1336 ));
1337 let wrong_pong = Frame::from_packet(&Packet::Pong([5; 8])).unwrap();
1338 assert!(matches!(
1339 session.handle_frame(&wrong_pong, now),
1340 Err(PeerError::WrongPong)
1341 ));
1342 let response_frame = Frame::from_packet(&Packet::Pong([4; 8])).unwrap();
1343 assert_eq!(
1344 session.handle_frame(&response_frame, now).unwrap(),
1345 PeerEvent::Pong([4; 8])
1346 );
1347 }
1348
1349 #[test]
1350 fn answers_ping_and_times_out_incomplete_handshake() {
1351 let now = 1_700_000_000;
1352 let mut session = ready(now);
1353 let inbound = Frame::from_packet(&Packet::Ping([6; 8])).unwrap();
1354 let outbound = match session.handle_frame(&inbound, now).unwrap() {
1355 PeerEvent::Send(frame) => Some(frame),
1356 _ => None,
1357 }
1358 .unwrap();
1359 assert_eq!(outbound.decode_packet().unwrap(), Packet::Pong([6; 8]));
1360
1361 let (mut incomplete, _) = PeerSession::start(
1362 PeerConfig::for_network(NetworkMagic::Regtest),
1363 &version([1; 8], now),
1364 now,
1365 )
1366 .unwrap();
1367 assert!(matches!(
1368 incomplete.expire(now + DEFAULT_HANDSHAKE_TIMEOUT_SECONDS + 1),
1369 Err(PeerError::HandshakeTimeout)
1370 ));
1371 assert_eq!(incomplete.state(), PeerState::Closed);
1372 }
1373
1374 #[test]
1375 fn admits_only_standard_wallet_flow_for_bloom_peers() {
1376 let now = 1_700_000_000;
1377 let mut session = ready_wallet(now);
1378 let filter = Packet::FilterLoad(vec![1, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
1379 assert_eq!(
1380 session
1381 .wallet_frame(&filter)
1382 .unwrap()
1383 .decode_packet()
1384 .unwrap(),
1385 filter
1386 );
1387 assert!(matches!(
1388 session.wallet_frame(&Packet::Ping([7; 8])),
1389 Err(PeerError::UnsupportedWalletPacket(PacketType::Ping))
1390 ));
1391
1392 let inventory = vec![Inventory {
1393 kind: InventoryKind::FilteredBlock,
1394 hash: [9; 32],
1395 }];
1396 let announced = Frame::from_packet(&Packet::Inv(inventory.clone())).unwrap();
1397 assert_eq!(
1398 session.handle_frame(&announced, now).unwrap(),
1399 PeerEvent::Wallet(WalletPeerEvent::Inventory(inventory))
1400 );
1401 let merkle = Frame::from_packet(&Packet::MerkleBlock(vec![8; 64])).unwrap();
1402 assert_eq!(
1403 session.handle_frame(&merkle, now).unwrap(),
1404 PeerEvent::Wallet(WalletPeerEvent::MerkleBlock(vec![8; 64]))
1405 );
1406
1407 let header_only = ready(now);
1408 assert!(matches!(
1409 header_only.wallet_frame(&Packet::FilterClear),
1410 Err(PeerError::MissingBloomService)
1411 ));
1412 }
1413
1414 #[test]
1415 fn preserves_bounded_unknown_packets_only_after_standard_handshake() {
1416 let now = 1_700_000_000;
1417 let mut session = ready(now);
1418 let experimental = Frame::from_packet(&Packet::Unknown {
1419 packet_type: 0xf4,
1420 payload: vec![1, 2, 3],
1421 })
1422 .unwrap();
1423 assert_eq!(
1424 session.handle_frame(&experimental, now).unwrap(),
1425 PeerEvent::Experimental {
1426 packet_type: 0xf4,
1427 payload: vec![1, 2, 3],
1428 }
1429 );
1430 }
1431
1432 #[test]
1433 fn experimental_send_requires_standard_handshake() {
1434 let now = 1_700_000_000;
1435 let (session, _) = PeerSession::start(
1436 PeerConfig::for_network(NetworkMagic::Regtest),
1437 &version([1; 8], now),
1438 now,
1439 )
1440 .unwrap();
1441 let mut connection = PeerConnection {
1442 transport: ScriptedIo::new(Vec::new(), 1),
1443 session,
1444 decoder: FrameDecoder::new(NetworkMagic::Regtest),
1445 pending: VecDeque::new(),
1446 };
1447 assert!(matches!(
1448 connection.send_experimental_packet(0xf4, vec![1]),
1449 Err(PeerError::NotReady)
1450 ));
1451 }
1452
1453 #[test]
1454 fn fragmented_stream_adapter_drives_handshake_headers_discovery_and_wallet_frames() {
1455 let now = 1_700_000_000;
1456 let remote_address = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 14_038);
1457 let mut remote_version = version([8; 8], now);
1458 remote_version.services |= SERVICE_BLOOM;
1459 let discovered = NetAddress::from_socket_addr(
1460 SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 2)), 14_038),
1461 now,
1462 SERVICE_NETWORK | SERVICE_BLOOM,
1463 );
1464 let inbound_packets = [
1465 Packet::Verack,
1466 Packet::Version(remote_version),
1467 Packet::Headers(Vec::new()),
1468 Packet::Addr(vec![discovered.clone()]),
1469 Packet::Ping([9; 8]),
1470 Packet::FeeFilter(2_000),
1471 ];
1472 let mut inbound = Vec::new();
1473 for packet in &inbound_packets {
1474 inbound.extend(
1475 Frame::from_packet(packet)
1476 .unwrap()
1477 .encode(NetworkMagic::Regtest)
1478 .unwrap(),
1479 );
1480 }
1481 let local_version = light_wallet_version(remote_address, [7; 8], 42, now);
1482 let mut connection = PeerConnection::start(
1483 ScriptedIo::new(inbound, 7),
1484 PeerConfig::for_wallet_network(NetworkMagic::Regtest),
1485 &local_version,
1486 now,
1487 )
1488 .unwrap();
1489 let metadata = connection.complete_handshake(|| now).unwrap();
1490 assert_eq!(metadata.height, 100);
1491 assert_eq!(connection.session().state(), PeerState::Ready);
1492
1493 connection
1494 .request_headers(vec![BlockHash::new([1; 32])], BlockHash::default(), now)
1495 .unwrap();
1496 assert_eq!(
1497 connection.receive_event(now).unwrap(),
1498 PeerEvent::Headers(Vec::new())
1499 );
1500 connection.request_addresses().unwrap();
1501 assert_eq!(
1502 connection.receive_event(now).unwrap(),
1503 PeerEvent::Addresses(vec![discovered])
1504 );
1505 connection
1506 .send_wallet_packet(&Packet::FilterLoad(vec![1, 0, 0, 0, 0, 0, 0, 0, 0, 0]))
1507 .unwrap();
1508 assert_eq!(
1509 connection.receive_event(now).unwrap(),
1510 PeerEvent::Wallet(WalletPeerEvent::FeeFilter(2_000))
1511 );
1512
1513 let io = connection.into_inner();
1514 let mut decoder = FrameDecoder::new(NetworkMagic::Regtest);
1515 let packets = decoder
1516 .push(&io.outbound)
1517 .unwrap()
1518 .into_iter()
1519 .map(|frame| frame.decode_packet().unwrap())
1520 .collect::<Vec<_>>();
1521 assert!(matches!(packets.first(), Some(Packet::Version(_))));
1522 assert_eq!(packets.get(1), Some(&Packet::Verack));
1523 assert!(matches!(packets.get(2), Some(Packet::GetHeaders(_))));
1524 assert_eq!(packets.get(3), Some(&Packet::GetAddr));
1525 assert!(matches!(packets.get(4), Some(Packet::FilterLoad(_))));
1526 assert_eq!(packets.get(5), Some(&Packet::Pong([9; 8])));
1527 }
1528}