nexaroa 0.0.111__py3-none-any.whl

neuroshard/core/consensus/verifier.py

@@ -0,0 +1,252 @@
+"""
+Proof of Neural Work - Semantic Verifier
+
+This module enforces UNIVERSAL verification rules - the "laws of physics" that apply
+to ALL nodes regardless of their internal state. These are constraints that no
+legitimate node can violate.
+
+Architecture:
+============
+The verification system has two layers:
+
+1. ProofVerifier (this file) - Universal Constraints
+   - Physical rate limits (no GPU can exceed certain throughput)
+   - Required fields validation
+   - Format and sanity checks
+   - Delegates to model_interface for node-specific checks
+
+2. ModelInterface (e.g., SwarmEnabledDynamicNode) - Node-Specific State
+   - Internal counter verification (only the node knows its true work count)
+   - Model hash matching against local architecture
+   - Training enabled status
+
+The Verifier enforces *laws of physics*.
+The Node enforces *personal integrity*.
+"""
+
+import logging
+from typing import Tuple, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# PHYSICAL CONSTANTS - Hardware Limits
+# =============================================================================
+# These are generous upper bounds based on current GPU capabilities.
+# Even an H100 cluster cannot exceed these sustained rates.
+
+# Maximum training batches per second (sustained)
+# Rationale: Even H100 with small batch takes ~50ms per step minimum
+# 2.0 batches/sec = 500ms/batch, very generous for any real training
+MAX_TRAINING_RATE_PER_SEC = 2.0
+
+# Maximum inference tokens per second per GPU
+# Rationale: H100 can do ~3000 tokens/sec for small models, ~500 for large
+# 5000 is generous upper bound for any realistic deployment
+MAX_INFERENCE_TOKENS_PER_SEC = 5000.0
+
+# Minimum uptime to claim meaningful work (prevents micro-farming)
+MIN_UPTIME_FOR_TRAINING_REWARD = 10.0  # 10 seconds
+
+
+class ProofVerifier:
+    """
+    Verifies the semantic validity of Proof of Neural Work.
+    
+    Enforces universal constraints that apply to ALL nodes:
+    - Physical hardware limits (rate caps)
+    - Required field validation
+    - Proof format sanity
+    
+    Delegates node-specific verification to the model_interface:
+    - Internal work counter validation
+    - Local model hash matching
+    - Training state verification
+    
+    Usage:
+        verifier = ProofVerifier(model_interface=swarm_node)
+        is_valid, reason = verifier.verify_work_content(proof)
+    """
+    
+    def __init__(self, model_interface: Optional[Any] = None):
+        """
+        Initialize the verifier.
+        
+        Args:
+            model_interface: Object implementing verify_training_work(proof).
+                             Typically a SwarmEnabledDynamicNode.
+                             Required for training proof verification.
+        """
+        self.model_interface = model_interface
+        
+    def verify_work_content(self, proof: Any) -> Tuple[bool, str]:
+        """
+        Verify the content of a PoNW proof.
+        
+        Applies universal constraints first, then delegates to
+        model_interface for node-specific validation.
+        
+        Args:
+            proof: The PoNWProof object to verify
+            
+        Returns:
+            (is_valid, reason) tuple
+        """
+        proof_type = getattr(proof, 'proof_type', None)
+        
+        if proof_type == "training":
+            return self._verify_training_work(proof)
+        elif proof_type == "inference":
+            return self._verify_inference_work(proof)
+        elif proof_type == "uptime":
+            return self._verify_uptime_work(proof)
+        elif proof_type == "data":
+            return self._verify_data_work(proof)
+        else:
+            return False, f"Unknown proof type: {proof_type}"
+            
+    def _verify_training_work(self, proof: Any) -> Tuple[bool, str]:
+        """
+        Verify training proof with both universal and node-specific checks.
+        
+        Universal Checks (this method):
+        1. Required fields present (model_hash)
+        2. Physical rate limit (can't exceed hardware capabilities)
+        3. Minimum uptime threshold
+        
+        Node-Specific Checks (delegated to model_interface):
+        4. Model hash matches local architecture
+        5. Claimed batches <= internal counter
+        6. Training is actually enabled
+        
+        The "Golden Rule" of PoNW: L(w - lr * g) < L(w)
+        We verify this indirectly through counter checks.
+        """
+        # =====================================================================
+        # UNIVERSAL CHECK 1: Required Fields
+        # =====================================================================
+        if not getattr(proof, 'model_hash', None):
+            return False, "Missing model hash for training proof"
+        
+        # =====================================================================
+        # UNIVERSAL CHECK 2: Physical Rate Limit
+        # =====================================================================
+        # No GPU can sustain more than MAX_TRAINING_RATE_PER_SEC batches/second.
+        # This is a hard physical constraint.
+        uptime = getattr(proof, 'uptime_seconds', 0)
+        batches = getattr(proof, 'training_batches', 0)
+        
+        if uptime > 0 and batches > 0:
+            rate = batches / uptime
+            if rate > MAX_TRAINING_RATE_PER_SEC:
+                return False, (
+                    f"Impossible training rate: {rate:.2f} batches/sec "
+                    f"(max: {MAX_TRAINING_RATE_PER_SEC})"
+                )
+        
+        # =====================================================================
+        # UNIVERSAL CHECK 3: Minimum Uptime
+        # =====================================================================
+        # Prevent micro-farming attacks with tiny uptimes
+        if batches > 0 and uptime < MIN_UPTIME_FOR_TRAINING_REWARD:
+            return False, (
+                f"Uptime too short for training reward: {uptime:.1f}s "
+                f"(min: {MIN_UPTIME_FOR_TRAINING_REWARD}s)"
+            )
+        
+        # =====================================================================
+        # NODE-SPECIFIC CHECKS: Delegate to ModelInterface
+        # =====================================================================
+        # These checks require knowledge of the node's internal state.
+        if self.model_interface is None:
+            return False, "Cannot verify training work: no model interface available"
+        
+        if not hasattr(self.model_interface, 'verify_training_work'):
+            return False, "Model interface missing verify_training_work method"
+        
+        return self.model_interface.verify_training_work(proof)
+
+    def _verify_inference_work(self, proof: Any) -> Tuple[bool, str]:
+        """
+        Verify inference proof via economic receipts.
+        
+        Inference rewards flow from User -> Node.
+        We verify that the User authorized this work.
+        
+        Universal Checks:
+        1. Request ID present (links to payment)
+        2. Token rate within physical limits
+        """
+        # =====================================================================
+        # UNIVERSAL CHECK 1: Request ID Required
+        # =====================================================================
+        if not getattr(proof, 'request_id', None):
+            return False, "Missing request_id: anonymous inference not verifiable"
+        
+        # =====================================================================
+        # UNIVERSAL CHECK 2: Token Rate Limit
+        # =====================================================================
+        uptime = getattr(proof, 'uptime_seconds', 0)
+        tokens = getattr(proof, 'tokens_processed', 0)
+        
+        if uptime > 0 and tokens > 0:
+            rate = tokens / uptime
+            if rate > MAX_INFERENCE_TOKENS_PER_SEC:
+                return False, (
+                    f"Impossible inference rate: {rate:.0f} tokens/sec "
+                    f"(max: {MAX_INFERENCE_TOKENS_PER_SEC})"
+                )
+        
+        # Inference receipts are further validated by the Market/Ledger
+        # which checks that the user actually paid for this request
+        return True, "Inference work linked to valid request"
+    
+    def _verify_uptime_work(self, proof: Any) -> Tuple[bool, str]:
+        """
+        Verify uptime proof.
+        
+        Uptime is verified through:
+        1. Gossip protocol (peers attest to availability)
+        2. Rate limits in the Ledger (can't claim faster than real time)
+        
+        The Ledger handles most uptime validation through its
+        rate limiting and gossip-based peer attestation.
+        """
+        uptime = getattr(proof, 'uptime_seconds', 0)
+        
+        # Sanity check: uptime can't be negative
+        if uptime < 0:
+            return False, "Negative uptime is invalid"
+        
+        # Sanity check: uptime can't exceed proof window
+        # (The Ledger enforces this more precisely with timestamps)
+        max_reasonable_uptime = 3600 * 24  # 24 hours max per proof
+        if uptime > max_reasonable_uptime:
+            return False, f"Uptime {uptime}s exceeds maximum proof window"
+        
+        return True, "Uptime valid"
+    
+    def _verify_data_work(self, proof: Any) -> Tuple[bool, str]:
+        """
+        Verify data serving proof.
+        
+        Data serving is verified optimistically:
+        - Nodes claim they served data shards
+        - The tracker/DHT can spot-check availability
+        - Economic incentives discourage false claims
+        
+        Future: Could add Merkle proofs for data possession.
+        """
+        layers_held = getattr(proof, 'layers_held', 0)
+        
+        # Sanity check: can't hold negative layers
+        if layers_held < 0:
+            return False, "Negative layers_held is invalid"
+        
+        # Sanity check: can't hold more layers than exist
+        max_layers = 128  # Generous upper bound
+        if layers_held > max_layers:
+            return False, f"layers_held {layers_held} exceeds maximum {max_layers}"
+        
+        return True, "Data serving valid (optimistic verification)"

