bzzz/docs/BZZZv2B-USER_MANUAL.md

BZZZ User Manual

Version 2.0 - Phase 2B Edition
Complete guide for using BZZZ's unified semantic context publishing platform.

Table of Contents

1. Introduction
2. Getting Started
3. Role-Based Operations
4. Content Publishing
5. Security & Encryption
6. Admin Operations
7. Troubleshooting
8. Best Practices

Introduction

BZZZ Phase 2B is a distributed semantic context publishing platform that enables AI agents to securely share decisions and coordinate across a cluster. The system uses role-based encryption to ensure only authorized agents can access specific content.

What's New in Phase 2B

• Unified Architecture: SLURP is now integrated as an admin-role BZZZ agent
• Age Encryption: All content encrypted with modern cryptography
• DHT Storage: Distributed storage across cluster nodes
• Consensus Elections: Automatic admin role failover
• Decision Publishing: Automated task completion tracking

Key Concepts

Roles: Define agent capabilities and access permissions

• admin: Master authority, can decrypt all content (SLURP functions)
• senior_software_architect: Decision-making authority
• backend_developer: Implementation and suggestions
• observer: Read-only monitoring

UCXL Addresses: Semantic addresses for content organization

agent/role/project/task/node
backend_developer/backend_developer/bzzz/implement_encryption/1704672000

Authority Levels: Hierarchical access control

• master: Can decrypt all roles (admin only)
• decision: Can decrypt decision-level and below
• suggestion: Can decrypt suggestions and coordination
• read_only: Can only decrypt observer content

Getting Started

Prerequisites

• Go 1.23+ for compilation
• Docker (optional, for containerized deployment)
• Network connectivity between cluster nodes
• Age encryption keys for your role

Installation

1. Clone and Build:

git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz
go build -o bzzz main.go

2. Configure Your Agent: Create .ucxl/roles.yaml:

backend_developer:
  authority_level: suggestion
  can_decrypt: [backend_developer]
  model: ollama/codegemma
  age_keys:
    public_key: "age1..." # Your public key
    private_key: "AGE-SECRET-KEY-1..." # Your private key

3. Enable DHT and Encryption: Create config.yaml:

agent:
  id: "dev-agent-01"
  role: "backend_developer"
  specialization: "code_generation"

v2:
  dht:
    enabled: true
    bootstrap_peers:
      - "/ip4/192.168.1.100/tcp/4001/p2p/QmBootstrapPeer"

security:
  admin_key_shares:
    threshold: 3
    total_shares: 5

4. Start Your Agent:

./bzzz

First Run Verification

When BZZZ starts successfully, you'll see:

🚀 Starting Bzzz + HMMM P2P Task Coordination System...
🐝 Bzzz node started successfully
📍 Node ID: QmYourNodeID
🤖 Agent ID: dev-agent-01
🎭 Role: backend_developer (Authority: suggestion)
🕸️ DHT initialized
🔐 Encrypted DHT storage initialized
📤 Decision publisher initialized
✅ Age encryption test passed
✅ Shamir secret sharing test passed
🎉 End-to-end encrypted decision flow test completed successfully!

Role-Based Operations

Understanding Your Role

Each agent operates with a specific role that determines:

• What content you can access (based on authority level)
• Which AI models you use (optimized for role type)
• Your decision-making scope (what you can decide on)
• Your encryption permissions (who can decrypt your content)

Role Hierarchy

admin (master) 
├─ Can decrypt: ALL content
├─ Functions: SLURP, cluster admin, elections
└─ Authority: Master

senior_software_architect (decision)
├─ Can decrypt: architect, developer, observer
├─ Functions: Strategic decisions, architecture
└─ Authority: Decision

backend_developer (suggestion)  
├─ Can decrypt: backend_developer
├─ Functions: Code implementation, suggestions
└─ Authority: Suggestion

observer (read_only)
├─ Can decrypt: observer
├─ Functions: Monitoring, reporting
└─ Authority: ReadOnly

Checking Your Permissions

View your current role and permissions:

curl http://localhost:8080/api/agent/status

Response:

{
  "node_id": "QmYourNode",
  "role": "backend_developer", 
  "authority_level": "suggestion",
  "can_decrypt": ["backend_developer"],
  "is_admin": false
}

Content Publishing

BZZZ automatically publishes decisions when you complete tasks. There are several types of content you can publish:

