From 92b8a2a41d5ceb10ed98f379141a97825f4d9de8 Mon Sep 17 00:00:00 2001
From: vasmohi <mohit.vashistha@aelf.io>
Date: Thu, 20 Jun 2024 00:01:30 +0530
Subject: [PATCH] Added network section

---
 docs/protocol/network.md | 155 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 docs/protocol/network.md

diff --git a/docs/protocol/network.md b/docs/protocol/network.md
new file mode 100644
index 00000000..d0ffdf72
--- /dev/null
+++ b/docs/protocol/network.md
@@ -0,0 +1,155 @@
+# Network
+
+## Introduction
+The network layer in aelf is vital for maintaining connections and communication between nodes. It supports higher-level logic like synchronization and allows node operators to monitor and manage network operations. aelf uses gRPC for connections to keep the design simple and flexible.
+
+## Architecture
+The network consists of three layers:
+
+1. **aelf.OS**
+   - Handles network events.
+   - Runs background tasks for network operations.
+
+2. **aelf.OS.Core.Network**
+   - Provides services to higher levels.
+   - Defines infrastructure components and types.
+
+3. **aelf.OS.Network.Grpc**
+   - Implements the infrastructure layer using gRPC.
+   - Manages low-level functions like serialization and retrying.
+
+### aelf.OS
+This layer monitors and handles network-related events:
+- **Transaction Accepted Event**: When a transaction is verified.
+- **Block Mined Event**: When a block is packaged.
+- **Block Accepted Event**: When a block is executed successfully.
+- **New Irreversible Block Found Event**: When a new irreversible block is found.
+
+It also performs regular tasks:
+- **Peer Health Check**: Ensures connected peers are healthy.
+- **Peer Retry Connection**: Attempts to reconnect with unhealthy peers.
+- **Network Node Discovery**: Finds new nodes.
+
+### aelf.OS.Core.Network
+This core module includes:
+- **NetworkService**: Manages sending/receiving requests, broadcasting items to peers, and handling network exceptions.
+- **IPeerPool/PeerPool**: Manages active peer connections.
+- **IPeer**: Defines peer interactions and metrics.
+- **IaelfNetworkServer**: Manages network lifecycle and connections.
+
+### aelf.OS.Network.Grpc
+Implements the infrastructure layer using gRPC:
+- **GrpcPeer**: Implements `IPeer`.
+- **GrpcStreamPeer**: Client-side `IPeer` implementation (node version >=1.4.0).
+- **GrpcStreamBackPeer**: Server-side `IPeer` implementation (node version >=1.4.0).
+- **GrpcNetworkServer**: Implements `IaelfNetworkServer`.
+- **GrpcServerService**: Manages network service interfaces and data exchange.
+
+Extra functionalities include:
+- Serializing and deserializing requests.
+- Implementing request/response mechanisms.
+- Authentication.
+
+## Protocol
+Nodes use a defined network interface protocol for normal operation and data synchronization.
+
+### Connection
+
+#### DoHandshake
+When a node connects, it exchanges handshake information. This includes chain status, current height, and more.
+
+- **Request**: 
+    ```proto
+    rpc DoHandshake (HandshakeRequest) returns (HandshakeReply) {}
+    ```
+- **Handshake Message**:
+    ```proto
+    message Handshake {
+        HandshakeData handshake_data = 1;
+        bytes signature = 2;
+        bytes session_id = 3;
+    }
+    ```
+- **HandshakeData Message**:
+    ```proto
+    message HandshakeData {
+        int32 chain_id = 1;
+        int32 version = 2;
+        int32 listening_port = 3;
+        bytes pubkey = 4;
+        aelf.Hash best_chain_hash = 5;
+        int64 best_chain_height = 6;
+        aelf.Hash last_irreversible_block_hash = 7;
+        int64 last_irreversible_block_height = 8;
+        google.protobuf.Timestamp time = 9;
+    }
+    ```
+
+#### ConfirmHandshake
+Confirms the handshake with the target node.
+- **Request**:
+    ```proto
+    rpc ConfirmHandshake (ConfirmHandshakeRequest) returns (VoidReply) {}
+    ```
+
+### Broadcasting
+
+#### BlockBroadcastStream
+Receives block information after packaging.
+- **Request**:
+    ```proto
+    rpc BlockBroadcastStream (stream BlockWithTransactions) returns (VoidReply) {}
+    ```
+
+#### TransactionBroadcastStream
+Receives forwarded transaction information.
+- **Request**:
+    ```proto
+    rpc TransactionBroadcastStream (stream aelf.Transaction) returns (VoidReply) {}
+    ```
+
+#### AnnouncementBroadcastStream
+Receives block announcements.
+- **Request**:
+    ```proto
+    rpc AnnouncementBroadcastStream (stream BlockAnnouncement) returns (VoidReply) {}
+    ```
+
+#### LibAnnouncementBroadcastStream
+Receives last irreversible block (LIB) announcements.
+- **Request**:
+    ```proto
+    rpc LibAnnouncementBroadcastStream (stream LibAnnouncement) returns (VoidReply) {}
+    ```
+
+### Block Request
+
+#### RequestBlock
+Requests a single block.
+- **Request**:
+    ```proto
+    rpc RequestBlock (BlockRequest) returns (BlockReply) {}
+    ```
+
+#### RequestBlocks
+Requests multiple blocks.
+- **Request**:
+    ```proto
+    rpc RequestBlocks (BlocksRequest) returns (BlockList) {}
+    ```
+
+### Peer Management
+
+#### Ping
+Verifies network availability.
+- **Request**:
+    ```proto
+    rpc Ping (PingRequest) returns (PongReply) {}
+    ```
+
+#### CheckHealth
+Performs health checks on peers.
+- **Request**:
+    ```proto
+    rpc CheckHealth (HealthCheckRequest) returns (HealthCheckReply) {}
+    ```
\ No newline at end of file