astreum 0.2.61__py3-none-any.whl → 0.3.9__py3-none-any.whl

astreum/communication/models/message.py

@@ -0,0 +1,124 @@
+import os
+from enum import IntEnum
+from typing import Optional
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+from astreum.crypto import chacha20poly1305
+
+class MessageTopic(IntEnum):
+    PING = 0
+    OBJECT_REQUEST = 1
+    OBJECT_RESPONSE = 2
+    ROUTE_REQUEST = 3
+    ROUTE_RESPONSE = 4
+    TRANSACTION = 5
+
+
+class Message:
+    def __init__(
+        self,
+        *,
+        handshake: bool = False,
+        sender: Optional[X25519PublicKey] = None,
+        topic: Optional[MessageTopic] = None,
+        content: Optional[bytes] = None,
+        body: Optional[bytes] = None,
+        sender_bytes: Optional[bytes] = None,
+        encrypted: Optional[bytes] = None,
+    ) -> None:
+        if body is not None:
+            if content is not None and content != b"":
+                raise ValueError("specify only one of 'content' or 'body'")
+            content = body
+
+        self.handshake = handshake
+        self.topic = topic
+        self.content = content if content is not None else b""
+        self.encrypted = encrypted
+
+        if self.handshake:
+            if sender_bytes is None and sender is None:
+                raise ValueError("handshake Message requires a sender public key or sender bytes")
+            self.topic = None
+        else:
+            if self.topic is None and self.encrypted is None:
+                raise ValueError("non-handshake Message requires a topic or encrypted payload")
+            if sender_bytes is None and sender is None:
+                raise ValueError("non-handshake Message requires a sender public key or sender bytes")
+
+        if sender_bytes is not None:
+            self.sender_bytes = sender_bytes
+        else:
+            if sender is None:
+                raise ValueError("sender public key required to derive sender bytes")
+            self.sender_bytes = sender.public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw,
+            )
+
+    def to_bytes(self):
+        if self.handshake:
+            # handshake byte (1) + raw public key bytes + payload
+            return bytes([1]) + self.sender_bytes + self.content
+        else:
+            # normal message: 0 + sender + encrypted payload (nonce + ciphertext)
+            if not self.encrypted:
+                raise ValueError("non-handshake Message missing encrypted payload; call encrypt() first")
+            return bytes([0]) + self.sender_bytes + self.encrypted
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Message":
+        if len(data) < 1:
+            raise ValueError("Cannot parse Message: no data")
+
+        if len(data) < 33:
+            raise ValueError("Cannot parse Message: missing sender bytes")
+
+        if data[0] == 1:
+            return Message(
+                handshake=True,
+                sender_bytes=data[1:33],
+                content=data[33:],
+            )
+
+        else:
+            if len(data) <= 33:
+                raise ValueError("Cannot parse Message: missing encrypted payload")
+
+            return Message(
+                handshake=False,
+                sender_bytes=data[1:33],
+                encrypted=data[33:],
+            )
+
+    def encrypt(self, shared_key_bytes: bytes) -> None:
+        if self.handshake:
+            return
+        
+        if len(shared_key_bytes) != 32:
+            raise ValueError("Shared key must be 32 bytes for ChaCha20-Poly1305")
+        
+        if self.topic is None:
+            raise ValueError("Cannot encrypt message without a topic")
+
+        nonce = os.urandom(12)
+        data_to_encrypt = bytes([self.topic.value]) + self.content
+        ciphertext = chacha20poly1305.encrypt(shared_key_bytes, nonce, data_to_encrypt)
+        self.encrypted = nonce + ciphertext
+
+    def decrypt(self, shared_key_bytes: bytes) -> None:
+        if self.handshake:
+            return
+        
+        if len(shared_key_bytes) != 32:
+            raise ValueError("Shared key must be 32 bytes for ChaCha20-Poly1305")
+        
+        if not self.encrypted or len(self.encrypted) < 13:
+            raise ValueError("Encrypted content missing or too short")
+
+        nonce = self.encrypted[:12]
+        ciphertext = self.encrypted[12:]
+        decrypted = chacha20poly1305.decrypt(shared_key_bytes, nonce, ciphertext)
+        topic_value = decrypted[0]
+        self.topic = MessageTopic(topic_value)
+        self.content = decrypted[1:]

astreum/communication/models/peer.py

