- Scheme 94.1%
- Makefile 5.9%
| docs | feat: byzantine fault tolerance simulation | |
| Makefile | docs: update readme | |
| minimal-bittensor.scm | fix: run-mechanism-comparison | |
| README.md | docs: update readme and code comments | |
Minimal Bittensor System with Pluggable Incentive Mechanisms
This repo contains a minimal implementation of Bittensor as an exercise to better understand the project's core concepts and economics.
A simplified implementation of Bittensor-like incentive mechanisms using GNU Guile Scheme, featuring Verifiable Random Function (VRF) based verifier selection and pluggable subnet incentive mechanisms.
System Overview
This implementation demonstrates how decentralized computation networks can achieve consensus through cryptoeconomic incentives. The system operates in distinct phases:
Minimal Bittensor VRF System Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Miner A │ │ Miner B │ │ Miner C │ │ Miner D │
│ Stake: 150 │ │ Stake: 100 │ │ Stake: 80 │ │ Stake: 120 │
│ Rep: 0.9 │ │ Rep: 0.7 │ │ Rep: 0.4 │ │ Rep: 0.8 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
│ ┌─────────── Task Distribution ─────────────┐ │
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ SUBNET PROTOCOL ENGINE │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Task │ │ Verifier │ │ Response │ │ Consensus │ │
│ │ Distribution │ │ Selection │ │ Evaluation │ │ Formation │ │
│ │ (Phase 1) │ │ (Phase 2) │ │ (Phase 3) │ │ (Phase 4) │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ └─────────────┘ │
│ ┌──────────────┐ ┌──────▼───────┐ │
│ │ Reward │ │ Reputation │ Selection Options: │
│ │ Distribution │ │ Management │ • VRF (Random) │
│ │ (Phase 5) │ │ (Phase 6) │ • Stake-weighted │
│ └──────────────┘ └──────────────┘ • Reputation-weighted │
└─────────────────────────────────────────────────────────────────────┘
▲さんかく │
│ │
┌───────────┴───────────┐ │
│ │ ▼
┌────▼───┐ ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ ┌─────────▼─────────┐ │
│Verifier│ │Verifier│ │Verifier│ │Verifier│ │ Selected │ │
│ 1 │ │ 2 │ │ 3 │ │ 4 │ │ Verifiers │ │
│Rep:0.95│ │Rep:0.85│ │Rep:0.90│ │Rep:0.75│ │ (Evaluate All │ │
└────────┘ └────────┘ └────────┘ └────────┘ │ Miner Responses) │ │
└───────────────────┘ │
│ │
┌───────────────────────────────────────────────┘ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────────┘
│ CONSENSUS & REWARDS
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ │ Accuracy │────▶│ Combined │────▶│ Reward │
│ │ Scores │ │ Consensus │ │ Distribution│
│ └─────────────┘ │ Scores │ │ & Rep Update│
│ ┌─────────────┐ └─────────────┘ └─────────────┘
│ │ Efficiency │────▶
│ │ Scores │
│ └─────────────┘
└─────────────────────────────────────────────────────────────────────┘
0. Computation Contract Interface Phase
- Computation Contracts define type-safe request/response formats for each subnet
- Each contract specifies data schemas, validation rules, and serialization methods
- Enables domain-specific optimization while maintaining interoperability
- Examples: Text processing, AI inference, image generation, financial analysis, storage, training
1. Task Distribution Phase
- Network receives computational requests using contract-specific formats
- Tasks are broadcast to registered miners with validated payloads
- Each task gets a unique ID for tracking and includes contract metadata
2. Computation Phase
- Miners perform the requested computation
- Response quality depends on miner reputation (higher reputation = better responses)
- Miners with low reputation may introduce errors or return low-quality results
- Each response includes computation time for efficiency evaluation
3. Verifier Selection Phase
- Multiple selection algorithms available: VRF, stake-weighted, reputation-weighted, round-robin
- VRF (Verifiable Random Function) is one example that uses task ID + network seed for deterministic selection
- Selection is unpredictable beforehand but verifiable afterward (when using VRF)
- Prevents miners from gaming the system by knowing which verifiers will evaluate them
- Each subnet can choose the selection mechanism that best fits their needs
4. Evaluation Phase
- Selected Verifiers evaluate all miner responses using subnet-specific criteria
- Each verifier produces accuracy and efficiency scores
- Evaluation algorithms are pluggable per subnet (see Incentive Mechanisms)
5. Consensus Phase
- Multiple verifier scores are averaged to create consensus scores
- Reduces impact of individual verifier bias or errors
- Weighted by verifier reputation for additional security
6. Reward Distribution Phase
- Rewards distributed based on consensus scores using subnet-specific algorithms
- Miner reputations updated based on performance
- System maintains long-term incentive alignment
7. Reputation Evaluatioon Phase
- Inactive verifiers experience reputation decay over time
- Prevents dead nodes from maintaining high influence
- Encourages active participation in the network
Comprehensive Subnet Protocol Interface
Each subnet can customize every phase of the computation process through a 7-phase pluggable interface:
Phase 0: Computation Contract Interface
;; Contract definition: (name request-schema response-schema validator serializer deserializer)
;; Defines type-safe data formats and validation for subnet-specific computation
- Type Safety: Requests/responses validated against schemas before processing
- Domain Specialization: Each subnet optimized for specific data types and workflows
- Interoperability: Standardized interface enables miner/verifier compatibility
- Versioning: Contracts evolve while maintaining backward compatibility
Phase-by-Phase Customization
Phase 1: Task Distribution
;; Function signature: (network-state params) -> list-of-computation-requests
;; Controls how tasks are created and distributed to miners
- Default: Predetermined arithmetic/text tasks
- AI Subnet: Progressive learning challenges
- Financial Subnet: Real-time market data processing
- Research Subnet: Creative text generation prompts
Phase 2: Verifier Selection
;; Function signature: (verifier-pool task request params) -> list-of-selected-verifiers
;; Controls which verifiers evaluate each task
- VRF (Verifiable Random Function): Deterministic but unpredictable, cryptographically verifiable
- Stake-weighted: Selection probability proportional to stake amount
- Reputation-weighted: Selection probability based on expertise/track record
- Round-robin: Deterministic rotation through available verifiers
Phase 3: Response Evaluation
;; Function signature: (verifier request response params) -> verification-result
;; Controls how verifiers score miner responses
- Accuracy-focused: Correctness heavily weighted
- Speed-focused: Efficiency heavily weighted
- Creativity-focused: Novel approaches rewarded
- Consensus-focused: Agreement with other responses
Phase 4: Consensus Formation
;; Function signature: (list-of-verification-results params) -> consensus-scores-hash
;; Controls how multiple verifier scores combine into final rankings
- Simple averaging: Equal weight to all verifiers
- Reputation-weighted: Expert verifiers count more
- Stake-weighted: Economic skin-in-the-game matters
- Outlier-resistant: Median or trimmed mean consensus
Phase 5: Reward Distribution
;; Function signature: (miners consensus-scores reward-pool params) -> rewards-hash
;; Controls how rewards are allocated based on performance
- Proportional: Rewards proportional to scores
- Winner-takes-most: Top performers get exponential rewards
- Diversity bonus: Extra rewards for novel approaches
- Participation rewards: Base rewards for all contributors
Phase 6: Reputation Management
;; Function signature: (nodes performance-data params) -> void (side effects)
;; Controls how node reputations are updated and decay over time
- Gradual updates: Slow reputation changes for stability
- Fast adaptation: Quick responses to performance changes
- Specialization tracking: Domain-specific reputation scores
- Activity-based decay: Inactive nodes lose influence
Subnet Protocol Interface
(define-record-type <subnet-protocol>
(make-subnet-protocol name computation-contract task-distributor verifier-selector
evaluator consensus-builder reward-distributor reputation-manager)
subnet-protocol?
(name subnet-name)
(computation-contract subnet-computation-contract) ; Phase 0: Data formats
(task-distributor subnet-task-distributor) ; Phase 1: Task creation
(verifier-selector subnet-verifier-selector) ; Phase 2: Verifier selection
(evaluator subnet-evaluator) ; Phase 3: Response evaluation
(consensus-builder subnet-consensus-builder) ; Phase 4: Score consensus
(reward-distributor subnet-reward-distributor) ; Phase 5: Reward allocation
(reputation-manager subnet-reputation-manager)) ; Phase 6: Reputation updates
Built-in Incentive Mechanisms
Default Mechanism
- Balanced 70% accuracy, 30% efficiency weighting
- Proportional reward distribution
- Gradual reputation updates
Accuracy-Focused Mechanism
- 90% accuracy, 10% efficiency weighting
- Exponential reward distribution favoring top performers
- Strict quality requirements
Speed-Focused Mechanism
- 40% accuracy, 60% efficiency weighting
- Aggressive efficiency penalties for slow responses
- Rewards fast computation
Running the Demos
Basic Demo (Verbose Step-by-Step)
make demo
This runs a detailed walkthrough showing each phase of the computation round with extensive logging.
Compare All Built-in Mechanisms
make compare-mechanisms
Byzantine Fault Tolerance Demo
make byzantine
Demonstrates how the network handles malicious verifiers:
- verifier-1: HONEST - provides accurate evaluations
- verifier-2: ALWAYS-HIGH - inflates all scores to 0.95
- verifier-3: ALWAYS-LOW - deflates all scores to 0.1
- verifier-4: RANDOM - gives completely random scores
Shows how consensus averaging mitigates Byzantine behavior.
Subnet Protocol Customization Demo
make subnet-protocols
Demonstrates how each of the 6 phases can be customized for different subnet types:
- Default Protocol: VRF selection + balanced evaluation + proportional rewards
- Speed-Focused Protocol: VRF selection + efficiency priority + proportional rewards
- Research-Collaborative Protocol: Stake-weighted selection + reputation-weighted consensus + diversity bonuses
Shows mix-and-match flexibility for domain-specific optimization.
Computation Contract Interface Demo
make contracts
Demonstrates how different subnet types require completely different request/response formats:
- Text Processing:
{prompt: string}→{text: string, word_count: number} - AI Inference:
{prompt: string, model: string}→{generated_text: string, confidence: number} - Image Generation:
{prompt: string, width: number}→{image_data: base64, format: string} - Financial Analysis:
{symbol: string, data: object}→{signals: [signal], confidence: number} - Storage Service:
{operation: string, data: bytes}→{success: boolean, file_hash: string} - Training Service:
{model_config: object}→{model_weights: bytes, metrics: object}
Shows type safety, interoperability, and specialization benefits.
Computation Contract Interface Layer
The computation contract interface is the foundation that enables subnet specialization. Each contract defines:
Contract Components
(define-record-type <computation-contract>
(make-computation-contract name request-schema response-schema validator serializer deserializer)
computation-contract?
(name contract-name) ; Unique contract identifier
(request-schema contract-request-schema) ; Input data format specification
(response-schema contract-response-schema) ; Output data format specification
(validator contract-validator) ; Request/response validation function
(serializer contract-serializer) ; Network transport encoding
(deserializer contract-deserializer)) ; Network transport decoding
Request/Response Structure
;; Generic computation request envelope
(define-record-type <computation-request>
(make-computation-request task-id contract-name payload metadata timestamp)
computation-request?
(task-id request-task-id) ; Unique task identifier
(contract-name request-contract-name) ; Which contract governs this request
(payload request-payload) ; Contract-specific input data
(metadata request-metadata) ; Generic metadata (difficulty, etc.)
(timestamp request-timestamp)) ; Request creation time
;; Generic computation response envelope
(define-record-type <computation-response>
(make-computation-response task-id miner-id contract-name payload computation-time timestamp)
computation-response?
(task-id response-task-id) ; Links back to original request
(miner-id response-miner-id) ; Which miner produced this response
(contract-name response-contract-name) ; Contract compatibility check
(payload response-payload) ; Contract-specific result data
(computation-time response-computation-time) ; Performance metric
(timestamp response-timestamp)) ; Response creation time
Built-in Contract Examples
Text Processing Contract
(define text-processing-contract
(make-computation-contract
"text-processing"
'((prompt . string) (max_length . number)) ; Request schema
'((text . string) (word_count . number)) ; Response schema
(lambda (data schema) #t) ; Validator
(lambda (data) (format #f "~a" data)) ; Serializer
(lambda (str) str))) ; Deserializer
AI Inference Contract
(define ai-inference-contract
(make-computation-contract
"ai-inference"
'((prompt . string) (model . string) (temperature . number) (max_tokens . number))
'((generated_text . string) (confidence . number) (tokens_used . number))
(lambda (data schema) #t)
(lambda (data) (format #f "~a" data))
(lambda (str) str)))
Financial Analysis Contract
(define financial-analysis-contract
(make-computation-contract
"financial-analysis"
'((symbol . string) (timeframe . string) (indicators . list) (data . object))
'((signals . list) (confidence . number) (rationale . string))
(lambda (data schema) #t)
(lambda (data) (format #f "~a" data))
(lambda (str) str)))
Contract Benefits
Type Safety
- Schema Validation: All requests/responses validated against contract schemas
- Runtime Checks: Invalid data rejected before computation begins
- Error Prevention: Catches format mismatches early in the pipeline
Domain Specialization
- Custom Data Types: Each subnet optimized for specific computation types
- Semantic Validation: Contract-specific business logic validation
- Performance Optimization: Data structures optimized for domain requirements
Interoperability
- Standard Interface: Common request/response envelope across all contracts
- Miner Compatibility: Miners can implement multiple contracts
- Verifier Flexibility: Verifiers can evaluate different contract types
Versioning & Evolution
- Backward Compatibility: New contract versions can coexist with old ones
- Migration Support: Gradual transition between contract versions
- Feature Extensions: Contracts can add optional fields without breaking changes
Contract Usage in Subnet Protocols
Each subnet protocol specifies its computation contract:
(define ai-training-subnet
(make-subnet-protocol
"ai-training"
ai-inference-contract ; Phase 0: Use AI inference contract
ai-training-task-distributor ; Phase 1: Generate AI training tasks
reputation-weighted-selector ; Phase 2: Select expert verifiers
creativity-focused-evaluator ; Phase 3: Reward novel approaches
expert-weighted-consensus ; Phase 4: Weight by AI expertise
diversity-bonus-rewards ; Phase 5: Bonus for creative solutions
specialization-reputation-manager)) ; Phase 6: Track AI-specific reputation
This layered approach enables:
- Subnet Independence: Each subnet can define completely different data formats
- Cross-Subnet Learning: Insights from one contract type can inform others
- Rapid Prototyping: New computation types can be quickly deployed and tested
- Economic Experimentation: Different contracts can have different incentive structures
Creating Custom Subnet Protocols
The system includes examples of:
- Quality-Focused Subnet: Zero tolerance for errors, winner-takes-most rewards (implemented in the main file)
Example: Custom Financial Trading Subnet
;; Create a high-frequency trading subnet
(define hft-subnet-protocol
(make-subnet-protocol
"high-frequency-trading"
;; Phase 1: Generate market data tasks
(lambda (network-state params)
(list (make-computation-request
"market-task"
"Process order book: BTC/USD depth analysis"
2.0
(current-timestamp))))
;; Phase 2: VRF selection (fairness critical)
default-verifier-selector
;; Phase 3: Speed is everything - 10% accuracy, 90% efficiency
(lambda (verifier request response params)
(let* ((accuracy (* 0.1 (default-accuracy-evaluator request response)))
(efficiency (* 0.9 (default-efficiency-evaluator response))))
(make-verification-result ... (+ accuracy efficiency) ...)))
;; Phase 4: Outlier-resistant consensus
(lambda (verifications params)
;; Use median instead of mean for stability
...)
;; Phase 5: Winner-takes-most rewards (performance critical)
(lambda (miners scores pool params)
;; Exponential rewards for top 10% performers
...)
;; Phase 6: Fast reputation adaptation
(lambda (nodes performance params)
;; Rapid reputation changes for real-time performance
...)))
;; Use the custom protocol
(make-network-state miners verifiers '() '() '() 1000.0 hft-subnet-protocol)
Example: Research Collaboration Subnet
;; Create a research-focused subnet
(define research-subnet-protocol
(make-subnet-protocol
"research-collaboration"
ai-training-task-distributor ; Creative tasks
stake-weighted-verifier-selector ; Skin in the game
default-evaluator ; Standard evaluation
reputation-weighted-consensus ; Expert opinions
diversity-bonus-rewards ; Novel approaches
default-reputation-manager)) ; Standard reputation
System Components
Miners
- Perform computational tasks
- Response quality influenced by reputation
- Earn rewards based on subnet-specific consensus scores
Verifiers
- Evaluate miner responses using subnet algorithms
- Selected via VRF for each task
- Maintain reputation that decays per subnet rules
VRF Oracle
- Deterministic but unpredictable verifier selection
- Ensures fairness and prevents gaming
- Uses task ID and network seed for selection
Subnet Networks
- Each subnet can define its own incentive mechanism
- Supports different task types and evaluation criteria
- Enables experimentation with novel incentive structures
Quick Start
# Check requirements
make check
# Run basic demonstration
make demo
# See all available demos
make help
Requirements
- GNU Guile 3.0 or later
- Standard SRFI libraries (included with Guile)
- GNU Make (for convenient demo execution)
Installation
macOS (with Homebrew):
make install-mac
Ubuntu/Debian:
make install-ubuntu
Verify installation:
make check
Step-by-Step Execution Walkthrough
When you run make demo, here's what happens under the hood:
Network Initialization
=== Minimal Bittensor VRF System Demo (Guile) ===
Using incentive mechanism: accuracy-focused
Registered 4 miners and 4 verifiers
The system initializes with:
-
4 Miners with different stakes and reputations:
miner-alpha: 150 stake, 0.9 reputation (high performer)miner-beta: 100 stake, 0.7 reputation (good performer)miner-gamma: 80 stake, 0.4 reputation (inconsistent performer)miner-delta: 120 stake, 0.8 reputation (reliable performer)
-
4 Verifiers with different activity levels:
verifier-1: 200 stake, 0.95 reputation (active)verifier-2: 180 stake, 0.85 reputation (active)verifier-3: 160 stake, 0.90 reputation (2 hours inactive)verifier-4: 140 stake, 0.75 reputation (24 hours inactive - will experience decay)
Round 1: Task Distribution & Mining
--- Starting computation round for task: task-1-1730295234 ---
Task: Calculate the sum of 15 25 30
What happens internally:
- Task broadcast to all 4 miners
- Each miner's response quality influenced by their reputation:
- High reputation miners (like
miner-alpha) return accurate results - Low reputation miners may introduce calculation errors
- Computation time varies realistically
- High reputation miners (like
Miner miner-alpha: 70 (time: 0.83s) # Correct answer, good time
Miner miner-beta: 71 (time: 0.46s) # Off by 1, fast time
Miner miner-gamma: 67 (time: 0.30s) # Off by 3, very fast
Miner miner-delta: 67 (time: 1.50s) # Off by 3, slow time
VRF Verifier Selection
VRF selected verifiers: (verifier-1 verifier-2 verifier-3)
VRF Process:
- Combines task ID (
task-1-1730295234) with network seed (12345) - Generates deterministic but unpredictable hash
- Uses hash to select 3 out of 4 available verifiers
- Selection is fair and cannot be gamed by miners
Verification & Scoring
Each selected verifier evaluates all 4 responses using the accuracy-focused mechanism:
Accuracy Evaluation (90% weight):
miner-alpha: 70 = perfect score (1.0)miner-beta: 71 = error penalty (0.9)miner-gamma: 67 = larger error (0.7)miner-delta: 67 = same error as gamma (0.7)
Efficiency Evaluation (10% weight):
miner-gamma: 0.30s = excellent (1.0)miner-beta: 0.46s = very good (1.0)miner-alpha: 0.83s = good (0.8)miner-delta: 1.50s = poor (0.6)
Consensus & Rewards
Miner miner-alpha: score=0.940, reward=481.20, new_reputation=0.904
Miner miner-beta: score=0.990, reward=368.90, new_reputation=0.729
Miner miner-gamma: score=0.970, reward=134.67, new_reputation=0.457
Miner miner-delta: score=0.850, reward=15.23, new_reputation=0.805
Consensus Calculation:
- 3 verifier scores averaged for each miner
- Accuracy-focused mechanism heavily weights correctness
miner-betagets highest score despite wrong answer due to speed bonus- Rewards distributed using exponential curve favoring top performers
Reputation Updates:
- Each miner's reputation updated:
new_rep = 0.9 * old_rep + 0.1 * score - Gradual reputation changes ensure system stability
- Poor performers slowly lose reputation, good performers gain it
Architecture Benefits
Flexibility
- Subnets can experiment with different incentive structures
- Easy to test new economic models and evaluation criteria
- Enables domain-specific optimization
Modularity
- Clean separation between consensus mechanism and evaluation logic
- Reusable VRF and network infrastructure
- Simple to add new incentive mechanisms
Byzantine Fault Tolerance
- Multiple verifier selection reduces single points of failure
- Consensus averaging mitigates impact of malicious verifiers
- VRF prevents verifier selection gaming
- Reputation decay removes inactive/compromised nodes over time
Educational Value
- Clear demonstration of different incentive philosophies
- Easy to understand the impact of mechanism design choices
- Practical experimentation with economic incentives
- Live demonstration of Byzantine fault tolerance
What's New in This Version
Comprehensive Subnet Protocol Interface
- Complete Customization: Every phase of computation can be customized independently
- Mix-and-Match Design: Combine different algorithms for optimal domain-specific performance
- Phase Isolation: Changes to one phase don't affect others, enabling modular development
- Interface Standardization: Consistent function signatures across all subnet types
Enhanced Verbosity & Step-by-Step Walkthrough
- Detailed Phase Logging: Each computation round shows all 7 phases with extensive logging
- Network Initialization Details: See miner and verifier configurations with stakes and reputations
- VRF Process Explanation: Understand how verifier selection works deterministically
- Verification Breakdown: Watch each verifier evaluate responses with accuracy/efficiency scores
- Consensus Formation: See how multiple verifier scores are averaged into final rankings
Byzantine Fault Tolerance Demo
- Malicious Verifier Simulation: Test network resilience against Byzantine actors
- Multiple Attack Patterns: Always-high, always-low, random, and targeted bias behaviors
- Consensus Robustness: Demonstrates how averaging mitigates individual verifier attacks
- Educational Value: Clear visualization of decentralized system security
Specialized Subnet Examples
- Default Protocol: Balanced general-purpose computation
- Speed-Focused Protocol: High-frequency trading optimization (30% accuracy, 70% efficiency)
- Research-Collaborative Protocol: AI training with stake-weighted selection and reputation consensus
- Mix-and-Match Flexibility: Financial, gaming, scientific, and storage subnet examples
Extensions
Potential improvements for deeper learning:
- Implement full cryptographic VRF with proper verification
- Add network simulation with latency and failures
- Create domain-specific evaluation mechanisms (AI, computation, storage)
- Implement mechanism selection and governance
- Add more sophisticated reputation models
- Enhance Byzantine fault tolerance with reputation-weighted consensus
License
MIT License - Educational implementation for learning decentralized computation incentives.
Acknowledgments
Inspired by the Bittensor protocol and the work of the Opentensor Foundation. This is an educational simplification to demonstrate core concepts with extensible subnet mechanisms.