astreum 0.2.12__tar.gz → 0.2.50__tar.gz

{astreum-0.2.12/src/astreum.egg-info → astreum-0.2.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.12
+Version: 0.2.50
 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
@@ -35,6 +35,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `validation_secret_key`     | hex string | `None`         | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node.                                                                 |
 | `storage_path`              | string     | `None`         | Directory where objects are persisted. If *None*, the node uses an in‑memory store.                                                                                              |
 | `storage_get_relay_timeout` | float      | `5`            | Seconds to wait for an object requested from peers before timing‑out.                                                                                                            |
+| `logging_retention`         | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Networking
 
@@ -76,24 +78,45 @@ node = Node(config)
 The Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated environment.
 
 ```python
-from astreum.node import Node
-from astreum.machine.tokenizer import tokenize
-from astreum.machine.parser import parse
+# Define a named function int.add (stack body) and call it with bytes 1 and 2
+
+import uuid
+from astreum import Node, Env, Expr
+
+# 1) Spin‑up a stand‑alone VM
+node = Node()
+
+# 2) Create an environment (simple manual setup)
+env_id = uuid.uuid4()
+node.environments[env_id] = Env()
+
+# 3) Build a function value using a low‑level stack body via `sk`.
+# Body does: $0 $1 add   (i.e., a + b)
+low_body = Expr.ListExpr([
+    Expr.Symbol("$0"),  # a (first arg)
+    Expr.Symbol("$1"),  # b (second arg)
+    Expr.Symbol("add"),
+])
 
-# 1. Spin‑up a stand‑alone VM (machine‑only node).
-node = Node({"machine-only": True})
+fn_body = Expr.ListExpr([
+    Expr.Symbol("a"),
+    Expr.Symbol("b"),
+    Expr.ListExpr([low_body, Expr.Symbol("sk")]),
+])
 
-# 2. Create an environment.
-env_id = node.machine_create_environment()
+params = Expr.ListExpr([Expr.Symbol("a"), Expr.Symbol("b")])
+int_add_fn = Expr.ListExpr([fn_body, params, Expr.Symbol("fn")])
 
-# 3. Convert Lispeum source → Expr AST.
-source = '(+ 1 (* 2 3))'
-expr, _ = parse(tokenize(source))
+# 4) Store under the name "int.add"
+node.env_set(env_id, b"int.add", int_add_fn)
 
-# 4. Evaluate
-result = node.machine_expr_eval(env_id=env_id, expr=expr)  # -> Expr.Integer(7)
+# 5) Retrieve the function and call it with bytes 1 and 2
+bound = node.env_get(env_id, b"int.add")
+call = Expr.ListExpr([Expr.Byte(1), Expr.Byte(2), bound])
+res  = node.high_eval(env_id, call)
 
-print(result.value)  # 7
+# sk returns a list of bytes; for 1+2 expect a single byte with value 3
+print([b.value for b in res.elements])  # [3]
 ```
 
 ### Handling errors
@@ -115,9 +138,22 @@ except ParseError as e:
 
 ---
 
+
+## Logging
+
+Every `Node` instance wires up structured logging automatically:
+
+- Logs land in per-instance files named `node.log` under `%LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id>` on Windows and `$XDG_STATE_HOME` (or `~/.local/state`)/`Astreum/lib-py/logs/<instance_id>` on other platforms. The `<instance_id>` is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
+- Files rotate at midnight UTC with gzip compression (`node-YYYY-MM-DD.log.gz`) and retain 90 days by default. Override via `config["logging_retention"]`.
+- Each event is a single JSON line containing timestamp, level, logger, message, process/thread info, module/function, and the derived `instance_id`.
+- Set `config["verbose"] = True` to mirror logs to stdout in a human-friendly format like `[2025-04-13-42-59] [info] Starting Astreum Node`.
+- The very first entry emitted is the banner `Starting Astreum Node`, signalling that the logging pipeline is live before other subsystems spin up.
+
 ## Testing
 
 ```bash
-
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
 python3 -m unittest discover -s tests
 ```

{astreum-0.2.12 → astreum-0.2.50}/README.md

@@ -17,6 +17,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `validation_secret_key`     | hex string | `None`         | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node.                                                                 |
 | `storage_path`              | string     | `None`         | Directory where objects are persisted. If *None*, the node uses an in‑memory store.                                                                                              |
 | `storage_get_relay_timeout` | float      | `5`            | Seconds to wait for an object requested from peers before timing‑out.                                                                                                            |
+| `logging_retention`         | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Networking
 
@@ -58,24 +60,45 @@ node = Node(config)
 The Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated environment.
 
 ```python
-from astreum.node import Node
-from astreum.machine.tokenizer import tokenize
-from astreum.machine.parser import parse
+# Define a named function int.add (stack body) and call it with bytes 1 and 2
+
+import uuid
+from astreum import Node, Env, Expr
+
+# 1) Spin‑up a stand‑alone VM
+node = Node()
+
+# 2) Create an environment (simple manual setup)
+env_id = uuid.uuid4()
+node.environments[env_id] = Env()
+
+# 3) Build a function value using a low‑level stack body via `sk`.
+# Body does: $0 $1 add   (i.e., a + b)
+low_body = Expr.ListExpr([
+    Expr.Symbol("$0"),  # a (first arg)
+    Expr.Symbol("$1"),  # b (second arg)
+    Expr.Symbol("add"),
+])
 
-# 1. Spin‑up a stand‑alone VM (machine‑only node).
-node = Node({"machine-only": True})
+fn_body = Expr.ListExpr([
+    Expr.Symbol("a"),
+    Expr.Symbol("b"),
+    Expr.ListExpr([low_body, Expr.Symbol("sk")]),
+])
 
-# 2. Create an environment.
-env_id = node.machine_create_environment()
+params = Expr.ListExpr([Expr.Symbol("a"), Expr.Symbol("b")])
+int_add_fn = Expr.ListExpr([fn_body, params, Expr.Symbol("fn")])
 
-# 3. Convert Lispeum source → Expr AST.
-source = '(+ 1 (* 2 3))'
-expr, _ = parse(tokenize(source))
+# 4) Store under the name "int.add"
+node.env_set(env_id, b"int.add", int_add_fn)
 
-# 4. Evaluate
-result = node.machine_expr_eval(env_id=env_id, expr=expr)  # -> Expr.Integer(7)
+# 5) Retrieve the function and call it with bytes 1 and 2
+bound = node.env_get(env_id, b"int.add")
+call = Expr.ListExpr([Expr.Byte(1), Expr.Byte(2), bound])
+res  = node.high_eval(env_id, call)
 
-print(result.value)  # 7
+# sk returns a list of bytes; for 1+2 expect a single byte with value 3
+print([b.value for b in res.elements])  # [3]
 ```
 
 ### Handling errors
@@ -97,9 +120,22 @@ except ParseError as e:
 
 ---
 
+
+## Logging
+
+Every `Node` instance wires up structured logging automatically:
+
+- Logs land in per-instance files named `node.log` under `%LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id>` on Windows and `$XDG_STATE_HOME` (or `~/.local/state`)/`Astreum/lib-py/logs/<instance_id>` on other platforms. The `<instance_id>` is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
+- Files rotate at midnight UTC with gzip compression (`node-YYYY-MM-DD.log.gz`) and retain 90 days by default. Override via `config["logging_retention"]`.
+- Each event is a single JSON line containing timestamp, level, logger, message, process/thread info, module/function, and the derived `instance_id`.
+- Set `config["verbose"] = True` to mirror logs to stdout in a human-friendly format like `[2025-04-13-42-59] [info] Starting Astreum Node`.
+- The very first entry emitted is the banner `Starting Astreum Node`, signalling that the logging pipeline is live before other subsystems spin up.
+
 ## Testing
 
 ```bash
-
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
 python3 -m unittest discover -s tests
 ```

{astreum-0.2.12 → astreum-0.2.50}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "astreum"
-version = "0.2.12"
+version = "0.2.50"
 authors = [
   { name="Roy R. O. Okello", email="roy@stelar.xyz" },
 ]

astreum-0.2.50/src/astreum/__init__.py

@@ -0,0 +1,9 @@
+"""Lightweight package initializer to avoid circular imports during tests.
+
+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] = []

astreum-0.2.50/src/astreum/_communication/__init__.py

@@ -0,0 +1,11 @@
+from .message import Message
+from .peer import Peer
+from .route import Route
+from .setup import communication_setup
+
+__all__ = [
+    "Message",
+    "Peer",
+    "Route",
+    "communication_setup",
+]

astreum-0.2.50/src/astreum/_communication/message.py

@@ -0,0 +1,101 @@
+from enum import IntEnum
+from typing import Optional
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+
+class MessageTopic(IntEnum):
+    PING = 0
+    OBJECT_REQUEST = 1
+    OBJECT_RESPONSE = 2
+    ROUTE_REQUEST = 3
+    ROUTE_RESPONSE = 4
+    TRANSACTION = 5
+    STORAGE_REQUEST = 6
+    
+
+class Message:
+    handshake: bool
+    sender: Optional[X25519PublicKey]
+
+    topic: Optional[MessageTopic]
+    content: bytes
+
+    def __init__(
+        self,
+        *,
+        handshake: bool = False,
+        sender: Optional[X25519PublicKey] = None,
+        topic: Optional[MessageTopic] = None,
+        content: bytes = b"",
+        body: Optional[bytes] = None,
+    ) -> None:
+        if body is not None:
+            if content and content != b"":
+                raise ValueError("specify only one of 'content' or 'body'")
+            content = body
+
+        self.handshake = handshake
+        self.sender = sender
+        self.topic = topic
+        self.content = content or b""
+
+        if self.handshake:
+            if self.sender is None:
+                raise ValueError("handshake Message requires a sender public key")
+            self.topic = None
+            self.content = b""
+        else:
+            if self.topic is None:
+                raise ValueError("non-handshake Message requires a topic")
+
+    def to_bytes(self):
+        if self.handshake:
+            # handshake byte (1) + raw public key bytes
+            return bytes([1]) + self.sender.public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw
+            )
+        else:
+            # normal message: 0 + topic + content
+            return bytes([0, self.topic.value]) + self.content
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Message":
+        if len(data) < 1:
+            raise ValueError("Cannot parse Message: no data")
+        flag = data[0]
+        # create empty instance
+        msg = cls.__new__(cls)
+
+        if flag == 1:
+            # handshake message: the rest is the peer’s public key
+            key_bytes = data[1:]
+            if not key_bytes:
+                raise ValueError("Handshake message missing sender public key bytes")
+            try:
+                sender = X25519PublicKey.from_public_bytes(key_bytes)
+            except ValueError:
+                raise ValueError("Invalid public key bytes")
+            if sender is None:
+                raise ValueError("Handshake message missing sender public key")
+            msg.handshake = True
+            msg.sender = sender
+            msg.topic = None
+            msg.content = b''
+        elif flag == 0:
+            # normal message: next byte is topic, rest is content
+            if len(data) < 2:
+                raise ValueError("Cannot parse Message: missing topic byte")
+            topic_val = data[1]
+            try:
+                topic = MessageTopic(topic_val)
+            except ValueError:
+                raise ValueError(f"Unknown MessageTopic: {topic_val}")
+            msg.handshake = False
+            msg.sender = None
+            msg.topic = topic
+            msg.content = data[2:]
+        else:
+            raise ValueError(f"Invalid handshake flag: {flag}")
+
+        return msg

astreum-0.2.50/src/astreum/_communication/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-0.2.50/src/astreum/_communication/ping.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class PingFormatError(ValueError):
+    """Raised when ping payload bytes are invalid."""
+
+
+@dataclass
+class Ping:
+    is_validator: bool
+    latest_block: bytes
+
+    PAYLOAD_SIZE = 33
+
+    def __post_init__(self) -> None:
+        lb = bytes(self.latest_block or b"")
+        if len(lb) != 32:
+            raise ValueError("latest_block must be exactly 32 bytes")
+        self.latest_block = lb
+
+    def to_bytes(self) -> bytes:
+        return (b"\x01" if self.is_validator else b"\x00") + self.latest_block
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Ping":
+        if len(data) != cls.PAYLOAD_SIZE:
+            raise PingFormatError("ping payload must be exactly 33 bytes")
+        flag = data[0]
+        if flag not in (0, 1):
+            raise PingFormatError("ping validator flag must be 0 or 1")
+        return cls(is_validator=bool(flag), latest_block=data[1:])

astreum-0.2.50/src/astreum/_communication/route.py

@@ -0,0 +1,95 @@
+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]
+
+
+class Route:
+    def __init__(self, relay_public_key: X25519PublicKey, bucket_size: int = 16):
+        self.relay_public_key_bytes = relay_public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        self.bucket_size = bucket_size
+        self.buckets: Dict[int, List[bytes]] = {
+            i: [] for i in range(len(self.relay_public_key_bytes) * 8)
+        }
+        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())
+        return len(a) * 8
+
+    def _normalize_peer_key(self, peer_public_key: PeerKey) -> bytes:
+        if isinstance(peer_public_key, X25519PublicKey):
+            return peer_public_key.public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw,
+            )
+        if isinstance(peer_public_key, (bytes, bytearray)):
+            key_bytes = bytes(peer_public_key)
+            if len(key_bytes) != len(self.relay_public_key_bytes):
+                raise ValueError("peer key must be raw 32-byte public key")
+            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)
+        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)
+        bucket_idx = self._matching_leading_bits(self.relay_public_key_bytes, peer_public_key_bytes)
+        bucket = self.buckets.get(bucket_idx)
+        if not bucket:
+            return
+        try:
+            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