@@ -0,0 +1,51 @@
+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, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...node import Node
+
+class Peer:
+    def __init__(
+        self,
+        node_secret_key: X25519PrivateKey,
+        peer_public_key: X25519PublicKey,
+        latest_block: Optional[bytes] = None,
+        address: Optional[Tuple[str, int]] = None,
+    ):
+        self.shared_key_bytes = node_secret_key.exchange(peer_public_key)
+        self.timestamp = datetime.now(timezone.utc)
+        self.latest_block = latest_block
+        self.address = address
+        self.public_key_bytes = peer_public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+
+
+def add_peer(node: "Node", peer_key, peer: "Peer") -> "Peer":
+    """Register a peer entry on the node under lock."""
+    with node.peers_lock:
+        node.peers[peer_key] = peer
+    return peer
+
+
+def replace_peer(node: "Node", old_key, peer_key, peer: "Peer") -> "Peer":
+    """Replace an existing peer entry (if any) with a new one under lock."""
+    with node.peers_lock:
+        node.peers.pop(old_key, None)
+        node.peers[peer_key] = peer
+    return peer
+
+
+def get_peer(node: "Node", peer_key):
+    """Retrieve a peer entry under lock."""
+    with node.peers_lock:
+        return node.peers.get(peer_key)
+
+
+def remove_peer(node: "Node", peer_key):
+    """Remove a peer entry under lock."""
+    with node.peers_lock:
+        return node.peers.pop(peer_key, None)

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

@@ -2,6 +2,7 @@ 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
+from ..util import xor_distance
 
 PeerKey = Union[X25519PublicKey, bytes, bytearray]
 
@@ -19,11 +20,11 @@ class Route:
         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:
@@ -39,12 +40,6 @@ class Route:
             return key_bytes
         raise TypeError("peer_public_key must be raw bytes or X25519PublicKey")
 
-    @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)
@@ -82,7 +77,7 @@ class Route:
         for bucket in self.buckets.values():
             for peer_key in bucket:
                 try:
-                    distance = self._xor_distance(target, peer_key)
+                    distance = xor_distance(target, peer_key)
                 except ValueError:
                     continue
                 if closest_distance is None or distance < closest_distance:

astreum/communication/processors/incoming.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..handlers.handshake import handle_handshake
+from ..handlers.object_request import handle_object_request
+from ..handlers.object_response import handle_object_response
+from ..handlers.ping import handle_ping
+from ..handlers.route_request import handle_route_request
+from ..handlers.route_response import handle_route_response
+from ..models.message import Message, MessageTopic
+from ..models.peer import Peer
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+
+if TYPE_CHECKING:
+    from .. import Node
+
+
+def process_incoming_messages(node: "Node") -> None:
+    """Process incoming messages (placeholder)."""
+    while True:
+        try:
+            data, addr = node.incoming_queue.get()
+        except Exception as exc:
+            node.logger.exception("Error taking from incoming queue")
+            continue
+
+        try:
+            message = Message.from_bytes(data)
+        except Exception as exc:
+            node.logger.warning("Error decoding message: %s", exc)
+            continue
+
+        if message.handshake:
+            if handle_handshake(node, addr, message):
+                continue
+        
+        peer = None
+        try:
+            peer = node.get_peer(message.sender_bytes)
+        except Exception:
+            peer = None
+        if peer is None:
+            try:
+                peer_key = X25519PublicKey.from_public_bytes(message.sender_bytes)
+                host, port = addr[0], int(addr[1])
+                peer = Peer(
+                    node_secret_key=node.relay_secret_key,
+                    peer_public_key=peer_key,
+                    address=(host, port),
+                )
+            except Exception:
+                peer = None
+
+        if peer is None:
+            node.logger.debug("Unable to resolve peer for message from %s", addr)
+            continue
+
+        # decrypt message payload before dispatch
+        try:
+            message.decrypt(peer.shared_key_bytes)
+        except Exception as exc:
+            node.logger.warning("Error decrypting message from %s: %s", peer.address, exc)
+            continue
+
+        match message.topic:
+            case MessageTopic.PING:
+                handle_ping(node, peer, message.content)
+
+            case MessageTopic.OBJECT_REQUEST:
+                handle_object_request(node, peer, message)
+
+            case MessageTopic.OBJECT_RESPONSE:
+                handle_object_response(node, peer, message)
+
+            case MessageTopic.ROUTE_REQUEST:
+                handle_route_request(node, peer, message)
+
+            case MessageTopic.ROUTE_RESPONSE:
+                handle_route_response(node, peer, message)
+
+            case MessageTopic.TRANSACTION:
+                if node.validation_secret_key is None:
+                    continue
+                node._validation_transaction_queue.put(message.content)
+
+            case _:
+                continue
+
+
+def populate_incoming_messages(node: "Node") -> None:
+    """Receive UDP packets and feed the incoming queue."""
+    while True:
+        try:
+            data, addr = node.incoming_socket.recvfrom(4096)
+            node.incoming_queue.put((data, addr))
+        except Exception as exc:
+            node.logger.warning("Error populating incoming queue: %s", exc)

