astreum 0.2.42__tar.gz → 0.2.53__tar.gz

{astreum-0.2.42/src/astreum.egg-info → astreum-0.2.53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.42
+Version: 0.2.53
 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
 
@@ -136,6 +138,17 @@ 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

{astreum-0.2.42 → astreum-0.2.53}/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
 
@@ -118,6 +120,17 @@ 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

{astreum-0.2.42 → astreum-0.2.53}/pyproject.toml

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

{astreum-0.2.42 → astreum-0.2.53}/src/astreum/_communication/message.py

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

astreum-0.2.53/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.42 → astreum-0.2.53}/src/astreum/_communication/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,7 +16,7 @@ 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:
@@ -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-0.2.42 → astreum-0.2.53}/src/astreum/_communication/setup.py

@@ -95,9 +95,10 @@ def process_incoming_messages(node: "Node") -> None:
                     peer = Peer(node.relay_secret_key, sender_key)
                 except Exception:
                     continue
-                
+                peer.address = address_key
+
                 node.peers[sender_public_key_bytes] = peer
-                node.peer_route.add_peer(sender_public_key_bytes)
+                node.peer_route.add_peer(sender_public_key_bytes, peer)
 
                 response = Message(handshake=True, sender=node.relay_public_key)
                 node.outgoing_queue.put((response.to_bytes(), address_key))
@@ -105,17 +106,25 @@ def process_incoming_messages(node: "Node") -> None:
             
             elif old_key_bytes == sender_public_key_bytes:
                 # existing mapping with same key -> nothing to change
-                pass
+                peer = node.peers.get(sender_public_key_bytes)
+                if peer is not None:
+                    peer.address = address_key
             
             else:
                 # address reused with a different key -> replace peer
                 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:
                     continue
-                
+                peer.address = address_key
+
                 node.peers[sender_public_key_bytes] = peer
+                node.peer_route.add_peer(sender_public_key_bytes, peer)
 
         match message.topic:
             case MessageTopic.PING:
@@ -164,6 +173,65 @@ 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:
+                payload = message.content
+                if len(payload) < 32:
+                    continue
+
+                atom_id = payload[:32]
+                provider_bytes = payload[32:]
+                if not provider_bytes:
+                    continue
+
+                try:
+                    provider_str = provider_bytes.decode("utf-8")
+                except UnicodeDecodeError:
+                    continue
+
+                try:
+                    host, port = addr[0], int(addr[1])
+                except Exception:
+                    continue
+                address_key = (host, port)
+                sender_key_bytes = node.addresses.get(address_key)
+                if sender_key_bytes is None:
+                    continue
+
+                try:
+                    local_key_bytes = node.relay_public_key.public_bytes(
+                        encoding=serialization.Encoding.Raw,
+                        format=serialization.PublicFormat.Raw,
+                    )
+                except Exception:
+                    continue
+
+                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:
+                            node.outgoing_queue.put((message.to_bytes(), target_addr))
+                            continue
+
+                node.storage_index[atom_id] = provider_str.strip()
             
             case _:
                 continue

{astreum-0.2.42 → astreum-0.2.53}/src/astreum/_consensus/account.py

@@ -33,7 +33,7 @@ class Account:
 
     @classmethod
     def from_atom(cls, node: Any, account_id: bytes) -> "Account":
-        storage_get = node._local_get
+        storage_get = node.storage_get
 
         type_atom = storage_get(account_id)
         if type_atom is None or type_atom.data != b"account":