neuroshard/core/crypto/__init__.py

@@ -0,0 +1,20 @@
+# neuroshard/core/crypto/__init__.py
+"""
+Cryptography components for NeuroShard.
+
+- ecdsa: ECDSA signing and verification
+"""
+
+__all__ = [
+    'sign_message',
+    'verify_signature',
+    'generate_keypair',
+    'is_valid_node_id_format',
+]
+
+def __getattr__(name):
+    """Lazy loading of submodules."""
+    if name in ('sign_message', 'verify_signature', 'generate_keypair', 'is_valid_node_id_format'):
+        from neuroshard.core.crypto import ecdsa
+        return getattr(ecdsa, name)
+    raise AttributeError(f"module 'neuroshard.core.crypto' has no attribute '{name}'")

neuroshard/core/crypto/ecdsa.py

@@ -0,0 +1,392 @@
+"""
+NEURO Cryptographic Module - ECDSA Only
+
+This module provides cryptographic primitives for the NEURO token system
+using ECDSA (Elliptic Curve Digital Signature Algorithm) with secp256k1.
+
+Security Model:
+===============
+ECDSA allows ANYONE to verify a signature without knowing the private key.
+This enables TRUE TRUSTLESS verification in the P2P network.
+
+Key Components:
+1. Private Key: 32-byte secret derived from node_token
+2. Public Key: 33-byte compressed point on secp256k1 curve
+3. Node ID: First 32 hex chars of SHA256(public_key)
+4. Signature: DER-encoded ECDSA signature
+
+Why ECDSA over HMAC:
+- HMAC requires shared secret - only the signer can verify
+- ECDSA uses public/private key pair - ANYONE can verify with public key
+- This enables trustless P2P verification without central authority
+"""
+
+import hashlib
+import os
+import logging
+from typing import Tuple, Optional
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+# Import cryptography library for ECDSA - REQUIRED
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.backends import default_backend
+from cryptography.exceptions import InvalidSignature
+
+ECDSA_AVAILABLE = True
+
+
+@dataclass
+class KeyPair:
+    """ECDSA key pair for signing and verification."""
+    private_key_bytes: bytes  # 32 bytes
+    public_key_bytes: bytes   # 33 bytes (compressed)
+    node_id: str              # 32 hex chars (from public key hash)
+
+
+def derive_keypair_from_token(node_token: str) -> KeyPair:
+    """
+    Derive an ECDSA key pair from a node token.
+    
+    The private key is derived deterministically from the token,
+    ensuring the same token always produces the same key pair.
+    
+    Args:
+        node_token: The node's secret token (from registration)
+        
+    Returns:
+        KeyPair with private key, public key, and derived node_id
+        
+    Raises:
+        ValueError: If key derivation fails
+    """
+    # Derive 32-byte private key from token
+    private_key_bytes = hashlib.sha256(node_token.encode()).digest()
+    
+    # Create ECDSA private key from bytes
+    private_key = ec.derive_private_key(
+        int.from_bytes(private_key_bytes, 'big'),
+        ec.SECP256K1(),
+        default_backend()
+    )
+    
+    # Get public key in compressed format
+    public_key = private_key.public_key()
+    public_key_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.X962,
+        format=serialization.PublicFormat.CompressedPoint
+    )
+    
+    # Derive node_id from public key (first 32 hex chars of SHA256)
+    node_id = hashlib.sha256(public_key_bytes).hexdigest()[:32]
+    
+    return KeyPair(
+        private_key_bytes=private_key_bytes,
+        public_key_bytes=public_key_bytes,
+        node_id=node_id
+    )
+
+
+def ecdsa_sign(payload: str, private_key_bytes: bytes) -> str:
+    """
+    Sign a payload using ECDSA with secp256k1 curve.
+    
+    Args:
+        payload: The message to sign
+        private_key_bytes: 32-byte private key
+        
+    Returns:
+        Hex-encoded DER signature
+    """
+    # Recreate private key from bytes
+    private_key = ec.derive_private_key(
+        int.from_bytes(private_key_bytes, 'big'),
+        ec.SECP256K1(),
+        default_backend()
+    )
+    
+    # Sign the payload
+    signature = private_key.sign(
+        payload.encode(),
+        ec.ECDSA(hashes.SHA256())
+    )
+    
+    # Return hex-encoded signature
+    return signature.hex()
+
+
+def ecdsa_verify(payload: str, signature_hex: str, public_key_bytes: bytes) -> bool:
+    """
+    Verify an ECDSA signature.
+    
+    This is the key function that enables TRUSTLESS verification.
+    Anyone can verify a signature using only the public key.
+    
+    Args:
+        payload: The original message
+        signature_hex: Hex-encoded DER signature
+        public_key_bytes: 33-byte compressed public key
+        
+    Returns:
+        True if signature is valid
+    """
+    try:
+        # Decode signature
+        signature = bytes.fromhex(signature_hex)
+        
+        # Recreate public key from bytes
+        public_key = ec.EllipticCurvePublicKey.from_encoded_point(
+            ec.SECP256K1(),
+            public_key_bytes
+        )
+        
+        # Verify signature
+        public_key.verify(
+            signature,
+            payload.encode(),
+            ec.ECDSA(hashes.SHA256())
+        )
+        
+        return True
+    except InvalidSignature:
+        logger.debug(f"ECDSA signature verification failed")
+        return False
+    except Exception as e:
+        logger.warning(f"ECDSA verification error: {e}")
+        return False
+
+
+def derive_node_id_from_token(token: str) -> str:
+    """
+    Derive a deterministic node ID from a token.
+    
+    node_id = SHA256(public_key)[:32]
+    
+    This ensures the same token always produces the same node_id.
+    """
+    keypair = derive_keypair_from_token(token)
+    return keypair.node_id
+
+
+def sign_message(payload: str, node_token: str) -> str:
+    """
+    Sign a message using the node's ECDSA private key.
+    
+    Convenience wrapper around ecdsa_sign that derives the key from token.
+    
+    Args:
+        payload: The message to sign
+        node_token: The node's secret token
+        
+    Returns:
+        Hex-encoded ECDSA signature
+    """
+    keypair = derive_keypair_from_token(node_token)
+    return ecdsa_sign(payload, keypair.private_key_bytes)
+
+
+class NodeCrypto:
+    """
+    Cryptographic operations for a node using ECDSA.
+    
+    Provides signing and verification using secp256k1 curve.
+    """
+    
+    def __init__(self, node_token: str):
+        """
+        Initialize crypto with node token.
+        
+        Args:
+            node_token: The node's secret token
+            
+        Raises:
+            ValueError: If key derivation fails
+        """
+        self.node_token = node_token
+        self.keypair = derive_keypair_from_token(node_token)
+        self.node_id = self.keypair.node_id
+        
+        logger.info(f"ECDSA initialized for node {self.node_id[:16]}...")
+    
+    def sign(self, payload: str) -> str:
+        """
+        Sign a payload using ECDSA.
+        
+        Args:
+            payload: The message to sign
+            
+        Returns:
+            Hex-encoded ECDSA signature
+        """
+        return ecdsa_sign(payload, self.keypair.private_key_bytes)
+    
+    def verify(self, payload: str, signature: str, public_key_bytes: Optional[bytes] = None) -> bool:
+        """
+        Verify a signature.
+        
+        Args:
+            payload: The original message
+            signature: Hex-encoded ECDSA signature
+            public_key_bytes: Public key to verify against (defaults to our own)
+            
+        Returns:
+            True if signature is valid
+        """
+        pk = public_key_bytes or self.keypair.public_key_bytes
+        return ecdsa_verify(payload, signature, pk)
+    
+    def get_public_key_hex(self) -> str:
+        """Get the public key in hex format for sharing."""
+        return self.keypair.public_key_bytes.hex()
+    
+    def get_public_key_bytes(self) -> bytes:
+        """Get the raw public key bytes."""
+        return self.keypair.public_key_bytes
+    
+    def store_public_key(self, node_id: str, public_key_hex: str) -> bool:
+        """
+        Store a public key for another node (for verification).
+        
+        This is called when receiving proofs/stakes from other nodes
+        that include their public key.
+        
+        Args:
+            node_id: The node's ID
+            public_key_hex: Hex-encoded public key
+            
+        Returns:
+            True if stored successfully
+        """
+        return register_public_key(node_id, public_key_hex)
+
+
+# Registry of known public keys (node_id -> public_key_bytes)
+# This is populated via DHT gossip
+_public_key_registry: dict = {}
+
+
+def register_public_key(node_id: str, public_key_hex: str) -> bool:
+    """
+    Register a node's public key for future verification.
+    
+    Called when receiving public key announcements via gossip.
+    
+    Args:
+        node_id: The node's ID (should match SHA256(public_key)[:32])
+        public_key_hex: Hex-encoded compressed public key
+        
+    Returns:
+        True if registration successful
+    """
+    try:
+        public_key_bytes = bytes.fromhex(public_key_hex)
+        
+        # Verify the public key matches the claimed node_id
+        expected_node_id = hashlib.sha256(public_key_bytes).hexdigest()[:32]
+        if expected_node_id != node_id:
+            logger.warning(f"Public key mismatch for {node_id[:16]}... "
+                          f"(expected {expected_node_id[:16]}...)")
+            return False
+        
+        _public_key_registry[node_id] = public_key_bytes
+        logger.debug(f"Registered public key for {node_id[:16]}...")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to register public key: {e}")
+        return False
+
+
+def get_public_key(node_id: str) -> Optional[bytes]:
+    """Get a registered public key for a node."""
+    return _public_key_registry.get(node_id)
+
+
+def verify_signature(node_id: str, payload: str, signature: str, public_key_hex: str = None) -> bool:
+    """
+    Verify a signature from any node.
+    
+    This is the key function for trustless verification in the P2P network.
+    
+    SECURITY: We NEVER accept unverified signatures. If we don't have the 
+    public key, the signature is REJECTED. The sender must include their
+    public key in the message for verification.
+    
+    Args:
+        node_id: The claimed signer's node ID
+        payload: The original message
+        signature: Hex-encoded ECDSA signature
+        public_key_hex: Optional public key (if not in registry)
+        
+    Returns:
+        True if signature is valid, False otherwise
+    """
+    # Try to get public key from registry first
+    public_key = get_public_key(node_id)
+    
+    # If not in registry, try the provided public key
+    if not public_key and public_key_hex:
+        try:
+            public_key = bytes.fromhex(public_key_hex)
+            
+            # CRITICAL: Verify node_id matches the public key!
+            # node_id should be SHA256(public_key)[:32]
+            expected_node_id = hashlib.sha256(public_key).hexdigest()[:32]
+            if expected_node_id != node_id:
+                logger.warning(f"Public key mismatch! Claimed {node_id[:16]}... but key gives {expected_node_id[:16]}...")
+                return False
+            
+            # Register for future use
+            register_public_key(node_id, public_key_hex)
+        except Exception as e:
+            logger.debug(f"Failed to parse provided public key: {e}")
+    
+    if not public_key:
+        # SECURITY: No public key = REJECT
+        # We cannot verify without the public key
+        logger.warning(f"Signature rejected: No public key for {node_id[:16]}...")
+        return False
+    
+    return ecdsa_verify(payload, signature, public_key)
+
+
+def is_valid_signature_format(signature: str) -> bool:
+    """
+    Check if a signature has valid ECDSA format.
+    
+    ECDSA DER signatures are typically 70-72 bytes (140-144 hex chars).
+    """
+    if not signature:
+        return False
+    
+    # Must be hex
+    if not all(c in '0123456789abcdef' for c in signature.lower()):
+        return False
+    
+    # ECDSA DER signatures are typically 70-72 bytes
+    # In hex that's 140-144 characters
+    sig_len = len(signature)
+    if sig_len < 128 or sig_len > 150:
+        logger.debug(f"Unusual signature length: {sig_len}")
+        # Still allow - some valid signatures can vary
+    
+    return True
+
+
+def is_valid_node_id_format(node_id: str) -> bool:
+    """
+    Check if a node ID has valid format.
+    
+    Node IDs are 32 hex characters (128 bits).
+    """
+    if not node_id:
+        return False
+    
+    if len(node_id) != 32:
+        return False
+    
+    if not all(c in '0123456789abcdef' for c in node_id.lower()):
+        return False
+    
+    return True