astreum 0.2.41__py3-none-any.whl → 0.3.1__py3-none-any.whl

astreum/__init__.py

@@ -1,9 +1,18 @@
-"""Lightweight package initializer to avoid circular imports during tests.
+
+from astreum.consensus import Account, Accounts, Block, Chain, Fork, Receipt, Transaction
+from astreum.machine import Env, Expr
+from astreum.node import Node
 
-Exports are intentionally minimal; import submodules directly as needed:
- - Node, Expr, Env, tokenize, parse -> from astreum._node or astreum.lispeum
- - Validation types -> from astreum._validation
- - Storage types -> from astreum._storage
-"""
 
-__all__: list[str] = []
+__all__: list[str] = [
+    "Node",
+    "Env",
+    "Expr",
+    "Block",
+    "Chain",
+    "Fork",
+    "Receipt",
+    "Transaction",
+    "Account",
+    "Accounts",
+]

astreum/{_communication → communication}/__init__.py

@@ -1,6 +1,6 @@
-from .message import Message
-from .peer import Peer
-from .route import Route
+from .models.message import Message
+from .models.peer import Peer
+from .models.route import Route
 from .setup import communication_setup
 
 __all__ = [

astreum/communication/handlers/handshake.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from cryptography.hazmat.primitives import serialization
+
+from ..models.peer import Peer
+from ..models.message import Message
+
+if TYPE_CHECKING:
+    from .... import Node
+
+
+def handle_handshake(node: "Node", addr: Sequence[object], message: Message) -> bool:
+    """Handle incoming handshake messages.
+
+    Returns True if the outer loop should `continue`, False otherwise.
+    """
+    logger = node.logger
+
+    sender_key = message.sender
+    try:
+        sender_public_key_bytes = sender_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    except Exception as exc:
+        logger.warning("Error extracting sender key bytes: %s", exc)
+        return True
+
+    try:
+        host, port = addr[0], int(addr[1])
+    except Exception:
+        return True
+    address_key = (host, port)
+
+    old_key_bytes = node.addresses.get(address_key)
+    node.addresses[address_key] = sender_public_key_bytes
+
+    if old_key_bytes is None:
+        try:
+            peer = Peer(node.relay_secret_key, sender_key)
+        except Exception:
+            return True
+        peer.address = address_key
+
+        node.peers[sender_public_key_bytes] = peer
+        node.peer_route.add_peer(sender_public_key_bytes, peer)
+
+        logger.info(
+            "Handshake accepted from %s:%s; peer added",
+            address_key[0],
+            address_key[1],
+        )
+        response = Message(handshake=True, sender=node.relay_public_key)
+        node.outgoing_queue.put((response.to_bytes(), address_key))
+        return True
+
+    if old_key_bytes == sender_public_key_bytes:
+        peer = node.peers.get(sender_public_key_bytes)
+        if peer is not None:
+            peer.address = address_key
+        return False
+
+    node.peers.pop(old_key_bytes, None)
+    try:
+        node.peer_route.remove_peer(old_key_bytes)
+    except Exception:
+        pass
+    try:
+        peer = Peer(node.relay_secret_key, sender_key)
+    except Exception:
+        return True
+    peer.address = address_key
+
+    node.peers[sender_public_key_bytes] = peer
+    node.peer_route.add_peer(sender_public_key_bytes, peer)
+    logger.info(
+        "Peer at %s:%s replaced due to key change",
+        address_key[0],
+        address_key[1],
+    )
+    return False

astreum/communication/handlers/ping.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Sequence
+
+from ..models.ping import Ping
+
+if TYPE_CHECKING:
+    from .... import Node
+
+
+def handle_ping(node: "Node", addr: Sequence[object], payload: bytes) -> None:
+    """Update peer and validation state based on an incoming ping message."""
+    logger = node.logger
+    try:
+        host, port = addr[0], int(addr[1])
+    except Exception:
+        return
+
+    address_key = (host, port)
+    sender_public_key_bytes = node.addresses.get(address_key)
+    if sender_public_key_bytes is None:
+        return
+
+    peer = node.peers.get(sender_public_key_bytes)
+    if peer is None:
+        return
+
+    try:
+        ping = Ping.from_bytes(payload)
+    except Exception as exc:
+        logger.warning("Error decoding ping: %s", exc)
+        return
+
+    peer.timestamp = datetime.now(timezone.utc)
+    peer.latest_block = ping.latest_block
+
+    validation_route = node.validation_route
+    if validation_route is None:
+        return
+
+    try:
+        if ping.is_validator:
+            validation_route.add_peer(sender_public_key_bytes)
+        else:
+            validation_route.remove_peer(sender_public_key_bytes)
+    except Exception:
+        pass

astreum/communication/handlers/storage_request.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from cryptography.hazmat.primitives import serialization
+
+if TYPE_CHECKING:
+    from .... import Node
+    from ..models.message import Message
+
+
+def handle_storage_request(node: "Node", addr: Sequence[object], message: "Message") -> None:
+    """Process incoming storage request payloads, forwarding if needed."""
+    logger = node.logger
+    payload = message.content
+    if len(payload) < 32:
+        return
+
+    atom_id = payload[:32]
+    provider_bytes = payload[32:]
+    if not provider_bytes:
+        return
+
+    try:
+        provider_str = provider_bytes.decode("utf-8")
+    except UnicodeDecodeError:
+        return
+
+    try:
+        host, port = addr[0], int(addr[1])
+    except Exception:
+        return
+    address_key = (host, port)
+    sender_key_bytes = node.addresses.get(address_key)
+    if sender_key_bytes is None:
+        return
+
+    try:
+        local_key_bytes = node.relay_public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    except Exception:
+        return
+
+    def xor_distance(target: bytes, key: bytes) -> int:
+        return int.from_bytes(
+            bytes(a ^ b for a, b in zip(target, key)),
+            byteorder="big",
+            signed=False,
+        )
+
+    self_distance = xor_distance(atom_id, local_key_bytes)
+
+    try:
+        closest_peer = node.peer_route.closest_peer_for_hash(atom_id)
+    except Exception:
+        closest_peer = None
+
+    if closest_peer is not None and closest_peer.public_key_bytes != sender_key_bytes:
+        closest_distance = xor_distance(atom_id, closest_peer.public_key_bytes)
+        if closest_distance < self_distance:
+            target_addr = closest_peer.address
+            if target_addr is not None and target_addr != addr:
+                try:
+                    node.outgoing_queue.put((message.to_bytes(), target_addr))
+                except Exception:
+                    return
+                logger.debug(
+                    "Forwarded storage request for %s to %s",
+                    atom_id.hex(),
+                    target_addr,
+                )
+                return
+
+    node.storage_index[atom_id] = provider_str.strip()
+    logger.debug(
+        "Stored provider %s for atom %s",
+        provider_str.strip(),
+        atom_id.hex(),
+    )

astreum/{_communication → communication/models}/message.py

@@ -10,6 +10,7 @@ class MessageTopic(IntEnum):
     ROUTE_REQUEST = 3
     ROUTE_RESPONSE = 4
     TRANSACTION = 5
+    STORAGE_REQUEST = 6
     
 
 class Message:

astreum/communication/models/peer.py

@@ -0,0 +1,23 @@
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives import serialization
+from datetime import datetime, timezone
+from typing import Optional, Tuple
+
+class Peer:
+    shared_key: bytes
+    timestamp: datetime
+    latest_block: bytes
+    address: Optional[Tuple[str, int]]
+    public_key: X25519PublicKey
+    public_key_bytes: bytes
+
+    def __init__(self, my_sec_key: X25519PrivateKey, peer_pub_key: X25519PublicKey):
+        self.shared_key = my_sec_key.exchange(peer_pub_key)
+        self.timestamp = datetime.now(timezone.utc)
+        self.latest_block = b""
+        self.address = None
+        self.public_key = peer_pub_key
+        self.public_key_bytes = peer_pub_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )

