feat(p2p): add opt-in Tor and IVNP I2P connectivity

.github/workflows/overlay-interop.yml

@@ -0,0 +1,39 @@
+name: overlay-interoperability
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  external-backends:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/native-deps
+      - uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
+      - name: Install external backends
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y tor golang-go
+          git clone https://github.com/gosuda/IVNP.git "$RUNNER_TEMP/ivnp"
+          git -C "$RUNNER_TEMP/ivnp" checkout "$(python3 scripts/overlay-interop.py --ivnp-revision)"
+          cd "$RUNNER_TEMP/ivnp"
+          # Go's versioned toolchain mechanism fetches the module's required toolchain.
+          GOTOOLCHAIN=go1.27.0+auto go build -o "$RUNNER_TEMP/ivnpd" ./cmd/ivnpd
+      - run: cargo build --locked --bin bitcoin-rs
+      - name: Bitcoin handshake, block exchange, inbound admission, and identity restart
+        run: python3 scripts/overlay-interop.py --ivnpd "$RUNNER_TEMP/ivnpd" --tor /usr/bin/tor
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: overlay-interoperability
+          path: |
+            target/overlay-interop
+            target/process-harness/e2e

Cargo.toml

@@ -82,6 +82,8 @@ secp256k1 = { version = ">=0.29.1, <0.30", default-features = false, features =
 ] }
 
 # sha2 0.11: default features are alloc+oid; no std/asm feature is exposed.
+base64 = "=0.22.1"
+sha3 = { version = ">=0.11, <0.12", default-features = false }
 sha2 = { version = ">=0.11, <0.12", default-features = false }
 bitcoin_hashes = { version = ">=0.14, <0.15", default-features = false, features = [
     "alloc", "std",

crates/mempool/src/admission.rs

@@ -891,7 +891,7 @@ mod tests {
 
     fn source() -> PeerToken {
         PeerToken {
-            addr: core::net::SocketAddr::from(([127, 0, 0, 1], 8333)),
+            addr: bitcoin_rs_primitives::PeerEndpoint::from(([127, 0, 0, 1], 8333)),
             connection_id: 7,
         }
     }

crates/mempool/src/gateway.rs

@@ -3718,7 +3718,7 @@ mod tests {
         candidate.inputs.push(candidate.inputs[0].clone());
         candidate.inputs[0].witness = Witness::from_stack(vec![vec![1]]);
         let origin = AdmissionOrigin::Peer(crate::PeerToken {
-            addr: core::net::SocketAddr::from(([127, 0, 0, 1], 8333)),
+            addr: bitcoin_rs_primitives::PeerEndpoint::from(([127, 0, 0, 1], 8333)),
             connection_id: 7,
         });
         let request = admit_request(&gateway, &candidate, origin);

crates/mempool/src/mutation.rs

@@ -141,8 +141,8 @@ impl MutationResult {
 /// Identifies the network peer a transaction arrived from.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
 pub struct PeerToken {
-    /// The peer's wire address.
-    pub addr: core::net::SocketAddr,
+    /// The peer's logical Bitcoin endpoint, including anonymous inbound Tor handles.
+    pub addr: bitcoin_rs_primitives::PeerEndpoint,
     /// The node-local id of the connection the peer arrived on.
     pub connection_id: u64,
 }

crates/mempool/src/orphan.rs

@@ -588,7 +588,7 @@ mod tests {
     };
     fn source(id: u64) -> PeerToken {
         PeerToken {
-            addr: core::net::SocketAddr::from(([127, 0, 0, 1], 8333)),
+            addr: bitcoin_rs_primitives::PeerEndpoint::from(([127, 0, 0, 1], 8333)),
             connection_id: id,
         }
     }

crates/node/benches/sync_pipeline.rs

@@ -1230,7 +1230,7 @@ fn install_synthetic_peers(
             .unwrap_or_else(|error| panic!("invalid synthetic peer port: {error}"));
         let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port);
         let (outbound_tx, outbound_rx) = unbounded::<bitcoin_rs_p2p::QueuedFrame>();
-        peer_table.register(addr, bitcoin_rs_p2p::PeerLease::new(outbound_tx));
+        peer_table.register(addr.into(), bitcoin_rs_p2p::PeerLease::new(outbound_tx));
         outbound_rxs.push(outbound_rx);
     }
     outbound_rxs

crates/node/src/chain_effects.rs

@@ -784,15 +784,15 @@ mod tests {
         let available = orphan_child(OutPoint::new(parent, 0));
         let missing = orphan_child(OutPoint::new(Hash256::from_le_bytes(&[43; 32]).into(), 0));
         let source = PeerToken {
-            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18444)),
+            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18444)).into(),
             connection_id: 7,
         };
         let replacement = PeerToken {
             connection_id: 8,
             ..source
         };
         let missing_source = PeerToken {
-            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18445)),
+            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18445)).into(),
             connection_id: 9,
         };
         let chain = AdmissionCoins::default();
