astreum 0.2.42__tar.gz → 0.3.5__tar.gz

astreum-0.3.5/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: astreum
+Version: 0.3.5
+Summary: Python library to interact with the Astreum blockchain and its virtual machine.
+Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
+Project-URL: Homepage, https://github.com/astreum/lib-py
+Project-URL: Issues, https://github.com/astreum/lib-py/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycryptodomex==3.21.0
+Requires-Dist: cryptography==44.0.2
+Requires-Dist: blake3==1.0.4
+Dynamic: license-file
+
+# lib
+
+Python library to interact with the Astreum blockchain and its virtual machine.
+
+[View on PyPI](https://pypi.org/project/astreum/)
+
+## Configuration
+
+When initializing an `astreum.Node`, pass a dictionary with any of the options below. Only the parameters you want to override need to be present – everything else falls back to its default.
+
+### Core Configuration
+
+| Parameter                   | Type       | Default        | Description                                                                                                                                                                      |
+| --------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hot_storage_limit`         | int        | `1073741824`   | Maximum bytes kept in the hot cache before new atoms are skipped (1 GiB).                                                                                                         |
+| `cold_storage_limit`        | int        | `10737418240`  | Cold storage write threshold (10 GiB by default); set to `0` to skip the limit.                                                                                                   |
+| `cold_storage_path`         | string     | `None`         | Directory where persisted atoms live; Astreum creates it on startup and skips cold storage when unset.                                                                            |
+| `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
+
+| Parameter                | Type        | Default               | Description                                                                                             |
+| ------------------------ | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `relay_secret_key`       | hex string  | Auto-generated        | X25519 private key used for the relay route; a new keypair is created when this field is omitted.        |
+| `validation_secret_key`  | hex string  | `None`                | Optional Ed25519 key that lets the node join the validation route; leave blank to opt out of validation. |
+| `use_ipv6`               | bool        | `False`               | Bind the incoming/outgoing sockets on IPv6 (the OS still listens on IPv4 if a peer speaks both).         |
+| `incoming_port`          | int         | `7373`                | UDP port the relay binds to; pass `0` or omit to let the OS pick an ephemeral port.                       |
+| `bootstrap`              | list\[str\] | `[]`                  | Addresses to ping with a handshake before joining; each must look like `host:port` or `[ipv6]:port`.     |
+
+> **Note**
+> The peer‑to‑peer *route* used for object discovery is always enabled.
+> If `validation_secret_key` is provided the node automatically joins the validation route too.
+
+### Example
+
+```python
+from astreum.node import Node
+
+config = {
+    "relay_secret_key": "ab…cd",             # optional – hex encoded
+    "validation_secret_key": "12…34",        # optional – validator
+    "hot_storage_limit": 1073741824,         # cap hot cache at 1 GiB
+    "cold_storage_limit": 10737418240,       # cap cold storage at 10 GiB
+    "cold_storage_path": "./data/node1",
+    "incoming_port": 7373,
+    "use_ipv6": False,
+    "bootstrap": [
+        "bootstrap.astreum.org:7373",
+        "127.0.0.1:7374"
+    ]
+}
+
+node = Node(config)
+# … your code …
+```
+
+
+## Astreum Machine Quickstart
+
+The Astreum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Astreum script, and the node tokenizes, parses, and evaluates.
+
+```python
+# 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"),
+])
+
+fn_body = Expr.ListExpr([
+    Expr.Symbol("a"),
+    Expr.Symbol("b"),
+    Expr.ListExpr([low_body, Expr.Symbol("sk")]),
+])
+
+params = Expr.ListExpr([Expr.Symbol("a"), Expr.Symbol("b")])
+int_add_fn = Expr.ListExpr([fn_body, params, Expr.Symbol("fn")])
+
+# 4) Store under the name "int.add"
+node.env_set(env_id, "int.add", int_add_fn)
+
+# 5) Retrieve the function and call it with bytes 1 and 2
+bound = node.env_get(env_id, "int.add")
+call = Expr.ListExpr([Expr.Byte(1), Expr.Byte(2), bound])
+res  = node.high_eval(env_id, call)
+
+# 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
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize`.
+* Unexpected or missing parentheses are caught by `parse`.
+
+Catch the exception to provide developer‑friendly diagnostics:
+
+```python
+try:
+    tokens = tokenize(bad_source)
+    expr, _ = parse(tokens)
+except ParseError as e:
+    print("Parse failed:", 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.3.5/README.md

@@ -0,0 +1,142 @@
+# lib
+
+Python library to interact with the Astreum blockchain and its virtual machine.
+
+[View on PyPI](https://pypi.org/project/astreum/)
+
+## Configuration
+
+When initializing an `astreum.Node`, pass a dictionary with any of the options below. Only the parameters you want to override need to be present – everything else falls back to its default.
+
+### Core Configuration
+
+| Parameter                   | Type       | Default        | Description                                                                                                                                                                      |
+| --------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hot_storage_limit`         | int        | `1073741824`   | Maximum bytes kept in the hot cache before new atoms are skipped (1 GiB).                                                                                                         |
+| `cold_storage_limit`        | int        | `10737418240`  | Cold storage write threshold (10 GiB by default); set to `0` to skip the limit.                                                                                                   |
+| `cold_storage_path`         | string     | `None`         | Directory where persisted atoms live; Astreum creates it on startup and skips cold storage when unset.                                                                            |
+| `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
+
+| Parameter                | Type        | Default               | Description                                                                                             |
+| ------------------------ | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `relay_secret_key`       | hex string  | Auto-generated        | X25519 private key used for the relay route; a new keypair is created when this field is omitted.        |
+| `validation_secret_key`  | hex string  | `None`                | Optional Ed25519 key that lets the node join the validation route; leave blank to opt out of validation. |
+| `use_ipv6`               | bool        | `False`               | Bind the incoming/outgoing sockets on IPv6 (the OS still listens on IPv4 if a peer speaks both).         |
+| `incoming_port`          | int         | `7373`                | UDP port the relay binds to; pass `0` or omit to let the OS pick an ephemeral port.                       |
+| `bootstrap`              | list\[str\] | `[]`                  | Addresses to ping with a handshake before joining; each must look like `host:port` or `[ipv6]:port`.     |
+
+> **Note**
+> The peer‑to‑peer *route* used for object discovery is always enabled.
+> If `validation_secret_key` is provided the node automatically joins the validation route too.
+
+### Example
+
+```python
+from astreum.node import Node
+
+config = {
+    "relay_secret_key": "ab…cd",             # optional – hex encoded
+    "validation_secret_key": "12…34",        # optional – validator
+    "hot_storage_limit": 1073741824,         # cap hot cache at 1 GiB
+    "cold_storage_limit": 10737418240,       # cap cold storage at 10 GiB
+    "cold_storage_path": "./data/node1",
+    "incoming_port": 7373,
+    "use_ipv6": False,
+    "bootstrap": [
+        "bootstrap.astreum.org:7373",
+        "127.0.0.1:7374"
+    ]
+}
+
+node = Node(config)
+# … your code …
+```
+
+
+## Astreum Machine Quickstart
+
+The Astreum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Astreum script, and the node tokenizes, parses, and evaluates.
+
+```python
+# 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"),
+])
+
+fn_body = Expr.ListExpr([
+    Expr.Symbol("a"),
+    Expr.Symbol("b"),
+    Expr.ListExpr([low_body, Expr.Symbol("sk")]),
+])
+
+params = Expr.ListExpr([Expr.Symbol("a"), Expr.Symbol("b")])
+int_add_fn = Expr.ListExpr([fn_body, params, Expr.Symbol("fn")])
+
+# 4) Store under the name "int.add"
+node.env_set(env_id, "int.add", int_add_fn)
+
+# 5) Retrieve the function and call it with bytes 1 and 2
+bound = node.env_get(env_id, "int.add")
+call = Expr.ListExpr([Expr.Byte(1), Expr.Byte(2), bound])
+res  = node.high_eval(env_id, call)
+
+# 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
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize`.
+* Unexpected or missing parentheses are caught by `parse`.
+
+Catch the exception to provide developer‑friendly diagnostics:
+
+```python
+try:
+    tokens = tokenize(bad_source)
+    expr, _ = parse(tokens)
+except ParseError as e:
+    print("Parse failed:", 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.42 → astreum-0.3.5}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "astreum"
-version = "0.2.42"
+version = "0.3.5"
 authors = [
   { name="Roy R. O. Okello", email="roy@stelar.xyz" },
 ]