astreum/{_communication → communication/models}/route.py

@@ -1,6 +1,7 @@
-from typing import Dict, List, Union
+from typing import Dict, List, Optional, Union
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+from .peer import Peer
 
 PeerKey = Union[X25519PublicKey, bytes, bytearray]
 
@@ -15,14 +16,14 @@ class Route:
         self.buckets: Dict[int, List[bytes]] = {
             i: [] for i in range(len(self.relay_public_key_bytes) * 8)
         }
-        self.peers = {}
+        self.peers: Dict[bytes, Peer] = {}
 
     @staticmethod
-    def _matching_leading_bits(a: bytes, b: bytes) -> int:
-        for byte_index, (ba, bb) in enumerate(zip(a, b)):
-            diff = ba ^ bb
-            if diff:
-                return byte_index * 8 + (8 - diff.bit_length())
+    def _matching_leading_bits(a: bytes, b: bytes) -> int:
+        for byte_index, (ba, bb) in enumerate(zip(a, b)):
+            diff = ba ^ bb
+            if diff:
+                return byte_index * 8 + (8 - diff.bit_length())
         return len(a) * 8
 
     def _normalize_peer_key(self, peer_public_key: PeerKey) -> bytes:
@@ -38,13 +39,21 @@ class Route:
             return key_bytes
         raise TypeError("peer_public_key must be raw bytes or X25519PublicKey")
 
