feat: enhance OptimumP2P documentation

.vitepress/theme/style.css

@@ -134,3 +134,34 @@
 .DocSearch {
   --docsearch-primary-color: var(--vp-c-brand-1) !important;
 }
+
+/**
+ * Component: Theme-aware Images
+ * -------------------------------------------------------------------------- */
+
+.theme-aware-image {
+  position: relative;
+}
+
+.theme-aware-image img {
+  width: 100%;
+  height: auto;
+}
+
+/* Hide dark images in light mode */
+.light-mode-only {
+  display: block !important;
+}
+
+.dark-mode-only {
+  display: none !important;
+}
+
+/* Show dark images in dark mode, hide light images */
+html.dark .light-mode-only {
+  display: none !important;
+}
+
+html.dark .dark-mode-only {
+  display: block !important;
+}

docs/learn/overview/p2p.md

@@ -1,29 +1,66 @@
-# What is OptimumP2P
+# OptimumP2P: High-Performance Network Coding for Decentralized Systems
 
-OptimumP2P is a performant message-passing (gossiping) protocol for fast, bandwidth-efficient data propagation in decentralized networks. It is optimized for high speed, low latency, and low bandwidth usage. OptimumP2P leverages Random Linear Network Coding (RLNC), a network coding technique developed at MIT, to address the limitations of traditional gossip protocols.
+OptimumP2P is a performant message-passing protocol designed for fast, bandwidth-efficient data propagation in decentralized networks. It leverages Random Linear Network Coding (RLNC), a network coding technique developed at MIT, to address fundamental limitations of traditional gossip protocols in blockchain and distributed systems.
 
-## Message-Passing Systems and Motivation
+## Architecture Overview
 
-Gossip protocols are widely used to disseminate information across peer-to-peer networks, including Web3 systems. In blockchain networks, gossip is critical for propagating transactions and blocks. Slow propagation can result in missed block rewards for validators and reduced profitability for MEV optimizers. Efficient message dissemination is essential for network health and participant incentives.
+OptimumP2P operates through a distributed architecture consisting of several key components that work together to enable efficient data propagation.
 
-## Limitations of Traditional Gossip
+The **Gateway Layer** provides API access and message coordination through HTTP and WebSocket interfaces. The gateway manages client connections, topic registries, and node pool coordination while handling authentication and authorization for secure access to the network.
 
-* High latency: Peers must receive full messages before forwarding.
-* Bandwidth waste: Peers may receive multiple redundant copies of the same message.
+The **P2P Node Network** implements the core networking protocol using libp2p infrastructure with optimized transport layers. Each node maintains peer connections through DHT-based discovery and supports both native OptimumP2P and fallback GossipSub protocols for maximum compatibility and reliability.
 
-## RLNC and OptimumP2P
+The **Protocol Abstraction** layer provides a unified interface that allows seamless switching between different P2P protocols based on network conditions and requirements. This enables dynamic protocol selection and fallback mechanisms to ensure consistent network operation under varying conditions.
 
-* Reduced latency: Forwarding starts with the first shard.
-* Bandwidth efficiency: Redundant data is minimized.
-* Fault tolerance: Any sufficient subset of shards enables decoding.
+**Message Coordination** handles topic-based message routing with single-node-per-topic assignment to prevent duplicate processing and optimize bandwidth utilization across the network.
 
-## Performance Characteristics
+## Data Flow and Propagation
 