-description = "Python library to interact with the Astreum blockchain and its Lispeum virtual machine."
+description = "Python library to interact with the Astreum blockchain and its virtual machine."
 readme = "README.md"
 requires-python = ">=3.8"
 classifiers = [
@@ -19,5 +19,5 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/astreum/lib"
-Issues = "https://github.com/astreum/lib/issues"
+Homepage = "https://github.com/astreum/lib-py"
+Issues = "https://github.com/astreum/lib-py/issues"

astreum-0.3.5/src/astreum/__init__.py

@@ -0,0 +1,18 @@
+
+from astreum.consensus import Account, Accounts, Block, Chain, Fork, Receipt, Transaction
+from astreum.machine import Env, Expr
+from astreum.node import Node
+
+
+__all__: list[str] = [
+    "Node",
+    "Env",
+    "Expr",
+    "Block",
+    "Chain",
+    "Fork",
+    "Receipt",
+    "Transaction",
+    "Account",
+    "Accounts",
+]

{astreum-0.2.42/src/astreum/_communication → astreum-0.3.5/src/astreum/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-0.3.5/src/astreum/communication/handlers/handshake.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+
+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_public_key_bytes = message.sender_bytes
+    try:
+        sender_key = X25519PublicKey.from_public_bytes(sender_public_key_bytes)
+    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-0.3.5/src/astreum/communication/handlers/object_request.py

@@ -0,0 +1,153 @@
+import logging
+import socket
+from enum import IntEnum
+from typing import TYPE_CHECKING, Tuple
+
+from .object_response import ObjectResponse, ObjectResponseType
+from ..models.message import Message, MessageTopic
+
+if TYPE_CHECKING:
+    from .. import Node
+    from ..models.peer import Peer
+
+
+class ObjectRequestType(IntEnum):
+    OBJECT_GET = 0
+    OBJECT_PUT = 1
+
+
+class ObjectRequest:
+    type: ObjectRequestType
+    data: bytes
+    atom_id: bytes
+
+    def __init__(self, type: ObjectRequestType, data: bytes, atom_id: bytes = None):
+        self.type = type
+        self.data = data
+        self.atom_id = atom_id
+
+    def to_bytes(self):
+        return [self.type.value] + self.atom_id + self.data
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "ObjectRequest":
+        # need at least 1 byte for type + 32 bytes for hash
+        if len(data) < 1 + 32:
+            raise ValueError(f"Too short for ObjectRequest ({len(data)} bytes)")
+
+        type_val = data[0]
+        try:
+            req_type = ObjectRequestType(type_val)
+        except ValueError:
+            raise ValueError(f"Unknown ObjectRequestType: {type_val!r}")
+
+        atom_id_bytes = data[1:33]
+        payload    = data[33:]
+        return cls(req_type, payload, atom_id_bytes)
+
+
+def encode_peer_contact_bytes(peer: "Peer") -> bytes:
+    """Return a fixed-width peer contact payload (32-byte key + IPv4 + port)."""
+    if not peer.address:
+        raise ValueError("peer address is required for encoding peer info")
+    host, port = peer.address
+    key_bytes = peer.public_key_bytes
+    try:
+        ip_bytes = socket.inet_aton(host)
+    except OSError as exc:  # pragma: no cover - inet_aton raises for invalid hosts
+        raise ValueError(f"invalid IPv4 address: {host}") from exc
+    if not (0 <= port <= 0xFFFF):
+        raise ValueError(f"port out of range (0-65535): {port}")
+    port_bytes = int(port).to_bytes(2, "big", signed=False)
+    return key_bytes + ip_bytes + port_bytes
+
+
+def handle_object_request(node: "Node", addr: Tuple[str, int], message: Message) -> None:
+    node_logger = getattr(node, "logger", logging.getLogger(__name__))
+    try:
+        object_request = ObjectRequest.from_bytes(message.body)
+    except Exception as exc:
+        node_logger.warning("Error decoding OBJECT_REQUEST from %s: %s", addr, exc)
+        return
+
+    match object_request.type:
+        case ObjectRequestType.OBJECT_GET:
+            atom_id = object_request.atom_id
+            node_logger.debug("Handling OBJECT_GET for %s from %s", atom_id.hex(), addr)
+
+            local_atom = node.local_get(atom_id)
+            if local_atom is not None:
+                node_logger.debug("Object %s found locally; returning to %s", atom_id.hex(), addr)
+                resp = ObjectResponse(
+                    type=ObjectResponseType.OBJECT_FOUND,
+                    data=local_atom.to_bytes(),
+                    atom_id=atom_id
+                )
+                obj_res_msg  = Message(
+                    topic=MessageTopic.OBJECT_RESPONSE,
+                    body=resp.to_bytes(),
+                    sender=node.relay_public_key,
+                )
+                node.outgoing_queue.put((obj_res_msg.to_bytes(), addr))
+                return
+
+            storage_index = getattr(node, "storage_index", None) or {}
+            if atom_id in storage_index:
+                node_logger.debug("Known provider for %s; informing %s", atom_id.hex(), addr)
+                provider_bytes = storage_index[atom_id]
+                resp = ObjectResponse(
+                    type=ObjectResponseType.OBJECT_PROVIDER,
+                    data=provider_bytes,
+                    atom_id=atom_id
+                )
+                obj_res_msg = Message(
+                    topic=MessageTopic.OBJECT_RESPONSE,
+                    body=resp.to_bytes(),
+                    sender=node.relay_public_key,
+                )
+                node.outgoing_queue.put((obj_res_msg.to_bytes(), addr))
+                return
+
+            nearest_peer = node.peer_route.closest_peer_for_hash(atom_id)
+            if nearest_peer:
+                node_logger.debug("Forwarding requester %s to nearest peer for %s", addr, atom_id.hex())
+                peer_info = encode_peer_contact_bytes(nearest_peer)
+                resp = ObjectResponse(
+                    type=ObjectResponseType.OBJECT_PROVIDER,
+                    # type=ObjectResponseType.OBJECT_NEAREST_PEER,
+                    data=peer_info,
+                    atom_id=atom_id
+                )
+                obj_res_msg = Message(
+                    topic=MessageTopic.OBJECT_RESPONSE,
+                    body=resp.to_bytes(),
+                    sender=node.relay_public_key,
+                )
+                node.outgoing_queue.put((obj_res_msg.to_bytes(), addr))
+
+        case ObjectRequestType.OBJECT_PUT:
+            atom_hash = object_request.data[:32]
+            node_logger.debug("Handling OBJECT_PUT for %s from %s", atom_hash.hex(), addr)
+
+            nearest_peer = node.peer_route.closest_peer_for_hash(atom_hash)
+            nearest = (nearest_peer.public_key, nearest_peer) if nearest_peer else None
+            if nearest:
+                node_logger.debug("Forwarding OBJECT_PUT for %s to nearer peer %s", atom_hash.hex(), nearest[1].address)
+                fwd_req = ObjectRequest(
+                    type=ObjectRequestType.OBJECT_PUT,
+                    data=object_request.data,
+                )
+                obj_req_msg = Message(
+                    topic=MessageTopic.OBJECT_REQUEST,
+                    body=fwd_req.to_bytes(),
+                    sender=node.relay_public_key,
+                )
+                node.outgoing_queue.put((obj_req_msg.to_bytes(), nearest[1].address))
+            else:
+                node_logger.debug("Storing provider info for %s locally", atom_hash.hex())
+                if not hasattr(node, "storage_index") or not isinstance(node.storage_index, dict):
+                    node.storage_index = {}
+                node.storage_index[atom_hash] = object_request.data[32:]
+
+        case _:
+            node_logger.warning("Unknown ObjectRequestType %s from %s", object_request.type, addr)

astreum-0.3.5/src/astreum/communication/handlers/object_response.py

@@ -0,0 +1,37 @@
+from enum import IntEnum
+
+
+class ObjectResponseType(IntEnum):
+    OBJECT_FOUND = 0
+    OBJECT_PROVIDER = 1
+    OBJECT_NEAREST_PEER = 2
+
+
+class ObjectResponse:
+    type: ObjectResponseType
+    data: bytes
+    atom_id: bytes
+
+    def __init__(self, type: ObjectResponseType, data: bytes, atom_id: bytes = None):
+        self.type = type
+        self.data = data
+        self.atom_id = atom_id
+
+    def to_bytes(self):
+        return [self.type.value] + self.atom_id + self.data
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "ObjectResponse":
+        # need at least 1 byte for type + 32 bytes for atom id
+        if len(data) < 1 + 32:
+            raise ValueError(f"Too short to be a valid ObjectResponse ({len(data)} bytes)")
+
+        type_val = data[0]
+        try:
+            resp_type = ObjectResponseType(type_val)
+        except ValueError:
+            raise ValueError(f"Unknown ObjectResponseType: {type_val}")
+
+        atom_id = data[1:33]
+        payload   = data[33:]
+        return cls(resp_type, payload, atom_id)

astreum-0.3.5/src/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