[Backport release-mainnet-1.2.0-rc] fix(libp2p): add network discriminators (#4443)

fix(libp2p): add network discriminators (#4418)

* test(libp2p): snapshot mainnet protocol identifiers

- Extract three helpers in `network/node.rs` returning the libp2p
  protocol identifiers used today (gossipsub prefix `None` = libp2p
  default, kademlia `/ipfs/kad/1.0.0`, direct message
  `/HotShot/direct_message/1.0`).
- Wire the helpers into the swarm builder so they are the single source
  of truth.
- Add an `insta` snapshot test that locks in the values. A future change
  that would silently shift these strings (and partition mainnet from
  itself) now fails the snapshot.

* feat(libp2p): partition non-mainnet networks via chain-id discriminator

- Add `network_discriminator: Option<String>` to `NetworkNodeConfig`.
  `None` keeps mainnet's libp2p protocol strings byte-identical to
  today; `Some(d)` appends `/{d}` to gossipsub's `protocol_id_prefix`,
  the kademlia `StreamProtocol`, and the request-response direct
  message `StreamProtocol`. Identify's `protocol_version` is left
  untouched since it does not gate substream negotiation.
- Plumb the discriminator through `Libp2pNetwork::from_config`.
- At the espresso-node call site, derive the discriminator from
  `genesis.chain_config.chain_id`: `None` when chain_id is 1
  (mainnet), else `Some(chain_id.to_string())`. Decaf and other
  non-mainnet networks now run on distinct libp2p protocols and
  cannot merge with mainnet at the gossipsub or kademlia layers.
- The snapshot test added in the previous commit confirms the
  mainnet path is unchanged.

* doc(libp2p): tighten network_discriminator field comment

* test(libp2p): snapshot decaf protocol identifiers

- Extract three `gossipsub_prefix` / `kad_protocol` /
  `direct_message_protocol` wrappers that take an optional
  discriminator and call the existing mainnet helpers when `None`.
- Replace the inline match arms in `NetworkNode::new` with calls to
  these wrappers so production code and tests share a single path.
- Add a decaf snapshot test alongside the mainnet one, both routed
  through a shared `snapshot_for(discriminator)` helper. Decaf's
  chain_id (`0xdecaf` = 912559) produces protocol IDs like
  `/ipfs/kad/1.0.0/912559`.

* refactor(libp2p): type network_discriminator as Option<U256>

- Discriminator is always a chain id; use `U256` rather than `String`
  at the libp2p-networking boundary.
- Format chain ids as hex with the `0x` prefix in the protocol
  strings, matching the spelling in `data/genesis/decaf.toml`. Decaf's
  protocols become `/ipfs/kad/1.0.0/0xdecaf`, etc.
- Test reads naturally as `snapshot_for(Some(U256::from(0xdecafu64)))`.
- Mainnet snapshot is unchanged (still goes through the `None`
  branch).

* refactor(node): promote MAINNET_CHAIN_ID to lib.rs, type as ChainId

- Move the constant out of `api/unlock_schedule.rs` so the libp2p
  call site can reuse it instead of comparing against a bare
  `U256::ONE`.
- Retype from `u64 = 1` to `ChainId = ChainId(U256::ONE)` so callers
  no longer wrap it in `U256::from(...)` or `ChainId(...)` at each
  use site.

(cherry picked from commit 284de7a)

Co-authored-by: Mathis <sveitser@gmail.com>

Author: github-actions[bot]

Cargo.lock

@@ -5,9 +5,9 @@ use chrono::{Months, NaiveDate, NaiveDateTime, NaiveTime};
 use espresso_types::{v0_1::ChainId, v0_3::RewardAmount};
 use serde::Deserialize;
 
-const SCHEDULE_TOML: &str = include_str!("../../../../../data/token-unlock-schedule.toml");
+use crate::MAINNET_CHAIN_ID;
 
-pub(crate) const MAINNET_CHAIN_ID: u64 = 1;
+const SCHEDULE_TOML: &str = include_str!("../../../../../data/token-unlock-schedule.toml");
 
 #[derive(Deserialize)]
 struct UnlockEntry {
@@ -120,7 +120,7 @@ impl SupplyCalculator {
     /// Tokens still locked on L1 per the unlock schedule.
     /// Mainnet: `initial_supply - unlocked(now)`. Non-mainnet: `0`.
     fn locked(&self) -> U256 {
-        if self.chain_id == U256::from(MAINNET_CHAIN_ID) {
+        if self.chain_id == MAINNET_CHAIN_ID.0 {
             self.initial_supply
                 .saturating_sub(unlocked_amount_at(self.now_secs))
         } else {
@@ -245,7 +245,7 @@ mod tests {
     // --- SupplyCalculator tests ---
 
     fn mainnet_id() -> ChainId {
-        ChainId(U256::from(MAINNET_CHAIN_ID))
+        MAINNET_CHAIN_ID
     }
 
     fn testnet_id() -> ChainId {

crates/espresso/node/src/api/unlock_schedule.rs

@@ -32,8 +32,11 @@ use espresso_types::{
     SeqTypes, ValidatedState,
     traits::{EventConsumer, MembershipPersistence},
     v0::traits::SequencerPersistence,
+    v0_1::ChainId,
     v0_3::Fetcher,
 };
+
+pub(crate) const MAINNET_CHAIN_ID: ChainId = ChainId(U256::ONE);
 pub use genesis::Genesis;
 use genesis::L1Finalized;
 use hotshot::{
@@ -758,6 +761,9 @@ where
 
     let combined_network = {
         info!("Initializing Libp2p network");
+        // Mainnet keeps today's libp2p protocol strings byte-identical.
+        let chain_id = genesis.chain_config.chain_id;
+        let network_discriminator = (chain_id != MAINNET_CHAIN_ID).then_some(chain_id.0);
         let p2p_network = Libp2pNetwork::from_config(
             network_config.clone(),
             persistence.clone(),
@@ -770,6 +776,7 @@ where
             // (using https://docs.rs/blake3/latest/blake3/fn.derive_key.html)
             &validator_config.private_key,
             hotshot::traits::implementations::Libp2pMetricsValue::new(&*metrics),
+            network_discriminator,
         )
         .await
         .with_context(|| {

crates/espresso/node/src/lib.rs

@@ -769,6 +769,7 @@ where
             public_key,
             private_key,
             Libp2pMetricsValue::default(),
+            None,
         )
         .await
         .expect("failed to create libp2p network");

crates/hotshot/examples/src/infra.rs

@@ -22,6 +22,7 @@ use std::{
 #[cfg(feature = "hotshot-testing")]
 use std::{collections::HashMap, str::FromStr};
 
+use alloy::primitives::U256;
 use anyhow::{Context, anyhow};
 use async_lock::RwLock;
 use async_trait::async_trait;
@@ -407,6 +408,7 @@ impl<T: NodeType> Libp2pNetwork<T> {
         pub_key: &T::SignatureKey,
         priv_key: &<T::SignatureKey as SignatureKey>::PrivateKey,
         metrics: Libp2pMetricsValue,
+        network_discriminator: Option<U256>,
     ) -> anyhow::Result<Self> {
         // Try to take our Libp2p config from our broader network config
         let libp2p_config = config
@@ -456,7 +458,8 @@ impl<T: NodeType> Libp2pNetwork<T> {
             .keypair(keypair)
             .replication_factor(replication_factor)
             .bind_address(Some(bind_address.clone()))
-            .announce_addresses(announce_addresses);
+            .announce_addresses(announce_addresses)
+            .network_discriminator(network_discriminator);
 
         // Connect to the provided bootstrap nodes
         config_builder.to_connect_addrs(HashSet::from_iter(libp2p_config.bootstrap_nodes.clone()));

crates/hotshot/hotshot/src/traits/networking/libp2p_network.rs

@@ -38,6 +38,7 @@ tracing-subscriber = { workspace = true }
 
 [dev-dependencies]
 hotshot-example-types = { workspace = true }
+insta = { workspace = true }
 tracing-test = { workspace = true }
 
 [lints]

crates/hotshot/libp2p-networking/Cargo.toml

@@ -19,6 +19,7 @@ use std::{
     time::{Duration, Instant},
 };
 
+use alloy::primitives::U256;
 use bimap::BiMap;
 use futures::{SinkExt, StreamExt, channel::mpsc};
 use hotshot_types::{
@@ -87,6 +88,53 @@ pub const ESTABLISHED_LIMIT: NonZeroU32 = NonZeroU32::new(ESTABLISHED_LIMIT_UNWR
 /// Number of connections to a single peer before logging an error
 pub const ESTABLISHED_LIMIT_UNWR: u32 = 10;
 
+/// Mainnet libp2p protocol identifiers. The snapshot tests below lock these down so a
+/// change that would partition mainnet (e.g. a stray `protocol_id_prefix` call) is caught.
+/// `None` for gossipsub means "do not call `protocol_id_prefix`" — libp2p's defaults
+/// (`/meshsub/1.1.0` and `/meshsub/1.0.0`) are then used.
+pub(crate) fn mainnet_gossipsub_prefix() -> Option<&'static str> {
+    None
+}
+
+pub(crate) fn mainnet_kad_protocol() -> StreamProtocol {
+    StreamProtocol::new("/ipfs/kad/1.0.0")
+}
+
+pub(crate) fn mainnet_direct_message_protocol() -> StreamProtocol {
+    StreamProtocol::new("/HotShot/direct_message/1.0")
+}
+
+/// Resolve the gossipsub `protocol_id_prefix` for the given network discriminator.
+/// `None` returns the mainnet value (the libp2p default).
+pub(crate) fn gossipsub_prefix(discriminator: Option<U256>) -> Option<String> {
+    match discriminator {
+        None => mainnet_gossipsub_prefix().map(String::from),
+        Some(d) => Some(format!("/HotShot/gossipsub/1.0/{d:#x}")),
+    }
+}
+
+/// Resolve the kademlia stream protocol for the given network discriminator.
+pub(crate) fn kad_protocol(discriminator: Option<U256>) -> Result<StreamProtocol, NetworkError> {
+    match discriminator {
+        None => Ok(mainnet_kad_protocol()),
+        Some(d) => StreamProtocol::try_from_owned(format!("/ipfs/kad/1.0.0/{d:#x}"))
+            .map_err(|err| NetworkError::ConfigError(format!("invalid kademlia protocol: {err}"))),
+    }
+}
+
+/// Resolve the direct-message stream protocol for the given network discriminator.
+pub(crate) fn direct_message_protocol(
+    discriminator: Option<U256>,
+) -> Result<StreamProtocol, NetworkError> {
+    match discriminator {
+        None => Ok(mainnet_direct_message_protocol()),
+        Some(d) => StreamProtocol::try_from_owned(format!("/HotShot/direct_message/1.0/{d:#x}"))
+            .map_err(|err| {
+                NetworkError::ConfigError(format!("invalid direct_message protocol: {err}"))
+            }),
+    }
+}
+
 /// Network definition
 #[derive(derive_more::Debug)]
 pub struct NetworkNode<T: NodeType, D: DhtPersistentStorage> {
@@ -215,7 +263,11 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
             };
 
             // Derive a `Gossipsub` config from our gossip config
-            let gossipsub_config = GossipsubConfigBuilder::default()
+            let mut gossipsub_builder = GossipsubConfigBuilder::default();
+            if let Some(prefix) = gossipsub_prefix(config.network_discriminator) {
+                gossipsub_builder.protocol_id_prefix(prefix);
+            }
+            let gossipsub_config = gossipsub_builder
                 .message_id_fn(message_id_fn) // Use the (blake3) hash of a message as its ID
                 .validation_mode(ValidationMode::Strict) // Force all messages to have valid signatures
                 .heartbeat_interval(config.gossip_config.heartbeat_interval) // Time between gossip heartbeats
@@ -263,7 +315,7 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
             let identify = IdentifyBehaviour::new(identify_cfg);
 
             // - Build DHT needed for peer discovery
-            let mut kconfig = Config::new(StreamProtocol::new("/ipfs/kad/1.0.0"));
+            let mut kconfig = Config::new(kad_protocol(config.network_discriminator)?);
             kconfig
                 .set_parallelism(NonZeroUsize::new(5).unwrap())
                 .set_provider_publication_interval(Some(kademlia_record_republication_interval))
@@ -303,7 +355,7 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
                 RequestResponse::with_codec(
                     cbor,
                     [(
-                        StreamProtocol::new("/HotShot/direct_message/1.0"),
+                        direct_message_protocol(config.network_discriminator)?,
                         ProtocolSupport::Full,
                     )],
                     rrconfig.clone(),
@@ -817,3 +869,30 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
         self.peer_id
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{U256, direct_message_protocol, gossipsub_prefix, kad_protocol};
+
+    fn snapshot_for(discriminator: Option<U256>) -> String {
+        format!(
+            "gossipsub_prefix: {:?}\nkad: {}\ndirect_message: {}",
+            gossipsub_prefix(discriminator),
+            kad_protocol(discriminator).unwrap(),
+            direct_message_protocol(discriminator).unwrap(),
+        )
+    }
+
+    #[test]
+    fn mainnet_libp2p_protocol_identifiers() {
+        insta::assert_snapshot!("mainnet_libp2p_protocol_identifiers", snapshot_for(None));
+    }
+
+    #[test]
+    fn decaf_libp2p_protocol_identifiers() {
+        insta::assert_snapshot!(
+            "decaf_libp2p_protocol_identifiers",
+            snapshot_for(Some(U256::from(0xdecafu64)))
+        );
+    }
+}

crates/hotshot/libp2p-networking/src/network/node.rs

@@ -6,6 +6,7 @@
 
 use std::{collections::HashSet, num::NonZeroUsize, time::Duration};
 
+use alloy::primitives::U256;
 use libp2p::{Multiaddr, identity::Keypair};
 use libp2p_identity::PeerId;
 
@@ -70,6 +71,10 @@ pub struct NetworkNodeConfig {
     #[builder(default)]
     /// The timeout for DHT lookups.
     pub dht_timeout: Option<Duration>,
+
+    /// `None` is the legacy value, used for mainnet.
+    #[builder(default)]
+    pub network_discriminator: Option<U256>,
 }
 
 impl Clone for NetworkNodeConfig {
@@ -87,6 +92,7 @@ impl Clone for NetworkNodeConfig {
             dht_file_path: self.dht_file_path.clone(),
             auth_message: self.auth_message.clone(),
             dht_timeout: self.dht_timeout,
+            network_discriminator: self.network_discriminator,
         }
     }
 }

crates/hotshot/libp2p-networking/src/network/node/config.rs

@@ -0,0 +1,7 @@
+---
+source: crates/hotshot/libp2p-networking/src/network/node.rs
+expression: "snapshot_for(Some(U256::from(0xdecafu64)))"
+---
+gossipsub_prefix: Some("/HotShot/gossipsub/1.0/0xdecaf")
+kad: /ipfs/kad/1.0.0/0xdecaf
+direct_message: /HotShot/direct_message/1.0/0xdecaf

crates/hotshot/libp2p-networking/src/network/snapshots/hotshot_libp2p_networking__network__node__tests__decaf_libp2p_protocol_identifiers.snap

@@ -0,0 +1,7 @@
+---
+source: crates/hotshot/libp2p-networking/src/network/node.rs
+expression: snapshot_for(None)
+---
+gossipsub_prefix: None
+kad: /ipfs/kad/1.0.0
+direct_message: /HotShot/direct_message/1.0