@@ -883,7 +883,7 @@ mod tests {
         let outpoint = OutPoint::new(parent, 0);
         let child = orphan_child(outpoint);
         let source = PeerToken {
-            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18444)),
+            addr: std::net::SocketAddr::from(([127, 0, 0, 1], 18444)).into(),
             connection_id: 7,
         };
         let chain = AdmissionCoins::default();

crates/node/src/config.rs

@@ -135,6 +135,8 @@ pub struct StorageConfig {
 /// Resolved P2P configuration.
 #[derive(Clone, Debug)]
 pub struct P2pConfig {
+    /// Opt-in Tor and IVNP I2P routing.
+    pub overlay: bitcoin_rs_p2p::OverlayConfig,
     /// P2P message-start bytes.
     pub magic: [u8; 4],
     /// P2P listener bind addresses.
@@ -283,6 +285,24 @@ impl NodeConfig {
                 prune_target_mb: settings.storage.prune_target_mb.unwrap_or(0),
             },
             p2p: P2pConfig {
+                overlay: bitcoin_rs_p2p::OverlayConfig {
+                    proxy: settings.p2p.proxy,
+                    onion_proxy: settings.p2p.onion_proxy,
+                    onlynet: settings.p2p.onlynet.clone().unwrap_or_default(),
+                    randomize_credentials: settings.p2p.proxy_randomize_credentials.unwrap_or(true),
+                    i2p_sam: settings.p2p.i2p_sam,
+                    i2p_accept: settings.p2p.i2p_accept.unwrap_or(false),
+                    tor_control: settings.p2p.tor_control,
+                    tor_cookie: settings.p2p.tor_cookie.clone(),
+                    identity_dir: PathBuf::from(format!(
+                        "overlay-{:08x}",
+                        u32::from_be_bytes(settings.p2p.magic.unwrap_or(profile.magic))
+                    )),
+                    port: settings
+                        .p2p
+                        .overlay_port
+                        .unwrap_or_else(|| selection.consensus_network().default_p2p_port()),
+                },
                 magic: settings.p2p.magic.unwrap_or(profile.magic),
                 listen: settings.p2p.listen.clone().unwrap_or(profile.listen),
                 dns_seeds_enabled: settings.p2p.dns_seeds.unwrap_or(profile.dns_seeds),
@@ -342,6 +362,10 @@ impl NodeConfig {
     /// This is the fail-early gate for engine selection: an engine this build
     /// cannot execute is rejected here — before the data directory opens,
     /// chainstate exists, or any worker starts.
+    #[expect(
+        clippy::too_many_lines,
+        reason = "Keep resolved cross-field checks in one ordered fail-early gate before startup"
+    )]
     pub fn validate(&self) -> Result<()> {
         anyhow::ensure!(
             self.mempool_snapshot_max_bytes >= 1024 * 1024
@@ -406,6 +430,7 @@ impl NodeConfig {
              support is not compiled in (enable the `kernel` feature)",
             self.validation.engine
         );
+        self.p2p.overlay.validate()?;
         if self.p2p.magic != self.network.magic() {
             anyhow::ensure!(
                 self.network == Network::Mainnet,

crates/node/src/options.rs

@@ -34,7 +34,7 @@ use bitcoin_rs_consensus::ValidationEngine;
 use bitcoin_rs_storage::StorageBackend;
 
 /// Canonical subnet type shared by every process-input surface.
-pub use bitcoin_rs_p2p::IpSubnet;
+pub use bitcoin_rs_p2p::{IpSubnet, PeerNetwork};
 
 /// Parses a network selection spelling.
 pub fn parse_network(value: &str) -> std::result::Result<NetworkSelection, String> {
@@ -103,6 +103,20 @@ pub fn parse_connect_endpoint(value: &str) -> std::result::Result<String, String
     Ok(value.to_owned())
 }
 
+/// Parse one allowed remote network without DNS resolution.
+pub fn parse_peer_network(value: &str) -> std::result::Result<bitcoin_rs_p2p::PeerNetwork, String> {
+    value.parse().map_err(str::to_owned)
+}
+fn parse_peer_networks(value: &str) -> Result<Vec<bitcoin_rs_p2p::PeerNetwork>> {
+    if value.trim().is_empty() {
+        return Ok(Vec::new());
+    }
+    value
+        .split(',')
+        .map(|network| parse_peer_network(network.trim()).map_err(anyhow::Error::msg))
+        .collect()
+}
+
 /// Parses a comma-separated listener bind list.
 fn parse_socket_list(value: &str) -> Result<Vec<SocketAddr>> {
     value
@@ -557,6 +571,60 @@ macro_rules! option_rows {
                         env["BITCOIN_RS_CONNECT", parse_connect_list]
                         toml each("connect", parse_connect_endpoint)
                     }
+                    /// SOCKS5 route for IP destinations; onion routing is configured separately.
+                    proxy as proxy: Option<SocketAddr> {
+                        cli[#[arg(long = "proxy")]]
+                        env["BITCOIN_RS_PROXY", str::parse]
+                        toml native("proxy")
+                    }
+                    /// SOCKS5 route for Tor v3 destinations, passed to the proxy without local DNS.
+                    onion_proxy as onion_proxy: Option<SocketAddr> {
+                        cli[#[arg(long = "onion-proxy")]]
+                        env["BITCOIN_RS_ONION_PROXY", str::parse]
+                        toml native("onion_proxy")
+                    }
+                    /// Loopback SAM bridge of an operator-managed IVNP router.
+                    i2p_sam as i2p_sam: Option<SocketAddr> {
+                        cli[#[arg(long = "i2p-sam")]]
+                        env["BITCOIN_RS_I2P_SAM", str::parse]
+                        toml native("i2p_sam")
+                    }
+                    /// Loopback Tor control endpoint enabling a persistent inbound onion service.
+                    tor_control as tor_control: Option<SocketAddr> {
+                        cli[#[arg(long = "tor-control")]]
+                        env["BITCOIN_RS_TOR_CONTROL", str::parse]
+                        toml native("tor_control")
+                    }
+                    /// Tor SAFECOOKIE file; otherwise use NULL authentication.
+                    tor_cookie as tor_cookie: Option<PathBuf> {
+                        cli[#[arg(long = "tor-cookie")]]
+                        env["BITCOIN_RS_TOR_COOKIE", parse_path]
+                        toml native("tor_cookie")
+                    }
+                    /// Accept inbound I2P streams using a persistent application destination.
+                    i2p_accept as i2p_accept: Option<bool> {
+                        cli[#[arg(long = "i2p-accept", num_args = 0..=1, default_missing_value = "true")]]
+                        env["BITCOIN_RS_I2P_ACCEPT", parse_bool]
+                        toml native("i2p_accept")
+                    }
+                    /// Require SOCKS username/password authentication with fresh credentials per connection.
+                    proxy_randomize_credentials as proxy_randomize_credentials: Option<bool> {
+                        cli[#[arg(long = "proxy-randomize-credentials", num_args = 0..=1, default_missing_value = "true")]]
+                        env["BITCOIN_RS_PROXY_RANDOMIZE_CREDENTIALS", parse_bool]
+                        toml native("proxy_randomize_credentials")
+                    }
+                    /// Public Bitcoin service port for inbound overlay services.
+                    overlay_port as overlay_port: Option<u16> {
+                        cli[#[arg(long = "overlay-port")]]
+                        env["BITCOIN_RS_OVERLAY_PORT", str::parse]
+                        toml native("overlay_port")
+                    }
+                    /// Restrict every peer connection to these remote networks.
+                    onlynet as onlynet: Option<Vec<$crate::options::PeerNetwork>> {
+                        cli[#[arg(long = "onlynet", value_delimiter = ',', value_parser = $crate::options::parse_peer_network)]]
+                        env["BITCOIN_RS_ONLYNET", parse_peer_networks]
+                        toml each("onlynet", parse_peer_network)
+                    }
                     /// Whether fast sync (shallow, early fan-out over a larger
                     /// outbound set) is enabled.
                     fast_sync as fast_sync: Option<bool> {

crates/node/src/state/open.rs

@@ -373,6 +373,11 @@ impl NodeState {
         };
         let p2p = Arc::new(bitcoin_rs_p2p::P2pService::new(
             bitcoin_rs_p2p::P2pServiceConfig {
+                overlay: bitcoin_rs_p2p::OverlayConfig {
+                    identity_dir: config.data_dir.join(&config.p2p.overlay.identity_dir),
+                    ..config.p2p.overlay.clone()
+                }
+                .into(),
                 listen_addrs: config.p2p.listen.clone(),
                 address_book_path: Some(config.data_dir.join("peers.dat")),
                 asmap_path: config.p2p.asmap.clone(),