-* **Latency**: Testnet results show 50%+ reduction in propagation latency compared to Gossipsub.
-* **Bandwidth**: RLNC reduces redundant transmissions, achieving sub-linear bandwidth growth as the network scales.
-* **Fault tolerance**: The protocol is resilient to packet loss and node churn; partial data is sufficient for message recovery.
-* **Scalability**: Efficient for both L1 and L2 chains, and supports high throughput under load.
+<div class="theme-aware-image">
+  <img src="/static/img/P2P_data_flow_light.png" alt="OptimumP2P Data Flow" class="light-mode-only">
+  <img src="/static/img/P2P_data_flow_dark.png" alt="OptimumP2P Data Flow" class="dark-mode-only">
+</div>
+
+The data flow diagram illustrates how OptimumP2P integrates with blockchain infrastructure to provide enhanced data propagation. The system operates through three main components: the Validator Node, the Optimum Service, and the Networks layer.
+
+At the **Validator Node** level, the Optimum Agent interfaces directly with the blockchain client through IPC (Inter-Process Communication). Transaction data flows from the blockchain client to the Optimum Agent, which serves as the bridge between the blockchain infrastructure and the OptimumP2P network.
+
+The **Optimum Service** acts as the central processing unit where the core RLNC encoding and network coordination takes place. When transaction data arrives from the Optimum Agent, the service applies Random Linear Network Coding to create redundant, encoded shards that can be efficiently propagated across the network.
+
+The **Networks** component demonstrates the dual-path approach for maximum reliability. The primary path uses Fast Sync through the Optimum Network for rapid propagation using RLNC-encoded data. This network injects encoded shards to global blockchain nodes and validator nodes, ensuring fast delivery of critical information.
+
+A fallback mechanism ensures network reliability through the standard Blockchain Network using traditional gossip protocols. This dual approach guarantees that even if the OptimumP2P network experiences issues, data can still propagate through conventional means, maintaining network integrity and consensus.
+
+![Network Introduction](/static/img/intro.png)
+
+The network topology shows the hierarchical structure where OptimumP2P nodes operate in the upper layer, connecting to gateway nodes that interface with user clients. This architecture enables efficient data distribution from the P2P network down to individual client applications while maintaining scalability and performance.
+
+## How OptimumP2P Works
+
+OptimumP2P integrates with networks at the validator level as a software component running on each validator's machine. Block data is read directly from the network client, then sharded and encoded using RLNC before being forwarded to other nodes on the network. The entire process from block data intake to full network propagation takes place in a few hundred milliseconds, maintaining this performance level as data size and frequency scales.
+
+The system leverages RLNC to reduce the amount of redundant data that needs to be transmitted. Unlike traditional gossip protocols that require complete message reception before forwarding, OptimumP2P allows data forwarding to begin as soon as any shards are received. This approach saves both time and computational resources while improving overall network efficiency.
+
+## Random Linear Network Coding Implementation
+
+The RLNC implementation in OptimumP2P provides the mathematical foundation for efficient data propagation. Data objects are systematically encoded into k-of-n coded elements using linear algebra over finite fields. This encoding process creates redundant information that allows complete reconstruction from any k received elements out of n transmitted elements.
+
+During the encoding process, original data is split into systematic chunks, and linear combinations are computed using randomly generated coefficients. This creates coded shards that contain both original data fragments and encoding vectors. Each shard carries its encoding coefficients, enabling recipients to perform Gaussian elimination for data reconstruction.
+
+The system includes recoding capability, where intermediate nodes can generate new coded packets by linearly combining received packets. This improves network efficiency without requiring full data reconstruction at intermediate nodes, allowing for more flexible and resilient data propagation paths.
+
+## Message Types and Protocol Handling
+
+OptimumP2P defines several message types for efficient network operation. Data messages carry encoded payload data with RLNC coefficients and metadata necessary for reconstruction. Control messages handle subscription management, peer discovery, and protocol negotiation between nodes. Trace events provide network monitoring capabilities by tracking shard propagation and performance metrics throughout the system.
+
+The protocol employs DHT-based peer discovery with configurable bootstrap nodes to establish and maintain network connectivity. Connection management includes adaptive connection pools that scale dynamically based on network conditions and message throughput, automated failure detection and recovery from node failures or network partitions, and capability-based selection between OptimumP2P and fallback protocols.
+
+## Security Model
+
+OptimumP2P implements a comprehensive security model to protect against various attack vectors. The system uses Boneh-Lynn-Shacham (BLS) signatures to provide authentication and non-repudiation for all network communications. Cryptographic hashing ensures data integrity throughout the network, while distributed key management with on-chain registration and verification provides secure identity management.
+
+The protocol includes protection against pollution attacks through coding-theoretic techniques that detect and mitigate data pollution attempts. Eclipse attacks are prevented through DHT-based discovery with multiple bootstrap nodes, preventing network isolation. Integration with blockchain identity systems provides resistance against Sybil attacks by leveraging existing trust infrastructure.
 
 ## Summary
 
-OptimumP2P is a high-performance, developer-friendly protocol for fast, reliable, and bandwidth-efficient data propagation in decentralized networks. By leveraging RLNC, it addresses the limitations of traditional gossip, providing measurable improvements in latency, bandwidth usage, and fault tolerance. The protocol is designed for easy integration, broad compatibility, and robust security, making it suitable for validators, chains, and applications seeking to optimize network performance.
+OptimumP2P is a high-performance, developer-friendly protocol for fast, reliable, and bandwidth-efficient data propagation in decentralized networks. By leveraging RLNC, it addresses the limitations of traditional gossip protocols, providing measurable improvements in latency, bandwidth usage, and fault tolerance. The protocol is designed for easy integration, broad compatibility, and robust security, making it suitable for validators, chains, and applications seeking to optimize network performance.