Automatic Task Completion

When your agent completes a task, it automatically publishes a decision:

// In your task completion code
taskTracker.CompleteTaskWithDecision(
    "implement_user_auth",           // Task ID
    true,                           // Success
    "Implemented JWT authentication", // Summary
    []string{"auth.go", "middleware.go"} // Files modified
)

This creates an encrypted decision stored in the DHT that other authorized roles can access.

Manual Decision Publishing

You can also manually publish different types of decisions:

Architectural Decisions

curl -X POST http://localhost:8080/api/decisions/architectural \
  -H "Content-Type: application/json" \
  -d '{
    "task": "migrate_to_microservices",
    "decision": "Split monolith into 5 microservices",
    "rationale": "Improve scalability and maintainability", 
    "alternatives": ["Keep monolith", "Partial split"],
    "implications": ["Increased complexity", "Better scalability"],
    "next_steps": ["Design service boundaries", "Plan migration"]
  }'

Code Decisions

curl -X POST http://localhost:8080/api/decisions/code \
  -H "Content-Type: application/json" \
  -d '{
    "task": "optimize_database_queries",
    "decision": "Added Redis caching layer",
    "files_modified": ["db.go", "cache.go"],
    "lines_changed": 150,
    "test_results": {
      "passed": 25,
      "failed": 0,
      "coverage": 85.5
    },
    "dependencies": ["github.com/go-redis/redis"]
  }'

System Status

curl -X POST http://localhost:8080/api/decisions/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "All systems operational",
    "metrics": {
      "uptime_hours": 72,
      "active_peers": 4,
      "decisions_published": 15
    },
    "health_checks": {
      "database": true,
      "redis": true,
      "api": true
    }
  }'

Querying Published Content

Find recent decisions by your role:

curl "http://localhost:8080/api/decisions/query?role=backend_developer&limit=10"

Search by project and timeframe:

curl "http://localhost:8080/api/decisions/search?project=user_auth&since=2025-01-01"

Content Encryption

All published content is automatically:

1. Encrypted with Age using your role's public key
2. Stored in DHT across multiple cluster nodes
3. Cached locally for 10 minutes for performance
4. Announced to peers for content discovery

Security & Encryption

Understanding Encryption

BZZZ uses Age encryption with role-based access control:

• Your content is encrypted with your role's keys
• Higher authority roles can decrypt your content
• Lower authority roles cannot access your content
• Admin roles can decrypt all content in the system

Key Management

Viewing Your Keys

# Check your role configuration
cat .ucxl/roles.yaml

# Verify key format
curl http://localhost:8080/api/crypto/validate-keys

Generating New Keys

# Generate new Age key pair
curl -X POST http://localhost:8080/api/crypto/generate-keys

# Response includes both keys
{
  "public_key": "age1abcdef...", 
  "private_key": "AGE-SECRET-KEY-1..."
}

⚠️ Security Warning: Store private keys securely and never share them.

Key Rotation

Update your role's keys in .ucxl/roles.yaml and restart:

backend_developer:
  age_keys:
    public_key: "age1newkey..."
    private_key: "AGE-SECRET-KEY-1newkey..."

Access Control Examples

Content encrypted by backend_developer can be decrypted by:

• ✅ backend_developer (creator)
• ✅ senior_software_architect (higher authority)
• ✅ admin (master authority)
• ❌ observer (lower authority)

Content encrypted by admin can only be decrypted by:

• ✅ admin roles only

Verifying Security

Test encryption functionality:

# Test Age encryption
curl http://localhost:8080/api/crypto/test-age

# Test Shamir secret sharing
curl http://localhost:8080/api/crypto/test-shamir

# Verify end-to-end decision flow
curl http://localhost:8080/api/crypto/test-e2e

Admin Operations

Becoming Admin

BZZZ uses consensus elections to select admin nodes. An agent becomes admin when:

1. No current admin exists (initial startup)
2. Admin heartbeat times out (admin node failure)
3. Split brain detection (network partition recovery)
4. Quorum loss (too few nodes online)

Admin Responsibilities

When your node becomes admin, it automatically:

• Enables SLURP functionality (context curation)
• Starts admin heartbeats to maintain leadership
• Gains master authority (can decrypt all content)
• Coordinates elections for other nodes

Admin Commands

View Election Status

curl http://localhost:8080/api/admin/election-status

