astreum 0.2.61__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}/route.py

@@ -19,11 +19,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:

astreum/communication/setup.py

@@ -0,0 +1,205 @@
+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 .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)."""
+    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 setup_outgoing(
+    use_ipv6: bool
+) -> Tuple[socket.socket, Queue, threading.Thread]:
+    fam  = socket.AF_INET6 if use_ipv6 else socket.AF_INET
+    sock = socket.socket(fam, socket.SOCK_DGRAM)
+    q    = Queue()
+    thr  = threading.Thread(target=lambda: None, daemon=True)
+    thr.start()
+    return sock, q, thr
+
+def make_maps():
+    """Empty lookup maps: peers and addresses."""
+    return
+
+
+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:
+            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
+
+        match message.topic:
+            case MessageTopic.PING:
+                handle_ping(node, addr, message.content)
+            case MessageTopic.OBJECT_REQUEST:
+                pass
+            case MessageTopic.OBJECT_RESPONSE:
+                pass
+            case MessageTopic.ROUTE_REQUEST:
+                pass
+            case MessageTopic.ROUTE_RESPONSE:
+                pass
+            case MessageTopic.TRANSACTION:
+                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
+
+
+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:
+            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
+    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.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
+    )
+
+    # 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,
+        node.outgoing_queue,
+        node.outgoing_thread
+    ) = setup_outgoing(node.use_ipv6)
+
+    # other workers & maps
+    node.object_request_queue = Queue()
+    node.peer_manager_thread  = threading.Thread(
+        target=node._relay_peer_manager,
+        daemon=True
+    )
+    node.peer_manager_thread.start()
+
+    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)
+        
+        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",
+]

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

astreum/consensus/models/account.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Tuple
+
+from ...storage.models.atom import Atom, ZERO32, AtomKind
+from ...storage.models.trie import Trie
+from ...utils.integer import bytes_to_int, int_to_bytes
+
+
+@dataclass
+class Account:
+    balance: int
+    code_hash: bytes
+    counter: int
+    data_hash: bytes
+    data: Trie
+    atom_hash: bytes = ZERO32
+    atoms: List[Atom] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, balance: int = 0, data_hash: bytes = ZERO32, code_hash: bytes = ZERO32, counter: int = 0) -> "Account":
+        account = cls(
+            balance=int(balance),
+            code_hash=bytes(code_hash),
+            counter=int(counter),
+            data_hash=bytes(data_hash),
+            data=Trie(root_hash=bytes(data_hash)),
+        )
+        atom_hash, atoms = account.to_atom()
+        account.atom_hash = atom_hash
+        account.atoms = atoms
+        return account
+
+    @classmethod
+    def from_atom(cls, node: Any, root_id: bytes) -> "Account":
+
+        account_atoms = node.get_atom_list_from_storage(root_hash=root_id)
+
+        if account_atoms is None or len(account_atoms) != 5:
+            raise ValueError("malformed account atom list")
+
+        type_atom, balance_atom, code_atom, counter_atom, data_atom = account_atoms
+        
+        if type_atom.data != b"account":
+            raise ValueError("not an account (type mismatch)")
+
+        account = cls.create(
+            balance=bytes_to_int(balance_atom.data),
+            data_hash=data_atom.data,
+            counter=bytes_to_int(counter_atom.data),
+            code_hash=code_atom.data,
+        )
+
+        return account
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        data_atom = Atom(
+            data=bytes(self.data_hash),
+            kind=AtomKind.LIST,
+        )
+        counter_atom = Atom(
+            data=int_to_bytes(self.counter),
+            next_id=data_atom.object_id(),
+            kind=AtomKind.BYTES,
+        )
+        code_atom = Atom(
+            data=bytes(self.code_hash),
+            next_id=counter_atom.object_id(),
+            kind=AtomKind.LIST,
+        )
+        balance_atom = Atom(
+            data=int_to_bytes(self.balance),
+            next_id=code_atom.object_id(),
+            kind=AtomKind.BYTES,
+        )
+        type_atom = Atom(
+            data=b"account",
+            next_id=balance_atom.object_id(),
+            kind=AtomKind.SYMBOL,
+        )
+
+        atoms = [data_atom, counter_atom, code_atom, balance_atom, type_atom]
+        return type_atom.object_id(), list(atoms)