Welcome to the complete documentation for ChainForge, an educational blockchain implementation built with Ruby, Sinatra, and MongoDB.
- Installation Guide - Set up your development environment
- Quick Start Tutorial - Get your first blockchain running in 5 minutes
- First Blockchain Tutorial - Complete walkthrough with mining examples
- System Overview - High-level architecture and data flow
- Proof of Work Deep Dive - Understanding the mining algorithm
- Data Models - MongoDB schema and relationships
- Security Design - Rate limiting, validation, and security layers
- API Reference - Complete endpoint documentation with examples
- Code Examples - Integration examples in multiple languages
- Rate Limiting - Understanding rate limits and quotas
- Development Setup - Complete development environment guide
- Testing Guide - RSpec, coverage, and CI/CD
- Deployment Guide - Docker and production deployment
- Troubleshooting - Common issues and solutions
- CHANGELOG - Version history and release notes
- CONTRIBUTING - How to contribute to the project
- SECURITY - Security policies and vulnerability reporting
- CLAUDE - Claude Code development guidance
ChainForge is an educational blockchain implementation designed to help developers understand core blockchain concepts through hands-on implementation. It demonstrates:
- Cryptographic Hashing: SHA256-based block linking
- Proof of Work: Mining algorithm with configurable difficulty
- Chain Integrity: Validation and immutability
- API Security: Rate limiting and input validation
- Modern Development: Testing, linting, and CI/CD
ChainForge v2 includes:
- ✅ Proof of Work (PoW) mining with difficulty 1-10
- ✅ Versioned REST API (
/api/v1) - ✅ Rate limiting (Rack::Attack)
- ✅ Input validation (dry-validation)
- ✅ Environment configuration
- ✅ GitHub Actions CI/CD
- ✅ Comprehensive test coverage
Important: ChainForge is a learning-focused project and is NOT intended for production use. It demonstrates blockchain fundamentals but lacks many features required for production systems (authentication, encryption, distributed consensus, P2P networking, etc.).
Use ChainForge to:
- ✅ Learn blockchain fundamentals
- ✅ Understand Proof of Work
- ✅ Experiment with mining algorithms
- ✅ Study API security patterns
- ✅ Practice Ruby development
Do NOT use ChainForge for:
- ❌ Production applications
- ❌ Cryptocurrency implementation
- ❌ Storing valuable data
- ❌ Distributed systems
- Installation Guide - Install prerequisites and dependencies
- Quick Start - Run your first blockchain in 5 minutes
- API Reference - Start making API calls
- Development Setup - Configure your dev environment
- Testing Guide - Write and run tests
- Architecture Overview - Understand the system design
- CONTRIBUTING - Contribution guidelines
- Development Setup - Set up your fork
- Testing Guide - Ensure quality
A blockchain is a distributed ledger of transactions organized into blocks. Each block contains:
- Data (transactions or information)
- A cryptographic hash of the previous block
- A timestamp
- A nonce (number used once)
Blocks are linked together through their hashes, creating an immutable chain where altering any block invalidates all subsequent blocks.
Proof of Work (PoW) is a consensus mechanism that requires computational work to add blocks to the chain. Miners must find a nonce value that, when hashed with the block data, produces a hash meeting specific criteria (e.g., starting with a certain number of zeros).
This makes it computationally expensive to modify the blockchain, providing security against tampering.
ChainForge validates chain integrity by checking:
- Each block's hash matches its calculated hash
- Each block's hash meets its difficulty requirement (PoW)
- Each block's
previous_hashmatches the prior block's hash
If any check fails, the chain is invalid.
- Language: Ruby 3.2.2
- Web Framework: Sinatra 4.0
- Database: MongoDB (via Mongoid ODM)
- Testing: RSpec 3.10 + SimpleCov
- Code Quality: RuboCop 1.57
- Security: Rack::Attack (rate limiting), dry-validation (input validation)
- CI/CD: GitHub Actions
This documentation is organized into four main sections:
Step-by-step tutorials for new users to install, configure, and run ChainForge.
In-depth explanations of system design, data models, algorithms, and security.
Complete API reference with endpoints, request/response formats, and integration examples.
Guides for developers contributing to or deploying ChainForge.
- Installation Issues: See Troubleshooting Guide
- API Questions: Check API Reference
- Contributing: Read CONTRIBUTING
- Security Issues: Report via SECURITY
MIT License - See LICENSE file for details.
Built as a learning exercise to understand blockchain technology. Special thanks to the blockchain community for educational resources and inspiration.
Ready to start? Head to the Quick Start Tutorial to create your first blockchain in 5 minutes!