Skip to content
BranchesTags

Repository files navigation

Blockchain Network Laboratory (NetLab)

An experimental laboratory for studying, testing, and comparing blockchain network layers across multiple generations of blockchain technologies.

Overview

This project implements reference-level network layer samples for multiple blockchains, from oldest to newest technologies. The goal is to observe and compare:

  • How different blockchains implement their networking layers
  • How newer blockchains improve upon or fix limitations of earlier designs
  • How network-layer evolution impacts performance, scalability, reliability, and decentralization

Features

Interactive TUI (Terminal User Interface)

  • Live Blockchain Comparison: Real-time monitoring of multiple blockchains side-by-side
  • 7 Specialized Comparison Criteria:
    • Bootstrap Speed
    • Peer Connectivity
    • Network Topology
    • Bandwidth Efficiency
    • Memory Efficiency
    • All Metrics (comprehensive view)
  • Scrollable Results: Navigate large result sets with keyboard controls
  • Progress Indicators: Real-time metrics updates during tests
  • Beautiful UI: Color-coded, intuitive interface built with Bubble Tea

Command-Line Tools

  • List all implemented blockchains
  • View detailed blockchain information
  • Run comparative benchmarks
  • Generate comprehensive reports
  • View project statistics

Implemented Blockchains

All 10 blockchain implementations are complete with simulated network behavior:

# Blockchain Year Network Innovation Port Status
1 Bitcoin 2009 Foundational P2P gossip protocol 8333 ✅ Complete
2 Litecoin 2011 Faster block time network stress 9333 ✅ Complete
3 Bitcoin Cash 2017 Large block optimizations (Graphene, Xthin) 8444 ✅ Complete
4 Ethereum 2015 State-based sync, DevP2P, RLPx 30303 ✅ Complete
5 Ethereum 2.0 2020 libp2p, gossipsub, discv5 9000 ✅ Complete
6 Cosmos 2019 IBC multi-chain, Tendermint reactors 26656 ✅ Complete
7 Polkadot 2020 Relay/parachain architecture, GRANDPA 30333 ✅ Complete
8 Solana 2020 UDP/QUIC, Turbine, Gulf Stream 8000 ✅ Complete
9 TON 2021 ADNL overlay, infinite sharding 3333 ✅ Complete
10 Chainlink 2017+ OCR 2.0 oracle consensus 5432 ✅ Complete

Project Structure

blockchain-netlab/
├── cmd/
│   └── netlab/              # CLI tool and TUI
│       ├── main.go          # Entry point
│       ├── tui_main.go      # Main TUI interface
│       ├── tui_enhanced_comparison.go  # Live comparison
│       ├── tui.go           # Basic TUI components
│       └── compare.go       # Text-mode comparison
├── internal/
│   ├── common/              # Shared interfaces and utilities
│   └── testing/             # Standardized test framework
├── implementations/         # Blockchain-specific implementations
│   ├── bitcoin/             # Bitcoin network layer
│   ├── litecoin/            # Litecoin network layer
│   ├── bitcoincash/         # Bitcoin Cash network layer
│   ├── ethereum/            # Ethereum 1.0 network layer
│   ├── ethereum2/           # Ethereum 2.0 network layer
│   ├── cosmos/              # Cosmos Hub network layer
│   ├── polkadot/            # Polkadot network layer
│   ├── solana/              # Solana network layer
│   ├── ton/                 # TON network layer
│   └── chainlink/           # Chainlink network layer
├── docs/
│   ├── blockchains/         # Per-blockchain documentation
│   └── architecture/        # Project architecture
├── go.mod
└── README.md

Getting Started

Prerequisites

  • Go 1.21 or later
  • Terminal with 256-color support (for TUI)

Installation

# Clone the repository
git clone https://github.com/mehdi124/blockchain-netlab.git
cd blockchain-netlab

# Build the CLI tool
go build -o netlab ./cmd/netlab

# Run the interactive TUI (recommended)
./netlab

Usage

Interactive TUI (Recommended)

# Launch the interactive interface
./netlab

# Or use the tui command explicitly
./netlab tui

The TUI provides:

  • Main menu with all options
  • Blockchain selection (multi-select with Space)
  • Comparison criteria selection
  • Duration selection (15s, 30s, 1m, 2m, 5m)
  • Live metrics during comparison
  • Scrollable results with keyboard navigation

Command-Line Mode

# List all implemented blockchains
./netlab list

# Show information about a specific blockchain
./netlab info bitcoin

# Compare blockchains (live text mode)
./netlab compare bitcoin ethereum
./netlab compare bitcoin ethereum solana 30s
./netlab compare bitcoin litecoin bitcoincash 1m

# View project statistics
./netlab stats

# Show version
./netlab version

# Show help
./netlab help

Comparison Output

When comparing blockchains, you'll see:

  • Bootstrap Time: Time until first peer connected
  • Peer Count: Number of discovered peers
  • Bandwidth Usage: Bytes sent/received
  • Memory Usage: RAM consumption
  • Live Updates: Metrics refresh every second
  • Comprehensive Results: Detailed analysis with key findings

Keyboard Controls (TUI)

Navigation

  • ↑/↓ or j/k: Move up/down in lists
  • Enter: Select/Confirm
  • Space: Toggle selection (multi-select lists)
  • Esc: Go back
  • q: Quit or stop comparison

Results Screen

  • ↑/↓ or j/k: Scroll line by line
  • PgUp/PgDn: Scroll page by page
  • Space: Page down
  • Home or g: Jump to top
  • End or G: Jump to bottom
  • q or Enter: Back to menu

Comparison Criteria

Bootstrap Speed

Measures how quickly each blockchain:

  • Starts its network stack
  • Discovers first peer
  • Establishes initial connections

Peer Connectivity

Evaluates connection patterns:

  • Total peers discovered
  • Connection stability
  • Network topology

Network Topology

Analyzes network structure:

  • Peer distribution
  • Connection patterns
  • Network efficiency

Bandwidth Efficiency

Compares bandwidth usage:

  • Bytes sent vs received
  • Per-peer bandwidth
  • Network efficiency ratio

Memory Efficiency

Monitors resource usage:

  • Memory per peer
  • Total memory footprint
  • Resource optimization

All Metrics

Comprehensive view of all criteria combined.

Testing Methodology

All blockchains are tested with:

  • Simulated Peers: Realistic peer behavior without full node overhead
  • Bandwidth Tracking: Accurate sent/received byte counts
  • Standardized Duration: Fair comparison with same test time
  • Isolated Ports: No conflicts between blockchain implementations
  • Clean Shutdown: Proper goroutine synchronization

Documentation

Detailed documentation for each blockchain's network layer:

Contributing

This is an open-source research project. Contributions are welcome:

  • Accuracy improvements to network implementations
  • Additional test cases
  • Performance optimizations
  • Documentation improvements
  • Bug fixes and enhancements

Please ensure:

  • Implementations are faithful to original designs
  • All changes include appropriate tests
  • Documentation is updated
  • Commits are clean and well-described

License

MIT License - See LICENSE file for details

Acknowledgments

This project is built on the research and implementation work of numerous blockchain projects. Each implementation references original specifications and implementations.

Project Status: ✅ COMPLETE Version: 1.0.0 Last Updated: 2026-02-06

🎉 All Features Complete:

  • 10 blockchain implementations
  • Interactive TUI with live comparison
  • 7 specialized comparison criteria
  • Scrollable results with full keyboard navigation
  • ~25,000+ lines of code
  • Comprehensive documentation

About

blockchain-netlab is a Go-based laboratory for experimenting with and understanding networking layers across different blockchain protocols.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages