projectmycelium/docs/dev/design/archive/SLICE_ARCHITECTURE.md

🍰 Project Mycelium Slice Management System - Complete Implementation Recap

📋 Overview

The Project Mycelium now features a comprehensive slice management system that automatically converts physical node capacity into rentable compute slices. This system replaces manual slice configuration with intelligent, automatic slice calculation based on real node data from the ThreeFold Grid.

🎯 Core Concept: "Slices"

What is a Slice?

• A slice is a standardized unit of compute resources: 1 vCPU + 4GB RAM + 200GB storage
• Slices can be combined to create larger configurations (2x, 4x, 8x, etc.)
• Each slice inherits characteristics from its parent node (location, uptime, certification, bandwidth)

Why Slices?

• Standardization: Consistent resource units across all nodes
• Flexibility: Users can rent exactly what they need
• Scalability: Easy to combine slices for larger workloads
• Inheritance: Slices maintain node quality characteristics

🏗️ System Architecture

1. Automatic Slice Calculation SliceCalculatorService

// Base slice unit: 1 vCPU, 4GB RAM, 200GB storage
let base_slice = SliceUnit {
    cpu_cores: 1,
    memory_gb: 4,
    storage_gb: 200,
};

// Automatically calculates how many base slices a node can provide
let total_base_slices = calculate_max_base_slices(&node.capacity);

// Generates combinations: 1x, 2x, 4x, 8x slices
let combinations = generate_slice_combinations(total_base_slices);

2. Node-Slice Inheritance SliceCombination

pub struct SliceCombination {
    // Slice specifications
    pub cpu_cores: i32,
    pub memory_gb: i32,
    pub storage_gb: i32,
    pub multiplier: u32,
    
    // INHERITED from parent node
    pub node_uptime_percentage: f32,
    pub node_bandwidth_mbps: i32,
    pub node_location: String,
    pub node_certification_type: String,
    pub node_id: String,
    
    // Availability & pricing
    pub quantity_available: u32,
    pub price_per_hour: Decimal,
}

3. Atomic Slice Rental SliceRentalService

// File locking prevents conflicts during rental
let rental = slice_rental_service.rent_slice_combination(
    &user_email,
    &farmer_email,
    &node_id,
    &combination_id,
    quantity,
    rental_duration_hours,
)?;

4. Grid Integration FarmerService

// Automatically fetch real node data from ThreeFold Grid
let grid_data = self.grid_service.fetch_node_data(grid_node_id).await?;

// Calculate slice capacity from real grid data
let total_base_slices = self.slice_calculator
    .calculate_max_base_slices(&grid_data.total_resources);

// Auto-generate slice combinations with node inheritance
node.available_combinations = self.slice_calculator
    .generate_slice_combinations(total_base_slices, allocated_slices, &node, user_email);

🔄 Data Flow

1. Node Registration

Farmer adds node → Grid data fetched → Slice capacity calculated → Combinations generated → Marketplace products created

2. Slice Rental Process

User browses slices → Selects combination → Rental request → Atomic allocation → Capacity updated → Confirmation sent

3. Capacity Management

Real-time sync → Grid data updated → Slice availability recalculated → Marketplace refreshed

🛠️ Key Components

Services

• SliceCalculatorService - Automatic slice calculation and combination generation
• SliceRentalService - Atomic rental operations with conflict resolution
• NodeMarketplaceService - Converts slices to marketplace products
• FarmerService - Enhanced with grid integration methods

Models

• SliceCombination - Represents a rentable slice configuration
• SliceAllocation - Tracks allocated slices
• SliceRental - Records rental transactions
• FarmNode - Enhanced with slice management fields

API Endpoints

• POST /marketplace/rent-slice - Rent slice combinations
• GET /api/dashboard/slice-products - Get user's slice products
• POST /api/dashboard/slice-products - Create custom slice products
• DELETE /api/dashboard/slice-products/{id} - Delete slice products

📊 Enhanced Data Models

FarmNode Enhancement

pub struct FarmNode {
    // ... existing fields ...
    
    // NEW: Automatic slice management
    pub total_base_slices: u32,           // Total slices this node can provide
    pub allocated_base_slices: u32,       // Currently allocated slices
    pub slice_allocations: Vec<SliceAllocation>, // Active allocations
    pub available_combinations: Vec<SliceCombination>, // Available slice combinations
    pub slice_pricing: SlicePricing,      // Pricing configuration
    pub slice_last_calculated: Option<DateTime<Utc>>, // Last calculation timestamp
}

Marketplace Integration

// Slices appear as marketplace products with inherited characteristics
attributes.insert("node_characteristics", ProductAttribute {
    value: json!({
        "uptime_percentage": combination.node_uptime_percentage,
        "bandwidth_mbps": combination.node_bandwidth_mbps,
        "location": combination.node_location,
        "certification_type": combination.node_certification_type,
        "node_id": combination.node_id
    }),
    attribute_type: AttributeType::Custom("node_inheritance".to_string()),
});

🎮 User Experience

For Farmers

1. Add nodes from ThreeFold Grid (automatic capacity detection)
2. View slice statistics in dashboard (total slices, allocated, earnings)
3. Sync with grid for real-time capacity updates
4. Automatic marketplace product generation

For Users

1. Browse slice marketplace with inherited node characteristics
2. Filter by location, certification, uptime (inherited from nodes)
3. Rent exact combinations needed (1x, 2x, 4x, 8x slices)
4. Real-time availability and pricing

🔧 Technical Benefits

Automatic Management

• No manual slice configuration required
• Real-time capacity calculation from grid data
• Automatic marketplace product generation

Data Consistency

• Atomic operations with file locking
• Conflict resolution during concurrent rentals
• Real-time availability updates

Scalability

• Standardized slice units enable easy scaling
• Efficient combination generation algorithms
• Optimized marketplace filtering and search

Quality Inheritance

• Slices inherit node uptime, location, certification
• Users can make informed decisions based on node quality
• Transparent pricing based on node characteristics

📁 File Structure

projectmycelium/src/
├── services/
│   ├── slice_calculator.rs     # Core slice calculation logic
│   ├── slice_rental.rs         # Atomic rental operations
│   ├── node_marketplace.rs     # Marketplace integration
│   ├── farmer.rs              # Enhanced with grid integration
│   └── grid.rs                # ThreeFold Grid API integration
├── controllers/
│   ├── marketplace.rs         # Slice rental API endpoint
│   └── dashboard.rs           # Slice management UI
└── models/
    ├── user.rs               # Enhanced FarmNode with slice fields
    └── product.rs            # Slice product representations

🚀 Future AI Developer Notes

Key Concepts to Remember

1. Base Slice Unit: Always 1 vCPU + 4GB RAM + 200GB storage
2. Inheritance: Slices ALWAYS inherit parent node characteristics
3. Atomic Operations: Use file locking for rental operations
4. Real-time Sync: Grid integration keeps data current
5. Builder Pattern: All services follow consistent builder pattern

Common Operations

// Calculate slice capacity
let total_slices = slice_calculator.calculate_max_base_slices(&node_capacity);

// Generate combinations
let combinations = slice_calculator.generate_slice_combinations(total_slices, allocated, &node, farmer_email);

// Rent a slice
let rental = slice_rental_service.rent_slice_combination(user, farmer, node, combination, quantity, duration)?;

// Sync with grid
farmer_service.sync_node_with_grid(user_email, node_id).await?;

Data Persistence

• All slice data stored in ./user_data/{email}.json
• Real-time updates to marketplace products
• Automatic cleanup of expired rentals

✅ Implementation Status: 100% COMPLETE

The slice management system provides a complete, automated, and scalable solution for converting ThreeFold Grid nodes into rentable compute resources while maintaining quality inheritance and ensuring data consistency. All core functionality is implemented and operational.