feat: add page about syncing and update config and peers API (#13)

* feat: add page about syncing and update config and peers API

* chore: add more details about syncing

* style: use less text in links

* docs: describe new peer properties

Author: yoxira

.vitepress/config.mts

@@ -39,6 +39,7 @@ export default defineConfig({
           { text: 'Configuration', link: '/own-node/configuration' },
           { text: 'Testnet', link: '/own-node/testnet' },
           { text: 'Consensus', link: '/own-node/consensus' },
+          { text: 'Syncing', link: '/own-node/syncing' },
         ],
       },
       {

api-endpoints/blockchain.md

@@ -30,6 +30,8 @@ GET /api/peers
   - `height` — current node's blockchain height
   - `updated` — Unix timestamp based in ms, when peer updated
   - `nonce` — unique Identifier for the peer. Random string.
+  - `syncProtocol` — `"http"` if the node is subscribed to the peer using HTTP only. `"ws"` if the node is subscribed to the peer using WebSocket (which also allows receiving transactions via both WebSocket and HTTP).
+  - `isBroadcastingViaSocket` — `true` if the node can send transactions to the peer over WebSocket.
 
   Available parameters:
 
@@ -62,7 +64,9 @@ GET /api/peers
         "height": 10146365,
         "clock": null,
         "updated": 1562424199553,
-        "nonce": "jxXV6g0sHJhmDubq"
+        "nonce": "jxXV6g0sHJhmDubq",
+        "isBroadcastingViaSocket": false,
+        "syncProtocol": "ws"
       },
       {
         "ip": "144.217.93.8",
@@ -74,7 +78,9 @@ GET /api/peers
         "height": 10146364,
         "clock": null,
         "updated": 1562424195742,
-        "nonce": "YngSDjA5MeUNk2iZ"
+        "nonce": "YngSDjA5MeUNk2iZ",
+        "isBroadcastingViaSocket": false,
+        "syncProtocol": "http"
       }
     ]
   }
@@ -154,7 +160,9 @@ GET /api/peers/get
       "height": 38723235,
       "clock": null,
       "updated": 1713630137277,
-      "nonce": "YWXG1LsX0QUw4tFD"
+      "nonce": "YWXG1LsX0QUw4tFD",
+      "isBroadcastingViaSocket": false,
+      "syncProtocol": "ws"
     }
   }
   ```

own-node/configuration.md

@@ -377,6 +377,26 @@ Redis is used for caching. Required.
   - `enabled`: Enable or disable WebSocket client (e.g., `true`).
   - `portWS`: WebSocket client port (e.g., `36668`).
 
+## WebSocket Node Configuration
+
+- **WebSocket Node**
+
+  Configure WebSocket node-to-node connection for syncing with the `wsNode` object:
+
+  ```json
+  {
+    "wsNode": {
+      "enabled": true,
+      "maxBroadcastConnections": 15,
+      "maxReceiveConnections": 25
+    }
+  }
+  ```
+
+  - `enabled`: Enable or disable WebSocket node-to-node communication.
+  - `maxBroadcastConnections`: Maximum number of outbound WebSocket connections used to broadcast data to other nodes.
+  - `maxReceiveConnections`: Maximum number of inbound WebSocket connections to other nodes.
+
 ## Nethash Configuration
 
 - **Nethash**

own-node/syncing.md

@@ -0,0 +1,44 @@
+# Syncing
+
+To maintain decentralization, a blockchain node must connect and synchronize with other nodes (peers) in the network.
+
+You can define the initial list of peers in the configuration file using the [`peers`](./configuration.md#peer-configuration) field and check synchronization status using the [`/api/loader/status/sync`](../api-endpoints/blockchain.md#get-synchronization-status) endpoint.
+
+:::info
+Make sure the peers are on the same network. You can verify this by checking the nethash using the [`/api/blocks/getNethash`](/api-endpoints/blockchain.md#get-blockchain-nethash) endpoint.
+:::
+
+Once connected, the node will automatically discover more peers by querying the peers of its current connections. Discovered peers are saved in the local database, which helps speed up future deployments and restarts.
+
+You can get the list of connected and discovered peers using the [`/api/peers`](/api-endpoints/blockchain.md#get-peers-list) endpoint.
+
+## Socket connections
+
+For faster transaction syncing between nodes, we recommend enabling [WebSocket Node connections](./configuration.md#websocket-node-configuration) in the configuration.
+
+If you enable the WebSocket, a node will connect to another peer using both WebSocket and HTTP at the same time. It’s up to the broadcasting node to decide how to send transactions. By default, transactions are not sent twice to the same peer using both methods.
+
+## Peer selection and rotation
+
+To avoid centralization, the node randomly selects peers to broadcast transactions to. This is the same strategy used for HTTP broadcasting.
+
+Every 30 minutes, the node replaces 20% of its current WebSocket connections with new ones. This rotation helps maintain a healthy and distributed peer network.
+
+## Transaction broadcasting
+
+When a node receives an unconfirmed transaction, it spreads it across the network by sending it to multiple randomly selected peers.
+
+The method used for broadcasting depends on the type of connection:
+
+- **WebSocket**: Transactions are sent instantly.
+- **HTTP (REST)**: Transactions are sent after a short delay, defined by the [`broadcastInterval`](./configuration.md#broadcast-configuration) configuration property.
+
+If a peer is connected via WebSocket, it may still receive the same transaction via HTTP. This design ensures redundancy.
+
+As a result, a node may receive the same unconfirmed transaction multiple times, from different peers, and through both REST and WebSocket. This helps ensure that transactions reliably reach their destination even if some connections fail.
+
+## Backward compability
+
+In earlier versions, nodes had a separate WebSocket server intended for transaction syncing, but it wasn't fully implemented and didn't receive transactions over WebSocket.
+
+After recent changes, new nodes now support full transaction syncing over WebSocket. Even if many nodes on the network still run older software, the newer nodes can receive transactions instantly. Older nodes will continue relying on HTTP broadcasting as before.