go-pow-lab

A comprehensive experimental laboratory for Proof-of-Work (PoW) algorithms in Go.

Overview

go-pow-lab is a research and benchmarking framework that allows developers and researchers to implement, compare, benchmark, visualize, and analyze PoW algorithms under controlled and configurable conditions.

This is not a blockchain implementation, but rather a specialized toolkit for studying PoW algorithms in isolation.

Features

• 🔧 Modular Design: Pluggable PoW algorithm architecture
• ⚡ Multiple Algorithms: SHA-256, Double SHA-256, Scrypt, Argon2, RandomX-like, and custom PoW
• 📊 Comprehensive Benchmarking: Performance testing with detailed metrics
• 🔍 Statistical Analysis: Mean, median, variance, and difficulty curve analysis
• ⚙️ Configurable Mining: Multi-threaded workers with adjustable parameters
• 🎯 Difficulty Management: Dynamic difficulty adjustment and target conversion
• 💻 CLI Tool: Full-featured command-line interface
• 📚 Library Usage: Import as a Go package in your own projects

Installation

As a CLI Tool

go install github.com/BaseMax/go-pow-lab/cmd/go-pow-lab@latest

As a Library

go get github.com/BaseMax/go-pow-lab

Quick Start

Using the CLI

# List available algorithms
go-pow-lab list

# Mine with SHA-256
go-pow-lab mine -a sha256 -d 100 -t 4

# Benchmark an algorithm
go-pow-lab benchmark -a argon2id -d 50 -r 5

# Compare multiple algorithms
go-pow-lab compare -d 100 -t 4

# Verify a solution
go-pow-lab verify -a sha256 -i "hello world" -n 12345 -d 100

Using as a Library

package main

import (
    "fmt"
    "github.com/BaseMax/go-pow-lab/api"
    "github.com/BaseMax/go-pow-lab/miner"
    "github.com/BaseMax/go-pow-lab/pow"
)

func main() {
    // Create a PoW algorithm
    powAlg := pow.NewSHA256()
    
    // Setup miner configuration
    config := api.WorkerConfig{
        ThreadCount: 4,
        BatchSize:   1000,
        MaxTime:     30, // seconds
    }
    
    // Create miner
    m := miner.New(powAlg, config)
    
    // Set difficulty and mine
    target := powAlg.DifficultyToTarget(100.0)
    result := m.Mine([]byte("Hello, PoW!"), target)
    
    if result.Success {
        fmt.Printf("Found nonce: %d\n", result.Nonce)
        fmt.Printf("Hash: %x\n", result.Hash)
    }
}

Supported Algorithms

Algorithm	Description	Use Case
SHA-256	Single SHA-256 hash	Fast, simple PoW
Double SHA-256	Bitcoin-style double hash	Blockchain simulation
Scrypt	Memory-hard algorithm	ASIC-resistant mining
Argon2i	Side-channel resistant	Password hashing adapted for PoW
Argon2id	Hybrid mode Argon2	Balanced security/performance
RandomX-Like	CPU-intensive simulation	Fair CPU mining
ToyPoW	Simple custom algorithm	Experimentation and learning

Architecture

go-pow-lab/
├── cmd/go-pow-lab/    # CLI application
├── api/               # Core interfaces and types
├── pow/               # PoW algorithm implementations
├── difficulty/        # Difficulty adjustment logic
├── miner/             # Mining simulation engine
├── verifier/          # Hash verification
├── benchmark/         # Performance testing
├── stats/             # Statistical analysis
├── config/            # Configuration system
├── internal/utils/    # Internal utilities
└── examples/          # Example programs

CLI Commands

mine

Mine for a valid nonce using specified algorithm:

go-pow-lab mine -a sha256 -d 100 -t 4 -i "test data"

Options:

• -a, --algorithm: PoW algorithm (default: sha256)
• -d, --difficulty: Mining difficulty (default: 1.0)
• -t, --threads: Number of worker threads (default: 4)
• -i, --input: Input data to mine (default: "hello world")
• -m, --max-time: Maximum time in seconds (0 for unlimited)

benchmark

Benchmark algorithm performance:

go-pow-lab benchmark -a argon2id -d 50 -r 5 --hash-rate

