1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
//! # dig-pex — Peer Exchange (PEX) for the DIG Node peer network
//!
//! PEX lets a participant that already holds an **authenticated** link to another participant tell
//! it, incrementally, which peers it knows **first-hand** — so the network's address books stay warm
//! without polling and without a central directory. It adapts the proven mechanics of BitTorrent PEX
//! (`ut_pex`): peers exchange **deltas of their first-hand known-peer set** over already-established
//! connections, on a bounded periodic cadence, with hard per-message caps and **no third-party
//! re-flooding**. This crate is the normative implementation of `SPEC.md` (wire version `1`).
//!
//! PEX runs in exactly two places (SPEC §1.1):
//!
//! 1. **Node ↔ Node** — over the mutual-TLS dig-nat mux stream transport ([`PexMessage::encode`] /
//! [`PexMessage::decode`], a u32-BE length prefix + JSON body).
//! 2. **Relay → Node** — by the `dig-relay` introducer, riding the existing `RelayMessage`
//! WebSocket (RLY-008) as bare JSON text frames ([`PexMessage::to_json`] /
//! [`PexMessage::from_json`]).
//!
//! ## What it is *not* (SPEC §1.3)
//!
//! - **Not a trust channel.** Every received entry is a *hint* — a candidate to dial and verify via
//! the mTLS handshake, never an authenticated fact ([`PexEvent::Candidates`]).
//! - **Not a gossip flood.** A participant advertises only what it knows **first-hand**; the
//! [`Provenance`] type has no `"pex"` token, so a PEX-learned entry can never be re-advertised
//! until independently verified.
//! - **Not a payment authority.** An entry MAY carry a self-signed payment address
//! ([`PeerEntry::verified_payment_address`], SPEC §3.4) so the incentive layer can pay the peer
//! that earned it. The claim proves itself — it carries the peer's TLS SPKI and a signature this
//! crate binds to `peer_id` — but PEX neither holds keys nor moves money.
//! - **Not content discovery.** Locating which peers hold content is the DHT's job (`dig-dht`); PEX
//! populates the pool of dialable peers underneath it.
//!
//! ## The engine (SPEC Appendix A)
//!
//! The crate ships a transport-agnostic, **sans-IO** [`PexEngine`]: you feed it link events, inbound
//! messages, local peer-set changes, and clock ticks; it returns the messages to send and the events
//! to act on. Both a DIG Node and the relay embed the same engine — only the I/O adapter differs.
//!
//! ```
//! use dig_pex::{PexConfig, PexEngine, PexMessage, PeerEntry, Provenance, Address};
//!
//! let me = "a".repeat(64);
//! let peer = "b".repeat(64);
//! let mut engine = PexEngine::new(PexConfig::new(me, "mainnet").with_jitter(false));
//!
//! // A first-hand peer we know enters our advertise set.
//! engine.upsert_known(
//! PeerEntry::new("c".repeat(64), "mainnet", 1_000, Provenance::Direct)
//! .with_address(Address::direct("203.0.113.7", 9444)),
//! );
//!
//! // A link comes up → we emit our handshake + a snapshot of our first-hand set.
//! let out = engine.link_up(&peer, 1_000_000);
//! assert!(matches!(out[0], PexMessage::PexHandshake { .. }));
//! assert!(matches!(out[1], PexMessage::PexSnapshot { .. }));
//! ```
//!
//! ### DIG Node embedding (node↔node, SPEC §10.1)
//!
//! On each established peer connection call [`PexEngine::link_up`] and write the returned frames on a
//! freshly opened mux stream (that stream is your sending direction). Feed each decoded inbound
//! message to [`PexEngine::on_message`]; send its replies and honor a muting
//! [`PexEvent::Violation`]. Drive [`PexEngine::tick`] ~1/s and write the returned deltas. Feed
//! first-hand knowledge back with [`PexEngine::upsert_known`] / [`PexEngine::remove_known`], and on
//! close call [`PexEngine::link_down`]. Route [`PexEvent::Candidates`] into the dig-gossip
//! `AddressManager` as new-table candidates to dial + verify (SPEC §9.3).
//!
//! ### dig-relay embedding (relay→node, SPEC §10.2)
//!
//! Create one engine for the introducer role (flags `["introducer"]`). Only after a registered
//! connection sends its `pex_handshake` do you [`PexEngine::link_up`] + [`PexEngine::on_message`] and
//! reply as WebSocket text frames. Mirror the registry into the engine
//! ([`PexEngine::upsert_known`] on register, [`PexEngine::remove_known`] on unregister); **never**
//! fold inbound node PEX data into the registry — discard node-sent [`PexEvent::Candidates`] (the
//! registry is registration-backed only, SPEC §10.2).
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use PexMessage;