Merge branch 'main' of https://github.com/algorealmInc/SwarmNL

Author: thewoodfish

.gitignore

@@ -14,4 +14,7 @@ Cargo.lock
 *.pdb
 
 # Ignore the client dir. It's for local experimental testing
-# client
+# client
+
+# Ignore VS Code settings
+.DS_Store

examples/http-client/README.md

@@ -34,7 +34,7 @@ repl amazing
 ```
 
 When the replicated data arrives on a node and reaches the application layer, it is immediately sent to a remote server.
-You should see the message `Successfully sent POST request.` printed to the terminal afte this operation.
+You should see the message `Successfully sent POST request.` printed to the terminal after this operation.
 
 ## Run with Docker
 

examples/http-client/src/main.rs

@@ -111,7 +111,7 @@ async fn run_node(
 	let mut node = setup_node(ports_1, &keypair[..], bootnodes).await;
 
 	// Join replica network
-	println!("Joining replication network...");
+	println!("Joining replica network...");
 	if let Ok(_) = node.join_repl_network(REPL_NETWORK_ID.into()).await {
 		println!("Replica network successfully joined");
 	} else {

examples/ipfs/README.md

@@ -17,7 +17,7 @@ cargo run --features=second-node
 And the third node:
 
 ```bash
-cargo run --features=first-node
+cargo run --features=third-node
 ```
 
 In the separate terminals where each node is running, submit the following commands:
@@ -31,7 +31,7 @@ repl Oranges
 repl Papayas
 ```
 When the replicated data arrived on a node and reaches the application layer, it is immediately uploaded to the IPFS network for persistence.
-After the operation, should see a message printed to the stdout of nodes 1 and 2 such as:
+After the operation, you should see a message printed to the stdout of each node such as:
 
 ```bash
 File successfully uploaded to IPFS with hash: QmX7epzCn2jD8nPUDiehmZDQs69HxKYcmM

examples/ipfs/run_nodes.sh

@@ -10,7 +10,7 @@ tmux select-layout tiled
 
 # Give the nodes some time to start
 echo "Waiting for all three nodes to start..."
-sleep 7
+sleep 60
 
 # Send commands to each pane
 # Pane 0 (first node)
@@ -25,9 +25,5 @@ sleep 2
 tmux send-keys -t rust-nodes:0.2 "repl Papayas" C-m
 sleep 2
 
-# Read and fetch commands
-tmux send-keys -t rust-nodes:0.2 "read" C-m
-tmux send-keys -t rust-nodes:0.1 "read" C-m
-
 # Attach to the session so you can observe the output
 tmux attach-session -t rust-nodes

examples/ipfs/src/main.rs

@@ -113,7 +113,7 @@ async fn run_node(
 	let mut node = setup_node(ports_1, &keypair[..], bootnodes).await;
 
 	// Join replica network
-	println!("Joining replication network...");
+	println!("Joining replica network...");
 	if let Ok(_) = node.join_repl_network(REPL_NETWORK_ID.into()).await {
 		println!("Replica network successfully joined");
 	} else {

examples/replication/README.md

@@ -1,5 +1,7 @@
 # Replication examples
 
+These examples demonstrate the configurations and operations of a replica network using SwarmNL using Eventual Consistency and Strong Consistency models.
+
 ## Eventual consistency
 
 To run this example, cd into the root of this directory and in separate terminals launch the following commands to launch three nodes:
@@ -38,7 +40,7 @@ Then the third node:
 repl Papayas
 ```
 
-Then in node 3, running the following command will return the values in its replication buffer (which contains data gotten from node 1 and 2):
+Then in node 3, running the following command will return the values in its replication buffer (which contains data received from node 1 and 2):
 
 ```bash
 read
@@ -77,7 +79,7 @@ cargo run --features=second-node
 And the third node:
 
 ```bash
-cargo run --features=first-node
+cargo run --features=third-node
 ```
 
 Now, submit the following commands to replicate data from nodes in the network, starting with the first node:
@@ -122,7 +124,7 @@ Hit `Ctrl+D` to exit.
 
 ## Peer cloning
 
-In this example, we expect a node to clone the data in the buffer of the specified peer ID when it calls `clone`.
+In this example, we expect a node to clone the data in the buffer of the specified replica peer when it calls `clone`.
 
 To run this example, cd into the root of this directory and in separate terminals launch the following commands:
 
@@ -139,7 +141,7 @@ cargo run --features=second-node
 And the third node:
 
 ```bash
