A production-ready blockchain implementation in Go with complete cryptocurrency trading platform features including digital signatures, transaction validation, block mining, market simulation, and real-time data streaming.
- Digital Wallet System - RSA-2048 key pairs for secure wallet creation
- Challenge-Response Authentication - Secure login without storing passwords
- JWT Authentication - Protected endpoints with token-based auth
- Digital Signatures - Sign and verify transactions using RSA encryption
- Transaction Nonce System - Prevent double-spending and replay attacks
- Transaction Fees - Dynamic fee calculation paid to miners
- Block Rewards - Halving schedule every 210,000 blocks (Bitcoin-like)
- Miner Rewards - All fees and coinbase rewards go to miner wallet
- Ledger System - Double-entry bookkeeping for all balance changes
- Proof of Work Mining - SHA256-based with configurable difficulty
- Dynamic Difficulty - Auto-adjusts every 10 blocks targeting 10s block time
- Merkle Tree - Transaction integrity verification with SPV support
- Blockchain Integrity - Complete chain validation with PoW verification
- Market Simulation - Real-time price discovery from buy/sell transactions
- Buy/Sell Orders - Execute market orders with instant settlement
- Market Ticks - Track price, volume, and transaction count per block
- Liquidity Pool - Initial liquidity for price stability
- OHLCV Candles - Multi-timeframe candlestick data (1m, 5m, 15m, 30m, 1h, 4h, 1d)
- Candle Aggregation - Automated worker for historical data generation
- WebSocket Streaming - Real-time market updates via WebSocket
- SSE (Server-Sent Events) - Real-time candle updates per interval
- Redis Pub/Sub - Scalable real-time data distribution
- Background Workers - Async block generation and candle aggregation
- Worker Pool Pattern - Concurrent job processing with timeout protection
- Graceful Shutdown - Proper cleanup of workers, connections, and resources
- Connection Pooling - Optimized MySQL and Redis connections
- Context Cancellation - Timeout handling for long-running operations
- Bulk Operations - 95% performance improvement with batch processing
- Indexed Queries - Optimized database schema with proper indexes
- Caching Layer - Redis-based caching for frequently accessed data
- Async Transaction Processing - Non-blocking transaction submission with queuing
- Multiple Workers - Configurable worker pool for concurrent transaction processing
- Retry Logic - Automatic message requeue on processing failure
- Transaction Types - Support for SEND, BUY, and SELL transaction types
- Message Durability - Persistent queues with durable exchanges
- Topic Routing - Advanced message routing based on routing keys
- Graceful Shutdown - Proper consumer cleanup on application termination
- Error Handling - Failed messages logged and requeued for retry
- REST API - 30+ endpoints for complete blockchain operations
- CORS Support - Multi-origin configuration for frontend integration
- WebSocket Hub - Pub/Sub system for real-time client updates
- SSE Streaming - HTTP streaming for candle data
- Health Checks - Ping endpoints for monitoring
- Error Handling - Structured error responses with proper HTTP codes
- Transaction Validation - Multi-layer validation before mining
- Balance Verification - Prevent overspending with real-time checks
- Signature Verification - Cryptographic proof of ownership
- Nonce Tracking - Redis-based nonce management
- Rate Limiting - Protect against spam (via Redis)
- Input Sanitization - Prevent injection attacks
- ✅ RabbitMQ Integration - Complete message queue setup with channel pooling
- ✅ Transaction Consumer - Async transaction processing with multiple workers
- ✅ Queue Topology - Exchanges, queues, and routing configuration
- ✅ Retry Mechanism - Automatic message requeue on failure
- ✅ Worker Pool - Configurable worker count for scaling
- ✅ Graceful Shutdown - Proper consumer cleanup on application termination
- ✅ Error Handling - Comprehensive logging and error management
- ✅ Market Engine - Complete trading system with buy/sell orders
- ✅ OHLCV Candles - Multi-timeframe candlestick generation
- ✅ Real-time Streaming - WebSocket + SSE for live updates
- ✅ Redis Pub/Sub - Scalable real-time architecture
- ✅ Worker System - Background jobs for block & candle generation
- ✅ Graceful Shutdown - Production-ready lifecycle management
- ✅ Context Handling - Timeout protection for all operations
- ✅ Blockchain Core - Complete PoW blockchain with rewards
- ✅ Wallet System - RSA key generation and management
- ✅ Transaction System - Full UTXO-like transaction flow
- ✅ Mining System - PoW with difficulty adjustment
- ✅ Ledger System - Accurate balance tracking
- Learning Blockchain - Understand cryptocurrency fundamentals
- Trading Simulation - Test trading strategies risk-free
- Algorithm Testing - Backtest trading algorithms with historical data
- Real-time Analytics - Monitor market data with WebSocket/SSE
- API Integration - Build frontend applications with REST API
- Research - Study blockchain consensus and economic models
- Go 1.23.0 or higher
- MySQL 8.0 or higher
- Redis 6.0 or higher (for caching and pub/sub)
- RabbitMQ 3.8 or higher (for async transaction processing)
- Make (optional, for using Makefile commands)
Get the application running in 5 minutes:
# 1. Clone and setup
git clone https://github.com/livingdolls/go-blockchain-simulate.git
cd go-blockchain-simulate
go mod download
# 2. Start services (requires Docker)
docker-compose up -d mysql redis rabbitmq
# 3. Setup database migrations
mysql -u root -p < database/migrations/users.sql
mysql -u root -p < database/migrations/transactions.sql
# ... run all migration files
# 4. Start application
go run main.go
# 5. Test API
curl -X POST http://localhost:3010/register \
-H "Content-Type: application/json" \
-d '{"initial_balance": 1000}'Access:
- API: http://localhost:3010
- RabbitMQ Dashboard: http://localhost:15672 (guest:guest)
- Database: localhost:3306
- Redis: localhost:6379
-
Clone the repository
git clone https://github.com/livingdolls/go-blockchain-simulate.git cd go-blockchain-simulate -
Install dependencies
go mod download
-
Setup MySQL Database
mysql -u root -p < database/migrations/users.sql mysql -u root -p < database/migrations/transactions.sql mysql -u root -p < database/migrations/ledger.sql mysql -u root -p < database/migrations/block.sql mysql -u root -p < database/migrations/user_balance_history.sql mysql -u root -p < database/migrations/market_engine.sql
Or manually create the database:
CREATE DATABASE blockchain_db; USE blockchain_db; -- Run all migration files from database/migrations/
-
Setup Redis
# Install Redis (Ubuntu/Debian) sudo apt-get install redis-server # Start Redis sudo systemctl start redis-server # Verify Redis is running redis-cli ping # Should return "PONG"
-
Configure Environment
Update database and Redis credentials in the code:
- Database:
database/conn.go - Redis:
redis/redis.go - JWT Secret:
main.go(line 29)
- Database:
-
Setup RabbitMQ
# Install RabbitMQ (Ubuntu/Debian) sudo apt-get install rabbitmq-server # Start RabbitMQ sudo systemctl start rabbitmq-server # Enable RabbitMQ management UI sudo rabbitmq-plugins enable rabbitmq_management # Verify RabbitMQ is running sudo rabbitmqctl status # Access Management UI: http://localhost:15672 (guest:guest)
Or using Docker Compose:
docker-compose up -d rabbitmq
make run # Run the application
make build # Build binary
make clean # Clean build filesgo run main.godocker-compose up -dThe API will start on http://localhost:3010
Create a new wallet with RSA key pair.
POST /register
Content-Type: application/json
{
"initial_balance": 1000
}Response:
{
"success": true,
"data": {
"address": "0x1a2b3c4d...",
"public_key": "-----BEGIN PUBLIC KEY-----\n...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"balance": 1000
}
}Request a challenge for signature verification.
POST /challenge/:addressResponse:
{
"success": true,
"data": {
"challenge": "random_string_to_sign"
}
}Submit signed challenge for JWT token.
POST /challenge/verify
Content-Type: application/json
{
"address": "0x1a2b3c4d...",
"signature": "signed_challenge_string"
}Response:
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs..."
}
}Transfer funds between wallets.
POST /send
Content-Type: application/json
{
"from_address": "0x1a2b3c4d...",
"to_address": "0x5e6f7g8h...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"amount": 50,
"nonce": 1
}Response:
{
"success": true,
"data": {
"id": 123,
"from_address": "0x1a2b3c4d...",
"to_address": "0x5e6f7g8h...",
"amount": 50,
"fee": 0.001,
"signature": "...",
"status": "PENDING",
"nonce": 1
}
}Execute market buy order.
POST /transaction/buy
Content-Type: application/json
{
"address": "0x1a2b3c4d...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"amount": 10,
"nonce": 2
}Execute market sell order.
POST /transaction/sell
Content-Type: application/json
{
"address": "0x1a2b3c4d...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"amount": 5,
"nonce": 3
}Retrieve transaction details.
GET /transaction/:idGet next available nonce for address.
GET /generate-tx-nonce/:addressResponse:
{
"success": true,
"data": {
"nonce": 4
}
}Check wallet balance from ledger.
GET /balance/:addressResponse:
{
"success": true,
"data": {
"address": "0x1a2b3c4d...",
"balance": 950.5
}
}Get complete wallet information.
GET /wallet/:addressMine a new block (manual trigger).
POST /generate-blockResponse:
{
"success": true,
"data": {
"block_number": 42,
"current_hash": "00001a2b3c...",
"previous_hash": "000034f5a6...",
"nonce": 142536,
"difficulty": 4,
"merkle_root": "abc123def456...",
"timestamp": 1735689600,
"transactions_count": 7
},
"message": "Block mined successfully"
}Note: Blocks are also auto-generated every 10 seconds by background worker.
Retrieve blockchain with transactions.
GET /blocksGet specific block by database ID.
GET /blocks/:idGet specific block by block number.
GET /blocks/detail/:numberValidate entire blockchain.
GET /blocks/integrityResponse:
{
"success": true,
"data": {
"valid": true,
"total_blocks": 42,
"invalid_blocks": []
}
}Get block reward for specific block number.
GET /reward/schedule/:numberResponse:
{
"success": true,
"data": {
"block_number": 100,
"reward": 50,
"halving_epoch": 0
}
}Get reward for mined block.
GET /reward/block/:numberGet current reward schedule information.
GET /reward/infoGet current market engine state.
GET /marketResponse:
{
"success": true,
"data": {
"price": 100.065,
"liquidity": 1000000,
"last_block": 42,
"updated_at": "2025-12-31T10:30:00Z"
}
}Get OHLCV candles for specific interval.
GET /candles?interval=1m&limit=100Parameters:
interval:1m,5m,15m,30m,1h,4h,1dlimit: Number of candles (default: 100)
Response:
{
"success": true,
"data": [
{
"id": 1,
"interval_type": "1m",
"start_time": 1735689600,
"open_price": 100.05,
"high_price": 100.08,
"low_price": 100.04,
"close_price": 100.065,
"volume": 150.5
}
]
}Get candles from specific timestamp.
GET /candles/range?interval=1h&start_time=1735689600&limit=50Real-time market updates via WebSocket.
const ws = new WebSocket("ws://localhost:3010/ws/market");
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log("Market update:", data);
};Real-time candle updates via Server-Sent Events.
const es = new EventSource("http://localhost:3010/sse/candles?interval=1m");
es.onmessage = (event) => {
const candle = JSON.parse(event.data);
console.log("New candle:", candle);
};Health check for SSE connection.
GET /sse/pingGet user profile (requires JWT token).
GET /profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...Response:
{
"success": true,
"data": {
"address": "0x1a2b3c4d...",
"balance": 950.5,
"public_key": "..."
}
}go-blockchain-simulate/
├── app/
│ ├── dto/ # Data Transfer Objects
│ │ ├── candle.go # Candle DTOs
│ │ └── http.go # HTTP response wrappers
│ ├── entity/ # Domain entities
│ │ ├── error.go # Custom error types
│ │ └── event.go # Event types for pub/sub
│ ├── handler/ # HTTP request handlers
│ │ ├── balance.go # Balance endpoints
│ │ ├── block.go # Block endpoints
│ │ ├── candles.go # Candle data endpoints
│ │ ├── jwt-middleware.go # Authentication middleware
│ │ ├── market.go # Market engine endpoints
│ │ ├── register.go # User registration
│ │ ├── reward.go # Block reward endpoints
│ │ ├── streams_candle.go # SSE streaming handler
│ │ ├── transaction.go # Transaction endpoints
│ │ └── user.go # User profile endpoints
│ ├── models/ # Database models
│ │ ├── block.go # Block model
│ │ ├── candles.go # Candle model
│ │ ├── market.go # Market engine model
│ │ ├── register.go # User model
│ │ ├── reward.go # Reward model
│ │ ├── transaction.go # Transaction model
│ │ ├── user.go # User account model
│ │ └── wallet.go # Wallet model
│ ├── port/ # Interface ports
│ │ └── message_broker.go # Pub/sub interface
│ ├── publisher/ # Event publishers
│ │ └── ws.go # WebSocket publisher
│ ├── repository/ # Data access layer
│ │ ├── block.go # Block repository
│ │ ├── candles.go # Candles repository
│ │ ├── ledger.go # Ledger repository
│ │ ├── market.go # Market repository
│ │ ├── transaction.go # Transaction repository
│ │ └── user.go # User repository
│ ├── services/ # Business logic layer
│ │ ├── balance.go # Balance calculation service
│ │ ├── block.go # Block mining service
│ │ ├── candles.go # Candle service
│ │ ├── candles_stream.go # Candle streaming service
│ │ ├── event.go # Event handling service
│ │ ├── market.go # Market engine service
│ │ ├── profile.go # User profile service
│ │ ├── register.go # Registration service
│ │ ├── reward.go # Reward calculation service
│ │ ├── transaction.go # Transaction service
│ │ └── verify.go # Signature verification service
│ ├── websocket/ # WebSocket infrastructure
│ │ ├── client.go # WebSocket client
│ │ ├── handler.go # WebSocket handler
│ │ ├── message.go # Message types
│ │ └── websocket.go # Hub implementation
│ └── worker/ # Background workers
│ ├── generate-block.go # Auto block mining worker
│ └── generate-candle.go # Candle aggregation worker
├── database/ # Database layer
│ ├── conn.go # MySQL connection
│ └── migrations/ # SQL migration files
│ ├── block.sql
│ ├── ledger.sql
│ ├── market_engine.sql
│ ├── reset_genesis.sql
│ ├── transactions.sql
│ ├── user_balance_history.sql
│ └── users.sql
├── docs/ # Documentation
│ ├── generate_block_flow.md
│ ├── register_flow.md
│ └── transaction_flow.md
├── redis/ # Redis layer
│ ├── redis.go # Redis client
│ └── redis-service.go # Redis service adapter
├── security/ # Security utilities
│ └── jwt.go # JWT token management
├── utils/ # Utility functions
│ ├── candles-interval.go # Interval utilities
│ ├── fake-crypto.go # Test data generator
│ ├── fee.go # Fee calculation
│ ├── merkle_root.go # Merkle tree implementation
│ ├── mnemonic.go # Mnemonic phrase generator
│ ├── pow.go # Proof of Work implementation
│ ├── prefixed-hash.go # Hash utilities
│ ├── random-hex.go # Random string generator
│ ├── reward-calc.go # Reward calculation
│ └── sse_setup.go # SSE setup utilities
├── view/ # Frontend (Next.js)
│ ├── app/ # Next.js app directory
│ ├── components/ # React components
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Frontend utilities
│ ├── providers/ # React context providers
│ ├── repository/ # API client layer
│ ├── store/ # State management
│ └── types/ # TypeScript types
├── go.mod # Go dependencies
├── go.sum # Go checksums
├── main.go # Application entry point
├── Makefile # Build automation
└── README.md # This file
The system uses RabbitMQ with Topic Exchange pattern for flexible message routing:
| Queue | Exchange | Routing Key | Purpose |
|---|---|---|---|
transaction.pending |
transactions |
transaction.submitted |
Pending transaction processing |
transaction.confirmed |
transactions |
transaction.confirmed |
Confirmed transaction notifications |
block.generation |
blocks |
block.generate |
Block mining requests |
block.mined |
blocks |
block.mined |
New block notifications |
market.pricing |
market |
market.pricing |
Market price updates |
The Transaction Consumer processes SEND, BUY, and SELL transactions asynchronously:
Features:
- Multi-worker Processing - Configurable worker pool (default: 5 workers)
- Concurrent Processing - Handle multiple transactions simultaneously
- Automatic Retry - Failed messages are automatically requeued
- Message Durability - Persistent storage on RabbitMQ
- Graceful Shutdown - Proper cleanup on application termination
- Comprehensive Logging - Detailed logs for debugging
Request Format:
{
"type": "SEND|BUY|SELL",
"address": "0x1a2b3c4d...",
"to_address": "0x5e6f7g8h...", // Only for SEND
"amount": 50.5,
"nonce": "1",
"signature": "signed_data..."
}Processing Flow:
1. Transaction submitted via HTTP endpoint
2. Message published to RabbitMQ queue
3. Consumer picks up message with available worker
4. Transaction processed based on type
5. On success: Message acknowledged, DB updated
6. On error: Message requeued for retry
7. Logs available for monitoring
Example Usage:
# Send transaction (API returns immediately with 202 Accepted)
curl -X POST http://localhost:3010/send \
-H "Content-Type: application/json" \
-d '{
"from_address": "0x1a2b3c4d...",
"to_address": "0x5e6f7g8h...",
"amount": 50,
"nonce": "1",
"signature": "..."
}'
# Response (202 Accepted)
{
"message": "Transaction queued for processing",
"status": "PENDING"
}Access RabbitMQ Management UI:
URL: http://localhost:15672
Username: guest
Password: guest
View consumer details:
# List all consumers
sudo rabbitmqctl list_consumers
# Check queue statistics
sudo rabbitmqctl list_queues name messages consumers
# Monitor exchange bindings
sudo rabbitmqctl list_bindings1. User submits transaction via HTTP endpoint
2. Handler validates input and publishes to RabbitMQ
3. API returns 202 Accepted (non-blocking)
4. Transaction Consumer picks up message
5. Message deserialized based on type (SEND/BUY/SELL)
6. Transaction validated (signature, balance, nonce)
7. Transaction processed in database
8. Message acknowledged to RabbitMQ
9. Worker mines block every 10 seconds
10. Block validation + PoW mining
11. Transactions marked as CONFIRMED
12. Market price updated from buy/sell orders
13. Candle data aggregated per interval
14. Real-time updates sent via WebSocket/SSE
On Error:
- Message processing fails → Nack with requeue
- Failed message goes back to queue
- Another worker retries after backoff
- Detailed logs for debugging
1. Collect PENDING transactions
2. Validate all transactions (balance, signature, nonce)
3. Calculate market price from buy/sell orders
4. Update market_ticks table
5. Calculate Merkle root
6. Perform Proof of Work (find valid nonce)
7. Save block to database
8. Update transaction status to CONFIRMED
9. Record miner rewards in ledger
10. Broadcast block event via WebSocket
11. Trigger candle aggregation
1. Worker runs every 1 minute
2. Check if interval boundary reached (1m, 5m, 1h, etc.)
3. Fetch market_ticks in time window
4. Calculate OHLCV from ticks
5. Upsert candle to database
6. Check if data changed (cache comparison)
7. If changed: Publish to Redis channel
8. SSE clients receive update
9. Frontend updates chart in real-time
Edit database/conn.go:
dsn := "username:password@tcp(localhost:3306)/blockchain_db?parseTime=true"Edit redis/redis.go:
addr: "localhost:6379"
password: "" // leave empty if no password
db: 0Edit main.go:
// RabbitMQ connection (default: amqp://guest:guest@localhost:5672/)
rmqClient, err := rabbitmq.NewClient("amqp://guest:guest@localhost:5672/", 10)
if err != nil {
panic(err)
}
// Configure transaction consumer with worker count
transactionConsumer := worker.NewTransactionConsumer(rmqClient, transactionService, 5)
// Start consumer in background
go func() {
ctx := context.Background()
if err := transactionConsumer.Start(ctx); err != nil {
log.Printf("Failed to start transaction consumer: %v\n", err)
}
}()Configuration options:
poolSize: Channel pool size (default: 10)workerCount: Concurrent workers (default: 5)processingTimeout: Message processing timeout (default: 30s)
Edit main.go:
jwt := security.NewJWTAdapter("your-secret-key-here", 24*time.Hour)Default: 4 (four leading zeros) Auto-adjusts every 10 blocks to target 10s block time.
- Block Worker: 10 seconds (auto-mining)
- Candle Worker: 1 minute (aggregation check)
Edit in main.go:
generateBlockWorker.Start(10 * time.Second)
candleWorker.Start(1 * time.Minute)Edit main.go:
allowedOrigins := map[string]bool{
"http://localhost:3000": true,
"http://localhost:3001": true,
// Add your frontend URLs
}Use the provided rest.http file with VS Code REST Client extension:
# Install VS Code REST Client extension
code --install-extension humao.rest-client
# Open rest.http and click "Send Request"- Register 2 wallets
- Send transaction between wallets
- Execute buy/sell orders
- Wait for block generation (10s)
- Check balances and market price
- Query candle data
- Test real-time streaming (WebSocket/SSE)
- Postman Collection: Import endpoints from README
- cURL: All examples use standard HTTP
- REST Client: VS Code extension with
rest.http
- Block Mining Time: 5-15 seconds (depends on difficulty)
- Transaction Validation: <100ms
- API Response Time: <50ms (average)
- Bulk Operations: 95% faster than individual inserts
- WebSocket Latency: <10ms
- SSE Latency: <50ms
- Database Queries: Optimized with indexes
- Concurrent Requests: Supports 1000+ req/s
# Check MySQL is running
sudo systemctl status mysql
# Test connection
mysql -u username -p -h localhost# Check Redis is running
sudo systemctl status redis-server
# Test connection
redis-cli ping# Check RabbitMQ is running
sudo systemctl status rabbitmq-server
# Test connection
sudo rabbitmqctl status
# Reset RabbitMQ (if needed)
sudo rabbitmqctl reset
sudo rabbitmqctl start_appSymptoms: API returns 202 but transactions not in database
# Check RabbitMQ has messages in queue
sudo rabbitmqctl list_queues name messages
# View consumer details
sudo rabbitmqctl list_consumers
# Check application logs for errors
tail -f logs/app.log | grep TRANSACTION_CONSUMER
# Purge queue if needed (WARNING: deletes messages)
sudo rabbitmqctl purge_queue transaction.pending# Check queue backlog
sudo rabbitmqctl list_queues name messages
# Increase worker count in main.go
transactionConsumer := worker.NewTransactionConsumer(rmqClient, txService, 10) // was 5
# Monitor resource usage
top # check CPU and memorySymptoms: Messages repeatedly requeued but never acknowledged
# Check transaction service is working
# Verify database connectivity
# Check if signature validation is failing
# View detailed logs
docker logs <rabbitmq-container> -f
# Enable RabbitMQ debug logs (optional)
sudo rabbitmq-server -l debug# Find process using port 3010
lsof -i :3010
# Kill process
kill -9 <PID>- Reduce difficulty in code (default: 4)
- Increase CPU cores available
- Check system resources
- Check CORS settings
- Verify WebSocket endpoint URL
- Check firewall rules
- Verify Redis Pub/Sub is working
- Check candle worker is running
- Ensure transactions are being created
- Check browser console for errors
- Change JWT secret to strong random string
- Update database credentials
- Configure Redis with password
- Set up HTTPS/TLS
- Configure proper CORS origins
- Enable rate limiting
- Set up monitoring/logging
- Configure backup strategy
- Test graceful shutdown
- Load test with expected traffic
# Build image
docker build -t blockchain-simulator .
# Run container
docker run -p 3010:3010 -d blockchain-simulatorsudo nano /etc/systemd/system/blockchain.service
[Unit]
Description=Blockchain Simulator
After=network.target mysql.service redis.service
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/go-blockchain-simulate
ExecStart=/usr/local/bin/blockchain-simulator
Restart=always
[Install]
WantedBy=multi-user.targetContributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
livingdolls
- GitHub: @livingdolls
- Bitcoin whitepaper for blockchain fundamentals
- Ethereum for smart contract concepts
- Go community for excellent libraries
- Next.js team for amazing frontend framework
- Advanced chart visualizations
- Order book implementation
- Limit orders
- Stop-loss orders
- Portfolio tracking
- Smart contracts support
- Multi-currency support
- P2P networking
- Light client support
- Mobile app
- Staking mechanism
- Governance system
- NFT marketplace
- DeFi protocols
- Layer 2 scaling solutions
⭐ If you find this project helpful, please give it a star on GitHub!
📧 Questions? Open an issue or contact via GitHub. ├── go.mod # Go module dependencies ├── Makefile # Build and run commands └── README.md # This file
## 🔐 How It Works
### 1. **Wallet Creation**
Generate RSA Key Pair (2048-bit) ↓ Private Key → Public Key ↓ Hash Public Key → Address
### 2. **Transaction Flow**
Create Transaction ↓ Sign with Private Key → Signature ↓ Verify Signature with Public Key ↓ Add to Mempool (PENDING) ↓ Mine Block → Status: CONFIRMED
### 3. **Proof of Work Mining**
The system implements SHA256-based Proof of Work mining:
Fetch Pending Transactions ↓ Phase 1: Read Validation (No locks)
- Verify sender/receiver wallets exist
- Check balances in-memory
- Pre-validate all transactions ↓ Phase 2: Mining (Outside DB transaction)
- Calculate Merkle Root from transactions
- Adjust difficulty if needed (every 10 blocks)
- Find valid nonce (hash with N leading zeros)
- Monitor mining progress ↓ Phase 3: Database Write (<2s transaction)
- Bulk lock all involved users
- Final balance validation
- Bulk update balances (single CASE query)
- Insert block with PoW data
- Bulk mark transactions CONFIRMED
- Bulk create ledger entries
- Commit transaction
**Mining Algorithm:**
- Target: Hash with N leading zeros (difficulty = 4 means "0000...")
- Method: Increment nonce until valid hash found
- Hash: SHA256(block_number + previous_hash + merkle_root + timestamp + nonce)
- Average time: 5-15 seconds per block at difficulty 4
**Difficulty Adjustment:**
- Triggered every 10 blocks
- Target block time: 10 seconds
- Formula: `new_difficulty = old_difficulty ± 1` based on actual vs target time
- Range: 1 to 10 leading zeros
**Merkle Tree:**
- Binary hash tree of all transactions
- Root stored in block header
- Enables SPV (Simplified Payment Verification)
- Transaction format: `from_address|to_address|amount`
### 4. **Balance Calculation**
Query Ledger Table ↓ Sum all change_amount for address ↓ Return current balance
## 🚀 Performance Optimizations
The system implements several critical optimizations:
### Bulk Database Operations
- **Problem:** N+1 query pattern caused 50-second lock timeouts
- **Solution:** Single bulk queries for all operations
- `GetMultipleByAddress`: Fetch all users in one query with `IN` clause
- `LockMultipleUsersWithTx`: Lock all users atomically with `FOR UPDATE`
- `BulkUpdateBalancesWithTx`: Update all balances in single `CASE` statement
- `BulkMarkConfirmedWithTx`: Mark transactions in one query
- `BulkCreateWithTx`: Insert all ledger entries at once
- `BulkInsertBlockTransactionsWithTx`: Create junction records in one query
### Two-Phase Mining
- **Phase 1 (Read):** Pre-validation with no database locks
- **Phase 2 (Mine):** CPU-intensive mining outside transaction
- **Phase 3 (Write):** Ultra-short transaction (<2s) for final persistence
### Results
- **Before:** 50+ seconds per block (lock timeout errors)
- **After:** <2 seconds database transaction time
- **Improvement:** 95% faster with zero lock timeout errors
- **Mining time:** 5-15 seconds (separate from DB transaction)
## 🏗️ Architecture
### Clean Architecture Pattern
Handler Layer (HTTP) ↓ Service Layer (Business Logic) ↓ Repository Layer (Database) ↓ Database (MySQL)
### Key Components
- **handlers/**: HTTP request/response handling
- **services/**: Core blockchain logic (mining, validation)
- **repository/**: Database operations with bulk support
- **models/**: Data structures (Block, Transaction, User)
- **utils/**: Cryptographic utilities (PoW, Merkle, signatures)
- **database/**: Connection and migration management
- **rabbitmq/**: Message queue client and pooling
- **worker/**: Background workers (block mining, transaction consuming)
### RabbitMQ Integration
```
HTTP Handler
↓
Publish to RabbitMQ (202 Accepted)
↓
Return immediately to client
↓
RabbitMQ Queue (transaction.pending)
↓
Consumer Workers (5 parallel)
↓
Process Transaction
↓
Update Database
↓
Acknowledge Message
```
**Benefits:**
- **Non-blocking API** - Requests return immediately
- **Scalability** - Add more workers for higher throughput
- **Reliability** - Failed messages are automatically requeued
- **Monitoring** - RabbitMQ Management UI for queue stats
## 🧪 Testing with cURL
### Testing RabbitMQ Transaction Processing
**Features tested:**
1. **Non-blocking submission** - API returns immediately (202)
2. **Async processing** - Message processed in background
3. **Worker scaling** - Multiple transactions processed in parallel
```bash
# 1. Register wallet
WALLET=$(curl -s -X POST http://localhost:3010/register \
-H "Content-Type: application/json" \
-d '{"initial_balance": 1000}')
ADDR=$(echo $WALLET | jq -r '.data.address')
echo "Address: $ADDR"
# 2. Get nonce for signing
NONCE=$(curl -s http://localhost:3010/transaction/generateNonce/$ADDR | jq -r '.data.nonce')
echo "Nonce: $NONCE"
# 3. Sign transaction (using your favorite crypto library)
# Example with OpenSSL:
SIGNATURE=$(echo -n "$NONCE" | openssl dgst -sha256 -sign private_key.pem | base64)
# 4. Submit transaction to RabbitMQ queue (non-blocking)
RESPONSE=$(curl -s -X POST http://localhost:3010/send \
-H "Content-Type: application/json" \
-d "{
\"from_address\": \"$ADDR\",
\"to_address\": \"RECEIVER_ADDR\",
\"amount\": 50,
\"nonce\": \"$NONCE\",
\"signature\": \"$SIGNATURE\"
}")
echo "API Response (202 Accepted):"
echo $RESPONSE | jq
# 5. Monitor RabbitMQ queue
echo "Checking queue status..."
sudo rabbitmqctl list_queues name messages
# 6. Monitor transaction consumer logs
tail -f logs/app.log | grep TRANSACTION_CONSUMER
# 7. Verify transaction was processed
curl http://localhost:3010/balance/$ADDR | jq
```
### Complete Workflow Example
```bash
# 1. Register first wallet
WALLET1=$(curl -s -X POST http://localhost:3010/register \
-H "Content-Type: application/json" \
-d '{"initial_balance": 1000}')
echo "Wallet 1: $WALLET1"
ADDR1=$(echo $WALLET1 | jq -r '.address')
PRIVKEY1=$(echo $WALLET1 | jq -r '.private_key')
# 2. Register second wallet
WALLET2=$(curl -s -X POST http://localhost:3010/register \
-H "Content-Type: application/json" \
-d '{"initial_balance": 500}')
echo "Wallet 2: $WALLET2"
ADDR2=$(echo $WALLET2 | jq -r '.address')
# 3. Send multiple transactions
curl -X POST http://localhost:3010/send \
-H "Content-Type: application/json" \
-d "{
\"from_address\": \"$ADDR1\",
\"to_address\": \"$ADDR2\",
\"private_key\": \"$PRIVKEY1\",
\"amount\": 50
}"
curl -X POST http://localhost:3010/send \
-H "Content-Type: application/json" \
-d "{
\"from_address\": \"$ADDR1\",
\"to_address\": \"$ADDR2\",
\"private_key\": \"$PRIVKEY1\",
\"amount\": 100
}"
# 4. Check balances (transactions still PENDING)
curl http://localhost:3010/balance/$ADDR1
curl http://localhost:3010/balance/$ADDR2
# 5. Mine a block (this will take 5-15 seconds)
echo "Mining block with PoW..."
curl -X POST http://localhost:3010/generate-block
# 6. Check balances again (transactions now CONFIRMED)
curl http://localhost:3010/balance/$ADDR1 # Should be 850
curl http://localhost:3010/balance/$ADDR2 # Should be 650
# 7. View complete blockchain
curl http://localhost:3010/blocks | jq
# Register wallet
curl -X POST http://localhost:3010/register \
-H "Content-Type: application/json" \
-d '{"initial_balance": 1000}'
# Send transaction
curl -X POST http://localhost:3010/send \
-H "Content-Type: application/json" \
-d '{
"from_address": "SENDER_ADDRESS",
"to_address": "RECEIVER_ADDRESS",
"private_key": "SENDER_PRIVATE_KEY",
"amount": 50
}'
# Check balance
curl http://localhost:3010/balance/WALLET_ADDRESS
# Mine block
curl -X POST http://localhost:3010/generate-block
# Get all blocks
curl http://localhost:3010/blocksmake run # Run the application
make build # Build binary to bin/app
make clean # Remove build artifacts- DO NOT use in production - This is for educational purposes only
- Private keys are stored in plain text in the database
- Simplified RSA signatures (real blockchains use ECDSA)
- Single-node implementation (no network/peer-to-peer)
- Transaction fees and block rewards are implemented, but consensus and distributed mining are not
- Centralized mining (no consensus between multiple nodes)
The system is optimized for educational demonstration:
- Database: Bulk operations prevent N+1 query issues
- Mining: Two-phase approach keeps database transactions short (<2s)
- Concurrency: Retry mechanism handles concurrent mining attempts
- Scalability: Suitable for hundreds of transactions per block
The system uses database transactions to ensure ACID compliance:
- All balance updates are atomic
- Rollback on any error
- Prevents double-spending and inconsistent states
- Bulk operations for performance (single query vs N queries)
Every transaction is validated:
- ✓ Sender wallet exists
- ✓ Receiver wallet exists
- ✓ Private key matches sender
- ✓ Sufficient balance (checked twice: pre-validation + final validation)
- ✓ Valid digital signature
- ✓ Amount > 0
The PoW implementation is simplified but demonstrates core concepts:
- Target: N leading zeros in hash (configurable difficulty)
- Range: Difficulty 1-10 (production Bitcoin uses ~19-20 leading zeros)
- Adjustment: Every 10 blocks (Bitcoin adjusts every 2016 blocks)
- Algorithm: SHA256 (Bitcoin uses double SHA256)
- Nonce: 64-bit integer (Bitcoin uses 32-bit + extraNonce in coinbase)
- Asymmetric Cryptography (RSA key pairs)
- Digital Signatures (Sign & Verify)
- Proof of Work (SHA256 mining with nonce)
- Dynamic Difficulty Adjustment (Target block time maintenance)
- Merkle Trees (Transaction verification and SPV)
- Hash Functions (SHA256 for blocks and Merkle nodes)
- Transaction Validation (Balance checks, signature verification)
- Transaction Fees & Block Rewards (Miner incentives, direct fee-to-miner logic)
- Miner Account (All rewards and fees go to miner wallet)
- Ledger Improvements (Coinbase/reward entries, nullable
tx_id) - Immutable Ledger (Append-only transaction history)
- Database Transactions (ACID compliance with bulk operations)
- Blockchain Integrity (Chain validation with PoW verification)
- REST API Design (Clean HTTP interface)
- Clean Architecture (Separation of concerns: Handler → Service → Repository)
Solution: Register the wallet using /register endpoint before sending transactions.
Solution: Check if database has data and connection is configured correctly.
Solution: Use the exact private key returned from /register endpoint.
Cause: Long-running database transaction holding locks while mining.
Solution: This has been fixed with two-phase mining approach. Mining now happens outside the database transaction. If you still encounter this:
- Ensure you're using the latest code with bulk operations
- Check for concurrent block generation attempts
- Use the retry mechanism with exponential backoff
Cause: Sender doesn't have enough balance for the transaction.
Solution:
- Check balance using
/balance/:addressendpoint - Ensure all previous transactions are confirmed (block mined)
- Register wallet with sufficient initial balance
Solution: Use backticks around column names or rename columns. In this project, change was renamed to change_amount in the ledger table.
Cause: Difficulty too high for your CPU.
Solution:
- Reduce difficulty in
utils/fake-crypto.go(changeDefaultDifficultyto 3 or 2) - Note: Difficulty auto-adjusts every 10 blocks, so wait for adjustment cycle
- Check CPU usage - mining should use 100% of one core
Possible causes:
- Genesis block (block_number=1) has special handling - check if genesis validation is skipped
- Merkle root NULL for existing blocks - update NULL values to empty string ''
- Manual database changes - verify hash calculations match stored values
Solution: Run integrity check endpoint and review specific error messages. Genesis block should always pass validation.
The mining algorithm is implemented in utils/fake-crypto.go:
func MineBlock(block *models.Block, difficulty int) error {
target := strings.Repeat("0", difficulty)
block.Nonce = 0
for {
hash := CalculateBlockHash(block)
if strings.HasPrefix(hash, target) {
block.CurrentHash = hash
return nil
}
block.Nonce++
// Progress indicator every 10,000 attempts
if block.Nonce%10000 == 0 {
log.Printf("Mining... Nonce: %d, Hash: %s", block.Nonce, hash[:10])
}
}
}Key aspects:
- Brute force search incrementing nonce
- Hash must match difficulty target (N leading zeros)
- Average iterations at difficulty 4: ~65,536 (16^4)
- CPU-bound operation (intentionally expensive)
Merkle root is calculated from transaction hashes:
func CalculateMerkleRoot(transactions []models.Transaction) string {
if len(transactions) == 0 {
return ""
}
var hashes []string
for _, tx := range transactions {
txString := fmt.Sprintf("%s|%s|%f", tx.FromAddress, tx.ToAddress, tx.Amount)
hashes = append(hashes, HashData(txString))
}
// Build tree bottom-up
for len(hashes) > 1 {
var newLevel []string
for i := 0; i < len(hashes); i += 2 {
if i+1 < len(hashes) {
combined := hashes[i] + hashes[i+1]
newLevel = append(newLevel, HashData(combined))
} else {
newLevel = append(newLevel, hashes[i]) // Duplicate if odd
}
}
hashes = newLevel
}
return hashes[0]
}Benefits:
- Efficient verification of transaction inclusion
- Tamper-evident (any change invalidates root)
- Enables SPV for lightweight clients
Example of bulk balance update (avoids N queries):
func (u *userRepository) BulkUpdateBalancesWithTx(tx *sqlx.Tx, updates []BalanceUpdate) error {
query := `UPDATE users SET balance = CASE address `
var args []interface{}
for _, update := range updates {
query += `WHEN ? THEN ? `
args = append(args, update.Address, update.NewBalance)
}
query += `END WHERE address IN (?)`
addresses := make([]string, len(updates))
for i, u := range updates {
addresses[i] = u.Address
}
query, args, _ := sqlx.In(query, args..., addresses)
_, err := tx.Exec(query, args...)
return err
}Performance impact:
- Before: N UPDATE queries (N transactions * 2 users = 2N queries)
- After: 1 UPDATE with CASE statement
- Reduction: 95% faster for typical block with 5+ transactions
Complete chain validation checks:
- Genesis Block: Special handling (block_number=1)
- Hash Chain: Each block's previous_hash matches prior block's current_hash
- Proof of Work: Each hash meets difficulty requirement (N leading zeros)
- Merkle Root: Recalculated root matches stored root
- Transaction Integrity: All transactions referenced in block exist and are CONFIRMED
This project is open source and available under the MIT License.
livingdolls
- GitHub: @livingdolls
Contributions, issues, and feature requests are welcome!
Note: This is a simplified blockchain implementation for educational purposes. It demonstrates core blockchain concepts but lacks many features required for a production cryptocurrency system (consensus mechanisms, network layer, advanced cryptography, etc.).
- Block Explorer API: Query blocks, transactions, and addresses (coming soon)
- Block Explorer Web UI: Browse blockchain data in a web interface
- Wallet Management: Improved wallet features and security
- Analytics Dashboard: Block and transaction statistics
- Websocket Support: Real-time updates for new blocks and transactions
See the Roadmap section above for priorities.