zde37.com/forge

Forge - Consensus-Agnostic Blockchain Framework

Forge is a flexible, production-ready framework for building blockchain consensus mechanisms in Go. It provides a comprehensive set of abstractions and utilities that enable developers to implement any consensus algorithm (PoW, PoS, BFT, etc.) without reinventing common blockchain infrastructure.

🎯 Key Features

• Consensus-Agnostic Design - Implement any consensus algorithm using clean interfaces
• Plugin Architecture - Extensible system with hooks, events, and custom extensions
• Production-Ready Components - Battle-tested implementations for common blockchain needs
• Comprehensive Testing - Full test coverage with mocks and integration tests
• Performance Monitoring - Built-in metrics collection with Prometheus support
• Example Implementations - Complete proof-of-work example to learn from

🚀 Installation

go get zde37.com/forge

Requirements

• Go 1.21 or higher
• Make (for build automation)
• mockgen (for generating mocks)

Install Development Tools

# Install mockgen for mock generation
go install go.uber.org/mock/mockgen@latest

# Install golangci-lint for code quality
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

⚡ Quick Start

1. Using the Framework

package main

import (
    "context"
    "log"

    "zde37.com/forge/builder"
    "zde37.com/forge/interfaces"
)

func main() {
    ctx := context.Background()

    // First, YOU must implement the Consensus interface
    // Forge is a framework - it doesn't provide implementations
    myConsensus := &MyConsensusImplementation{
        // Your consensus logic here
    }

    // Create a builder with your implementation
    consensusBuilder := builder.NewConsensusBuilder(myConsensus)

    // Configure using fluent API
    consensusBuilder.
        WithWorker(&MyWorker{}).                    // Add workers
        WithValidator(&MyValidator{}).              // Add validators
        WithParameter("difficulty", uint64(16)).    // Set parameters
        WithValidationMode("sequential").           // Configure validation
        WithWorkerCount(4)                          // Set worker count

    // Build with context to initialize everything
    consensus, err := consensusBuilder.BuildWithContext(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Start your consensus
    if err := consensus.Start(ctx); err != nil {
        log.Fatal(err)
    }
}

2. Running the Proof-of-Work Example

# Navigate to the example
cd examples/proof-of-work

# Run with default settings
go run cmd/main.go

# Or customize the configuration
go run cmd/main.go -miners=8 -block-interval=5s -duration=120s

🏗️ Architecture

Forge follows a modular, interface-based architecture that separates concerns and enables flexibility:

┌─────────────────────────────────────────────────────────┐
│                    Application Layer                     │
│           (Your Consensus Implementation)                │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                     Forge Framework                      │
├───────────────┬───────────────┬─────────────────────────┤
│   Interfaces  │     Plugin    │        Core             │
│               │     System    │      Components         │
├───────────────┼───────────────┼─────────────────────────┤
│ • Consensus   │ • Hooks       │ • Builder Pattern       │
│ • Block       │ • Events      │ • Worker Pools          │
│ • Validator   │ • Extensions  │ • Validation Pipeline   │
│ • Worker      │ • Registry    │ • Difficulty Calc       │
│ • Storage     │               │ • Hash Functions        │
└───────────────┴───────────────┴─────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                 Infrastructure Layer                     │
├───────────────┬───────────────┬─────────────────────────┤
│    Storage    │    Metrics    │     Error Handling      │
│  • Memory     │  • Collector  │   • Retry Logic         │
│  • File       │  • Prometheus │   • Circuit Breaker     │
│               │  • Tracking   │   • Recovery            │
└───────────────┴───────────────┴─────────────────────────┘

📦 Core Modules

Interfaces

Core abstractions for consensus mechanisms:

• Consensus - Main consensus engine interface
• Block - Block data structure
• Validator - Validation logic
• Worker - Work processing (mining, validation)
• Storage - Persistence layer

Builder

Fluent API for constructing consensus mechanisms:

• Pre-configured builders for common consensus types
• Validation and configuration management
• Factory patterns for PoW, PoS, PBFT, Raft

Worker

Distributed work processing framework:

• Worker pools with multiple distribution strategies
• Concurrent job processing
• Metrics and throughput tracking

Validation

Flexible validation pipeline:

• Sequential and parallel validation modes
• Composable validators
• Rich error reporting

Plugin System

Extensibility through plugins:

• Hook system with 14+ injection points
• Event bus with pub/sub pattern
• Extension registry for custom logic

Storage

Multiple storage backends:

• In-memory storage for testing
• File-based persistent storage
• Transaction support with rollback

Metrics

Comprehensive observability:

• Counters, gauges, histograms, summaries
• Prometheus exposition format
• System and application metrics

Error Handling

Robust error management:

• Structured error types
• Retry with exponential backoff
• Circuit breaker pattern
• Panic recovery

🔧 Examples

Proof-of-Work Implementation

The examples/proof-of-work directory contains a complete Bitcoin-style PoW implementation:

# Features demonstrated:
- Multi-threaded mining with worker pools
- Dynamic difficulty adjustment
- Transaction pool management
- Block validation pipeline
- Event-driven architecture
- Real-time metrics

Running the Example

cd examples/proof-of-work

# Basic run
go run cmd/main.go

# With custom parameters
go run cmd/main.go \
    -miners=8 \              # Number of mining workers
    -tx-generators=5 \       # Transaction generators
    -tx-rate=200ms \         # Transaction generation rate
    -block-interval=10s \    # Target block time
    -duration=300s           # Run duration

🧪 Testing

Run Tests

# Run all tests
make test

# Run with race detection
make test-race

# Generate coverage report
make test-coverage

# Run specific module tests
go test ./worker/... -v

Generate Mocks

# Generate all mocks
make mocks

# Clean and regenerate
make refresh

Code Quality

# Format code
make fmt

# Run linter
make lint

# Run go vet
make vet

📖 Documentation

Module Documentation

Each module has detailed documentation in the main doc file:

• Builder Module - Consensus construction patterns
• Worker Module - Distributed work processing
• Validation Module - Validation pipeline architecture
• Plugin Module - Extensibility and hooks
• Storage Module - Persistence layer
• Metrics Module - Observability and monitoring
• Error Module - Error handling strategies

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Code Standards

• Follow Go best practices and idioms
• Maintain test coverage above 80%
• Update documentation for new features
• Add examples for complex features

📊 Performance

Forge is designed for production use with excellent performance characteristics:

• Concurrent Processing - Leverage Go's goroutines for parallel execution
• Memory Efficient - Minimal allocations with pooling where appropriate
• Scalable - Worker pools scale with available CPU cores
• Observable - Built-in metrics for performance monitoring

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions, issues, or suggestions, please open an issue on GitHub or feel free to reach out anytime [e-mail]