Skip to content

README.md

Latest commit

 

History

History
260 lines (201 loc) · 8.45 KB

README.md

File metadata and controls

260 lines (201 loc) · 8.45 KB

🎯 Consensus Engine

An interactive educational tool to learn and understand different consensus protocols in distributed systems and blockchain networks. This engine supports multiple consensus algorithms, allowing students and developers to compare and learn how different consensus mechanisms work in practice.

🌟 Features

  • Multiple Consensus Protocols: Choose between BFT and Stellar Consensus Protocol (SCP)
  • Interactive CLI Interface: User-friendly command-line interface with help system
  • Educational Output: Detailed explanations of each step in the consensus process
  • Mining Simulation: Proof-of-work mining simulation with visual feedback
  • Multi-Node Support: Connect multiple nodes to form a distributed network
  • Real-Time Consensus: Watch consensus happen in real-time across nodes
  • Blockchain Validation: Built-in blockchain integrity validation
  • Visual Status Tracking: Colorful emojis and clear status messages

📚 Supported Consensus Protocols

1. BFT (Byzantine Fault Tolerance)

  • Traditional BFT consensus with 2/3 majority voting
  • Fixed threshold consensus
  • Best for learning classic BFT concepts
  • Documentation: See docs/BFT.md

2. SCP (Stellar Consensus Protocol)

  • Federated Byzantine Agreement (FBA)
  • Quorum slice-based consensus
  • Flexible trust relationships
  • Best for learning modern consensus with flexible trust
  • Documentation: See docs/SCP.md

🚀 Getting Started

Prerequisites

  • Node.js (v12 or higher)
  • npm

Installation

  1. Clone or download this repository
  2. Install dependencies: 
    npm install

Quick Start

  1. Start the engine:

    node index.js [port]

    Example: node index.js 6001

  2. Select a consensus protocol:

    • Choose 1 for BFT (Byzantine Fault Tolerance)
    • Choose 2 for SCP (Stellar Consensus Protocol)

  3. Try basic commands:

    propose "Hello Consensus World"
blockchain
status
help

📖 Available Commands

Command Description Example
help Show all available commands help
propose <data> Propose/nominate a new block with data propose "My transaction"
connect <port> Connect to another node connect 6002
status Show current node status status
blockchain Display the blockchain blockchain
validate Validate blockchain integrity validate
explain Detailed consensus explanation explain
demo Show demo scenarios demo
network Show network connection status network
clear Clear screen clear
exit Exit the application exit

🎓 Learning with Multi-Node Networks

Multi-Node Demo

Terminal 1 (Node 1):

node index.js 6001
# Select protocol (1 for BFT or 2 for SCP)

Terminal 2 (Node 2):

node index.js 6002
# Select the SAME protocol as Terminal 1

Terminal 3 (Node 3):

node index.js 6003
# Select the SAME protocol as Terminal 1

Connect the nodes:

  • In Terminal 2: connect 6001
  • In Terminal 3: connect 6001

Test consensus:

  • In Terminal 1: propose "Multi-node consensus test"
  • Watch consensus happen across all terminals! 🎉

🧪 Educational Experiments

Experiment 1: Compare BFT vs SCP

  • Run the same scenario with BFT and SCP
  • Observe the differences in consensus mechanisms
  • Notice how BFT uses fixed 2/3 threshold
  • Notice how SCP uses flexible quorum slices

Experiment 2: Consensus with Different Network Sizes

  • Try with 2, 3, 4, or 5 nodes
  • Observe how consensus threshold changes in BFT
  • Observe how quorum slices work in SCP
  • Note: With 2 nodes, both must agree (100% consensus needed in BFT)

Experiment 3: Network Partitions

  • Start 3 nodes, connect them all
  • Disconnect one node during consensus
  • Observe how the remaining nodes handle consensus
  • Compare behavior between BFT and SCP

Experiment 4: Concurrent Proposals

  • Have multiple nodes propose blocks simultaneously
  • See how the network handles competing proposals
  • Only one block will achieve consensus based on timing and votes

Experiment 5: Blockchain Validation

  • Create several blocks in sequence
  • Use the validate command to check blockchain integrity
  • Try manually modifying a block and see validation fail

🔧 Technical Details

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Node 6001     │    │   Node 6002     │    │   Node 6003     │
│                 │◄──►│                 │◄──►│                 │
│  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
│  │Blockchain │  │    │  │Blockchain │  │    │  │Blockchain │  │
│  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
│  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
│  │Consensus  │  │    │  │Consensus  │  │    │  │Consensus  │  │
│  │Engine     │  │    │  │Engine     │  │    │  │Engine     │  │
│  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Key Components

  • Block: Represents a block in the blockchain with hash, data, and metadata
  • Blockchain: Manages the chain of blocks with validation
  • Node: Manages consensus, networking, and blockchain state
  • NetworkManager: Handles peer-to-peer connections
  • ConsensusEngine: Main CLI interface and protocol selection

Network Protocol

Simple JSON message protocol over TCP:

{
  "type": "VOTE" | "NOMINATION" | "BALLOT",
  "blockHash": "abc123...",
  "voterNodeId": "Node-6001",
  "blockIndex": 1
}

📚 Documentation

🎓 Learning Objectives

After using this tool, you should understand:

  • How different consensus protocols work in distributed systems
  • The differences between BFT and Federated Byzantine Agreement
  • Why consensus thresholds matter (2/3 in BFT vs quorum slices in SCP)
  • The role of mining/proof-of-work in blockchain systems
  • How nodes communicate and vote in a distributed network
  • Blockchain validation and integrity checking
  • The challenges of achieving consensus in distributed systems

🔍 Understanding the Output

Mining Output

🔨 Mining block 1...
📊 Target: Hash must start with 00
⚡ Mining attempt 10000: a7f3d2e1...
✅ Block mined! Nonce: 15847, Hash: 00a7f3d2...

Consensus Output (BFT)

🗳️  CONSENSUS PHASE:
   Required votes: 2 out of 3 nodes
   Current votes: 1 (self-vote)
📡 Broadcasting vote for block 1 to 2 peers...

🗳️  VOTE RECEIVED:
   From: Node-6002
   Block: 00a7f3d2e1b5c8f9...
   Current votes: 2/2

🎉 CONSENSUS REACHED!
   Block 1 has been accepted by the network!

Consensus Output (SCP)

📨 NOMINATION RECEIVED:
   From: SCP-Node-6002
   Block: 00a7f3d2e1b5c8f9...

🗳️  BALLOT PHASE:
   Voted: ACCEPT for block 00a7f3d2e1b5c8f9...
   Current votes: 2/2 (need majority of quorum slice)

🎉 QUORUM REACHED! (SCP Consensus):
   Block 1 has been accepted by the network!

🤝 Contributing

This is an educational tool! Feel free to:

  • Add new consensus protocols
  • Improve the educational explanations
  • Add visualization features
  • Enhance the CLI interface
  • Add more comprehensive examples
  • Fix bugs or improve code quality

📄 License

ISC

🔗 Resources

Happy Learning! 🎓