-cargo run --features=first-node
+cargo run --features=third-node
 ```
 
 Now, submit the following commands to replicate data from nodes in the network, starting with the first node:
@@ -162,11 +164,12 @@ repl Papayas
 
 Then in node 3, run the following command to clone node 2's buffer (by passing in node 2's peer ID):
 
-```clone
+```bash
 clone 12D3KooWFPuUnCFtbhtWPQk1HSGEiDxzVrQAxYZW5zuv2kGrsam4
 ```
 
-We expect node 2 to contain "Papayas" and "Apples" in its buffer which you can verify by submitting `read` to stdin from node 3's terminal to read it's buffer content:
+We expect node 2 to contain "Papayas" and "Apples" in its buffer.
+This can be verified by submitting `read` to stdin from node 3's terminal to read it's buffer content:
 
 ```bash
 read

examples/replication/eventual-consistency/src/main.rs

@@ -104,7 +104,7 @@ async fn run_node(
 	let mut node = setup_node(ports_1, &keypair[..], bootnodes).await;
 
 	// Join replica network
-	println!("Joining replication network");
+	println!("Joining replica network");
 	if let Ok(_) = node.join_repl_network(REPL_NETWORK_ID.into()).await {
 		println!("Replica network successfully joined");
 	} else {

examples/replication/peer-cloning/run_nodes.sh

@@ -26,7 +26,7 @@ tmux send-keys -t rust-nodes:0.2 "repl Papayas" C-m
 sleep 2
 
 # Clone and read
-tmux send-keys -t rust-nodes:0.2 "clone 12D3KooWQDpMufFJytG2xQuz7JzfK2vBH2g3XXBJ9v2xY7SegRUk" C-m
+tmux send-keys -t rust-nodes:0.2 "clone 12D3KooWFPuUnCFtbhtWPQk1HSGEiDxzVrQAxYZW5zuv2kGrsam4" C-m
 
 sleep 4
 

examples/replication/peer-cloning/src/main.rs

@@ -107,7 +107,7 @@ async fn run_node(
 	let mut node = setup_node(ports_1, &keypair[..], bootnodes).await;
 
 	// Join replica network
-	println!("Joining replication network");
+	println!("Joining replica network");
 	if let Ok(_) = node.join_repl_network(REPL_NETWORK_ID.into()).await {
 		println!("Replica network successfully joined");
 	} else {

examples/replication/strong-consistency/run_nodes.sh

@@ -15,15 +15,15 @@ sleep 60
 # Send commands to each pane
 # Pane 0 (first node)
 tmux send-keys -t rust-nodes:0.0 "repl Apples" C-m
-sleep 2
+sleep 4
 
 # Pane 1 (second node)
 tmux send-keys -t rust-nodes:0.1 "repl Oranges" C-m
-sleep 2
+sleep 4
 
 # Pane 2 (third node)
 tmux send-keys -t rust-nodes:0.2 "repl Papayas" C-m
-sleep 2
+sleep 4
 
 # Read and fetch commands
 tmux send-keys -t rust-nodes:0.2 "read" C-m

examples/replication/strong-consistency/src/main.rs

@@ -102,7 +102,7 @@ async fn run_node(
 	let mut node = setup_node(ports_1, &keypair[..], bootnodes).await;
 
 	// Join replica network
-	println!("Joining replication network");
+	println!("Joining replica network");
 	if let Ok(_) = node.join_repl_network(REPL_NETWORK_ID.into()).await {
 		println!("Replica network successfully joined");
 	} else {
@@ -155,7 +155,7 @@ async fn run_node(
 			// confirmations are complete
 			if let Some(repl_data) = node.consume_repl_data(REPL_NETWORK_ID).await {
 				println!(
-					"Data gotten from replica: {} ({} confirmations)",
+					"Data received from replica: {} ({} confirmations)",
 					repl_data.data[0],
 					repl_data.confirmations.unwrap()
 				);

examples/sharding/README.md

@@ -19,7 +19,7 @@ cargo run --features=second-node
 And the third node:
 
 ```bash
