astreum 0.1.8__py3-none-any.whl → 0.1.10__py3-none-any.whl

astreum/node/relay/bucket.py

@@ -2,7 +2,8 @@
 K-bucket implementation for Kademlia-style routing in Astreum node.
 """
 
-from typing import List, Tuple
+from typing import List, Set
+from .peer import Peer
 
 class KBucket:
     """
@@ -14,67 +15,76 @@ class KBucket:
     This creates a least-recently seen eviction policy.
     """
     
-    def __init__(self, size: int):
+    def __init__(self, k: int = 20):
         """
         Initialize a k-bucket with a fixed size.
         
         Args:
-            size (int): Maximum number of peers in the bucket
+            k (int): Maximum number of peers in the bucket
         """
-        self.size = size
-        self.peers: List[Tuple[str, int]] = []
+        self.k = k
+        self.peers: List[Peer] = []
+        self._peer_ids: Set[bytes] = set()  # Track peer IDs for quick lookup
 
-    def add(self, peer: Tuple[str, int]) -> bool:
+    def add(self, peer: Peer) -> bool:
         """
         Add peer to bucket if not full or if peer exists.
         
         Args:
-            peer (Tuple[str, int]): Peer address (host, port)
+            peer (Peer): Peer to add to the bucket
             
         Returns:
             bool: True if added/exists, False if bucket full and peer not in bucket
         """
-        if peer in self.peers:
-            # Move to end (most recently seen)
-            self.peers.remove(peer)
+        # If peer already in bucket, move to end (most recently seen)
+        if peer.public_key in self._peer_ids:
+            # Find and remove the peer
+            for i, existing_peer in enumerate(self.peers):
+                if existing_peer.public_key == peer.public_key:
+                    del self.peers[i]
+                    break
+            
+            # Add back at the end (most recently seen)
             self.peers.append(peer)
+            peer.update_last_seen()
             return True
-        
-        if len(self.peers) < self.size:
+            
+        # If bucket not full, add peer
+        if len(self.peers) < self.k:
             self.peers.append(peer)
+            self._peer_ids.add(peer.public_key)
+            peer.update_last_seen()
             return True
             
+        # Bucket full and peer not in bucket
         return False
 
-    def remove(self, peer: Tuple[str, int]) -> bool:
+    def remove(self, peer: Peer) -> bool:
         """
         Remove peer from bucket.
         
         Args:
-            peer (Tuple[str, int]): Peer address to remove
+            peer (Peer): Peer to remove
             
         Returns:
-            bool: True if peer was removed, False if peer not in bucket
+            bool: True if removed, False if not in bucket
         """
-        if peer in self.peers:
-            self.peers.remove(peer)
-            return True
+        if peer.public_key in self._peer_ids:
+            for i, existing_peer in enumerate(self.peers):
+                if existing_peer.public_key == peer.public_key:
+                    del self.peers[i]
+                    self._peer_ids.remove(peer.public_key)
+                    return True
         return False
         
-    def get_peers(self) -> List[Tuple[str, int]]:
-        """
-        Get all peers in the bucket.
-        
-        Returns:
-            List[Tuple[str, int]]: List of peer addresses
-        """
+    def get_peers(self) -> List[Peer]:
+        """Get all peers in the bucket."""
         return self.peers.copy()
         
-    def __len__(self) -> int:
-        """
-        Get the number of peers in the bucket.
+    def contains(self, peer_id: bytes) -> bool:
+        """Check if a peer ID is in the bucket."""
+        return peer_id in self._peer_ids
         
-        Returns:
-            int: Number of peers
-        """
+    def __len__(self) -> int:
+        """Get the number of peers in the bucket."""
         return len(self.peers)

astreum/node/relay/message.py

@@ -3,25 +3,30 @@ Message related classes and utilities for Astreum node network.
 """
 
 import struct
-from enum import Enum, auto
+from enum import IntEnum, auto
 from dataclasses import dataclass
 from typing import Optional
 from astreum.utils.bytes_format import encode, decode
 
-class Topic(Enum):
+class Topic(IntEnum):
     """
     Enum for different message topics in the Astreum network.
     """