astreum/communication/processors/outgoing.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Tuple
+
+if TYPE_CHECKING:
+    from .. import Node
+
+def process_outgoing_messages(node: "Node") -> None:
+    """Send queued outbound packets."""
+    while True:
+        try:
+            payload, addr = node.outgoing_queue.get()
+        except Exception:
+            node.logger.exception("Error taking from outgoing queue")
+            continue
+
+        try:
+            node.outgoing_socket.sendto(payload, addr)
+        except Exception as exc:
+            node.logger.warning("Error sending message to %s: %s", addr, exc)

astreum/communication/setup.py

@@ -0,0 +1,166 @@
+import socket, threading
+from queue import Queue
+from typing import Tuple, Optional
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .. import Node
+
+from . import Route, Message
+from .processors.incoming import (
+    process_incoming_messages,
+    populate_incoming_messages,
+)
+from .processors.outgoing import process_outgoing_messages
+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)."""
+    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."""
+    return ed25519.Ed25519PrivateKey.from_private_bytes(bytes.fromhex(hex_key)) \
+           if hex_key else None
+
+def make_routes(
+    relay_pk: X25519PublicKey,
+    val_sk: Optional[ed25519.Ed25519PrivateKey]
+) -> Tuple[Route, Optional[Route]]:
+    """Peer route (DH pubkey) + optional validation route (ed pubkey)."""
+    peer_rt = Route(relay_pk)
+    val_rt  = Route(val_sk.public_key()) if val_sk else None
+    return peer_rt, val_rt
+
+def make_maps():
+    """Empty lookup maps: peers and addresses."""
+    return
+
+
+def communication_setup(node: "Node", config: dict):
+    node.logger.info("Setting up node communication")
+    node.use_ipv6              = config.get('use_ipv6', False)
+    node.peers_lock = threading.RLock()
+
+    # key loading
+    node.relay_secret_key      = load_x25519(config.get('relay_secret_key'))
+    node.validation_secret_key = load_ed25519(config.get('validation_secret_key'))
+
+    # derive pubs + routes
+    node.relay_public_key      = node.relay_secret_key.public_key()
+    node.relay_public_key_bytes = node.relay_public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    node.validation_public_key = (
+        node.validation_secret_key.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        if node.validation_secret_key
+        else None
+    )
+    node.peer_route, node.validation_route = make_routes(
+        node.relay_public_key,
+        node.validation_secret_key
+    )
+
+    # connection state & atom request tracking
+    node.is_connected = False
+    node.atom_requests = set()
+    node.atom_requests_lock = threading.RLock()
+
+    # sockets + queues + threads
+    incoming_port = config.get('incoming_port', 7373)
+    fam = socket.AF_INET6 if node.use_ipv6 else socket.AF_INET
+    node.incoming_socket = socket.socket(fam, socket.SOCK_DGRAM)
+    if node.use_ipv6:
+        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,
+        args=(node,),
+        daemon=True,
+    )
+    node.incoming_process_thread = threading.Thread(
+        target=process_incoming_messages,
+        args=(node,),
+        daemon=True,
+    )
+    node.incoming_populate_thread.start()
+    node.incoming_process_thread.start()
+
+    node.outgoing_socket = socket.socket(
+        socket.AF_INET6 if node.use_ipv6 else socket.AF_INET,
+        socket.SOCK_DGRAM,
+    )
+    node.outgoing_queue = Queue()
+
+    node.outgoing_thread = threading.Thread(
+        target=process_outgoing_messages,
+        args=(node,),
+        daemon=True,
+    )
+    node.outgoing_thread.start()
+
+    # other workers & maps
+    # track atom requests we initiated; guarded by atom_requests_lock on the node
+    node.peer_manager_thread  = threading.Thread(
+        target=node._relay_peer_manager,
+        daemon=True
+    )
+    node.peer_manager_thread.start()
+
+    with node.peers_lock:
+        node.peers, node.addresses = {}, {} # peers: Dict[bytes,Peer], addresses: Dict[(str,int),bytes]
+
+    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 = None
+
+    # bootstrap pings
+    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 as exc:
+            node.logger.warning("Invalid bootstrap address %s: %s", addr, exc)
+            continue
+
+        handshake_message = Message(
+            handshake=True,
+            sender=node.relay_public_key,
+            content=int(node.config["incoming_port"]).to_bytes(2, "big", signed=False),
+        )
+        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),
+    )
+    node.is_connected = True