-    def add_peer(self, peer_public_key: PeerKey):
+    @staticmethod
+    def _xor_distance(a: bytes, b: bytes) -> int:
+        if len(a) != len(b):
+            raise ValueError("xor distance requires equal-length operands")
+        return int.from_bytes(bytes(x ^ y for x, y in zip(a, b)), "big", signed=False)
+
+    def add_peer(self, peer_public_key: PeerKey, peer: Optional[Peer] = None):
         peer_public_key_bytes = self._normalize_peer_key(peer_public_key)
         bucket_idx = self._matching_leading_bits(self.relay_public_key_bytes, peer_public_key_bytes)
         if len(self.buckets[bucket_idx]) < self.bucket_size:
             bucket = self.buckets[bucket_idx]
             if peer_public_key_bytes not in bucket:
                 bucket.append(peer_public_key_bytes)
+        if peer is not None:
+            self.peers[peer_public_key_bytes] = peer
 
     def remove_peer(self, peer_public_key: PeerKey):
         peer_public_key_bytes = self._normalize_peer_key(peer_public_key)
@@ -56,3 +65,31 @@ class Route:
             bucket.remove(peer_public_key_bytes)
         except ValueError:
             pass
+        self.peers.pop(peer_public_key_bytes, None)
+
+    def closest_peer_for_hash(self, target_hash: bytes) -> Optional[Peer]:
+        """Return the peer with the minimal XOR distance to ``target_hash``."""
+        if not isinstance(target_hash, (bytes, bytearray)):
+            raise TypeError("target_hash must be bytes-like")
+
+        target = bytes(target_hash)
+        if len(target) != len(self.relay_public_key_bytes):
+            raise ValueError("target_hash must match peer key length (32 bytes)")
+
+        closest_key: Optional[bytes] = None
+        closest_distance: Optional[int] = None
+
+        for bucket in self.buckets.values():
+            for peer_key in bucket:
+                try:
+                    distance = self._xor_distance(target, peer_key)
+                except ValueError:
+                    continue
+                if closest_distance is None or distance < closest_distance:
+                    closest_distance = distance
+                    closest_key = peer_key
+
+        if closest_key is None:
+            return None
+        peer = self.peers.get(closest_key)
+        return peer

astreum/{_communication → communication}/setup.py

@@ -1,9 +1,8 @@
 import socket, threading
-from datetime import datetime, timezone
 from queue import Queue
 from typing import Tuple, Optional