-    OBJECT_REQUEST = auto()
-    OBJECT = auto()
-    PING = auto()
-    PONG = auto()
-    ROUTE = auto()
-    ROUTE_REQUEST = auto()
-    LATEST_BLOCK = auto()
-    BLOCK = auto()
-    LATEST_BLOCK_REQUEST = auto()
-    TRANSACTION = auto()
+    PEER_ROUTE = 1
+    LATEST_BLOCK_REQUEST = 2
+    LATEST_BLOCK_RESPONSE = 3
+    GET_BLOCKS = 4
+    BLOCKS = 5
+    TRANSACTION = 6
+    BLOCK_COMMIT = 7
+    OBJECT_REQUEST = 8
+    OBJECT_RESPONSE = 9
+    PING = 10
+    PONG = 11
+    ROUTE = 12
+    ROUTE_REQUEST = 13
+    LATEST_BLOCK = 14
+    BLOCK = 15
     
     def to_bytes(self) -> bytes:
         """

astreum/node/relay/peer.py

@@ -151,6 +151,9 @@ class PeerManager:
         """
         Calculate the XOR distance between our node ID and the given public key.
         
+        In Kademlia, peers are organized into buckets based on the XOR distance.
+        The bucket index (0-255) represents the position of the first bit that differs.
+        
         Args:
             public_key (bytes): The remote node's public key
             

astreum/node/relay/route.py

@@ -11,25 +11,32 @@ class RouteTable:
     Kademlia-style routing table using k-buckets.
     
     The routing table consists of k-buckets, each covering a specific range of distances.
-    Each k-bucket is a list of nodes with specific IDs in a certain distance range from ourselves.
+    In Kademlia, bucket index (i) contains nodes that share exactly i bits with the local node:
+    - Bucket 0: Contains peers that don't share the first bit with our node ID
+    - Bucket 1: Contains peers that share the first bit, but differ on the second bit
+    - Bucket 2: Contains peers that share the first two bits, but differ on the third bit
+    - And so on...
+    
+    This structuring ensures efficient routing to any node in the network.
     """
     
-    def __init__(self, config: dict, our_node_id: bytes):
+    def __init__(self, relay):
         """
         Initialize the routing table.
         
         Args:
-            config (dict): Configuration dictionary
-            our_node_id (bytes): Our node's unique identifier
+            relay: The relay instance this route table belongs to
         """
-        self.our_node_id = our_node_id
-        self.bucket_size = config.get('max_peers_per_bucket', 20)
-        self.buckets: Dict[int, KBucket] = {}
-        self.peer_manager = PeerManager(our_node_id)
+        self.relay = relay
+        self.our_node_id = relay.node_id
+        self.bucket_size = relay.config.get('max_peers_per_bucket', 20)
+        # Initialize buckets - for a 256-bit key, we need up to 256 buckets
+        self.buckets = {i: KBucket(k=self.bucket_size) for i in range(256)}
+        self.peer_manager = PeerManager(self.our_node_id)
         
     def add_peer(self, peer: Peer) -> bool:
         """
-        Add a peer to the appropriate k-bucket based on distance.
+        Add a peer to the appropriate k-bucket based on bit prefix matching.
         
         Args:
             peer (Peer): The peer to add
@@ -37,14 +44,32 @@ class RouteTable:
         Returns:
             bool: True if the peer was added, False otherwise
         """
-        distance = self.peer_manager.calculate_distance(peer.public_key)
+        # Calculate the number of matching prefix bits
+        matching_bits = self.peer_manager.calculate_distance(peer.public_key)
+        
+        # Add to the appropriate bucket based on the number of matching bits
+        return self.buckets[matching_bits].add(peer)
+        
+    def update_peer(self, addr: tuple, public_key: bytes, difficulty: int = 1) -> Peer:
+        """
+        Update or add a peer to the routing table.
         
-        # Create bucket if it doesn't exist
-        if distance not in self.buckets:
-            self.buckets[distance] = KBucket(self.bucket_size)
+        Args:
+            addr: Tuple of (ip, port)
+            public_key: Peer's public key
+            difficulty: Peer's proof-of-work difficulty
             
-        # Add to bucket
-        return self.buckets[distance].add(peer.address)
+        Returns:
+            Peer: The updated or added peer
+        """
+        # Create or update the peer
+        peer = self.peer_manager.add_or_update_peer(addr, public_key)
+        peer.difficulty = difficulty
+        
+        # Add to the appropriate bucket
+        self.add_peer(peer)
+        
+        return peer
         
     def remove_peer(self, peer: Peer) -> bool:
         """
