zexus 1.6.2

package/src/zexus/blockchain/ledger.py

@@ -0,0 +1,255 @@
+"""
+Zexus Blockchain Ledger System
+
+Implements immutable, versioned state storage for blockchain and smart contract features.
+"""
+
+import json
+import time
+import hashlib
+from copy import deepcopy
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class LedgerEntry:
+    """A single versioned entry in the ledger"""
+    
+    def __init__(self, key: str, value: Any, version: int, timestamp: float, tx_hash: str):
+        self.key = key
+        self.value = value
+        self.version = version
+        self.timestamp = timestamp
+        self.tx_hash = tx_hash
+        self.prev_hash = None
+    
+    def to_dict(self) -> Dict:
+        """Convert entry to dictionary for hashing"""
+        return {
+            'key': self.key,
+            'value': str(self.value),
+            'version': self.version,
+            'timestamp': self.timestamp,
+            'tx_hash': self.tx_hash,
+            'prev_hash': self.prev_hash
+        }
+    
+    def hash(self) -> str:
+        """Calculate hash of this entry"""
+        data = json.dumps(self.to_dict(), sort_keys=True)
+        return hashlib.sha256(data.encode()).hexdigest()
+
+
+class Ledger:
+    """
+    Immutable, versioned ledger for blockchain state.
+    
+    Features:
+    - Immutability: Old values are never modified, only new versions created
+    - Versioning: Every write creates a new version
+    - Cryptographic integrity: Each entry is hashed and linked
+    - Audit trail: Complete history of all changes
+    """
+    
+    def __init__(self, name: str):
+        self.name = name
+        self.entries: List[LedgerEntry] = []
+        self.current_state: Dict[str, Any] = {}
+        self.version_index: Dict[str, List[LedgerEntry]] = {}  # key -> list of versions
+        self.locked = False
+    
+    def write(self, key: str, value: Any, tx_hash: str) -> LedgerEntry:
+        """
+        Write a new value to the ledger (creates new version, doesn't modify old)
+        
+        Args:
+            key: The variable name
+            value: The new value
+            tx_hash: Hash of the transaction making this write
+            
+        Returns:
+            The new ledger entry
+        """
+        if self.locked:
+            raise RuntimeError(f"Ledger '{self.name}' is locked (immutable)")
+        
+        # Get current version number
+        version = len(self.version_index.get(key, [])) + 1
+        
+        # Create new entry
+        entry = LedgerEntry(
+            key=key,
+            value=deepcopy(value),  # Deep copy to prevent external modification
+            version=version,
+            timestamp=time.time(),
+            tx_hash=tx_hash
+        )
+        
+        # Link to previous entry
+        if key in self.version_index and self.version_index[key]:
+            prev_entry = self.version_index[key][-1]
+            entry.prev_hash = prev_entry.hash()
+        
+        # Add to ledger
+        self.entries.append(entry)
+        
+        # Update indices
+        if key not in self.version_index:
+            self.version_index[key] = []
+        self.version_index[key].append(entry)
+        
+        # Update current state
+        self.current_state[key] = value
+        
+        return entry
+    
+    def read(self, key: str, version: Optional[int] = None) -> Any:
+        """
+        Read a value from the ledger
+        
+        Args:
+            key: The variable name
+            version: Optional version number (defaults to latest)
+            
+        Returns:
+            The value at the specified version
+        """
+        if key not in self.version_index:
+            raise KeyError(f"Key '{key}' not found in ledger '{self.name}'")
+        
+        if version is None:
+            # Return current version
+            return deepcopy(self.current_state[key])
+        
+        # Return specific version
+        versions = self.version_index[key]
+        if version < 1 or version > len(versions):
+            raise ValueError(f"Invalid version {version} for key '{key}' (1-{len(versions)} available)")
+        
+        return deepcopy(versions[version - 1].value)
+    
+    def get_history(self, key: str) -> List[Tuple[int, Any, float, str]]:
+        """
+        Get complete history for a key
+        
+        Returns:
+            List of (version, value, timestamp, tx_hash) tuples
+        """
+        if key not in self.version_index:
+            return []
+        
+        return [
+            (entry.version, entry.value, entry.timestamp, entry.tx_hash)
+            for entry in self.version_index[key]
+        ]
+    
+    def verify_integrity(self) -> bool:
+        """
+        Verify the cryptographic integrity of the ledger
+        
+        Returns:
+            True if all hashes are valid and chain is intact
+        """
+        for key, versions in self.version_index.items():
+            prev_hash = None
+            for entry in versions:
+                # Verify hash chain
+                if entry.prev_hash != prev_hash:
+                    return False
+                prev_hash = entry.hash()
+        return True
+    
+    def seal(self):
+        """Make the ledger immutable (no more writes allowed)"""
+        self.locked = True
+    
+    def get_state_root(self) -> str:
+        """
+        Calculate the merkle root hash of the current state
+        
+        Returns:
+            SHA256 hash representing the entire current state
+        """
+        state_data = json.dumps(self.current_state, sort_keys=True)
+        return hashlib.sha256(state_data.encode()).hexdigest()
+    
+    def export_audit_trail(self) -> List[Dict]:
+        """Export complete audit trail as JSON-serializable data"""
+        return [entry.to_dict() for entry in self.entries]
+
+
+class LedgerManager:
+    """
+    Global ledger manager
+    
+    Manages all ledgers in the system and provides transaction isolation.
+    """
+    
+    def __init__(self):
+        self.ledgers: Dict[str, Ledger] = {}
+        self.transaction_stack: List[Dict[str, Any]] = []
+    
+    def create_ledger(self, name: str) -> Ledger:
+        """Create a new ledger"""
+        if name in self.ledgers:
+            raise ValueError(f"Ledger '{name}' already exists")
+        
+        ledger = Ledger(name)
+        self.ledgers[name] = ledger
+        return ledger
+    
+    def get_ledger(self, name: str) -> Ledger:
+        """Get existing ledger"""
+        if name not in self.ledgers:
+            raise KeyError(f"Ledger '{name}' not found")
+        return self.ledgers[name]
+    
+    def begin_transaction(self, tx_hash: str, caller: str, timestamp: float):
+        """Begin a new transaction scope"""
+        tx_context = {
+            'tx_hash': tx_hash,
+            'caller': caller,
+            'timestamp': timestamp,
+            'writes': [],  # List of (ledger_name, key, old_value)
+            'gas_used': 0,
+            'gas_limit': None
+        }
+        self.transaction_stack.append(tx_context)
+    
+    def commit_transaction(self):
+        """Commit current transaction"""
+        if not self.transaction_stack:
+            raise RuntimeError("No active transaction to commit")
+        
+        # Remove transaction from stack
+        self.transaction_stack.pop()
+    
+    def revert_transaction(self):
+        """
+        Revert current transaction
+        
+        Note: For ledgers, we can't truly "revert" since they're immutable.
+        Instead, we write compensating entries to restore old values.
+        """
+        if not self.transaction_stack:
+            raise RuntimeError("No active transaction to revert")
+        
+        tx = self.transaction_stack.pop()
+        
+        # Write compensating entries
+        for ledger_name, key, old_value in reversed(tx['writes']):
+            ledger = self.ledgers[ledger_name]
+            # Create a revert entry
+            ledger.write(key, old_value, f"REVERT:{tx['tx_hash']}")
+    
+    def get_current_tx(self) -> Optional[Dict]:
+        """Get current transaction context"""
+        return self.transaction_stack[-1] if self.transaction_stack else None
+
+
+# Global ledger manager instance
+_ledger_manager = LedgerManager()
+
+
+def get_ledger_manager() -> LedgerManager:
+    """Get the global ledger manager"""
+    return _ledger_manager