-cargo run --features=first-node
+cargo run --features=third-node
 ```
 
 In the separate terminals where each node is running, submit the following commands:
@@ -34,21 +34,21 @@ shard mars mars_creatures.txt Inkls
 ```
 
 According to the configuration in the example, node 1 and 2 belongs to the shard with key "mars". Node 3 beloings to a separate shard with key "earth".
-To read the local data stored on node 1 (mars shard). Run the following command:
+To read the local data stored on node 1 ("mars" shard), run the following command from the first terminal:
 
 ```bash
 read
 ```
 
-After that, we would query the "earth" shard for the data it holds. To do that, please run the following command:
+After that, we would query the "earth" shard for the data it holds. To do that, run the following command:
 
 ```bash
 fetch earth earth_creatures.txt
 ```
 
 Here, we are sending a data request to the sharded network, telling it to read the file "earth_creatures.txt" on the shard "earth".
 
-From node 3's terminal, you can also read what is stored in node 3 by submitting the `read` command. To request data stored in the "mars" shard, kindly run the following:
+From node 3's terminal, you can also read what is stored in node 3 by submitting the `read` command. To request data stored in the "mars" shard, run the following:
 
 ```bash
 fetch mars mars_creatures.txt
@@ -57,7 +57,7 @@ fetch mars mars_creatures.txt
 In node 2's terminal, you can also run the following:
 
 ```bash
- fetch earth earth_creatures.txt
+fetch earth earth_creatures.txt
 ```
 
 ## Run with Docker
@@ -114,9 +114,10 @@ To read data stored locally on a particular node, run the following command:
 ```bash
 read
 ```
-Please note that once read is called, all the available data is removed from the replica buffer and consumed.
 
-TO fetch a song placed in a particular shard, please run the following:
+Note that once `read` is called, all the available data is removed from local storage and consumed.
+
+To fetch a "song" placed in a particular shard, please run the following:
 
 ```bash
 # Run this in node 1's terminal

examples/sharding/hash-based/run_nodes.sh

@@ -15,17 +15,18 @@ sleep 60
 # Send commands to each pane
 # Pane 0 (first node)
 tmux send-keys -t rust-nodes:0.0 "shard mars mars_creatures.txt Boggles" C-m
-sleep 1
+sleep 2
 
 # Pane 1 (second node)
 tmux send-keys -t rust-nodes:0.1 "shard earth earth_creatures.txt Unicorns" C-m
 sleep 2
 
 # Pane 2 (third node)
 tmux send-keys -t rust-nodes:0.2 "shard mars mars_creatures.txt Inkls" C-m
+sleep 2
 
 # Read and fetch commands
-tmux send-keys -t rust-nodes:0.2 "read mars_creatures.txt" C-m
+tmux send-keys -t rust-nodes:0.0 "read mars_creatures.txt" C-m
 tmux send-keys -t rust-nodes:0.2 "fetch mars mars_creatures.txt" C-m
 tmux send-keys -t rust-nodes:0.1 "fetch earth earth_creatures.txt" C-m
 

examples/sharding/range-based/run_nodes.sh

@@ -15,15 +15,15 @@ sleep 60
 # Send commands to each pane
 # Pane 0 (first node)
 tmux send-keys -t rust-nodes:0.0 "shard 150 song --> Give It Away" C-m
-sleep 7
+sleep 2
 
 # Pane 1 (second node)
 tmux send-keys -t rust-nodes:0.1 "shard 250 song --> Under the Bridge" C-m
-sleep 7
+sleep 2
 
 # Pane 2 (third node)
 tmux send-keys -t rust-nodes:0.2 "shard 55 song --> I Could Have Lied" C-m
-sleep 7
+sleep 2
 
 tmux send-keys -t rust-nodes:0.0 "shard 210 song --> Castles Made of Sand" C-m
 sleep 2
@@ -34,7 +34,8 @@ sleep 2
 
 # Read and fetch commands
 tmux send-keys -t rust-nodes:0.2 "read" C-m
-tmux send-keys -t rust-nodes:0.1 "fetch 150 song" C-m
+tmux send-keys -t rust-nodes:0.1 "fetch 210 song" C-m
+tmux send-keys -t rust-nodes:0.0 "fetch 50 song" C-m
 
 # Attach to the session so you can observe the output
 tmux attach-session -t rust-nodes

research.md