@@ -56,70 +81,81 @@ class RouteTable:
         Returns:
             bool: True if the peer was removed, False otherwise
         """
-        distance = self.peer_manager.calculate_distance(peer.public_key)
-        
-        if distance in self.buckets:
-            return self.buckets[distance].remove(peer.address)
+        matching_bits = self.peer_manager.calculate_distance(peer.public_key)
+        if matching_bits in self.buckets:
+            return self.buckets[matching_bits].remove(peer)
         return False
-            
-    def get_closest_peers(self, target_id: bytes, limit: int = 20) -> List[Peer]:
+        
+    def get_closest_peers(self, target_id: bytes, count: int = 3) -> List[Peer]:
         """
-        Get the closest peers to a target ID.
+        Get the closest peers to the target ID.
         
         Args:
-            target_id (bytes): The target ID to find closest peers to
-            limit (int): Maximum number of peers to return
+            target_id: Target ID to find peers close to
+            count: Maximum number of peers to return
             
         Returns:
-            List[Peer]: The closest peers
+            List of peers closest to the target ID
         """
-        # Calculate distances from all known peers to the target
-        peers_with_distance = []
-        
-        for bucket in self.buckets.values():
-            for address in bucket.addresses:
-                peer = self.peer_manager.get_peer_by_address(address)
-                if peer:
-                    # Calculate XOR distance between target and this peer
-                    xor_distance = 0
-                    for i in range(min(len(target_id), len(peer.public_key))):
-                        xor_bit = target_id[i] ^ peer.public_key[i]
-                        xor_distance = (xor_distance << 8) | xor_bit
-                    
-                    peers_with_distance.append((peer, xor_distance))
-        
-        # Sort by distance (closest first)
-        peers_with_distance.sort(key=lambda x: x[1])
-        
-        # Return only the peers (without distances), up to the limit
-        return [p[0] for p in peers_with_distance[:limit]]
+        # Calculate the number of matching prefix bits with the target
+        matching_bits = self.peer_manager.calculate_distance(target_id)
+        
+        closest_peers = []
+        
+        # First check the exact matching bucket
+        if matching_bits in self.buckets:
+            bucket_peers = self.buckets[matching_bits].get_peers()
+            closest_peers.extend(bucket_peers)
+            
+        # If we need more peers, also check adjacent buckets (farther first)
+        if len(closest_peers) < count:
+            # Check buckets with fewer matching bits (higher XOR distance)
+            for i in range(matching_bits - 1, -1, -1):
+                if i in self.buckets:
+                    bucket_peers = self.buckets[i].get_peers()
+                    closest_peers.extend(bucket_peers)
+                    if len(closest_peers) >= count:
+                        break
+                        
+            # If still not enough, check buckets with more matching bits
+            if len(closest_peers) < count:
+                for i in range(matching_bits + 1, 256):
+                    if i in self.buckets:
+                        bucket_peers = self.buckets[i].get_peers()
+                        closest_peers.extend(bucket_peers)
+                        if len(closest_peers) >= count:
+                            break
+        
+        # Return the closest peers, limited by count
+        return closest_peers[:count]
     
-    def get_bucket_stats(self) -> Dict[int, int]:
+    def get_bucket_peers(self, bucket_index: int) -> List[Peer]:
         """
-        Get statistics about the buckets in the routing table.
+        Get all peers from a specific bucket.
         
+        Args:
+            bucket_index: Index of the bucket to get peers from
+            
         Returns:
-            Dict[int, int]: Mapping of distance to number of peers in that bucket
+            List of peers in the bucket
         """
-        return {distance: len(bucket) for distance, bucket in self.buckets.items()}
-    
-    def get_peers_in_bucket(self, distance: int) -> List[Peer]:
+        if bucket_index in self.buckets:
+            return self.buckets[bucket_index].get_peers()
+        return []
+        
+    def has_peer(self, addr: tuple) -> bool:
         """
-        Get all peers in a specific bucket.
+        Check if a peer with the given address exists in the routing table.
         
         Args:
-            distance (int): Bucket distance
+            addr: Tuple of (ip, port)
             
         Returns:
-            List[Peer]: Peers in the bucket
+            bool: True if the peer exists, False otherwise
         """
-        if distance not in self.buckets:
-            return []
-            
-        peers = []
-        for address in self.buckets[distance].addresses:
-            peer = self.peer_manager.get_peer_by_address(address)
-            if peer:
-                peers.append(peer)
-                
-        return peers
+        return self.peer_manager.get_peer_by_address(addr) is not None
+    
+    @property
+    def num_buckets(self) -> int:
+        """Get the number of active buckets."""
+        return len(self.buckets)

{astreum-0.1.8.dist-info → astreum-0.1.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: astreum
-Version: 0.1.8
+Version: 0.1.10
 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
@@ -11,6 +11,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pycryptodomex==3.21.0
+Requires-Dist: cryptography==44.0.2
 
 # lib
 
@@ -26,9 +28,10 @@ When initializing an Astreum Node, you need to provide a configuration dictionar
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `node_id` | bytes | Random 32 bytes | Unique identifier for the node |
-| `followed_chain_id` | bytes | None | ID of the blockchain that this node follows |
-| `storage_path` | str | "./storage" | Directory path where node data will be stored |
+| `private_key` | string | Auto-generated | Hex string of Ed25519 private key. If not provided, a new keypair will be generated automatically |
+| `storage_path` | string | "storage" | Path to store data |
+| `max_storage_space` | int | 1073741824 (1GB) | Maximum storage space in bytes |
+| `max_object_recursion` | int | 50 | Maximum recursion depth for resolving nested objects |
 
 ### Network Configuration
 
@@ -38,15 +41,17 @@ When initializing an Astreum Node, you need to provide a configuration dictionar
 | `incoming_port` | int | 7373 | Port to listen for incoming messages |
 | `max_message_size` | int | 65536 | Maximum size of UDP datagrams in bytes |
 | `num_workers` | int | 4 | Number of worker threads for message processing |
+| `network_request_timeout` | float | 5.0 | Maximum time (in seconds) to wait for network object requests |
 
 ### Route Configuration
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `peer_route` | bool | False | Whether to participate in the peer discovery route |
 | `validation_route` | bool | False | Whether to participate in the block validation route |
 | `bootstrap_peers` | list | [] | List of bootstrap peers in the format `[("hostname", port), ...]` |
 
+> **Note:** The peer route is always enabled as it's necessary for object discovery and retrieval.
+
 ### Example Usage
 
 ```python
@@ -54,8 +59,7 @@ from astreum.node import Node
 
 # Configuration dictionary
 config = {
-    "node_id": b"my-unique-node-id-goes-here-exactly-32",  # 32 bytes
-    "followed_chain_id": b"main-chain-id-goes-here",
+    "private_key": "my-private-key-goes-here",
     "storage_path": "./data/node1",
     "incoming_port": 7373,
     "use_ipv6": False,

{astreum-0.1.8.dist-info → astreum-0.1.10.dist-info}/RECORD

@@ -2,7 +2,7 @@ astreum/__init__.py,sha256=di8SwGUW1lNKUwvNWCjH9eLmz__sk1SbtuNZVjjpRe4,59
 astreum/lispeum/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/lispeum/expression.py,sha256=3zOEoXFHpzEFUIi1clONY55WYAh5K0YkYhaLmtvQj0I,2939
 astreum/lispeum/parser.py,sha256=SU8mjPj1ub4xQbU4CeX15HmKZAj4vI6TeefX2B72VCo,1191
-astreum/lispeum/storage.py,sha256=SmVDfropIP4fTOXq2_xWsWzYesLNsQBst8AIbyXdao4,16174
+astreum/lispeum/storage.py,sha256=34BXwn6RVPqdGc6q-SxHT8Qn-lH8YDtnvwJh_7E-gNQ,13948
 astreum/lispeum/tokenizer.py,sha256=4obr1Jt-k1TqhsImHWUn7adQl9Ks5_VmcEFOTlQwocQ,1437
 astreum/lispeum/special/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/lispeum/special/definition.py,sha256=ukQJ-Mz57bpqbTPQiwmevdE4uxec3Zt--apT3VhUYqU,840
@@ -17,21 +17,21 @@ astreum/lispeum/special/list/position.py,sha256=1EcD5fzfjUCUhHCk8iotFoWdeE9Z2Rjj
 astreum/lispeum/special/list/remove.py,sha256=EPhkWFwyKG8HyWPheVvtxCvMaEGvODFUbx7h1fli_hg,690
 astreum/lispeum/special/number/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/lispeum/special/number/addition.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-astreum/machine/__init__.py,sha256=5Sx-_MEYFG-089q2G8JtLp9_ELiPYnYIXhagjy6C4w0,11048
+astreum/machine/__init__.py,sha256=GOdZl1tS9uIJHbq5WVcplifMDPDLQroX7CVew-K2YbA,15262
 astreum/machine/environment.py,sha256=K0084U6B7wwjrDZ9b2_7cEcbBzsB7UOy_Zpbrr7B3GY,834
 astreum/machine/error.py,sha256=MvqBaZZt33rNELNhUJ2lER3TE3aS8WVqsWF2hz2AwoA,38
-astreum/node/__init__.py,sha256=LVNFvIpTMojaBCZ6OjunoumhVWRcQAteEobY8kxuFac,19523
-astreum/node/models.py,sha256=CBYuMJVD0uI5i6fWSFE2egkZXtFQHvR79kKTU4KP1WE,3086
-astreum/node/relay/__init__.py,sha256=i_uD8ZMuA8Xa4vdzVAdiyd5uhIv-7-n9SBUG7WiL8mk,10024
-astreum/node/relay/bucket.py,sha256=w0jzOrSUVT5WmRW_ggmtBcdf8sgZW-_MTeT4YQuhAvg,2211
+astreum/node/__init__.py,sha256=wvmMMACicwhJ-ipSLpR1rsEUXWuHaZ8fnsBCkUA_RA8,22387
+astreum/node/models.py,sha256=MScDCNEpR-SfaFsRSU567mVuZRhH1Lqc7gmlqb3j-nI,10980
+astreum/node/relay/__init__.py,sha256=gQNYDxllkjZqE6bvgPOYkKu3QHkjPFn11RvtP-BxtKI,13994
+astreum/node/relay/bucket.py,sha256=pcmollbbM-xeHlmDxLZnzvf0Ut-9v9RoN6SijYiQuu8,2893
 astreum/node/relay/envelope.py,sha256=TfkynttoPX7smvMV7xEAdtIlfz-Z-EZjuhZ826csZxA,10078
-astreum/node/relay/message.py,sha256=9j3Q5T5VVj47g0xqxUCWxtf2EFXutIPbj0mt1KbVw3M,2812
-astreum/node/relay/peer.py,sha256=eOml9G4xMoQeR_BuONVgJvpvCwhQo-QXCpRhShAxz4Q,5721
-astreum/node/relay/route.py,sha256=ZyWoTC2EXX-SU_80fFS0TP-lITH6e9mDeS-irsfcMp4,4303
+astreum/node/relay/message.py,sha256=uezmGjNaQK4fZmYQLCHd2YpiosaaFb8DOa3H58HS1jA,2887
+astreum/node/relay/peer.py,sha256=DlvTR9j0BZQ1dW-p_9UGgfLvQqwNdpNLMSCYEW4FhyI,5899
+astreum/node/relay/route.py,sha256=fyOSsAe1mfsCVeN6LtQ_OEUEb1FiC5dobZBEJKNGU9U,5814
 astreum/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/utils/bytes_format.py,sha256=X4tG5GGPweNCE54bHYkLFiuLTbmpy5upO_s1Cef-MGA,2711
-astreum-0.1.8.dist-info/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
-astreum-0.1.8.dist-info/METADATA,sha256=Uu8SnsLZ2vdk5fhicfnsqB3jCQN08u4hMB3_KZYMxOQ,2686
-astreum-0.1.8.dist-info/WHEEL,sha256=EaM1zKIUYa7rQnxGiOCGhzJABRwy4WO57rWMR3_tj4I,91
-astreum-0.1.8.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
-astreum-0.1.8.dist-info/RECORD,,
+astreum-0.1.10.dist-info/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
+astreum-0.1.10.dist-info/METADATA,sha256=50hGAAYObIlHpnh2ikWSAALUtOIwmw9O_U6c1qLCre8,2942
+astreum-0.1.10.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+astreum-0.1.10.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
+astreum-0.1.10.dist-info/RECORD,,

{astreum-0.1.8.dist-info → astreum-0.1.10.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.9.1)
+Generator: setuptools (76.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any