package/src/zexus/blockchain/transaction.py

@@ -0,0 +1,267 @@
+"""
+Zexus Blockchain Transaction Context
+
+Implements the TX object and gas tracking for smart contracts.
+"""
+
+import time
+import hashlib
+import secrets
+from typing import Optional, Dict, Any
+
+
+class TransactionContext:
+    """
+    Immutable transaction context (TX object)
+    
+    Provides mandatory information about the current execution environment:
+    - TX.caller: Address/ID of the entity executing the code
+    - TX.timestamp: Canonical, un-tamperable time of execution
+    - TX.block_hash: Cryptographic reference to the preceding state
+    - TX.gas_remaining: Remaining gas for execution
+    - TX.gas_used: Gas consumed so far
+    """
+    
+    def __init__(self, caller: str, timestamp: Optional[float] = None, 
+                 block_hash: Optional[str] = None, gas_limit: Optional[int] = None):
+        # Immutable properties
+        self._caller = caller
+        self._timestamp = timestamp if timestamp is not None else time.time()
+        self._block_hash = block_hash if block_hash else self._generate_block_hash()
+        self._gas_limit = gas_limit if gas_limit is not None else 1_000_000
+        self._gas_used = 0
+        self._reverted = False
+        self._revert_reason = None
+        
+    @property
+    def caller(self) -> str:
+        """The address/ID of the entity executing the code"""
+        return self._caller
+    
+    @property
+    def timestamp(self) -> float:
+        """The canonical, un-tamperable time of execution"""
+        return self._timestamp
+    
+    @property
+    def block_hash(self) -> str:
+        """Cryptographic reference to the preceding state"""
+        return self._block_hash
+    
+    @property
+    def gas_limit(self) -> int:
+        """Maximum gas allowed for this transaction"""
+        return self._gas_limit
+    
+    @gas_limit.setter
+    def gas_limit(self, value: int):
+        """Set gas limit (can be changed during execution via LIMIT statement)"""
+        if value < 0:
+            raise ValueError("Gas limit cannot be negative")
+        self._gas_limit = value
+    
+    @property
+    def gas_used(self) -> int:
+        """Gas consumed so far"""
+        return self._gas_used
+    
+    @property
+    def gas_remaining(self) -> int:
+        """Remaining gas for execution"""
+        return max(0, self._gas_limit - self._gas_used)
+    
+    @property
+    def reverted(self) -> bool:
+        """Whether this transaction has been reverted"""
+        return self._reverted
+    
+    @property
+    def revert_reason(self) -> Optional[str]:
+        """Reason for revert (if reverted)"""
+        return self._revert_reason
+    
+    def consume_gas(self, amount: int) -> bool:
+        """
+        Consume gas for an operation
+        
+        Returns:
+            True if enough gas available, False otherwise
+        """
+        if self._gas_used + amount > self._gas_limit:
+            return False
+        self._gas_used += amount
+        return True
+    
+    def revert(self, reason: Optional[str] = None):
+        """Mark transaction as reverted"""
+        self._reverted = True
+        self._revert_reason = reason
+    
+    def _generate_block_hash(self) -> str:
+        """Generate a pseudo-random block hash"""
+        data = f"{self._caller}{self._timestamp}{secrets.token_hex(16)}"
+        return hashlib.sha256(data.encode()).hexdigest()
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert TX context to dictionary"""
+        return {
+            'caller': self.caller,
+            'timestamp': self.timestamp,
+            'block_hash': self.block_hash,
+            'gas_limit': self.gas_limit,
+            'gas_used': self.gas_used,
+            'gas_remaining': self.gas_remaining,
+            'reverted': self.reverted,
+            'revert_reason': self.revert_reason
+        }
+    
+    def __repr__(self):
+        return f"TX(caller={self.caller}, timestamp={self.timestamp}, gas={self.gas_remaining}/{self.gas_limit})"
+
+
+class GasTracker:
+    """
+    Gas consumption tracker for operations
+    
+    Defines gas costs for different operations to prevent DoS attacks.
+    """
+    
+    # Base gas costs (inspired by EVM gas model)
+    BASE_COSTS = {
+        # Storage operations
+        'ledger_write': 20_000,
+        'ledger_read': 200,
+        'state_write': 5_000,
+        'state_read': 200,
+        
+        # Computation
+        'add': 3,
+        'sub': 3,
+        'mul': 5,
+        'div': 5,
+        'mod': 5,
+        'compare': 3,
+        
+        # Control flow
+        'if': 10,
+        'loop': 10,
+        'function_call': 100,
+        'return': 10,
+        
+        # Cryptography
+        'hash_sha256': 60,
+        'hash_keccak256': 30,
+        'signature_create': 3_000,
+        'signature_verify': 3_000,
+        
+        # Memory
+        'memory_read': 3,
+        'memory_write': 3,
+        'memory_allocate': 100,
+        
+        # Base operation
+        'base': 21_000,
+    }
+    
+    @classmethod
+    def get_cost(cls, operation: str, **kwargs) -> int:
+        """
+        Get gas cost for an operation
+        
+        Args:
+            operation: Operation name
+            **kwargs: Additional parameters (e.g., data_size for hashing)
+            
+        Returns:
+            Gas cost
+        """
+        base_cost = cls.BASE_COSTS.get(operation, 1)
+        
+        # Adjust for data size if applicable
+        if 'data_size' in kwargs:
+            # Additional cost per 32 bytes
+            size = kwargs['data_size']
+            word_cost = (size + 31) // 32
+            base_cost += word_cost * 3
+        
+        return base_cost
+    
+    @classmethod
+    def estimate_limit(cls, action_name: str) -> int:
+        """
+        Estimate reasonable gas limit for an action
+        
+        Returns:
+            Suggested gas limit
+        """
+        # Default limits for common action types
+        limits = {
+            'transfer': 50_000,
+            'mint': 100_000,
+            'burn': 50_000,
+            'approve': 50_000,
+            'swap': 150_000,
+            'stake': 100_000,
+            'unstake': 100_000,
+        }
+        
+        return limits.get(action_name, 1_000_000)
+
+
+# Transaction context stack (for nested calls)
+_tx_stack = []
+
+
+def create_tx_context(caller: str, gas_limit: Optional[int] = None,
+                      timestamp: Optional[float] = None, 
+                      block_hash: Optional[str] = None) -> TransactionContext:
+    """Create a new transaction context"""
+    tx = TransactionContext(
+        caller=caller,
+        timestamp=timestamp,
+        block_hash=block_hash,
+        gas_limit=gas_limit
+    )
+    _tx_stack.append(tx)
+    return tx
+
+
+def get_current_tx() -> Optional[TransactionContext]:
+    """Get the current transaction context"""
+    return _tx_stack[-1] if _tx_stack else None
+
+
+def end_tx_context():
+    """End the current transaction context"""
+    if _tx_stack:
+        _tx_stack.pop()
+
+
+def consume_gas(amount: int, operation: str = "unknown") -> bool:
+    """
+    Consume gas from current transaction
+    
+    Returns:
+        True if enough gas available, False otherwise
+    """
+    tx = get_current_tx()
+    if not tx:
+        return True  # No transaction context = no gas tracking
+    
+    if not tx.consume_gas(amount):
+        # Out of gas!
+        tx.revert(f"Out of gas during operation: {operation}")
+        return False
+    
+    return True
+
+
+def check_gas_and_consume(operation: str, **kwargs) -> bool:
+    """
+    Check if enough gas and consume it
+    
+    Returns:
+        True if successful, False if out of gas
+    """
+    cost = GasTracker.get_cost(operation, **kwargs)
+    return consume_gas(cost, operation)