@@ -57,7 +57,7 @@ SwarmNL simplifies data replication across nodes, ensuring consistency and relia
   The raw data received from a replica peer. This field contains a `StringVector`, which is a vector of strings representing the replicated payload.
 
 - **`lamport_clock`**  
-  A critical synchronization and ordering primitive in distributed systems. The Lamport clock is used internally in the replication buffer queue to order messages and data across the replication network. The clock is incremented whenever a node receives a message or sends data for replication. Each node maintains its own Lamport clock, updating it with the highest value received in messages. The replication buffer is implemented as a `BTreeSet`, ordered by this clock.
+  A critical synchronization and ordering primitive in distributed systems. The Lamport clock is used internally in the replication buffer queue to order messages and data across the replica network. The clock is incremented whenever a node receives a message or sends data for replication. Each node maintains its own Lamport clock, updating it with the highest value received in messages. The replication buffer is implemented as a `BTreeSet`, ordered by this clock.
 
 ```rust
    /// Implement Ord.
@@ -142,7 +142,7 @@ Replication is governed by key primitives that define the behavior of individual
   The interval (in seconds) between synchronization attempts for data in the buffer. This ensures efficient utilization of network resources while maintaining data freshness.
 
 - **`consistency_model`**  
-  Defines the level of consistency required for data replication and the behaviour to ensure it. This must be uniform across all nodes in the replication network to prevent inconsistent or undefined behavior.
+  Defines the level of consistency required for data replication and the behaviour to ensure it. This must be uniform across all nodes in the replica network to prevent inconsistent or undefined behavior.
 
 - **`data_aging_period`**  
   The waiting period (in seconds) after data is saved into the buffer before it is eligible for synchronization. This allows for additional processing or validations if needed.
@@ -420,7 +420,7 @@ All nodes within a shard act as replicas of each other and synchronize their dat
 
 By combining replication and sharding, SwarmNL offers a scalable and fault-tolerant framework for managing decentralized networks while giving developers the freedom to design shard configurations that align with their use case.
 
-### **No Central point of failure**
+### No central point of failure
 
 SwarmNL is designed with resilience and fault tolerance at its core, ensuring that the network has no single point of failure. This is achieved by eliminating reliance on coordinator-based algorithms or centralized decision-making mechanisms. Instead, SwarmNL leverages fully decentralized algorithms to handle all network operations, enhancing the robustness and scalability of the system.
 

swarm-nl/doc/core/Replication.md

@@ -4,6 +4,6 @@ After configuring your node for replication, you can participate in replication
 
 - [`Core::replicate`]: Replicates data across replica nodes on the network.
 - [`Core::replicate_buffer`]: Clone a remote node's replica buffer.
-- [`Core::join_repl_network`]: Join a replication network.
-- [`Core::leave_repl_network`]: Exit a replication network.
+- [`Core::join_repl_network`]: Join a replica network.
+- [`Core::leave_repl_network`]: Exit a replica network.
 - Etc.

swarm-nl/src/core/replication.rs

@@ -738,7 +738,7 @@ impl ReplicaBufferQueue {
 			peer: replica_node,
 		};
 
-		// Try to query the replica node and insert data gotten into buffer
+		// Try to query the replica node and insert data received into buffer
 		let mut queue = self.queue.lock().await;
 		match queue.get_mut(&repl_network) {
 			Some(local_state) => {

swarm-nl/src/core/sharding.rs

@@ -82,7 +82,7 @@ where
 		// Free `Core`
 		drop(shard_state);
 
-		// Join the shard network (as a replication network)
+		// Join the shard network (as a replica network)
 		let _ = core.join_repl_network(shard_id.to_string()).await;
 
 		// Inform the entire network about our decision

swarm-nl/src/core/tests/layer_communication.rs

@@ -133,7 +133,7 @@ fn echo_for_node1_query_network() {
 			.await
 		{
 			if let AppResponse::Echo(echoed_response) = result {
-				// Assert that what was sent was gotten back
+				// Assert that what was sent was received
 				assert_eq!(echo_string, echoed_response);
 			}
 		}
@@ -159,7 +159,7 @@ fn echo_for_node1_send_and_receive() {
 			.await
 		{
 			if let AppResponse::Echo(echoed_response) = result {
-				// Assert that what was sent was gotten back
+				// Assert that what was sent was received
 				assert_eq!(echo_string, echoed_response);
 			}
 		}