network_config.rs

Overview

This file defines the NetworkConfig struct, which encapsulates the configuration settings for the network layer of a node within a distributed system. The network configuration includes addresses for various network sockets, TLS certificate paths, cryptographic key information, gossip protocol parameters, and API endpoint settings. The file provides default values, serialization/deserialization support through serde, and builder pattern construction via typed_builder.

The configuration parameters allow a node to establish secure and efficient communication with peers, proxies, and clients using QUIC over UDP, manage gossip protocol participation, and expose APIs for block management and general SDK interactions.

Detailed Description of Components

NetworkConfig Struct

The primary struct in this file, NetworkConfig, represents all necessary network-related settings for a node.

Properties

• bind: SocketAddr
  The socket address (IP and port) where the node listens for incoming messages from other nodes using QUIC over UDP.

  • Default: "127.0.0.1:8500"

  • Usage: Essential for receiving peer-to-peer network traffic.

• my_cert: PathBuf
  Path to the node's TLS authentication certificate file (*.ca.pem).

  • Usage: Used by the node to authenticate itself when acting as a server or a client.

• my_key: PathBuf
  Path to the node's TLS authentication private key file (*.key.pem).

  • Usage: Paired with my_cert for mutual TLS authentication.

• my_ed_key_secret: Vec<String>
  Optional secret key of the block keeper's owner wallet, represented as a 64-character hex string.

  • Mutually exclusive with my_ed_key_path.

  • Usage: Used for cryptographic operations related to block ownership.

• my_ed_key_path: Vec<String>
  Optional path(s) to the block keeper's owner wallet key file(s) stored as JSON objects containing public and secret keys.

  • Mutually exclusive with my_ed_key_secret.

• subscribe: Vec<Vec<SocketAddr>>
  Nested list of socket addresses for block and broadcast protocol message subscriptions.

  • Serialized/deserialized with custom functions (network::serialize_subscribe and network::deserialize_subscribe).

  • Usage: Defines which nodes or groups the node subscribes to for receiving broadcast messages.

• proxies: Vec<SocketAddr>
  List of proxy addresses propagated via gossip.

  • Deserialized with network::deserialize_publisher_addrs.

  • Usage: Enables routing and message forwarding in the network.

• peer_certs: Vec<PathBuf>
  Paths to trusted TLS certificate files or directories used to verify server certificates during client connections.

  • Usage: Ensures secure connections by verifying peer identities.

• peer_ed_pubkeys: Vec<transport_layer::VerifyingKey>
  List of Ed25519 public keys used for verifying signatures from peers.

  • Serialized/deserialized using transport_layer::hex_verifying_keys.

  • Usage: Provides cryptographic verification of peer messages.

• node_advertise_addr: SocketAddr
  Public socket address advertised to the network via gossip.

  • Usage: Other nodes use this address to connect to this node.

• gossip_listen_addr: SocketAddr
  UDP socket address where the node listens for gossip messages.

  • Default: "127.0.0.1:10000"

• gossip_advertise_addr: Option<SocketAddr>
  Optional socket address advertised for gossip. Defaults to the bind address if not set.

• gossip_seeds: Vec<SocketAddr>
  List of seed nodes for gossip protocol initialization.

• block_manager_listen_addr: SocketAddr
  Socket address for listening to lite node requests (QUIC UDP).

  • Default: "127.0.0.1:12000"

• static_storages: Vec<url::Url>
  URLs of static storage locations used by the node (e.g., for fetching resources).

• api_addr: String
  Socket address for the SDK API exposed by the node.

• api_advertise_addr: url::Url
  Public URL advertised for the SDK API.

• send_buffer_size: usize
  Network send buffer size, controlling the size of outgoing message queues.

  • Default: 1000

• bm_api_socket: Option<SocketAddr>
  Optional public socket address for the Block Manager API.

• bk_api_socket: Option<SocketAddr>
  Optional public socket address for the Block Keeper API.

• shared_state_max_download_tries: u8
  Maximum number of attempts to download shared state data.

  • Default: 50

