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.
- 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
go get zde37.com/forge- Go 1.21 or higher
- Make (for build automation)
- mockgen (for generating mocks)
# 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)/binpackage 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)
}
}# 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=120sForge 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 abstractions for consensus mechanisms:
Consensus- Main consensus engine interfaceBlock- Block data structureValidator- Validation logicWorker- Work processing (mining, validation)Storage- Persistence layer
Fluent API for constructing consensus mechanisms:
- Pre-configured builders for common consensus types
- Validation and configuration management
- Factory patterns for PoW, PoS, PBFT, Raft
Distributed work processing framework:
- Worker pools with multiple distribution strategies
- Concurrent job processing
- Metrics and throughput tracking
Flexible validation pipeline:
- Sequential and parallel validation modes
- Composable validators
- Rich error reporting
Extensibility through plugins:
- Hook system with 14+ injection points
- Event bus with pub/sub pattern
- Extension registry for custom logic
Multiple storage backends:
- In-memory storage for testing
- File-based persistent storage
- Transaction support with rollback
Comprehensive observability:
- Counters, gauges, histograms, summaries
- Prometheus exposition format
- System and application metrics
Robust error management:
- Structured error types
- Retry with exponential backoff
- Circuit breaker pattern
- Panic recovery
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 metricscd 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# 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 all mocks
make mocks
# Clean and regenerate
make refresh# Format code
make fmt
# Run linter
make lint
# Run go vet
make vetEach 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
We welcome contributions! Please see our Contributing Guide for details.
- 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
- Follow Go best practices and idioms
- Maintain test coverage above 80%
- Update documentation for new features
- Add examples for complex features
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
This project is licensed under the MIT License - see the LICENSE file for details.
For questions, issues, or suggestions, please open an issue on GitHub or feel free to reach out anytime hi@zde37.com