-from cryptography.hazmat.primitives.asymmetric import ed25519
 from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
 from cryptography.hazmat.primitives.asymmetric.x25519 import (
     X25519PrivateKey,
     X25519PublicKey,
@@ -14,14 +13,18 @@ if TYPE_CHECKING:
     from .. import Node
 
 from . import Route, Message
-from .message import MessageTopic
-from .peer import Peer
-from .ping import Ping
+from .handlers.handshake import handle_handshake
+from .handlers.ping import handle_ping
+from .handlers.storage_request import handle_storage_request
+from .models.message import MessageTopic
 from .util import address_str_to_host_and_port
+from ..utils.bytes import hex_to_bytes
 
 def load_x25519(hex_key: Optional[str]) -> X25519PrivateKey:
     """DH key for relaying (always X25519)."""
-    return 
+    if hex_key:
+        return X25519PrivateKey.from_private_bytes(bytes.fromhex(hex_key))
+    return X25519PrivateKey.generate()
 
 def load_ed25519(hex_key: Optional[str]) -> Optional[ed25519.Ed25519PrivateKey]:
     """Signing key for validation (Ed25519), or None if absent."""
@@ -54,104 +57,27 @@ def make_maps():
 
 def process_incoming_messages(node: "Node") -> None:
     """Process incoming messages (placeholder)."""
+    node_logger = node.logger
     while True:
         try:
             data, addr = node.incoming_queue.get()
         except Exception as exc:
-            print(f"Error taking from incoming queue: {exc}")
+            node_logger.exception("Error taking from incoming queue")
             continue
 
         try:
             message = Message.from_bytes(data)
         except Exception as exc:
-            print(f"Error decoding message: {exc}")
+            node_logger.warning("Error decoding message: %s", exc)
             continue
 
         if message.handshake:
-            sender_key = message.sender
-
-            try:
-                sender_public_key_bytes = sender_key.public_bytes(
-                    encoding=serialization.Encoding.Raw,
-                    format=serialization.PublicFormat.Raw,
-                )
-            except Exception as exc:
-                print(f"Error extracting sender key bytes: {exc}")
-                continue
-
-            # Normalize remote address (IPv6 tuples may be 4 elements)
-            try:
-                host, port = addr[0], int(addr[1])
-            except Exception:
-                continue
-            address_key = (host, port)
-
-            old_key_bytes = node.addresses.get(address_key)
-            node.addresses[address_key] = sender_public_key_bytes
-
-            if old_key_bytes is None:
-                # brand-new address -> brand-new peer
-                try:
-                    peer = Peer(node.relay_secret_key, sender_key)
-                except Exception:
-                    continue
-                
-                node.peers[sender_public_key_bytes] = peer
-                node.peer_route.add_peer(sender_public_key_bytes)
-
-                response = Message(handshake=True, sender=node.relay_public_key)
-                node.outgoing_queue.put((response.to_bytes(), address_key))
+            if handle_handshake(node, addr, message):
                 continue
-            
-            elif old_key_bytes == sender_public_key_bytes:
-                # existing mapping with same key -> nothing to change
-                pass
-            
-            else:
-                # address reused with a different key -> replace peer
-                node.peers.pop(old_key_bytes, None)
-                try:
-                    peer = Peer(node.relay_secret_key, sender_key)
-                except Exception:
-                    continue
-                
-                node.peers[sender_public_key_bytes] = peer
 
         match message.topic:
             case MessageTopic.PING:
-                try:
-                    host, port = addr[0], int(addr[1])
-                except Exception:
-                    continue
-                address_key = (host, port)
-                sender_public_key_bytes = node.addresses.get(address_key)
-                if sender_public_key_bytes is None:
-                    continue
-                peer = node.peers.get(sender_public_key_bytes)
-                if peer is None:
-                    continue
-                try:
-                    ping = Ping.from_bytes(message.content)
-                except Exception as exc:
-                    print(f"Error decoding ping: {exc}")
-                    continue
-
-                peer.timestamp = datetime.now(timezone.utc)
-                peer.latest_block = ping.latest_block
-
-                validation_route = node.validation_route
-                if validation_route is None:
-                    continue
-                if ping.is_validator:
-                    try:
-                        validation_route.add_peer(sender_public_key_bytes)
-                    except Exception:
-                        pass
-                else:
-                    try:
-                        validation_route.remove_peer(sender_public_key_bytes)
-                    except Exception:
-                        pass
+                handle_ping(node, addr, message.content)
             case MessageTopic.OBJECT_REQUEST:
                 pass
             case MessageTopic.OBJECT_RESPONSE:
@@ -164,6 +90,9 @@ def process_incoming_messages(node: "Node") -> None:
                 if node.validation_secret_key is None:
                     continue
                 node._validation_transaction_queue.put(message.content)
+
+            case MessageTopic.STORAGE_REQUEST:
+                handle_storage_request(node, addr, message)
             
             case _:
                 continue
@@ -171,14 +100,16 @@ def process_incoming_messages(node: "Node") -> None:
 
 def populate_incoming_messages(node: "Node") -> None:
     """Receive UDP packets and feed the incoming queue (placeholder)."""
+    node_logger = node.logger
     while True:
         try:
             data, addr = node.incoming_socket.recvfrom(4096)
             node.incoming_queue.put((data, addr))
         except Exception as exc:
-            print(f"Error populating incoming queue: {exc}")
+            node_logger.warning("Error populating incoming queue: %s", exc)
 
 def communication_setup(node: "Node", config: dict):
+    node.logger.info("Setting up node communication")
     node.use_ipv6              = config.get('use_ipv6', False)
 
     # key loading
@@ -208,6 +139,11 @@ def communication_setup(node: "Node", config: dict):
         node.incoming_socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 0)
     node.incoming_socket.bind(("::" if node.use_ipv6 else "0.0.0.0", incoming_port or 0))
     node.incoming_port = node.incoming_socket.getsockname()[1]
