astreum 0.2.14__py3-none-any.whl → 0.2.15__py3-none-any.whl

{astreum-0.2.14.dist-info → astreum-0.2.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.14
+Version: 0.2.15
 Summary: Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
 Project-URL: Homepage, https://github.com/astreum/lib

{astreum-0.2.14.dist-info → astreum-0.2.15.dist-info}/RECORD

@@ -1,10 +1,6 @@
 astreum/__init__.py,sha256=y2Ok3EY_FstcmlVASr80lGR_0w-dH-SXDCCQFmL6uwA,28
 astreum/format.py,sha256=X4tG5GGPweNCE54bHYkLFiuLTbmpy5upO_s1Cef-MGA,2711
 astreum/node.py,sha256=dPloCXuDyIn3-KDqxlgl3jxsonJlFMLi_quwJRsoLC8,46259
-astreum/_node/__init__.py,sha256=7yz1YHo0DCUgUQvJf75qdUo_ocl5-XZRU-Vc2NhcvJs,18639
-astreum/_node/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-astreum/_node/storage/merkle.py,sha256=XCQBrHbwI0FuPTCUwHOy-Kva3uWbvCdw_-13hRPf1UI,10219
-astreum/_node/storage/patricia.py,sha256=tynxn_qETCU9X7yJdeh_0GHpC8Pzcoq4CWrSZlMUeRc,11546
 astreum/crypto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/crypto/ed25519.py,sha256=FRnvlN0kZlxn4j-sJKl-C9tqiz_0z4LZyXLj3KIj1TQ,1760
 astreum/crypto/quadratic_form.py,sha256=pJgbORey2NTWbQNhdyvrjy_6yjORudQ67jBz2ScHptg,4037
@@ -18,8 +14,8 @@ astreum/models/block.py,sha256=NKYyxL6_BrtXRgcgIrnkYsobX0Z_bGqQT-fQ_09zEOo,3226
 astreum/models/merkle.py,sha256=ceH4yJlt82XDTXe46hyoU88QIaGVOsVDsBZeDnOJYv8,8590
 astreum/models/patricia.py,sha256=D7UVU4b6Yvn2_McI35VoMEbpqwR8OmZon5LGoUSRADo,8913
 astreum/models/transaction.py,sha256=Vu0cfmh80S31nEbxyJfv1dk9_zqtgGNyMdhlM0uQF4E,2611
-astreum-0.2.14.dist-info/licenses/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
-astreum-0.2.14.dist-info/METADATA,sha256=hW59JgJ5SxnVi7OJSrCuMT2XHIwYQonvD-3JITr-wok,5478
-astreum-0.2.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-astreum-0.2.14.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
-astreum-0.2.14.dist-info/RECORD,,
+astreum-0.2.15.dist-info/licenses/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
+astreum-0.2.15.dist-info/METADATA,sha256=7Nv0BCooioBjPEUhtTB1SdaNceBCgGf2iPZY2BLSx1E,5478
+astreum-0.2.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+astreum-0.2.15.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
+astreum-0.2.15.dist-info/RECORD,,

astreum/_node/__init__.py

@@ -1,447 +0,0 @@
-import time
-import threading
-from typing import List
-from cryptography.hazmat.primitives.asymmetric import ed25519
-from cryptography.hazmat.primitives import serialization
-
-from .relay import Relay, Topic
-from ..machine import AstreumMachine
-from .utils import hash_data
-from .validation.block import Block
-from .storage.storage import Storage
-
-class Node:
-    def __init__(self, config: dict):
-        # Ensure config is a dictionary, but allow it to be None
-        self.config = config if config is not None else {}
-        
-        # Handle validation key if provided
-        self.validation_private_key = None
-        self.validation_public_key = None
-        self.is_validator = False
-        
-        # Extract validation private key from config
-        if 'validation_private_key' in self.config:
-            try:
-                key_bytes = bytes.fromhex(self.config['validation_private_key'])
-                self.validation_private_key = ed25519.Ed25519PrivateKey.from_private_bytes(key_bytes)
-                self.validation_public_key = self.validation_private_key.public_key()
-                self.is_validator = True
-                
-                # Set validation_route to True in config so relay will join validation route
-                self.config['validation_route'] = True
-                print(f"Node is configured as a validator with validation key")
-            except Exception as e:
-                print(f"Error loading validation private key: {e}")
-        
-        # Initialize relay with our config
-        self.relay = Relay(self.config)
-        
-        # Get the node_id from relay
-        self.node_id = self.relay.node_id
-        
-        # Initialize storage
-        self.storage = Storage(self.config)
-        self.storage.node = self  # Set the storage node reference to self
-        
-        # Initialize blockchain state
-        self.blockchain = create_account_state(self.config)
-        
-        # Store our validator info if we're a validator
-        if self.is_validator and self.validation_public_key:
-            self.validator_address = self.validation_public_key.public_bytes(
-                encoding=serialization.Encoding.Raw, 
-                format=serialization.PublicFormat.Raw
-            )
-            self.validator_private_bytes = self.validation_private_key.private_bytes(
-                encoding=serialization.Encoding.Raw,
-                format=serialization.PrivateFormat.Raw,
-                encryption_algorithm=serialization.NoEncryption()
-            )
-            print(f"Registered validator with address: {self.validator_address.hex()}")
-        else:
-            self.validator_address = None
-            self.validator_private_bytes = None
-        
-        # Latest block of the chain this node is following
-        self.latest_block = None
-        self.followed_chain_id = self.config.get('followed_chain_id', None)
-        
-        # Initialize machine
-        self.machine = AstreumMachine(node=self)
-        
-        # Register message handlers
-        self.relay.message_handlers[Topic.PEER_ROUTE] = self._handle_peer_route
-        self.relay.message_handlers[Topic.PING] = self._handle_ping
-        self.relay.message_handlers[Topic.PONG] = self._handle_pong
-        self.relay.message_handlers[Topic.OBJECT_REQUEST] = self._handle_object_request
-        self.relay.message_handlers[Topic.OBJECT_RESPONSE] = self._handle_object_response
-        self.relay.message_handlers[Topic.ROUTE_REQUEST] = self._handle_route_request
-        self.relay.message_handlers[Topic.ROUTE] = self._handle_route
-        self.relay.message_handlers[Topic.LATEST_BLOCK_REQUEST] = self._handle_latest_block_request
-        self.relay.message_handlers[Topic.LATEST_BLOCK] = self._handle_latest_block
-        self.relay.message_handlers[Topic.TRANSACTION] = self._handle_transaction
-        self.relay.message_handlers[Topic.BLOCK_REQUEST] = self._handle_block_request
-        self.relay.message_handlers[Topic.BLOCK_RESPONSE] = self._handle_block_response
-        
-        # Initialize latest block from storage if available
-        self._initialize_latest_block()
-        
-        # Candidate chains that might be adopted
-        self.candidate_chains = {}  # chain_id -> {'latest_block': block, 'timestamp': time.time()}
-        self.pending_blocks = {}  # block_hash -> {'block': block, 'timestamp': time.time()}
-        
-        # Threads for validation and chain monitoring
-        self.running = False
-        self.main_chain_validation_thread = None
-        self.candidate_chain_validation_thread = None
-        
-        # Pending transactions for a block
-        self.pending_transactions = {}  # tx_hash -> {'transaction': tx, 'timestamp': time.time()}
-        
-        # Last block production attempt time
-        self.last_block_attempt_time = 0
-
-    def start(self):
-        """Start the node."""
-        self.running = True
-        
-        # Start relay
-        self.relay.start()
-        
-        # Start chain monitoring thread
-        self.main_chain_validation_thread = threading.Thread(
-            target=self._main_chain_validation_loop,
-            name="MainChainValidation"
-        )
-        self.main_chain_validation_thread.daemon = True
-        self.main_chain_validation_thread.start()
-        
-        self.candidate_chain_validation_thread = threading.Thread(
-            target=self._candidate_chain_validation_loop,
-            name="CandidateChainValidation"
-        )
-        self.candidate_chain_validation_thread.daemon = True
-        self.candidate_chain_validation_thread.start()
-        
-        # Set up recurring block query tasks
-        main_query_thread = threading.Thread(
-            target=self._block_query_loop,
-            args=('main',),
-            daemon=True
-        )
-        main_query_thread.start()
-        
-        validation_query_thread = threading.Thread(
-            target=self._block_query_loop,
-            args=('validation',),
-            daemon=True
-        )
-        validation_query_thread.start()
-        
-        print(f"Node started with ID {self.node_id.hex()}")
-
-    def stop(self):
-        """Stop the node and all its services."""
-        self.running = False
-        
-        # Stop all threads
-        if self.main_chain_validation_thread and self.main_chain_validation_thread.is_alive():
-            self.main_chain_validation_thread.join(timeout=1.0)
-            
-        if self.candidate_chain_validation_thread and self.candidate_chain_validation_thread.is_alive():
-            self.candidate_chain_validation_thread.join(timeout=1.0)
-            
-        # Stop relay last
-        if self.relay:
-            self.relay.stop()
-            
-        print("Node stopped")
-    
-    def _main_chain_validation_loop(self):
-        """
-        Main validation loop for the primary blockchain.
-        This thread prioritizes validating blocks on the main chain we're following.
-        """
-        while self.running:
-            try:
-                # Update latest block if we don't have one yet
-                if not self.latest_block and hasattr(self.blockchain, 'get_latest_block'):
-                    self.latest_block = self.blockchain.get_latest_block()
-                
-                # Process any blocks that extend our main chain immediately
-                self._process_main_chain_blocks()
-                
-                # Attempt block production if we are a validator
-                if self.is_validator and self.validator_address:
-                    self._attempt_block_production()
-                
-                # Cleanup old items
-                self._prune_pending_items()
-                
-                # Sleep to prevent high CPU usage
-                time.sleep(0.1)  # Short sleep for main chain validation
-            except Exception as e:
-                print(f"Error in main chain validation loop: {e}")
-                time.sleep(1)  # Longer sleep on error
-                
-    def _candidate_chain_validation_loop(self):
-        """
-        Validation loop for candidate chains (potential forks).
-        This thread handles validation of blocks from alternate chains 
-        without slowing down the main chain processing.
-        """
-        while self.running:
-            try:
-                # Process candidate chains
-                self._evaluate_candidate_chains()
-                
-                # Prune old candidate chains
-                self._prune_candidate_chains()
-                
-                # Sleep longer for candidate chain validation (lower priority)
-                time.sleep(1)  # Longer sleep for candidate chain validation
-            except Exception as e:
-                print(f"Error in candidate chain validation loop: {e}")
-                time.sleep(2)  # Even longer sleep on error
-                
-    def _prune_pending_items(self):
-        """Remove old pending blocks and transactions."""
-        current_time = time.time()
-        
-        # Prune old pending blocks (older than 1 hour)
-        blocks_to_remove = [
-            block_hash for block_hash, data in self.pending_blocks.items()
-            if current_time - data['timestamp'] > 3600  # 1 hour
-        ]
-        for block_hash in blocks_to_remove:
-            del self.pending_blocks[block_hash]
-            
-        # Prune old pending transactions (older than 30 minutes)
-        txs_to_remove = [
-            tx_hash for tx_hash, data in self.pending_transactions.items()
-            if current_time - data['timestamp'] > 1800  # 30 minutes
-        ]
-        for tx_hash in txs_to_remove:
-            del self.pending_transactions[tx_hash]
-            
-    def _process_main_chain_blocks(self):
-        """
-        Process blocks that extend our current main chain.
-        Prioritizes blocks that build on our latest block.
-        """
-        # Skip if we don't have a latest block yet
-        if not self.latest_block:
-            return
-            
-        # Get the hash of our latest block
-        latest_hash = self.latest_block.get_hash()
-        
-        # Find any pending blocks that build on our latest block
-        main_chain_blocks = []
-        for block_hash, data in list(self.pending_blocks.items()):
-            block = data['block']
-            
-            # Check if this block extends our latest block
-            if block.previous == latest_hash:
-                main_chain_blocks.append(block)
-                
-        # Process found blocks
-        for block in main_chain_blocks:
-            self._validate_and_process_main_chain_block(block)
-            
-    def _validate_and_process_main_chain_block(self, block: Block):
-        """
-        Validate and process a block that extends our main chain.
-        
-        Args:
-            block: Block to validate and process
-        """
-        try:
-            # Validate block
-            is_valid = validate_block(block, self.blockchain.get_accounts_at_block(block.previous), self.blockchain.get_blocks())
-            
-            if is_valid:
-                # Apply block to our state
-                success = validate_and_apply_block(self.blockchain, block)
-                if success:
-                    print(f"Applied valid block {block.number} to blockchain state")
-                    self._update_latest_block(block)
-                    blocks_to_remove = [block.get_hash()]
-                    for block_hash in blocks_to_remove:
-                        if block_hash in self.pending_blocks:
-                            del self.pending_blocks[block_hash]
-                    print(f"Added block {block.number} to blockchain")
-                    return True
-        except Exception as e:
-            print(f"Error validating main chain block {block.number}: {e}")
-            
-        return False
-            
-    def _evaluate_candidate_chains(self):
-        """
-        Evaluate candidate chains to determine if any should become our main chain.
-        This will validate pending blocks and look for chains with higher cumulative difficulty.
-        """
-        # Skip if no candidate chains
-        if not self.candidate_chains:
-            return
-            
-        # For each candidate chain, validate blocks and calculate metrics
-        for chain_id, data in list(self.candidate_chains.items()):
-            latest_candidate_block = data['latest_block']
-            
-            # Build the chain backwards
-            chain_blocks = self._build_chain_from_latest(latest_candidate_block)
-            
-            # Skip if we couldn't build a complete chain
-            if not chain_blocks:
-                continue
-                
-            # Validate the entire chain
-            valid_chain = self._validate_candidate_chain(chain_blocks)
-            
-            # If valid and better than our current chain, switch to it
-            if valid_chain and self._is_better_chain(chain_blocks):
-                self._switch_to_new_chain(chain_blocks)
-                
-    def _build_chain_from_latest(self, latest_block: Block) -> List[Block]:
-        """
-        Build a chain from the latest block back to a known point in our blockchain.
-        
-        Args:
-            latest_block: Latest block in the candidate chain
-            
-        Returns:
-            List of blocks in the chain, ordered from oldest to newest
-        """
-        chain_blocks = [latest_block]
-        current_block = latest_block
-        
-        # Track visited blocks to avoid cycles
-        visited = {current_block.get_hash()}
-        
-        # Build chain backwards until we either:
-        # 1. Find a block in our main chain
-        # 2. Run out of blocks
-        # 3. Detect a cycle
-        while current_block.number > 0:
-            previous_hash = current_block.previous
-            
-            # Check if we have this block in our blockchain
-            if hasattr(self.blockchain, 'has_block') and self.blockchain.has_block(previous_hash):
-                # Found connection to our main chain
-                previous_block = self.blockchain.get_block(previous_hash)
-                chain_blocks.insert(0, previous_block)
-                break
-                
-            # Check if block is in pending blocks
-            elif previous_hash in self.pending_blocks:
-                previous_block = self.pending_blocks[previous_hash]['block']
-                
-                # Check for cycles
-                if previous_hash in visited:
-                    print(f"Cycle detected in candidate chain at block {previous_block.number}")
-                    return []
-                    
-                visited.add(previous_hash)
-                chain_blocks.insert(0, previous_block)
-                current_block = previous_block
-            else:
-                # Missing block, cannot validate the chain
-                print(f"Missing block {previous_hash.hex()} in candidate chain")
-                return []
-                
-        return chain_blocks
-        
-    def _validate_candidate_chain(self, chain_blocks: List[Block]) -> bool:
-        """
-        Validate a candidate chain of blocks.
-        
-        Args:
-            chain_blocks: List of blocks in the chain (oldest to newest)
-            
-        Returns:
-            True if the chain is valid, False otherwise
-        """
-        # Validate each block in the chain
-        for i, block in enumerate(chain_blocks):
-            # Skip first block, it's either genesis or a block we already have
-            if i == 0:
-                continue
-                
-            # Validate block connections
-            if block.previous != chain_blocks[i-1].get_hash():
-                print(f"Invalid chain: block {block.number} does not reference previous block")
-                return False
-                
-            # Validate block
-            is_valid = validate_block(block, self.blockchain.get_accounts_at_block(block.previous), self.blockchain.get_blocks())
-            if not is_valid:
-                print(f"Invalid chain: block {block.number} is invalid")
-                return False
-                
-        return True
-        
-    def _is_better_chain(self, chain_blocks: List[Block]) -> bool:
-        """
-        Determine if a candidate chain is better than our current chain.
-        
-        Args:
-            chain_blocks: List of blocks in the candidate chain
-            
-        Returns:
-            True if the candidate chain is better, False otherwise
-        """
-        # Get the latest block from the candidate chain
-        candidate_latest = chain_blocks[-1]
-        
-        # If we don't have a latest block, any valid chain is better
-        if not self.latest_block:
-            return True
-            
-        # Compare block numbers (longest chain rule)
-        if candidate_latest.number > self.latest_block.number:
-            print(f"Candidate chain is longer: {candidate_latest.number} vs {self.latest_block.number}")
-            return True
-            
-        return False
-        
-    def _switch_to_new_chain(self, chain_blocks: List[Block]):
-        """
-        Switch to a new chain by adding all blocks to our blockchain.
-        
-        Args:
-            chain_blocks: List of blocks in the chain (oldest to newest)
-        """
-        # Find the point where the chains diverge
-        divergence_point = 0
-        for i, block in enumerate(chain_blocks):
-            # Check if we have this block in our blockchain
-            if hasattr(self.blockchain, 'has_block') and self.blockchain.has_block(block.get_hash()):
-                divergence_point = i + 1
-            else:
-                break
-                
-        # Add all blocks after the divergence point
-        for i in range(divergence_point, len(chain_blocks)):
-            block = chain_blocks[i]
-            
-            # Add block to blockchain
-            if hasattr(self.blockchain, 'add_block'):
-                try:
-                    self.blockchain.add_block(block)
-                    
-                    # Remove from pending blocks
-                    block_hash = block.get_hash()
-                    if block_hash in self.pending_blocks:
-                        del self.pending_blocks[block_hash]
-                        
-                    print(f"Added block {block.number} to blockchain")
-                except Exception as e:
-                    print(f"Error adding block {block.number} to blockchain: {e}")
-                    return
-                    
-        # Update latest block
-        self._update_latest_block(chain_blocks[-1])
-        print(f"Switched to new chain, latest block: {self.latest_block.number}")

astreum/_node/storage/merkle.py

@@ -1,224 +0,0 @@
-import blake3
-from .storage import Storage
-from astreum import format
-
-class MerkleNode:
-    def __init__(self, leaf: bool, data: bytes):
-        """
-        Initialize a Merkle node.
-        
-        For a leaf node, `data` is the actual content to be stored.
-        For an internal node, `data` should be the concatenation of the two child hashes.
-        
-        :param leaf: A boolean flag indicating whether this node is a leaf node (True) or an internal node (False).
-        :param data: The node's data. For leaves, the stored data; for internal nodes, concatenated child hashes.
-        """
-        self.leaf = leaf
-        self.data = data
-        self._hash = None  # Cached hash value to avoid recomputation.
-
-    @classmethod
-    def from_bytes(cls, data: bytes) -> 'MerkleNode':
-        """
-        Deserialize a MerkleNode from its byte representation.
-        
-        The input bytes are expected to be in the Astreum format, containing a leaf flag and node data.
-        
-        :param data: The serialized node data.
-        :return: A new MerkleNode instance.
-        """
-        leaf_flag, node_data = format.decode(data)
-        return cls(True if leaf_flag == 1 else False, node_data)
-
-    @classmethod
-    def from_storage(cls, storage: Storage, hash_value: bytes) -> 'MerkleNode' or None:
-        """
-        Retrieve and deserialize a MerkleNode from storage using its hash.
-        
-        :param storage: The Storage instance used to retrieve the node.
-        :param hash_value: The hash key under which the node is stored.
-        :return: A MerkleNode instance if found, otherwise None.
-        """
-        node_bytes = storage.get(hash_value)
-        if node_bytes is None:
-            return None
-        return cls.from_bytes(node_bytes)
-
-    def to_bytes(self) -> bytes:
-        """
-        Serialize the MerkleNode into bytes using the Astreum format.
-        
-        The format encodes a list containing the leaf flag and the node data.
-        
-        :return: The serialized bytes representing the node.
-        """
-        return format.encode([1 if self.leaf else 0, self.data])
-
-    def hash(self) -> bytes:
-        """
-        Compute (or retrieve a cached) hash of the node using the Blake3 algorithm.
-        
-        For leaf nodes, the hash is computed over the actual data.
-        For internal nodes, the hash is computed over the concatenated child hashes.
-        
-        :return: The Blake3 digest of the node's data.
-        """
-        if self._hash is None:
-            self._hash = blake3.blake3(self.data).digest()
-        return self._hash
-
-
-class MerkleTree:
-    def __init__(self, storage: Storage, root_hash: bytes = None, leaves: list[bytes] = None):
-        """
-        Initialize a Merkle tree from an existing root hash or by constructing a new tree from leaf data.
-        
-        If a list of leaf data is provided, the tree will be built from the bottom up,
-        every node will be stored in the provided storage, and the computed root hash
-        will be used as the tree's identifier.
-        
-        :param storage: A Storage instance used for storing and retrieving tree nodes.
-        :param root_hash: An optional existing root hash of a Merkle tree.
-        :param leaves: An optional list of leaf data (each as bytes). If provided, a new tree is built.
-        :raises ValueError: If neither root_hash nor leaves is provided.
-        """
-        self.storage = storage
-        if leaves is not None:
-            self.root_hash = self.build_tree_from_leaves(leaves)
-        elif root_hash is not None:
-            self.root_hash = root_hash
-        else:
-            raise ValueError("Either root_hash or leaves must be provided.")
-
-    def build_tree_from_leaves(self, leaves: list[bytes]) -> bytes:
-        """
-        Construct a Merkle tree from a list of leaf data and store each node in storage.
-        
-        Each leaf data entry is wrapped in a MerkleNode (with leaf=True) and stored.
-        Then, nodes are paired (duplicating the last node if needed when the count is odd)
-        to form parent nodes. For each parent node, the data is the concatenation of its
-        two child hashes. This process repeats until a single root hash remains.
-        
-        :param leaves: A list of bytes objects, each representing leaf data.
-        :return: The computed root hash of the newly built tree.
-        """
-        # Create leaf nodes and store them.
-        current_level = []
-        for leaf_data in leaves:
-            leaf_node = MerkleNode(True, leaf_data)
-            leaf_hash = leaf_node.hash()
-            self.storage.put(leaf_hash, leaf_node.to_bytes())
-            current_level.append(leaf_hash)
-
-        # Build the tree upward until one node remains.
-        while len(current_level) > 1:
-            next_level = []
-            # If an odd number of nodes, duplicate the last node.
-            if len(current_level) % 2 == 1:
-                current_level.append(current_level[-1])
-            for i in range(0, len(current_level), 2):
-                left_hash = current_level[i]
-                right_hash = current_level[i + 1]
-                # Create a parent node from the concatenated child hashes.
-                parent_node = MerkleNode(False, left_hash + right_hash)
-                parent_hash = parent_node.hash()
-                self.storage.put(parent_hash, parent_node.to_bytes())
-                next_level.append(parent_hash)
-            current_level = next_level
-
-        # The remaining hash is the root of the tree.
-        return current_level[0]
-
-    def get(self, index: int, level: int = 0) -> bytes:
-        """
-        Retrieve the data stored in the leaf at a given index.
-        
-        The method traverses the tree from the root, using the binary representation
-        of the index to choose which branch to follow at each level. It assumes that
-        non-leaf nodes store two child hashes concatenated together (each 32 bytes).
-        
-        :param index: The index of the leaf to retrieve. The bits of this number determine the path.
-        :param level: The current tree level (used internally for recursion).
-        :return: The data stored in the target leaf node, or None if not found.
-        """
-        current_node = MerkleNode.from_storage(self.storage, self.root_hash)
-        if current_node is None:
-            return None
-
-        # If at a leaf node, return its data.
-        if current_node.leaf:
-            return current_node.data
-
-        # For non-leaf nodes, extract the left and right child hashes.
-        left_hash = current_node.data[:32]
-        right_hash = current_node.data[32:64]
-
-        # Use the bit at position `level` in the index to select the branch:
-        # 0 selects the left branch, 1 selects the right branch.
-        bit = (index >> level) & 1
-        next_hash = left_hash if bit == 0 else right_hash
-
-        # Recursively traverse the tree.
-        return MerkleTree(self.storage, root_hash=next_hash).get(index, level + 1)
-
-    def set(self, index: int, new_data: bytes) -> None:
-        """
-        Update the leaf at the specified index with new data, rebuilding all affected nodes.
-        
-        The update process recursively creates new nodes for the branch from the updated leaf
-        back to the root. At each step, the old node is removed from storage and replaced with
-        a new node that reflects the updated hash.
-        
-        :param index: The index of the leaf node to update.
-        :param new_data: The new data (as bytes) to store in the leaf.
-        """
-        self.root_hash = self._update(self.root_hash, index, 0, new_data)
-
-    def _update(self, node_hash: bytes, index: int, level: int, new_data: bytes) -> bytes:
-        """
-        Recursive helper function to update a node on the path to the target leaf.
-        
-        For a leaf node, a new node is created with the updated data.
-        For an internal node, the correct branch (determined by the index and level) is updated,
-        and a new parent node is constructed from the updated child hash and the unchanged sibling hash.
-        
-        :param node_hash: The hash of the current node to update.
-        :param index: The target leaf index whose path is being updated.
-        :param level: The current depth in the tree.
-        :param new_data: The new data to set at the target leaf.
-        :return: The hash of the newly constructed node replacing the current node.
-        :raises Exception: If the node is not found in storage.
-        """
-        current_node = MerkleNode.from_storage(self.storage, node_hash)
-        if current_node is None:
-            raise Exception("Node not found in storage")
-
-        if current_node.leaf:
-            # At the leaf, create a new node with updated data.
-            new_leaf = MerkleNode(True, new_data)
-            new_hash = new_leaf.hash()
-            self.storage.put(new_hash, new_leaf.to_bytes())
-            self.storage.delete(node_hash)  # Remove the outdated node.
-            return new_hash
-        else:
-            # For non-leaf nodes, update the correct branch.
-            left_hash = current_node.data[:32]
-            right_hash = current_node.data[32:64]
-            bit = (index >> level) & 1
-
-            if bit == 0:
-                new_left_hash = self._update(left_hash, index, level + 1, new_data)
-                new_right_hash = right_hash
-            else:
-                new_left_hash = left_hash
-                new_right_hash = self._update(right_hash, index, level + 1, new_data)
-
-            # Create a new parent node with updated child hashes.
-            updated_node_data = new_left_hash + new_right_hash
-            new_node = MerkleNode(False, updated_node_data)
-            new_node_hash = new_node.hash()
-            self.storage.put(new_node_hash, new_node.to_bytes())
-            self.storage.delete(node_hash)  # Remove the outdated parent node.
-            return new_node_hash
-
-

astreum/_node/storage/patricia.py

@@ -1,289 +0,0 @@
-import blake3
-from typing import Optional, List
-from .storage import Storage
-import astreum.format as format format.decode, format.encode
-
-
-def common_prefix_length(a: bytes, b: bytes) -> int:
-    """Return the number of common prefix bytes between a and b."""
-    i = 0
-    while i < len(a) and i < len(b) and a[i] == b[i]:
-        i += 1
-    return i
-
-
-class PatriciaNode:
-    def __init__(self, key: bytes, value: Optional[bytes], children: Optional[List[bytes]] = None):
-        """
-        Initialize a Patricia node.
-        
-        :param key: A compressed part of the key.
-        :param value: The stored value (if this node represents a complete key) or None.
-        :param children: A list of child node hashes (bytes). The children are ordered by the first
-                         byte of the child's key.
-        """
-        self.key = key
-        self.value = value
-        self.children = children if children is not None else []
-        self._hash: Optional[bytes] = None
-
-    @classmethod
-    def from_bytes(cls, data: bytes) -> 'PatriciaNode':
-        """
-        Deserialize a PatriciaNode from its byte representation.
-        
-        Expected format: [key, value, children]
-        where children is a list of child node hashes (bytes).
-        """
-        decoded = format.decode(data)
-        key, value, children = decoded
-        return cls(key, value, children)
-
-    @classmethod
-    def from_storage(cls, storage: Storage, hash_value: bytes) -> Optional['PatriciaNode']:
-        """
-        Retrieve and deserialize a PatriciaNode from storage using its hash.
-        
-        :param storage: The Storage instance used to retrieve the node.
-        :param hash_value: The hash key under which the node is stored.
-        :return: A PatriciaNode instance if found, otherwise None.
-        """
-        node_bytes = storage.get(hash_value)
-        if node_bytes is None:
-            return None
-        return cls.from_bytes(node_bytes)
-
-    def to_bytes(self) -> bytes:
-        """
-        Serialize the PatriciaNode into bytes using the Astreum format.
-        
-        Structure: [key, value, children]
-        """
-        return format.encode([self.key, self.value, self.children])
-
-    def hash(self) -> bytes:
-        """
-        Compute (or retrieve a cached) Blake3 hash over the node's serialized bytes.
-        """
-        if self._hash is None:
-            self._hash = blake3.blake3(self.to_bytes()).digest()
-        return self._hash
-
-    def invalidate_hash(self) -> None:
-        """Clear the cached hash so that it is recomputed on next use."""
-        self._hash = None
-
-
-class PatriciaTrie:
-    def __init__(self, storage: Storage, root_hash: Optional[bytes] = None):
-        """
-        Initialize a Patricia Trie.
-        
-        :param storage: A Storage instance for persisting nodes.
-        :param root_hash: Optionally, an existing root hash. If None, the trie is empty.
-        """
-        self.storage = storage
-        self.root_hash = root_hash
-
-    def get(self, key: bytes) -> Optional[bytes]:
-        """
-        Retrieve the value associated with the given key.
-        
-        :param key: The key (as bytes) to search for.
-        :return: The stored value if found, otherwise None.
-        """
-        if self.root_hash is None:
-            return None
-        return self._get(self.root_hash, key)
-
-    def _get(self, node_hash: bytes, key: bytes) -> Optional[bytes]:
-        node = PatriciaNode.from_storage(self.storage, node_hash)
-        if node is None:
-            return None
-
-        cp_len = common_prefix_length(key, node.key)
-        # If node.key completely matches the beginning of key...
-        if cp_len == len(node.key):
-            if cp_len == len(key):
-                return node.value
-            remainder = key[cp_len:]
-            branch = remainder[0]
-            child_hash = self._find_child(node.children, branch)
-            if child_hash is None:
-                return None
-            return self._get(child_hash, remainder)
-        return None
-
-    def put(self, key: bytes, value: bytes) -> None:
-        """
-        Insert or update the key with the provided value.
-        
-        :param key: The key (as bytes) to insert.
-        :param value: The value (as bytes) to associate with the key.
-        """
-        if self.root_hash is None:
-            new_node = PatriciaNode(key, value, [])
-            new_hash = new_node.hash()
-            self.storage.put(new_hash, new_node.to_bytes())
-            self.root_hash = new_hash
-        else:
-            self.root_hash = self._put(self.root_hash, key, value)
-
-    def _put(self, node_hash: bytes, key: bytes, value: bytes) -> bytes:
-        """
-        Recursive helper for inserting or updating a key.
-        
-        Returns the new hash for the node that replaces the current node.
-        """
-        node = PatriciaNode.from_storage(self.storage, node_hash)
-        if node is None:
-            # Node missing: create a new leaf.
-            new_node = PatriciaNode(key, value, [])
-            new_hash = new_node.hash()
-            self.storage.put(new_hash, new_node.to_bytes())
-            return new_hash
-
-        cp_len = common_prefix_length(key, node.key)
-        len_node_key = len(node.key)
-        len_key = len(key)
-
-        # Case 1: Exact match: update the value.
-        if cp_len == len_node_key and cp_len == len_key:
-            node.value = value
-            node.invalidate_hash()
-            new_hash = node.hash()
-            self.storage.put(new_hash, node.to_bytes())
-            self.storage.delete(node_hash)
-            return new_hash
-
-        # Case 2: Node key is a prefix of key (descend to child).
-        if cp_len == len_node_key:
-            remainder = key[cp_len:]
-            branch = remainder[0]
-            child_hash = self._find_child(node.children, branch)
-            if child_hash is not None:
-                new_child_hash = self._put(child_hash, remainder, value)
-                # Update the child pointer in the list.
-                idx = self._find_child_index(node.children, branch)
-                if idx is None:
-                    raise Exception("Child not found during update.")
-                node.children[idx] = new_child_hash
-            else:
-                # Create a new leaf for the remainder.
-                new_leaf = PatriciaNode(remainder, value, [])
-                new_leaf_hash = new_leaf.hash()
-                self.storage.put(new_leaf_hash, new_leaf.to_bytes())
-                self._insert_child(node.children, new_leaf_hash)
-            node.invalidate_hash()
-            new_hash = node.hash()
-            self.storage.put(new_hash, node.to_bytes())
-            self.storage.delete(node_hash)
-            return new_hash
-
-        # Case 3: Key is a prefix of node.key (split node).
-        if cp_len == len_key and cp_len < len_node_key:
-            old_suffix = node.key[cp_len:]
-            node.key = old_suffix  # update node to hold only the suffix
-            node.invalidate_hash()
-
-            # Create a new branch node with the key as prefix and value.
-            branch_node = PatriciaNode(key, value, [])
-            # The existing node becomes a child of the branch.
-            self._insert_child(branch_node.children, node.hash())
-            branch_hash = branch_node.hash()
-            self.storage.put(branch_hash, branch_node.to_bytes())
-            self.storage.put(node.hash(), node.to_bytes())
-            self.storage.delete(node_hash)
-            return branch_hash
-
-        # Case 4: Partial common prefix (split into a branch with two children).
-        if cp_len < len_node_key and cp_len < len_key:
-            common_prefix = key[:cp_len]
-            old_suffix = node.key[cp_len:]
-            new_suffix = key[cp_len:]
-            branch_node = PatriciaNode(common_prefix, None, [])
-            
-            # Adjust the existing node.
-            node.key = old_suffix
-            node.invalidate_hash()
-            self._insert_child(branch_node.children, node.hash())
-
-            # Create a new leaf for the new key’s remaining portion.
-            new_leaf = PatriciaNode(new_suffix, value, [])
-            new_leaf_hash = new_leaf.hash()
-            self.storage.put(new_leaf_hash, new_leaf.to_bytes())
-            self._insert_child(branch_node.children, new_leaf_hash)
-
-            branch_hash = branch_node.hash()
-            self.storage.put(branch_hash, branch_node.to_bytes())
-            self.storage.put(node.hash(), node.to_bytes())
-            self.storage.delete(node_hash)
-            return branch_hash
-
-        raise Exception("Unhandled case in PatriciaTrie.put")
-
-    def _find_child(self, children: List[bytes], branch: int) -> Optional[bytes]:
-        """
-        Perform a binary search over the ordered children list to find the child hash whose
-        branch (first byte of its key) equals the target branch.
-        """
-        lo = 0
-        hi = len(children)
-        while lo < hi:
-            mid = (lo + hi) // 2
-            child_hash = children[mid]
-            child_node = PatriciaNode.from_storage(self.storage, child_hash)
-            if child_node is None or not child_node.key:
-                raise Exception("Child node missing or has empty key.")
-            child_branch = child_node.key[0]
-            if child_branch == branch:
-                return child_hash
-            elif child_branch < branch:
-                lo = mid + 1
-            else:
-                hi = mid
-        return None
-
-    def _find_child_index(self, children: List[bytes], branch: int) -> Optional[int]:
-        """
-        Similar to _find_child but returns the index in the list.
-        """
-        lo = 0
-        hi = len(children)
-        while lo < hi:
-            mid = (lo + hi) // 2
-            child_hash = children[mid]
-            child_node = PatriciaNode.from_storage(self.storage, child_hash)
-            if child_node is None or not child_node.key:
-                raise Exception("Child node missing or has empty key.")
-            child_branch = child_node.key[0]
-            if child_branch == branch:
-                return mid
-            elif child_branch < branch:
-                lo = mid + 1
-            else:
-                hi = mid
-        return None
-
-    def _insert_child(self, children: List[bytes], new_child_hash: bytes) -> None:
-        """
-        Insert a new child hash into the ordered children list.
-        """
-        new_child_node = PatriciaNode.from_storage(self.storage, new_child_hash)
-        if new_child_node is None or not new_child_node.key:
-            raise Exception("New child node missing or has empty key.")
-        new_branch = new_child_node.key[0]
-        lo = 0
-        hi = len(children)
-        while lo < hi:
-            mid = (lo + hi) // 2
-            child_hash = children[mid]
-            child_node = PatriciaNode.from_storage(self.storage, child_hash)
-            if child_node is None or not child_node.key:
-                raise Exception("Child node missing or has empty key.")
-            child_branch = child_node.key[0]
-            if child_branch < new_branch:
-                lo = mid + 1
-            else:
-                hi = mid
-        children.insert(lo, new_child_hash)