astreum/communication/start.py

@@ -0,0 +1,37 @@
+def connect_to_network_and_verify(self):
+    """Initialize communication and consensus components, then load latest block state."""
+    self.logger.info("Starting communication and consensus setup")
+    try:
+        from astreum.communication import communication_setup  # type: ignore
+        communication_setup(node=self, config=self.config)
+        self.logger.info("Communication setup completed")
+    except Exception:
+        self.logger.exception("Communication setup failed")
+
+    try:
+        from astreum.consensus import consensus_setup  # type: ignore
+        consensus_setup(node=self, config=self.config)
+        self.logger.info("Consensus setup completed")
+    except Exception:
+        self.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)
+            self.logger.debug("Loaded latest_block_hash override from config")
+        except Exception as exc:
+            self.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)
+            self.logger.info("Loaded latest block %s from storage", self.latest_block_hash.hex())
+        except Exception as exc:
+            self.logger.warning("Could not load latest block from storage: %s", exc)

astreum/{_communication → communication}/util.py

@@ -40,3 +40,10 @@ def address_str_to_host_and_port(address: str) -> Tuple[str, int]:
         raise ValueError(f"port out of range: {port}")
 
     return host, port
+
+
+def xor_distance(a: bytes, b: bytes) -> int:
+    """Return the unsigned integer XOR distance between two equal-length identifiers."""
+    if len(a) != len(b):
+        raise ValueError("xor distance requires operands of equal length")
+    return int.from_bytes(bytes(x ^ y for x, y in zip(a, b)), "big", signed=False)

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",
+]

astreum/consensus/genesis.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from .models.account import Account
+from .models.accounts import Accounts
+from .models.block import Block
+from ..storage.models.atom import ZERO32
+from ..storage.models.trie import Trie
+from ..utils.integer import int_to_bytes
+
+TREASURY_ADDRESS = b"\x01" * 32
+BURN_ADDRESS = b"\x00" * 32
+
+
+def create_genesis_block(
+    node: Any,
+    validator_public_key: bytes,
+    chain_id: int = 0,
+) -> Block:
+    validator_pk = bytes(validator_public_key)
+
+    if len(validator_pk) != 32:
+        raise ValueError("validator_public_key must be 32 bytes")
+
+    stake_trie = Trie()
+    stake_amount = int_to_bytes(1)
+    stake_trie.put(storage_node=node, key=validator_pk, value=stake_amount)
+    stake_root = stake_trie.root_hash or ZERO32
+
+    treasury_account = Account.create(balance=1, data_hash=stake_root, counter=0)
+    treasury_account.data = stake_trie
+    treasury_account.data_hash = stake_root
+    burn_account = Account.create(balance=0, data_hash=b"", counter=0)
+    validator_account = Account.create(balance=0, data_hash=b"", counter=0)
+
+    accounts = Accounts()
+    accounts.set_account(TREASURY_ADDRESS, treasury_account)
+    accounts.set_account(BURN_ADDRESS, burn_account)
+    accounts.set_account(validator_pk, validator_account)
+
+    accounts.update_trie(node)
+    accounts_root = accounts.root_hash
+    if accounts_root is None:
+        raise ValueError("genesis accounts trie is empty")
+
+    block = Block(
+        chain_id=chain_id,
+        previous_block_hash=ZERO32,
+        previous_block=None,
+        number=0,
+        timestamp=0,
+        accounts_hash=accounts_root,
+        transactions_total_fees=0,
+        transactions_hash=ZERO32,
+        receipts_hash=ZERO32,
+        delay_difficulty=0,
+        validator_public_key=validator_pk,
+        nonce=0,
+        signature=b"",
+        accounts=accounts,
+        transactions=[],
+        receipts=[],
+    )
+
+    return block