@ruvector/edge-net 0.5.0 → 0.5.3

package/README.md

@@ -1,35 +1,51 @@
 # @ruvector/edge-net
 
-**Collective AI Computing Network - Share, Contribute, Compute Together**
+**The Decentralized AI Compute Network - Private, Modular, Unstoppable**
 
-A distributed computing platform that enables collective resource sharing for AI workloads. Contributors share idle compute resources, earning participation units (rUv) that can be used to access the network's collective AI computing power.
+> *Cogito, Creo, Codex* — I think, I create, I code.
+
+Transform idle browser compute into a globally distributed AI infrastructure. Edge-net combines WebRTC P2P networking, WASM-accelerated cryptography, and a modular plugin architecture to create a self-sustaining collective intelligence network.
+
+> **v0.5.1** - Now with hardened plugin system featuring Ed25519 verification, rate limiting, and HKDF key derivation.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│              EDGE-NET: COLLECTIVE AI COMPUTING NETWORK                      │
+│              EDGE-NET: DECENTRALIZED AI COMPUTE NETWORK                     │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                             │
 │   ┌─────────────┐       ┌─────────────┐       ┌─────────────┐              │
-│   │  Your       │       │  Collective │       │  AI Tasks   │              │
-│   │  Browser    │◄─────►│  Network    │◄─────►│  Completed  │              │
-│   │  (Idle CPU) │  P2P  │  (1000s)    │       │  for You    │              │
+│   │  Browser    │       │  Global P2P │       │  AI Tasks   │              │
+│   │  Nodes      │◄─────►│  Mesh       │◄─────►│  Executed   │              │
+│   │  (WASM)     │ WebRTC│  (Genesis)  │       │  Privately  │              │
 │   └─────────────┘       └─────────────┘       └─────────────┘              │
 │         │                     │                     │                       │
 │         ▼                     ▼                     ▼                       │
 │   ┌─────────────┐       ┌─────────────┐       ┌─────────────┐              │
-│   │  Contribute │       │  Earn rUv   │       │  Use rUv    │              │
-│   │  Compute    │  ───► │  Units      │  ───► │  for AI     │              │
-│   │  When Idle  │       │  (Credits)  │       │  Workloads  │              │
+│   │  Contribute │       │  Earn rUv   │       │  Extend via │              │
+│   │  Idle CPU   │  ───► │  Credits    │  ───► │  Plugins    │              │
+│   │  Securely   │       │  Privately  │       │  Modularly  │              │
 │   └─────────────┘       └─────────────┘       └─────────────┘              │
 │                                                                             │
-│   Vector Search │ Embeddings │ Semantic Match │ Encryption │ Compression   │
+│   Vector Search │ Embeddings │ E2E Encryption │ Federated ML │ Swarm AI    │
 │                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