+    node.logger.info(
+        "Incoming UDP socket bound to %s:%s",
+        "::" if node.use_ipv6 else "0.0.0.0",
+        node.incoming_port,
+    )
     node.incoming_queue = Queue()
     node.incoming_populate_thread = threading.Thread(
         target=populate_incoming_messages,
@@ -236,19 +172,34 @@ def communication_setup(node: "Node", config: dict):
     node.peer_manager_thread.start()
 
     node.peers, node.addresses = {}, {} # peers: Dict[bytes,Peer], addresses: Dict[(str,int),bytes]
-    latest_hash = getattr(node, "latest_block_hash", None)
-    if not isinstance(latest_hash, (bytes, bytearray)) or len(latest_hash) != 32:
-        node.latest_block_hash = bytes(32)
+
+    latest_block_hex = config.get("latest_block_hash")
+    if latest_block_hex:
+        try:
+            node.latest_block_hash = hex_to_bytes(latest_block_hex, expected_length=32)
+        except Exception as exc:
+            node.logger.warning("Invalid latest_block_hash in config: %s", exc)
+            node.latest_block_hash = None
     else:
-        node.latest_block_hash = bytes(latest_hash)
+        node.latest_block_hash = None
 
     # bootstrap pings
-    for addr in config.get('bootstrap', []):
+    bootstrap_peers = config.get('bootstrap', [])
+    for addr in bootstrap_peers:
         try:
             host, port = address_str_to_host_and_port(addr)  # type: ignore[arg-type]
-        except Exception:
+        except Exception as exc:
+            node.logger.warning("Invalid bootstrap address %s: %s", addr, exc)
             continue
 
         handshake_message = Message(handshake=True, sender=node.relay_public_key)
         
         node.outgoing_queue.put((handshake_message.to_bytes(), (host, port)))
+        node.logger.info("Sent bootstrap handshake to %s:%s", host, port)
+
+    node.logger.info(
+        "Communication ready (incoming_port=%s, outgoing_socket_initialized=%s, bootstrap_count=%s)",
+        node.incoming_port,
+        node.outgoing_socket is not None,
+        len(bootstrap_peers),
+    )

astreum/communication/start.py

@@ -0,0 +1,38 @@
+def connect_to_network_and_verify(self):
+    """Initialize communication and consensus components, then load latest block state."""
+    node_logger = self.logger
+    node_logger.info("Starting communication and consensus setup")
+    try:
+        from astreum.communication import communication_setup  # type: ignore
+        communication_setup(node=self, config=self.config)
+        node_logger.info("Communication setup completed")
+    except Exception:
+        node_logger.exception("Communication setup failed")
+
+    try:
+        from astreum.consensus import consensus_setup  # type: ignore
+        consensus_setup(node=self, config=self.config)
+        node_logger.info("Consensus setup completed")
+    except Exception:
+        node_logger.exception("Consensus setup failed")
+
+    # Load latest_block_hash from config
+    self.latest_block_hash = getattr(self, "latest_block_hash", None)
+    self.latest_block = getattr(self, "latest_block", None)
+
+    latest_block_hex = self.config.get("latest_block_hash")
+    if latest_block_hex and self.latest_block_hash is None:
+        try:
+            from astreum.utils.bytes import hex_to_bytes
+            self.latest_block_hash = hex_to_bytes(latest_block_hex, expected_length=32)
+            node_logger.debug("Loaded latest_block_hash override from config")
+        except Exception as exc:
+            node_logger.error("Invalid latest_block_hash in config: %s", exc)
+
+    if self.latest_block_hash and self.latest_block is None:
+        try:
+            from astreum.consensus.models.block import Block
+            self.latest_block = Block.from_atom(self, self.latest_block_hash)
+            node_logger.info("Loaded latest block %s from storage", self.latest_block_hash.hex())
+        except Exception as exc:
+            node_logger.warning("Could not load latest block from storage: %s", exc)

astreum/consensus/__init__.py

@@ -0,0 +1,20 @@
+from .models.account import Account
+from .models.accounts import Accounts
+from .models.block import Block
+from .models.chain import Chain
+from .models.fork import Fork
+from .models.receipt import Receipt
+from .models.transaction import Transaction
+from .setup import consensus_setup
+
+
+__all__ = [
+    "Block",
+    "Chain",
+    "Fork",
+    "Receipt",
+    "Transaction",
+    "Account",
+    "Accounts",
+    "consensus_setup",
+]