• shared_state_retry_download_timeout_millis: u64
  Retry timeout in milliseconds between attempts to download shared state data.

  • Default: 500 ms

• chitchat_cluster_id: String
  Identifier for the chitchat gossip cluster.

  • Default: "acki_nacki"

• max_nodes_with_same_id: u8
  Maximum number of nodes allowed with the same cluster ID in the gossip network.

  • Default: 5

Methods

• get_gossip_seeds(&self) -> Vec<String>
  Returns a vector of gossip seed addresses as strings.

  • Usage Example:

    let seeds = config.get_gossip_seeds();
    for seed in seeds {
        println!("Gossip seed: {}", seed);
    }
    

Default Value Functions

Several helper functions provide default values for fields in NetworkConfig to ensure sensible defaults and reduce configuration verbosity:

• default_bind() → SocketAddr

• default_gossip_listen_addr() → SocketAddr

• default_block_manager_listen_addr() → SocketAddr

• default_send_buffer_size() → usize

• default_shared_state_retry_download_timeout_millis() → u64

• default_shared_state_max_download_tries() → u8

• default_chitchat_cluster_id() → String

• default_max_nodes_with_same_id() → u8

These functions are used as default value providers for serialization and builder defaulting.

Implementation Details and Algorithms

• The use of the typed_builder crate enables ergonomic and type-safe construction of configuration instances with optional and defaulted fields.

• Serialization and deserialization leverage serde, with custom (de)serializers for complex nested fields like subscribe and proxies.

• Cryptographic keys and certificates are represented as paths or byte vectors, consistent with usage in TLS and Ed25519-based authentication.

• Gossip protocol parameters like seeds, cluster ID, and max nodes with the same ID control the node's participation and behavior in the gossip network, which is a key component of decentralized message propagation.

Interactions with Other System Components

• Network Layer:
  The configuration data is consumed by the network transport layer to set up UDP sockets (QUIC) for peer-to-peer communication, gossip message handling, and API exposure.

• TLS and Cryptography Modules:
  Paths to certificates and keys are used by TLS stacks to establish secure channels. The peer_ed_pubkeys are used to verify signed messages from other nodes, interacting with cryptographic verification subsystems.

• Gossip Protocol:
  Gossip-specific settings (gossip_seeds, chitchat_cluster_id, etc.) interact with the gossip subsystem, influencing cluster membership and message dissemination.

• Block Manager and Block Keeper APIs:
  Addresses configured for block management APIs allow other components or clients to interact with block storage and management services.

• Static Storage Access:
  URLs in static_storages may be used by resource-fetching components to retrieve static data needed by the node.

Mermaid Diagram: Structure of NetworkConfig

classDiagram
class NetworkConfig {
+bind: SocketAddr
+my_cert: PathBuf
+my_key: PathBuf
+my_ed_key_secret: Vec<String>
+my_ed_key_path: Vec<String>
+subscribe: Vec<Vec<SocketAddr>>
+proxies: Vec<SocketAddr>
+peer_certs: Vec<PathBuf>
+peer_ed_pubkeys: Vec<VerifyingKey>
+node_advertise_addr: SocketAddr
+gossip_listen_addr: SocketAddr
+gossip_advertise_addr: Option<SocketAddr>
+gossip_seeds: Vec<SocketAddr>
+block_manager_listen_addr: SocketAddr
+static_storages: Vec<Url>
+api_addr: String
+api_advertise_addr: Url
+send_buffer_size: usize
+bm_api_socket: Option<SocketAddr>
+bk_api_socket: Option<SocketAddr>
+shared_state_max_download_tries: u8
+shared_state_retry_download_timeout_millis: u64
+chitchat_cluster_id: String
+max_nodes_with_same_id: u8
+get_gossip_seeds(): Vec<String>
}

This diagram visually represents the NetworkConfig struct including its fields and the single method get_gossip_seeds. The fields' types are abbreviated for clarity (SocketAddr, PathBuf, Vec, etc.). The diagram reflects that NetworkConfig is a data structure organizing network and protocol configuration parameters.