astreum 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

astreum/node/relay/message.py

@@ -0,0 +1,105 @@
+"""
+Message related classes and utilities for Astreum node network.
+"""
+
+import struct
+from enum import Enum, auto
+from dataclasses import dataclass
+from typing import Optional
+from astreum.utils.bytes_format import encode, decode
+
+class Topic(Enum):
+    """
+    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()
+    
+    def to_bytes(self) -> bytes:
+        """
+        Convert this Topic enum value to bytes.
+        
+        Returns:
+            bytes: Single byte representing the topic
+        """
+        return struct.pack('!B', self.value)
+    
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Optional['Topic']:
+        """
+        Create a Topic from its serialized form.
+        
+        Args:
+            data (bytes): Serialized topic (single byte)
+            
+        Returns:
+            Optional[Topic]: The deserialized topic, or None if the data is invalid
+        """
+        if not data or len(data) != 1:
+            return None
+            
+        try:
+            topic_value = struct.unpack('!B', data)[0]
+            return cls(topic_value)
+        except (struct.error, ValueError) as e:
+            print(f"Error deserializing topic: {e}")
+            return None
+
+@dataclass
+class Message:
+    """
+    Represents a message in the Astreum network.
+    
+    Attributes:
+        body (bytes): The actual content of the message
+        topic (Topic): The topic/type of the message
+    """
+    body: bytes
+    topic: Topic
+    
+    def to_bytes(self) -> bytes:
+        """
+        Convert this Message to bytes using bytes_format.
+        
+        Returns:
+            bytes: Serialized message
+        """
+        return encode([
+            self.topic.to_bytes(),
+            self.body
+        ])
+    
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Optional['Message']:
+        """
+        Create a Message from its serialized form using bytes_format.
+        
+        Args:
+            data (bytes): Serialized message
+            
+        Returns:
+            Optional[Message]: The deserialized message, or None if the data is invalid
+        """
+        try:
+            parts = decode(data)
+            if len(parts) != 2:
+                return None
+                
+            topic_data, body = parts
+            topic = Topic.from_bytes(topic_data)
+            
+            if not topic:
+                return None
+                
+            return cls(body=body, topic=topic)
+        except (ValueError, struct.error) as e:
+            print(f"Error deserializing message: {e}")
+            return None

astreum/node/relay/peer.py

@@ -0,0 +1,171 @@
+"""
+Peer management for Astreum node's Kademlia-style network.
+"""
+
+from dataclasses import dataclass
+from typing import Tuple, Optional
+import time
+
+@dataclass
+class Peer:
+    """
+    Represents a peer in the Astreum network.
+    
+    Attributes:
+        address (Tuple[str, int]): The network address (host, port)
+        public_key (bytes): The public key of the peer
+        difficulty (int): The proof-of-work difficulty required for this peer
+        last_seen (int): Timestamp when the peer was last seen
+        failed_attempts (int): Number of consecutive failed communication attempts
+    """
+    address: Tuple[str, int]
+    public_key: bytes
+    difficulty: int = 1
+    last_seen: int = 0
+    failed_attempts: int = 0
+    
+    def __post_init__(self):
+        if self.last_seen == 0:
+            self.last_seen = int(time.time())
+    
+    def update_last_seen(self):
+        """Update the last seen timestamp to current time."""
+        self.last_seen = int(time.time())
+        self.failed_attempts = 0
+    
+    def register_failed_attempt(self):
+        """Register a failed communication attempt with this peer."""
+        self.failed_attempts += 1
+    
+    def is_active(self, max_age: int = 3600, max_failures: int = 3) -> bool:
+        """
+        Check if the peer is considered active.
+        
+        Args:
+            max_age (int): Maximum age in seconds before peer is considered inactive
+            max_failures (int): Maximum consecutive failures before peer is considered inactive
+            
+        Returns:
+            bool: True if the peer is active, False otherwise
+        """
+        current_time = int(time.time())
+        return (
+            (current_time - self.last_seen) <= max_age and 
+            self.failed_attempts < max_failures
+        )
+
+class PeerManager:
+    """
+    Manages a collection of peers and provides utilities for peer operations.
+    """
+    
+    def __init__(self, our_node_id: bytes):
+        """
+        Initialize a peer manager.
+        
+        Args:
+            our_node_id (bytes): Our node's unique identifier
+        """
+        self.our_node_id = our_node_id
+        self.peers_by_id = {}  # node_id: Peer
+        self.peers_by_address = {}  # address: Peer
+    
+    def add_or_update_peer(self, address: Tuple[str, int], public_key: bytes) -> Peer:
+        """
+        Add a new peer or update an existing one.
+        
+        Args:
+            address (Tuple[str, int]): Network address (host, port)
+            public_key (bytes): The public key of the peer
+            
+        Returns:
+            Peer: The added or updated peer
+        """
+        # Check if we already know this peer by ID
+        if public_key in self.peers_by_id:
+            peer = self.peers_by_id[public_key]
+            # Update address if changed
+            if peer.address != address:
+                if peer.address in self.peers_by_address:
+                    del self.peers_by_address[peer.address]
+                peer.address = address
+                self.peers_by_address[address] = peer
+            peer.update_last_seen()
+            return peer
+        
+        # Check if address exists with different ID
+        if address in self.peers_by_address:
+            old_peer = self.peers_by_address[address]
+            if old_peer.public_key in self.peers_by_id:
+                del self.peers_by_id[old_peer.public_key]
+        
+        # Create and add new peer
+        peer = Peer(address=address, public_key=public_key)
+        self.peers_by_id[public_key] = peer
+        self.peers_by_address[address] = peer
+        return peer
+    
+    def get_peer_by_id(self, public_key: bytes) -> Optional[Peer]:
+        """
+        Get a peer by its public key.
+        
+        Args:
+            public_key (bytes): The peer's public key
+            
+        Returns:
+            Optional[Peer]: The peer if found, None otherwise
+        """
+        return self.peers_by_id.get(public_key)
+    
+    def get_peer_by_address(self, address: Tuple[str, int]) -> Optional[Peer]:
+        """
+        Get a peer by its network address.
+        
+        Args:
+            address (Tuple[str, int]): The peer's network address
+            
+        Returns:
+            Optional[Peer]: The peer if found, None otherwise
+        """
+        return self.peers_by_address.get(address)
+    
+    def remove_peer(self, public_key: bytes) -> bool:
+        """
+        Remove a peer by its public key.
+        
+        Args:
+            public_key (bytes): The peer's public key
+            
+        Returns:
+            bool: True if the peer was removed, False otherwise
+        """
+        if public_key in self.peers_by_id:
+            peer = self.peers_by_id[public_key]
+            del self.peers_by_id[public_key]
+            if peer.address in self.peers_by_address:
+                del self.peers_by_address[peer.address]
+            return True
+        return False
+    
+    def calculate_distance(self, public_key: bytes) -> int:
+        """
+        Calculate the XOR distance between our node ID and the given public key.
+        
+        Args:
+            public_key (bytes): The remote node's public key
+            
+        Returns:
+            int: XOR distance (0-255)
+        """
+        # Assuming IDs are 256-bit (32 bytes)
+        for i in range(min(len(self.our_node_id), len(public_key))):
+            xor_byte = self.our_node_id[i] ^ public_key[i]
+            if xor_byte == 0:
+                continue
+                
+            # Find the most significant bit
+            for bit in range(7, -1, -1):
+                if (xor_byte >> bit) & 1:
+                    return (i * 8) + (7 - bit)
+        
+        return 255  # Default maximum distance

astreum/node/relay/route.py

@@ -0,0 +1,125 @@
+"""
+Kademlia-style routing table implementation for Astreum node.
+"""
+
+from typing import List, Dict, Set, Tuple, Optional
+from .bucket import KBucket
+from .peer import Peer, PeerManager
+
+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.
+    """
+    
+    def __init__(self, config: dict, our_node_id: bytes):
+        """
+        Initialize the routing table.
+        
+        Args:
+            config (dict): Configuration dictionary
+            our_node_id (bytes): Our node's unique identifier
+        """
+        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)
+        
+    def add_peer(self, peer: Peer) -> bool:
+        """
+        Add a peer to the appropriate k-bucket based on distance.
+        
+        Args:
+            peer (Peer): The peer to add
+            
+        Returns:
+            bool: True if the peer was added, False otherwise
+        """
+        distance = self.peer_manager.calculate_distance(peer.public_key)
+        
+        # Create bucket if it doesn't exist
+        if distance not in self.buckets:
+            self.buckets[distance] = KBucket(self.bucket_size)
+            
+        # Add to bucket
+        return self.buckets[distance].add(peer.address)
+        
+    def remove_peer(self, peer: Peer) -> bool:
+        """
+        Remove a peer from its k-bucket.
+        
+        Args:
+            peer (Peer): The peer to remove
+            
+        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)
+        return False
+            
+    def get_closest_peers(self, target_id: bytes, limit: int = 20) -> List[Peer]:
+        """
+        Get the closest peers to a target ID.
+        
+        Args:
+            target_id (bytes): The target ID to find closest peers to
+            limit (int): Maximum number of peers to return
+            
+        Returns:
+            List[Peer]: The closest peers
+        """
+        # 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]]
+    
+    def get_bucket_stats(self) -> Dict[int, int]:
+        """
+        Get statistics about the buckets in the routing table.
+        
+        Returns:
+            Dict[int, int]: Mapping of distance to number of peers in that bucket
+        """
+        return {distance: len(bucket) for distance, bucket in self.buckets.items()}
+    
+    def get_peers_in_bucket(self, distance: int) -> List[Peer]:
+        """
+        Get all peers in a specific bucket.
+        
+        Args:
+            distance (int): Bucket distance
+            
+        Returns:
+            List[Peer]: Peers in the bucket
+        """
+        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

astreum/utils/bytes_format.py

@@ -0,0 +1,75 @@
+def encode(iterable, encoder=lambda x: x):
+    """
+    Encode an iterable of items into a single bytes object, applying the
+    provided encoder function to each item to convert it into bytes.
+    
+    For each item (after applying encoder), we:
+      - Determine its length (n)
+      - Write a single byte to indicate how many bytes were used for the length:
+          0: n == 0
+          1: n <= 255
+          2: 256 <= n <= 65535
+          4: 65536 <= n <= 4294967295
+          8: n > 4294967295
+      - Write the little-endian encoding of n in the specified number of bytes (if n > 0)
+      - Append the item’s data
+    """
+    result = bytearray()
+    for item in iterable:
+        item_bytes = encoder(item)
+        n = len(item_bytes)
+        if n > 4294967295:
+            result.append(8)
+            result.extend(n.to_bytes(8, byteorder='little'))
+        elif n > 65535:
+            result.append(4)
+            result.extend(n.to_bytes(4, byteorder='little'))
+        elif n > 255:
+            result.append(2)
+            result.extend(n.to_bytes(2, byteorder='little'))
+        elif n > 0:
+            result.append(1)
+            result.extend(n.to_bytes(1, byteorder='little'))
+        else:
+            result.append(0)
+        result.extend(item_bytes)
+    return bytes(result)
+
+
+def decode(buffer, decoder=lambda x: x):
+    """
+    Decode a bytes buffer into a list of items, applying the provided decoder
+    function to convert the bytes into the desired type.
+    
+    The buffer is read sequentially:
+      - Read one byte that indicates how many bytes were used for the length.
+      - If this value is 0, then the item is empty.
+      - Otherwise, read that many bytes to get the item's length (as a little-endian integer).
+      - Then, slice the next 'length' bytes from the buffer to get the item data.
+      - Apply the decoder function to the item data before appending it.
+    
+    By default, the decoder is the identity function, so items are returned as bytes.
+    """
+    decoded_data = []
+    offset = 0
+    buf_len = len(buffer)
+    
+    while offset < buf_len:
+        length_type = buffer[offset]
+        offset += 1
+
+        if length_type == 0:
+            n = 0
+        else:
+            if offset + length_type > buf_len:
+                raise ValueError("Buffer too short for length field")
+            n = int.from_bytes(buffer[offset: offset+length_type], byteorder='little')
+            offset += length_type
+        
+        if offset + n > buf_len:
+            raise ValueError("Buffer is too short for item data")
+        item_data = buffer[offset:offset+n]
+        offset += n
+        decoded_data.append(decoder(item_data))
+        
+    return decoded_data

{astreum-0.1.5.dist-info → astreum-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: astreum
-Version: 0.1.5
+Version: 0.1.6
 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.1.5.dist-info → astreum-0.1.6.dist-info}/RECORD

@@ -1,4 +1,4 @@
-astreum/__init__.py,sha256=-hmy95qFWlCbmHEcj5sGniM-UtpIn-iwwhVWFrFkd_w,37
+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
@@ -16,11 +16,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=DJjbYnR--oeUta5xYZtxHBf1-zFzJ33vkRufTVWFkNM,11027
-astreum/machine/environment.py,sha256=sW1ws7M6cfa2xWL9783ZRRte5AZ0qslYDVZozcTdiQk,607
+astreum/machine/__init__.py,sha256=5Sx-_MEYFG-089q2G8JtLp9_ELiPYnYIXhagjy6C4w0,11048
+astreum/machine/environment.py,sha256=K0084U6B7wwjrDZ9b2_7cEcbBzsB7UOy_Zpbrr7B3GY,834
 astreum/machine/error.py,sha256=MvqBaZZt33rNELNhUJ2lER3TE3aS8WVqsWF2hz2AwoA,38
-astreum-0.1.5.dist-info/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
-astreum-0.1.5.dist-info/METADATA,sha256=H8-xQAHYH0aBx4S9nnC4sb-YQDjazdyyB_tdtJoCqnA,741
-astreum-0.1.5.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-astreum-0.1.5.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
-astreum-0.1.5.dist-info/RECORD,,
+astreum/node/__init__.py,sha256=OUU7zcTp-eFv-4jB9JETfrei0wqx8CzozOaNfPHRm-0,18003
+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/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/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+astreum/utils/bytes_format.py,sha256=X4tG5GGPweNCE54bHYkLFiuLTbmpy5upO_s1Cef-MGA,2711
+astreum-0.1.6.dist-info/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
+astreum-0.1.6.dist-info/METADATA,sha256=b_LZeCHI1_ST9e53ACed8__f9NwZkEUTA7qwSu9oep0,741
+astreum-0.1.6.dist-info/WHEEL,sha256=EaM1zKIUYa7rQnxGiOCGhzJABRwy4WO57rWMR3_tj4I,91
+astreum-0.1.6.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
+astreum-0.1.6.dist-info/RECORD,,

{astreum-0.1.5.dist-info → astreum-0.1.6.dist-info}/WHEEL

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