+## Why Edge-Net?
+
+| Problem | Edge-Net Solution |
+|---------|-------------------|
+| **Centralized AI** requires sending your data to cloud providers | **Local-first** - your data never leaves your browser |
+| **GPU scarcity** makes AI expensive and inaccessible | **Collective compute** - thousands of browsers working together |
+| **Monolithic systems** force all-or-nothing adoption | **Plugin architecture** - enable only what you need |
+| **Closed networks** lock you into vendor ecosystems | **Open P2P** - WebRTC mesh with no central authority |
+| **Opaque AI** - you can't verify what's running | **Transparent WASM** - auditable, reproducible compute |
+
 ## Table of Contents
 
 - [WebRTC P2P Networking](#webrtc-p2p-networking)
+- [Plugin System](#plugin-system)
+- [Core Invariants](#core-invariants)
 - [What is Edge-Net?](#what-is-edge-net)
 - [Key Features](#key-features)
 - [Quick Start](#quick-start)
@@ -165,6 +181,259 @@ const channel = pc.createDataChannel('edge-net');
 
 ---
 
+## Plugin System
+
+Edge-net features a **modular plugin architecture** that lets you enable only the capabilities you need. Plugins are cryptographically verified, sandboxed, and rate-limited for security.
+
+### Plugin Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      EDGE-NET PLUGIN ARCHITECTURE                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                        Plugin Loader (Secure)                        │   │
+│   │  • Ed25519 signature verification  • Rate limiting (100 req/min)    │   │
+│   │  • SHA-256 integrity checks        • Capability-based sandbox       │   │
+│   │  • Lazy loading with cache         • Frozen manifest objects        │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│   ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐   │
+│   │   CORE    │ │  NETWORK  │ │  CRYPTO   │ │  PRIVACY  │ │    AI     │   │
+│   │           │ │           │ │           │ │           │ │           │   │
+│   │ Compress  │ │ Mesh Opt  │ │ ZK-Proofs │ │ Onion     │ │ Federated │   │
+│   │ Metrics   │ │ Gossip    │ │ MPC       │ │ Mixnet    │ │ Swarm     │   │
+│   │ Logging   │ │ DHT       │ │ Threshold │ │ PIR       │ │ RL Agent  │   │
+│   └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘   │
+│                                                                             │
+│   ┌───────────┐ ┌───────────┐ ┌───────────┐                               │
+│   │ ECONOMIC  │ │  STORAGE  │ │  EXOTIC   │                               │
+│   │           │ │           │ │           │                               │
+│   │ Staking   │ │ IPFS      │ │ Time      │                               │
+│   │ AMM       │ │ Arweave   │ │ Crystal   │                               │
+│   │ Auction   │ │ Filecoin  │ │ Morpho    │                               │
+│   └───────────┘ └───────────┘ └───────────┘                               │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Plugin Categories
+
+| Category | Description | Example Plugins |
+|----------|-------------|-----------------|
+| **core** | Essential functionality | compression, metrics, logging |
+| **network** | Network topology & routing | mesh-optimization, gossip-protocol, dht-routing |
+| **crypto** | Cryptographic features | zk-proofs, mpc-compute, threshold-signatures, e2e-encryption |
+| **privacy** | Privacy-enhancing tech | onion-routing, mixnet, pir (private info retrieval) |
+| **ai** | AI/ML capabilities | federated-learning, swarm-intelligence, rl-agents, onnx-inference |
+| **economic** | Incentive mechanisms | reputation-staking, amm-pricing, auction-mechanism |
+| **storage** | Data persistence | ipfs-storage, arweave-persist, filecoin-deals |
+| **exotic** | Experimental features | time-crystal, morphogenetic-net, quantum-sim |
+
+### Plugin Tiers
+
+| Tier | Badge | Description |
+|------|-------|-------------|
+| **stable** | 🟢 | Production-ready, security audited |
+| **beta** | 🟡 | Feature complete, needs testing |
+| **experimental** | 🟠 | Works but may change |
+| **research** | 🔴 | Academic/research only |
+
+### Capability Permissions
+
+Plugins declare required capabilities. The loader enforces these at runtime:
+
+| Capability | Permission | Description |
+|------------|------------|-------------|
+| `network:connect` | Network | Outbound connections |
+| `network:listen` | Network | Accept connections |
+| `network:relay` | Network | Relay for other nodes |
+| `crypto:sign` | Crypto | Digital signatures |
+| `crypto:encrypt` | Crypto | Encryption/decryption |
+| `crypto:keygen` | Crypto | Key generation |
+| `storage:read` | Storage | Read local data |
+| `storage:write` | Storage | Write local data |
+| `storage:delete` | Storage | Delete local data |
+| `compute:cpu` | Compute | CPU-intensive work |
+| `compute:gpu` | Compute | WebGPU acceleration |
+| `compute:wasm` | Compute | WASM module execution |
+| `system:env` | System | Environment variables |
+| `system:fs` | System | Filesystem access |
+| `system:exec` | System | Execute commands (denied by default) |
+
+### Quick Start with Plugins
+
+```javascript
+import { PluginManager } from '@ruvector/edge-net/plugins';
+
+// Get plugin manager instance
+const plugins = PluginManager.getInstance({
+    allowedTiers: ['stable', 'beta'],
+    verifySignatures: true,
+});
+
+// Load individual plugins
+const compression = await plugins.load('core.compression');
+const encryption = await plugins.load('crypto.e2e-encryption');
+
+// Or load a bundle
+await plugins.loadBundle('privacy-focused');
+// Loads: compression, e2e-encryption, onion-routing, zk-proofs, pir
+
+// Use plugins
+const compressed = compression.compress(data);
+const encrypted = encryption.encrypt('peer-123', sensitiveData);
+```
+
+### Available Bundles
+
+| Bundle | Plugins | Use Case |
+|--------|---------|----------|
+| **minimal** | (none) | Bare-bones, maximum control |
+| **standard** | compression, metrics, e2e-encryption | Typical usage |
+| **privacy-focused** | compression, e2e-encryption, onion-routing, zk-proofs, pir | Maximum privacy |
+| **ai-compute** | compression, federated-learning, swarm-intelligence, onnx-inference | AI workloads |
+| **experimental** | All experimental tier plugins | Research & testing |
+
+### CLI Commands
+
+```bash
+# List all plugins
+edge-net plugins list
+
+# Filter by category or tier
+edge-net plugins list privacy
+edge-net plugins list experimental
+
+# Get plugin details
+edge-net plugins info crypto.zk-proofs
+
+# List bundles
+edge-net plugins bundles
+
+# Create custom plugin
+edge-net plugins create my-plugin --category ai --tier experimental
+
+# Validate plugin
+edge-net plugins validate ./my-plugin/index.js
+```
+
+### Creating Custom Plugins
+
+```javascript
+import { BasePlugin, PluginCategory, PluginTier, Capability } from '@ruvector/edge-net/plugins/sdk';
+
+class MyCustomPlugin extends BasePlugin {
+    static manifest = {
+        id: 'custom.my-plugin',
+        name: 'My Custom Plugin',
+        version: '1.0.0',
+        description: 'Does amazing things',
+        category: PluginCategory.AI,
+        tier: PluginTier.EXPERIMENTAL,
+        capabilities: [Capability.COMPUTE_WASM, Capability.NETWORK_CONNECT],
+    };
+
+    async onInit(config, sandbox) {
+        sandbox.require(Capability.COMPUTE_WASM);
+        this.ready = true;
+    }
+
+    async process(data) {
+        // Your plugin logic
+        return { processed: true, data };
+    }
+}
+
+// Register with the plugin system
+import { getRegistry } from '@ruvector/edge-net/plugins/sdk';
+getRegistry().register(MyCustomPlugin);
+```
+
+### Security Features
+
+| Feature | Implementation |
+|---------|----------------|
+| **Ed25519 Signatures** | All non-stable plugins must be cryptographically signed |
+| **SHA-256 Checksums** | Verify plugin integrity before loading |
+| **Rate Limiting** | 100 requests/minute per plugin to prevent DoS |
+| **Capability Sandbox** | Plugins can only access declared capabilities |
+| **Frozen Manifests** | Plugin metadata immutable after load |
+| **HKDF Key Derivation** | Secure key generation with proper entropy |
+| **Path Validation** | Prevent directory traversal attacks |
+| **Trusted Authors** | Public key registry for verified developers |
+
+### Plugin Failure Semantics
+
+Plugins operate under explicit failure constraints to prevent ecosystem fragility:
+
+- **Silent degradation**: Plugins may fail, be unloaded, or be rate-limited without warning to the caller
+- **Core isolation**: Network liveness, task routing, and credit settlement never depend on plugin success
+- **No blocking**: Plugins cannot block core operations; timeouts are enforced at the sandbox level
+
+### Built-in Plugin Implementations
+
+| Plugin | Description | Performance |
+|--------|-------------|-------------|
+| **compression** | LZ4/Zstd compression | 354 MB/s |
+| **e2e-encryption** | AES-256-GCM with HKDF | 54K ops/sec |
+| **federated-learning** | Byzantine-tolerant FL | 12.7M samples/sec |
+| **reputation-staking** | Stake-weighted trust | Instant |
+| **swarm-intelligence** | PSO/GA/DE/ACO optimization | 19K iter/sec |
+
+---
+
+## Core Invariants
+
+> *Cogito, Creo, Codex* — The system thinks collectively, creates through contribution, and codifies trust in cryptographic proof.
+
+These rules are not configurable. They define what Edge-net *is*.
+
+| Invariant | Constraint |
+|-----------|------------|
+| **Network liveness without plugins** | The network must route tasks, settle credits, and maintain connections with zero plugins loaded. Plugins extend; they never enable. |
+| **Economic settlement isolation** | rUv minting, burning, and settlement are core-only operations. Economic plugins may observe, suggest, or model—but never execute settlement. |
+| **Identity persistence and decay** | Identities are permanent once created, but reputation decays without activity. New identities face a warm-up curve before full participation. |
+| **Verifiable work or no reward** | Credit issuance requires cryptographic proof of work completion. Unverifiable claims are rejected, not trusted. |
+| **Degradation over halt** | The system degrades gracefully under load, attack, or partial failure. It never halts. Consistency is sacrificed before availability. |
+
+### Economic Boundaries
+
+The credit system is explicitly **not extensible**:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         ECONOMIC SETTLEMENT BOUNDARY                         │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   CORE (immutable)                    PLUGINS (observable only)             │
+│   ┌─────────────────────────┐        ┌─────────────────────────┐           │
+│   │ • rUv minting           │        │ • Pricing suggestions   │           │
+│   │ • rUv burning           │   ──►  │ • Reputation scoring    │           │
+│   │ • Credit settlement     │  read  │ • Economic modeling     │           │
+│   │ • Balance enforcement   │  only  │ • Auction mechanisms    │           │
+│   │ • Slashing execution    │        │ • AMM simulations       │           │
+│   └─────────────────────────┘        └─────────────────────────┘           │
+│                                                                             │
+│   Plugins CANNOT: mint, burn, transfer, or settle credits directly         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Identity Anti-Sybil Measures
+
+New identities face friction to prevent plugin marketplace Sybil attacks:
+
+| Mechanism | Description |
+|-----------|-------------|
+| **Delayed activation** | 24-hour window before full task execution privileges |
+| **Reputation warm-up** | Linear ramp from 0.1 to 1.0 reputation over first 100 tasks |
+| **Stake requirement** | Optional stake to unlock higher task priority (slashable) |
+| **Witness diversity** | Task results require confirmation from identities with independent creation times |
+
+---
+
 ## What is Edge-Net?
 
 Edge-net creates a **collective computing network** where participants share idle browser resources to power distributed AI workloads. Think of it as a cooperative where:
@@ -1433,6 +1702,8 @@ Edge-net is a **research platform** for collective computing. The rUv units are:
 - Used for balancing contribution and consumption
 - Not redeemable for money or goods outside the network
 
+**Edge-net makes no correctness claims. All results are challengeable.** The system optimizes for coherence and availability, not guaranteed correctness. Disputes are resolved through cryptographic evidence and stake-weighted arbitration, not authority.
+
 ---
 
 ## Links