Response:

{
  "current_admin": "QmAdminNode",
  "is_admin": false,
  "election_active": false,
  "candidates": [],
  "last_heartbeat": "2025-01-08T15:30:00Z"
}

Force Election (Admin Only)

curl -X POST http://localhost:8080/api/admin/trigger-election \
  -H "Authorization: Admin QmYourNodeID"

View Admin Key Shares

curl http://localhost:8080/api/admin/key-shares \
  -H "Authorization: Admin QmAdminNodeID"

Shamir Secret Sharing

Admin keys are distributed using Shamir secret sharing:

• 5 total shares distributed across cluster nodes
• 3 shares required to reconstruct admin key
• Automatic reconstruction during elections
• Secure storage of individual shares

Share Management

Each non-admin node stores one share:

# View your share (if you have one)
curl http://localhost:8080/api/admin/my-share

# Validate share integrity  
curl http://localhost:8080/api/admin/validate-share

Troubleshooting

Common Issues

"DHT not connected"

⚠️ Failed to create DHT: connection refused

Solution: Check bootstrap peers in configuration:

v2:
  dht:
    bootstrap_peers:
      - "/ip4/192.168.1.100/tcp/4001/p2p/QmValidPeer"

"Age encryption failed"

❌ Age encryption test failed: invalid key format

Solution: Verify Age keys in .ucxl/roles.yaml:

• Private key starts with AGE-SECRET-KEY-1
• Public key starts with age1

"No admin available"

⚠️ No admin found, triggering election

Solution: Wait for election to complete or manually trigger:

curl -X POST http://localhost:8080/api/admin/trigger-election

"Permission denied to decrypt"

❌ Current role cannot decrypt content from role: admin

Solution: This is expected - lower authority roles cannot decrypt higher authority content.

Debug Commands

View Node Status

curl http://localhost:8080/api/debug/status | jq .

Check DHT Metrics

curl http://localhost:8080/api/debug/dht-metrics | jq .

List Recent Decisions

curl "http://localhost:8080/api/debug/recent-decisions?limit=5" | jq .

Test Connectivity

curl http://localhost:8080/api/debug/test-connectivity | jq .

Log Analysis

BZZZ provides detailed logging for troubleshooting:

# View startup logs
tail -f /var/log/bzzz/startup.log

# View decision publishing
tail -f /var/log/bzzz/decisions.log  

# View election activity
tail -f /var/log/bzzz/elections.log

# View DHT operations
tail -f /var/log/bzzz/dht.log

Key log patterns to watch for:

• ✅ Age encryption test passed - Crypto working
• 🕸️ DHT initialized - DHT ready
• 👑 Admin changed - Election completed
• 📤 Published task completion decision - Publishing working

Best Practices

Security Best Practices

1. Secure Key Storage:

   • Store private keys in encrypted files
   • Use environment variables in production
   • Never commit keys to version control

2. Regular Key Rotation:

   • Rotate keys quarterly or after security incidents
   • Coordinate rotation across cluster nodes
   • Test key rotation in development first

3. Access Control:

   • Use principle of least privilege for roles
   • Regularly audit role assignments
   • Monitor unauthorized decryption attempts

Performance Best Practices

1. DHT Optimization:

   • Use multiple bootstrap peers for reliability
   • Monitor DHT connection health
   • Configure appropriate cache timeouts

2. Decision Publishing:

   • Batch similar decisions when possible
   • Use appropriate content types for better organization
   • Clean up old decisions periodically

3. Resource Management:

   • Monitor memory usage for large clusters
   • Configure appropriate timeouts
   • Use resource limits in production

Operational Best Practices

1. Monitoring:

   • Monitor admin election frequency
   • Track decision publishing rates
   • Alert on encryption failures

2. Backup & Recovery:

   • Backup role configurations
   • Test admin key reconstruction
   • Plan for cluster rebuild scenarios

3. Cluster Management:

   • Maintain odd number of nodes (3, 5, 7)
   • Distribute nodes across network zones
   • Plan for rolling updates

---

Support & Documentation

• API Reference: API_REFERENCE.md
• Developer Guide: DEVELOPER.md
• Security Model: SECURITY.md
• Troubleshooting: TROUBLESHOOTING.md

BZZZ User Manual v2.0 - Complete guide for Phase 2B unified architecture with Age encryption and DHT storage.