astreum 0.3.21__tar.gz → 0.3.34__tar.gz

{astreum-0.3.21/src/astreum.egg-info → astreum-0.3.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.3.21
+Version: 0.3.34
 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
@@ -45,9 +45,13 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `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         | `52780`                | 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`.     |
+| `default_seed`           | string     | `"bootstrap.astreum.org:52780"` | Default address to ping before joining; set to `None` to disable the built-in default.          |
+| `additional_seeds`       | list\[str\] | `[]`                  | Extra addresses appended to the bootstrap list; each must look like `host:port` or `[ipv6]:port`.        |
 | `peer_timeout`           | int         | `900`                 | Evict peers that have not been seen within this many seconds (15 minutes).                               |
 | `peer_timeout_interval`  | int         | `10`                  | How often (seconds) the peer manager checks for stale peers.                                             |
+| `bootstrap_retry_interval` | int       | `30`                  | How often (seconds) to retry bootstrapping when the peer list is empty.                                  |
+| `storage_index_interval` | int         | `600`                 | How often (seconds) to re-advertise cold storage atoms to the closest known peer.                        |
+| `outgoing_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for `enqueue_outgoing`-tracked outgoing queue usage; set to `0` to disable.            |
 
 > **Note**
 > The peer‑to‑peer *route* used for object discovery is always enabled.
@@ -66,8 +70,8 @@ config = {
     "cold_storage_path": "./data/node1",
     "incoming_port": 52780,
     "use_ipv6": False,
-    "bootstrap": [
-        "bootstrap.astreum.org:52780",
+    "default_seed": None,
+    "additional_seeds": [
         "127.0.0.1:7374"
     ]
 }

{astreum-0.3.21 → astreum-0.3.34}/README.md

@@ -15,8 +15,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `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_days`    | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
-| `chain_id`                  | int        | `0`            | Chain identifier used for validation (0 = test, 1 = main).                                                                                                                        |
+| `logging_retention_days`    | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `chain_id`                  | int        | `0`            | Chain identifier used for validation (0 = test, 1 = main).                                                                                                                        |
 | `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Communication
@@ -25,11 +25,15 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | ------------------------ | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
 | `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         | `52780`                | 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`.     |
+| `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         | `52780`                | UDP port the relay binds to; pass `0` or omit to let the OS pick an ephemeral port.                       |
+| `default_seed`           | string     | `"bootstrap.astreum.org:52780"` | Default address to ping before joining; set to `None` to disable the built-in default.          |
+| `additional_seeds`       | list\[str\] | `[]`                  | Extra addresses appended to the bootstrap list; each must look like `host:port` or `[ipv6]:port`.        |
 | `peer_timeout`           | int         | `900`                 | Evict peers that have not been seen within this many seconds (15 minutes).                               |
 | `peer_timeout_interval`  | int         | `10`                  | How often (seconds) the peer manager checks for stale peers.                                             |
+| `bootstrap_retry_interval` | int       | `30`                  | How often (seconds) to retry bootstrapping when the peer list is empty.                                  |
+| `storage_index_interval` | int         | `600`                 | How often (seconds) to re-advertise cold storage atoms to the closest known peer.                        |
+| `outgoing_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for `enqueue_outgoing`-tracked outgoing queue usage; set to `0` to disable.            |
 
 > **Note**
 > The peer‑to‑peer *route* used for object discovery is always enabled.
@@ -48,8 +52,8 @@ config = {
     "cold_storage_path": "./data/node1",
     "incoming_port": 52780,
     "use_ipv6": False,
-    "bootstrap": [
-        "bootstrap.astreum.org:52780",
+    "default_seed": None,
+    "additional_seeds": [
         "127.0.0.1:7374"
     ]
 }
@@ -130,7 +134,7 @@ except ParseError as e:
 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_days"]`.
+- 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_days"]`.
 - 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.

{astreum-0.3.21 → astreum-0.3.34}/pyproject.toml

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

{astreum-0.3.21 → astreum-0.3.34}/src/astreum/__init__.py

@@ -1,5 +1,5 @@
 
-from astreum.validation import Account, Accounts, Block, Chain, Fork, Receipt, Transaction
+from astreum.validation import Account, Accounts, Block, Fork, Receipt, Transaction
 from astreum.machine import Env, Expr, parse, tokenize
 from astreum.node import Node
 
@@ -9,7 +9,6 @@ __all__: list[str] = [
     "Env",
     "Expr",
     "Block",
-    "Chain",
     "Fork",
     "Receipt",
     "Transaction",

{astreum-0.3.21 → astreum-0.3.34}/src/astreum/communication/__init__.py

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

{astreum-0.3.21 → astreum-0.3.34}/src/astreum/communication/handlers/handshake.py

@@ -5,18 +5,42 @@ 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
+from ..models.peer import Peer
+from ..models.message import Message, MessageTopic
+from ..models.ping import Ping
 
 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.
-    """
+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.
+    """
+    def _queue_handshake_ping(peer: Peer, peer_address: tuple[str, int]) -> None:
+        latest_block = getattr(node, "latest_block_hash", None)
+        if not isinstance(latest_block, (bytes, bytearray)) or len(latest_block) != 32:
+            latest_block = None
+        try:
+            ping_payload = Ping(
+                is_validator=bool(getattr(node, "validation_public_key", None)),
+                latest_block=latest_block,
+            ).to_bytes()
+            ping_msg = Message(
+                topic=MessageTopic.PING,
+                content=ping_payload,
+                sender=node.relay_public_key,
+            )
+            ping_msg.encrypt(peer.shared_key_bytes)
+            node.outgoing_queue.put((ping_msg.to_bytes(), peer_address))
+        except Exception as exc:
+            node.logger.debug(
+                "Failed sending handshake ping to %s:%s: %s",
+                peer_address[0],
+                peer_address[1],
+                exc,
+            )
     sender_public_key_bytes = message.sender_bytes
     try:
         sender_key = X25519PublicKey.from_public_bytes(sender_public_key_bytes)
@@ -24,39 +48,45 @@ def handle_handshake(node: "Node", addr: Sequence[object], message: Message) ->
         node.logger.warning("Error extracting sender key bytes: %s", exc)
         return True
 
-    try:
-        host = addr[0]
-        port = int.from_bytes(message.content[:2], "big", signed=False)
-    except Exception:
-        return True
-    peer_address = (host, port)
-
-    existing_peer = node.get_peer(sender_public_key_bytes)
-    if existing_peer is not None:
-        existing_peer.address = peer_address
-        return False
+    try:
+        host = addr[0]
+        port = int.from_bytes(message.content[:2], "big", signed=False)
+    except Exception:
+        return True
+    peer_address = (host, port)
+    default_seed_ips = getattr(node, "default_seed_ips", None)
+    is_default_seed = bool(default_seed_ips) and host in default_seed_ips
+
+    existing_peer = node.get_peer(sender_public_key_bytes)
+    if existing_peer is not None:
+        existing_peer.address = peer_address
+        existing_peer.is_default_seed = is_default_seed
+        _queue_handshake_ping(existing_peer, peer_address)
+        return False
 
     try:
-        peer = Peer(
-            node_secret_key=node.relay_secret_key,
-            peer_public_key=sender_key,
-            address=peer_address,
-        )
+        peer = Peer(
+            node_secret_key=node.relay_secret_key,
+            peer_public_key=sender_key,
+            address=peer_address,
+            is_default_seed=is_default_seed,
+        )
     except Exception:
         return True
 
     node.add_peer(sender_public_key_bytes, peer)
     node.peer_route.add_peer(sender_public_key_bytes, peer)
 
-    node.logger.info(
-        "Handshake accepted from %s:%s; peer added",
-        peer_address[0],
-        peer_address[1],
-    )
-    response = Message(
-        handshake=True,
-        sender=node.relay_public_key,
-        content=int(node.config["incoming_port"]).to_bytes(2, "big", signed=False),
+    node.logger.info(
+        "Handshake accepted from %s:%s; peer added",
+        peer_address[0],
+        peer_address[1],
     )
-    node.outgoing_queue.put((response.to_bytes(), peer_address))
-    return True
+    response = Message(
+        handshake=True,
+        sender=node.relay_public_key,
+        content=int(node.config["incoming_port"]).to_bytes(2, "big", signed=False),
+    )
+    node.outgoing_queue.put((response.to_bytes(), peer_address))
+    _queue_handshake_ping(peer, peer_address)
+    return True

{astreum-0.3.21 → astreum-0.3.34}/src/astreum/communication/handlers/object_request.py

@@ -1,176 +1,185 @@
-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
-from ..util import xor_distance
-
-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 bytes([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)."""
-    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", peer: "Peer", message: Message) -> None:
-    if message.content is None:
-        node.logger.warning("OBJECT_REQUEST from %s missing content", peer.address)
-        return
-
-    try:
-        object_request = ObjectRequest.from_bytes(message.content)
-    except Exception as exc:
-        node.logger.warning("Error decoding OBJECT_REQUEST from %s: %s", peer.address, 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(), peer.address)
-
-            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(), peer.address)
-                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,
-                )
-                obj_res_msg.encrypt(peer.shared_key_bytes)
-                node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
-                return
-
-            if atom_id in node.storage_index:
-                node.logger.debug("Known provider for %s; informing %s", atom_id.hex(), peer.address)
-                provider_bytes = node.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,
-                )
-                obj_res_msg.encrypt(peer.shared_key_bytes)
-                node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
-                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", peer.address, 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,
-                )
-                obj_res_msg.encrypt(nearest_peer.shared_key_bytes)
-                node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
-
-        case ObjectRequestType.OBJECT_PUT:
-            node.logger.debug("Handling OBJECT_PUT for %s from %s", object_request.atom_id.hex(), peer.address)
-
-            nearest_peer = node.peer_route.closest_peer_for_hash(object_request.atom_id)
-            is_self_closest = False
-            if nearest_peer is None or nearest_peer.address is None:
-                is_self_closest = True
-            else:
-                try:
-                    self_distance = xor_distance(object_request.atom_id, node.relay_public_key_bytes)
-                    peer_distance = xor_distance(object_request.atom_id, nearest_peer.public_key_bytes)
-                except Exception as exc:
-                    node.logger.warning(
-                        "Failed distance comparison for OBJECT_PUT %s: %s",
-                        object_request.atom_id.hex(),
-                        exc,
-                    )
-                    is_self_closest = True
-                else:
-                    is_self_closest = self_distance <= peer_distance
-
-            if is_self_closest:
-                node.logger.debug("Storing provider info for %s locally", object_request.atom_id.hex())
-                node.storage_index[object_request.atom_id] = object_request.data
-            else:
-                node.logger.debug(
-                    "Forwarding OBJECT_PUT for %s to nearer peer %s",
-                    object_request.atom_id.hex(),
-                    nearest_peer.address,
-                )
-                fwd_req = ObjectRequest(
-                    type=ObjectRequestType.OBJECT_PUT,
-                    data=object_request.data,
-                    atom_id=object_request.atom_id,
-                )
-                obj_req_msg = Message(
-                    topic=MessageTopic.OBJECT_REQUEST,
-                    body=fwd_req.to_bytes(),
-                    sender=node.relay_public_key,
-                )
-                obj_req_msg.encrypt(nearest_peer.shared_key_bytes)
-                node.outgoing_queue.put((obj_req_msg.to_bytes(), nearest_peer.address))
-
-        case _:
-            node.logger.warning("Unknown ObjectRequestType %s from %s", object_request.type, peer.address)
+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
+from ..util import xor_distance
+from ...storage.providers import provider_id_for_payload, provider_payload_for_id
+
+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 bytes([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)."""
+    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", peer: "Peer", message: Message) -> None:
+    if message.content is None:
+        node.logger.warning("OBJECT_REQUEST from %s missing content", peer.address)
+        return
+
+    try:
+        object_request = ObjectRequest.from_bytes(message.content)
+    except Exception as exc:
+        node.logger.warning("Error decoding OBJECT_REQUEST from %s: %s", peer.address, 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(), peer.address)
+
+            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(), peer.address)
+                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,
+                )
+                obj_res_msg.encrypt(peer.shared_key_bytes)
+                node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
+                return
+
+            if atom_id in node.storage_index:
+                provider_id = node.storage_index[atom_id]
+                provider_bytes = provider_payload_for_id(node, provider_id)
+                if provider_bytes is not None:
+                    node.logger.debug("Known provider for %s; informing %s", atom_id.hex(), peer.address)
+                    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,
+                    )
+                    obj_res_msg.encrypt(peer.shared_key_bytes)
+                    node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
+                    return
+                node.logger.warning(
+                    "Unknown provider id %s for %s",
+                    provider_id,
+                    atom_id.hex(),
+                )
+
+            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", peer.address, 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,
+                )
+                obj_res_msg.encrypt(nearest_peer.shared_key_bytes)
+                node.outgoing_queue.put((obj_res_msg.to_bytes(), peer.address))
+
+        case ObjectRequestType.OBJECT_PUT:
+            node.logger.debug("Handling OBJECT_PUT for %s from %s", object_request.atom_id.hex(), peer.address)
+
+            nearest_peer = node.peer_route.closest_peer_for_hash(object_request.atom_id)
+            is_self_closest = False
+            if nearest_peer is None or nearest_peer.address is None:
+                is_self_closest = True
+            else:
+                try:
+                    self_distance = xor_distance(object_request.atom_id, node.relay_public_key_bytes)
+                    peer_distance = xor_distance(object_request.atom_id, nearest_peer.public_key_bytes)
+                except Exception as exc:
+                    node.logger.warning(
+                        "Failed distance comparison for OBJECT_PUT %s: %s",
+                        object_request.atom_id.hex(),
+                        exc,
+                    )
+                    is_self_closest = True
+                else:
+                    is_self_closest = self_distance <= peer_distance
+
+            if is_self_closest:
+                node.logger.debug("Storing provider info for %s locally", object_request.atom_id.hex())
+                provider_id = provider_id_for_payload(node, object_request.data)
+                node.storage_index[object_request.atom_id] = provider_id
+            else:
+                node.logger.debug(
+                    "Forwarding OBJECT_PUT for %s to nearer peer %s",
+                    object_request.atom_id.hex(),
+                    nearest_peer.address,
+                )
+                fwd_req = ObjectRequest(
+                    type=ObjectRequestType.OBJECT_PUT,
+                    data=object_request.data,
+                    atom_id=object_request.atom_id,
+                )
+                obj_req_msg = Message(
+                    topic=MessageTopic.OBJECT_REQUEST,
+                    body=fwd_req.to_bytes(),
+                    sender=node.relay_public_key,
+                )
+                obj_req_msg.encrypt(nearest_peer.shared_key_bytes)
+                node.outgoing_queue.put((obj_req_msg.to_bytes(), nearest_peer.address))
+
+        case _:
+            node.logger.warning("Unknown ObjectRequestType %s from %s", object_request.type, peer.address)