Skip to main content

hns_light_p2p/
lib.rs

1//! Bounded standard Handshake P2P session for light clients.
2//!
3//! The state machine is runtime independent: socket adapters exchange
4//! `hns-p2p-wire` frames and provide an explicit clock. Only standard HSD
5//! version/verack, ping/pong, headers, name-proof, and wallet-filter traffic is
6//! admitted here. Chain and wallet evidence remains authoritative only after
7//! local verification. Experimental HIP sessions remain separate.
8
9#![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
32/// Default complete version/verack deadline.
33pub const DEFAULT_HANDSHAKE_TIMEOUT_SECONDS: u64 = 10;
34/// Default header/proof/ping response deadline.
35pub const DEFAULT_REQUEST_TIMEOUT_SECONDS: u64 = 15;
36/// Default maximum peer wall-clock skew.
37pub const DEFAULT_MAX_CLOCK_SKEW_SECONDS: u64 = 2 * 60 * 60;
38/// Bounded stack read used by the standard stream adapter.
39pub const PEER_READ_BUFFER_SIZE: usize = 8 * 1_024;
40/// Maximum decoded frames retained between caller polls.
41pub const MAX_PENDING_PEER_FRAMES: usize = 1_024;
42
43/// Standard-peer session bounds and admission.
44#[derive(Clone, Copy, Debug, Eq, PartialEq)]
45pub struct PeerConfig {
46    /// Selected Handshake wire network.
47    pub network: NetworkMagic,
48    /// Required standard service bits.
49    pub required_services: u64,
50    /// Complete handshake deadline.
51    pub handshake_timeout_seconds: u64,
52    /// Per-request deadline.
53    pub request_timeout_seconds: u64,
54    /// Maximum version timestamp skew.
55    pub max_clock_skew_seconds: u64,
56}
57
58impl PeerConfig {
59    /// Secure defaults for one network.
60    #[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    /// Secure defaults for a wallet peer that must support HSD bloom filters.
72    #[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/// Peer session phase.
98#[derive(Clone, Copy, Debug, Eq, PartialEq)]
99pub enum PeerState {
100    /// Local version sent; remote version required.
101    AwaitingVersion,
102    /// Remote version accepted and local verack sent.
103    AwaitingVerack,
104    /// Standard requests may be issued.
105    Ready,
106    /// Session is permanently closed.
107    Closed,
108}
109
110/// Admitted remote version metadata.
111#[derive(Clone, Debug, Eq, PartialEq)]
112pub struct PeerMetadata {
113    /// Negotiated HSD protocol version.
114    pub version: u32,
115    /// Advertised standard services.
116    pub services: u64,
117    /// Remote Unix timestamp.
118    pub time: u64,
119    /// Remote user agent.
120    pub agent: String,
121    /// Advertised best height.
122    pub height: u32,
123}
124
125/// Standard wallet traffic admitted after version/verack.
126///
127/// Every variant is still untrusted peer input. The wallet coordinator must
128/// correlate requested inventory and verify filtered blocks and transactions
129/// against its locally validated header chain before changing wallet state.
130#[derive(Clone, Debug, Eq, PartialEq)]
131pub enum WalletPeerEvent {
132    /// Newly announced transaction or block inventory.
133    Inventory(Vec<Inventory>),
134    /// The peer requested data previously announced by this wallet.
135    DataRequest(Vec<Inventory>),
136    /// Requested inventory that the peer could not provide.
137    NotFound(Vec<Inventory>),
138    /// Untrusted transaction bytes decoded by the shared canonical codec.
139    Transaction(Transaction),
140    /// Raw HSD MerkleBlock payload awaiting local partial-tree verification.
141    MerkleBlock(Vec<u8>),
142    /// Remote minimum transaction fee rate.
143    FeeFilter(i64),
144}
145
146/// Response-bearing request category.
147#[repr(u8)]
148#[derive(Clone, Copy, Debug, Eq, PartialEq)]
149pub enum RequestKind {
150    /// Standard `getheaders`.
151    Headers = 0,
152    /// Standard `getproof`.
153    Proof = 1,
154    /// Standard ping.
155    Ping = 2,
156}
157
158/// Requests that exceeded their explicit deadline.
159#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
160pub struct ExpiredRequests {
161    /// Header request expired.
162    pub headers: bool,
163    /// Name-proof request expired.
164    pub proof: bool,
165    /// Ping expired.
166    pub ping: bool,
167}
168
169impl ExpiredRequests {
170    /// Whether at least one request expired.
171    #[must_use]
172    pub const fn any(self) -> bool {
173        self.headers || self.proof || self.ping
174    }
175}
176
177/// Event emitted by one admitted inbound frame.
178#[derive(Clone, Debug, Eq, PartialEq)]
179pub enum PeerEvent {
180    /// Send this standard frame to the peer.
181    Send(Frame),
182    /// Version/verack completed.
183    Ready(PeerMetadata),
184    /// Correlated bounded header batch.
185    Headers(Vec<Header>),
186    /// Correlated exact-root/key Urkel proof.
187    Proof(ProofPacket),
188    /// Bounded standard peer addresses supplied for discovery.
189    Addresses(Vec<NetAddress>),
190    /// The remote peer requested bounded address gossip from a serving
191    /// connection. The transport does not invent a response; its owner must
192    /// supply addresses from its own validated, privacy-bounded host list.
193    GetAddresses,
194    /// The remote peer requested canonical block inventory after one locator.
195    /// Serving peers retain the complete request so locally verified chain
196    /// storage can select the response without reparsing untrusted bytes.
197    GetBlocks(LocatorPacket),
198    /// The remote peer requested canonical headers after one locator.
199    /// Serving peers retain the complete request so locally verified chain
200    /// storage can construct a standard bounded `headers` response.
201    GetHeaders(LocatorPacket),
202    /// Matching pong arrived.
203    Pong([u8; 8]),
204    /// Peer rejected a request.
205    Rejected(RejectPacket),
206    /// Standard wallet traffic awaiting correlation and local verification.
207    Wallet(WalletPeerEvent),
208    /// One bounded unknown packet preserved for an explicitly opted-in
209    /// experimental protocol. The standard session neither interprets nor
210    /// authorizes this payload; its consumer owns registry negotiation,
211    /// correlation, and all protocol-specific validation.
212    Experimental {
213        /// The unassigned standard packet type that carried `payload`.
214        packet_type: u8,
215        /// Bounded raw packet bytes, already framed for the selected network.
216        payload: Vec<u8>,
217    },
218    /// Ordinary packet was safely outside the light-client flow.
219    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/// One bounded standard HSD peer session.
241#[derive(Clone, Debug)]
242pub struct PeerSession {
243    config: PeerConfig,
244    state: PeerState,
245    local_nonce: [u8; 8],
246    handshake_deadline: u64,
247    // HSD may acknowledge our version before it transmits its own version.
248    // Remember that early acknowledgement so receiving the remote version can
249    // complete the handshake immediately after we send our verack.
250    peer_verack_received: bool,
251    // `PeerEvent::Send` is intentionally also used for ready-state ping/pong
252    // traffic. This flag lets the stream adapter emit the one `Ready` event
253    // that follows an early-verack handshake response without mistaking a
254    // later pong for a second handshake completion.
255    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/// One standard peer session bound to a blocking byte stream.
263///
264/// The stream may be a native [`TcpStream`] or a deterministic test/host
265/// adapter. All bytes pass through the bounded shared frame decoder and the
266/// same [`PeerSession`] correlation rules before being exposed as events.
267#[derive(Debug)]
268pub struct PeerConnection<T> {
269    transport: T,
270    session: PeerSession,
271    decoder: FrameDecoder,
272    pending: VecDeque<Frame>,
273}
274
275impl PeerSession {
276    /// Start a session and return the local version frame.
277    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    /// Selected wire network for the adapter's frame decoder.
311    #[must_use]
312    pub const fn network(&self) -> NetworkMagic {
313        self.config.network
314    }
315
316    /// Current session phase.
317    #[must_use]
318    pub const fn state(&self) -> PeerState {
319        self.state
320    }
321
322    /// Admitted remote metadata after version.
323    #[must_use]
324    pub const fn metadata(&self) -> Option<&PeerMetadata> {
325        self.metadata.as_ref()
326    }
327
328    /// Close permanently and revoke all outstanding requests.
329    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    /// Admit one strict frame from the selected-network decoder.
337    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            // Several current HSD peers legally emit their verack as soon as
348            // they receive the local version, before their own version frame.
349            // Preserve the acknowledgement and continue waiting for the
350            // remote version rather than rejecting an otherwise standard peer.
351            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    /// Build one bounded `getheaders`; only one may be outstanding.
371    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    /// Build one exact-root/key standard name-proof request.
391    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    /// Build one standard wallet packet after the peer has advertised bloom
412    /// support and completed version/verack.
413    ///
414    /// This deliberately admits only the client side of HSD's BIP37 flow and
415    /// direct transaction propagation. Callers should construct filter
416    /// payloads with the strict wallet codec rather than passing arbitrary
417    /// bytes from an external source.
418    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    /// Build a standard peer-discovery request after version/verack.
443    pub fn address_request(&self) -> Result<Frame, PeerError> {
444        self.require_ready()?;
445        Ok(Frame::from_packet(&Packet::GetAddr)?)
446    }
447
448    /// Build one ping; only one may be outstanding.
449    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    /// Expire all overdue work and return name-free timeout flags.
464    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    /// Start a standard session and immediately write the local version frame.
623    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    /// Immutable admitted session state.
642    #[must_use]
643    pub const fn session(&self) -> &PeerSession {
644        &self.session
645    }
646
647    /// Mutable admitted session state for explicit request construction.
648    #[must_use]
649    pub const fn session_mut(&mut self) -> &mut PeerSession {
650        &mut self.session
651    }
652
653    /// Underlying host stream.
654    #[must_use]
655    pub const fn transport(&self) -> &T {
656        &self.transport
657    }
658
659    /// Mutable underlying host stream.
660    #[must_use]
661    pub const fn transport_mut(&mut self) -> &mut T {
662        &mut self.transport
663    }
664
665    /// Consume the peer and return its host stream.
666    pub fn into_inner(self) -> T {
667        self.transport
668    }
669
670    /// Complete version/verack while sampling the caller's monotonic Unix
671    /// clock before every admitted frame.
672    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    /// Write one already-admitted frame completely.
704    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    /// Send one same-locator header request and arm exact response correlation.
715    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    /// Send one exact-root/key name proof request.
726    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    /// Send one admitted BIP37, inventory, mempool, or transaction packet.
737    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    /// Send one explicitly selected experimental packet after the standard
743    /// handshake. This does not negotiate or authorize a subprotocol; callers
744    /// must do both before treating any response as useful.
745    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    /// Request bounded standard peer addresses.
756    pub fn request_addresses(&mut self) -> Result<(), PeerError> {
757        let frame = self.session.address_request()?;
758        self.send_frame(&frame)
759    }
760
761    /// Send one correlated liveness ping.
762    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    /// Read and admit the next non-automatic peer event. Ping responses and
768    /// the local verack are written internally before this method returns.
769    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    /// Revoke requests and close the logical session without assuming that a
785    /// host adapter has a transport-level shutdown primitive.
786    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    /// Connect a native socket, install bounded I/O timeouts, and send the
819    /// standard local version frame.
820    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    /// Bind an already accepted native socket to a bounded standard HSD
838    /// session and immediately advertise the local version frame.
839    ///
840    /// This is deliberately only the socket/session adapter. Callers own
841    /// listener lifecycle, admission policy, and every protocol service above
842    /// the standard version/verack exchange.
843    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    /// Close both directions of the native socket and revoke session state.
855    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/// Construct the standard version packet for a non-serving light wallet.
881#[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/// Standard peer handshake, correlation, or deadline failure.
905#[derive(Debug, Error)]
906#[non_exhaustive]
907pub enum PeerError {
908    /// Canonical shared wire codec failed.
909    #[error("standard Handshake wire failure: {0}")]
910    Wire(#[from] WireError),
911    /// Host stream read, write, flush, or connection failed.
912    #[error("standard Handshake peer I/O failed: {0:?}")]
913    Io(std::io::ErrorKind),
914    /// The host stream ended before the session completed.
915    #[error("standard Handshake peer closed the connection")]
916    ConnectionClosed,
917    /// One host read decoded more queued frames than the bounded adapter admits.
918    #[error("standard Handshake peer frame queue exceeded its bound")]
919    FrameQueueLimit,
920    /// Session configuration is zero, excessive, or omits NETWORK service.
921    #[error("invalid light-peer configuration")]
922    InvalidConfig,
923    /// Native connection timeout is zero or exceeds the five-minute bound.
924    #[error("invalid native peer connection timeout")]
925    InvalidConnectTimeout,
926    /// Local version has a zero nonce, obsolete version, or implausible timestamp.
927    #[error("invalid local version packet")]
928    InvalidLocalVersion,
929    /// Clock/deadline arithmetic overflowed.
930    #[error("peer deadline overflow")]
931    TimeOverflow,
932    /// Version/verack did not complete by its deadline.
933    #[error("peer handshake timed out")]
934    HandshakeTimeout,
935    /// Version was required before this packet.
936    #[error("expected remote version packet")]
937    ExpectedVersion,
938    /// Verack was required after remote version.
939    #[error("expected remote verack packet")]
940    ExpectedVerack,
941    /// Remote protocol version is obsolete.
942    #[error("remote Handshake protocol version is obsolete")]
943    ObsoleteVersion,
944    /// Remote omitted a required standard service.
945    #[error("remote peer omitted a required service")]
946    MissingService,
947    /// Wallet traffic requires a peer that advertised standard bloom service.
948    #[error("remote peer omitted the standard bloom-filter service")]
949    MissingBloomService,
950    /// Remote nonce identifies a self-connection.
951    #[error("remote version nonce matches local nonce")]
952    SelfConnection,
953    /// Remote version timestamp exceeds configured skew.
954    #[error("remote version timestamp exceeds clock-skew policy")]
955    ClockSkew,
956    /// Handshake packet repeated after readiness.
957    #[error("duplicate version or verack")]
958    DuplicateHandshake,
959    /// Request was attempted before version/verack.
960    #[error("peer session is not ready")]
961    NotReady,
962    /// Session has been closed.
963    #[error("peer session is closed")]
964    Closed,
965    /// Block locator cannot be empty.
966    #[error("header locator is empty")]
967    EmptyLocator,
968    /// A response-bearing request of this kind is already outstanding.
969    #[error("duplicate outstanding {0:?} request")]
970    DuplicateRequest(RequestKind),
971    /// A response arrived after its exact request deadline.
972    #[error("{0:?} response arrived after its request deadline")]
973    RequestTimeout(RequestKind),
974    /// Peer sent headers without an outstanding request.
975    #[error("unsolicited headers packet")]
976    UnsolicitedHeaders,
977    /// Peer sent proof without an outstanding request.
978    #[error("unsolicited proof packet")]
979    UnsolicitedProof,
980    /// Proof root or name key differs from the exact request.
981    #[error("proof response does not match requested root and key")]
982    WrongProof,
983    /// Peer sent pong without an outstanding ping.
984    #[error("unsolicited pong")]
985    UnsolicitedPong,
986    /// Pong nonce differs from the outstanding ping.
987    #[error("pong nonce mismatch")]
988    WrongPong,
989    /// Zero ping nonce is not admitted.
990    #[error("ping nonce must be nonzero")]
991    ZeroPingNonce,
992    /// Packet is not part of the admitted client-side wallet flow.
993    #[error("unsupported outbound wallet packet: {0:?}")]
994    UnsupportedWalletPacket(PacketType),
995    /// Internal handshake metadata invariant failed.
996    #[error("peer session internal invariant failed")]
997    InternalInvariant,
998    /// A response-bearing event appeared while version/verack was incomplete.
999    #[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    // Keep protocol nonces generated in tests too: fixed nonce literals are
1074    // indistinguishable from production cryptographic material to static
1075    // analysis, while this helper still gives each assertion a reproducible,
1076    // nonzero identity.
1077    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}