Options:

• -r, --runs: Number of benchmark runs (default: 1)
• --hash-rate: Run hash rate test instead of mining
• --duration: Duration for hash rate test in seconds (default: 5)

compare

Compare multiple algorithms side-by-side:

go-pow-lab compare -d 100 -A sha256,scrypt,argon2id

Options:

• -A, --algorithms: Comma-separated list of algorithms (default: all)

verify

Verify a PoW solution:

go-pow-lab verify -a sha256 -i "data" -n 12345 -d 100

stats

Generate statistical analysis from multiple runs:

go-pow-lab stats -a sha256 -d 100 -r 20

Configuration

Configuration can be provided via YAML, JSON, or CLI flags.

Example YAML Config

algorithm: sha256
difficulty: 100.0
workers:
  thread_count: 4
  batch_size: 1000
  max_time: 30
output:
  format: console
  verbose: true
benchmark:
  runs: 5
  algorithms:
    - sha256
    - argon2id
  difficulties:
    - 1.0
    - 10.0
    - 100.0

Use with: go-pow-lab mine -c config.yaml

Examples

See the examples/ directory for complete example programs:

• simple-mine: Basic mining example
• compare: Compare SHA-256 vs Argon2
• difficulty-analysis: Analyze difficulty scaling

Run examples:

go run examples/simple-mine/main.go
go run examples/compare/main.go
go run examples/difficulty-analysis/main.go

Understanding Proof-of-Work

Proof-of-Work is a consensus mechanism that requires computational effort to solve a cryptographic puzzle. Key concepts:

Difficulty

Difficulty determines how hard it is to find a valid solution. Higher difficulty = more computation required.

Target

The target is derived from difficulty. A hash is valid if it's numerically less than or equal to the target.

Nonce

The nonce is a number that miners iterate through to find a hash that meets the target.

Hash Rate

Hash rate measures computational power in hashes per second (H/s, KH/s, MH/s, GH/s).

Development

Building from Source

git clone https://github.com/BaseMax/go-pow-lab.git
cd go-pow-lab
go build ./cmd/go-pow-lab

Running Tests

go test ./...

Adding a New PoW Algorithm

1. Create a new file in pow/ (e.g., myalgo.go)
2. Implement the api.ProofOfWork interface
3. Add to the factory in pow/factory.go

Example:

type MyAlgo struct {
    calculator *difficulty.Calculator
}

func (m *MyAlgo) Hash(input []byte) []byte { /* ... */ }
func (m *MyAlgo) Verify(input []byte, nonce uint64, target api.Target) bool { /* ... */ }
func (m *MyAlgo) DifficultyToTarget(diff float64) api.Target { /* ... */ }
func (m *MyAlgo) Name() string { return "MyAlgo" }
func (m *MyAlgo) HashSize() int { return 32 }

Use Cases

• Academic Research: Study PoW algorithm properties
• Algorithm Comparison: Compare performance characteristics
• Performance Analysis: Benchmark different configurations
• Security Research: Analyze attack vectors and vulnerabilities
• Education: Learn how PoW systems work

Requirements

• Go 1.21 or higher
• No external runtime dependencies

Performance Notes

• SHA-256: Fastest, suitable for high-difficulty tests
• Scrypt/Argon2: Memory-intensive, slower but ASIC-resistant
• RandomX-Like: CPU-intensive, balances fairness
• Thread Count: More threads = better performance (up to CPU core count)
• Batch Size: Larger batches reduce synchronization overhead

Limitations

• This is a research tool, not a production blockchain
• No networking or peer-to-peer functionality
• No transaction handling or wallet features
• Simplified difficulty adjustment (not Bitcoin-accurate)

Contributing

Contributions are welcome! Areas for improvement:

• Additional PoW algorithms
• Performance optimizations
• Enhanced statistical analysis
• GPU acceleration support
• WebAssembly compilation
• Visualization tools

License

MIT License - see LICENSE file for details.

Acknowledgments

This project is inspired by various blockchain implementations and cryptographic research. It's designed as an educational and research tool for understanding Proof-of-Work systems.

Contact

• GitHub: @BaseMax
• Repository: go-pow-lab

---

Happy Mining! ⛏️