astreum 0.3.25__tar.gz → 0.3.46__tar.gz

{astreum-0.3.25/src/astreum.egg-info → astreum-0.3.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.3.25
+Version: 0.3.46
 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,11 +45,17 @@ 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.                       |
-| `default_seeds`          | list\[str\] | `["bootstrap.astreum.org:52780"]` | Default addresses to ping before joining; pass `[]` to disable the built-in default.          |
-| `additional_seeds`       | list\[str\] | `[]`                  | Extra addresses appended to `default_seeds`; 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.                        |
+| `cold_storage_advertise_limit` | int   | `1000`                | Max cold storage atoms advertised per cycle using last-modified time; `-1` unlimited, `0` disable.       |
+| `incoming_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for inbound queue usage tracked by `enqueue_incoming`; set to `0` to disable.           |
+| `incoming_queue_timeout` | float      | `1.0`                 | When > 0, `enqueue_incoming` waits up to this many seconds for space before dropping the payload.        |
+| `outgoing_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for `enqueue_outgoing`-tracked outgoing queue usage; set to `0` to disable.            |
+| `outgoing_queue_timeout` | float      | `1.0`                 | When > 0, `enqueue_outgoing` waits up to this many seconds for space before dropping the payload.        |
 
 > **Note**
 > The peer‑to‑peer *route* used for object discovery is always enabled.
@@ -66,9 +72,10 @@ config = {
     "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",
+    "cold_storage_advertise_limit": 1000,   # -1 unlimited, 0 disable, >0 limit
     "incoming_port": 52780,
     "use_ipv6": False,
-    "default_seeds": [],
+    "default_seed": None,
     "additional_seeds": [
         "127.0.0.1:7374"
     ]
@@ -175,6 +182,7 @@ python3 -m unittest tests.node.test_current_validator
 python3 -m unittest tests.node.test_node_connection
 python3 -m unittest tests.node.test_node_init
 python3 -m unittest tests.node.test_node_validation
+python3 -m unittest tests.node.config.default_seed
 python3 -m unittest tests.node.tokenize
 python3 -m unittest tests.node.parse
 python3 -m unittest tests.node.function

{astreum-0.3.25 → astreum-0.3.46}/README.md

@@ -15,23 +15,29 @@ 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
 
 | 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         | `52780`                | UDP port the relay binds to; pass `0` or omit to let the OS pick an ephemeral port.                       |
-| `default_seeds`          | list\[str\] | `["bootstrap.astreum.org:52780"]` | Default addresses to ping before joining; pass `[]` to disable the built-in default.          |
-| `additional_seeds`       | list\[str\] | `[]`                  | Extra addresses appended to `default_seeds`; 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.                                  |
+| `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.                       |
+| `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.                        |
+| `cold_storage_advertise_limit` | int   | `1000`                | Max cold storage atoms advertised per cycle using last-modified time; `-1` unlimited, `0` disable.       |
+| `incoming_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for inbound queue usage tracked by `enqueue_incoming`; set to `0` to disable.           |
+| `incoming_queue_timeout` | float      | `1.0`                 | When > 0, `enqueue_incoming` waits up to this many seconds for space before dropping the payload.        |
+| `outgoing_queue_size_limit` | int     | `67108864`            | Soft cap (bytes) for `enqueue_outgoing`-tracked outgoing queue usage; set to `0` to disable.            |
+| `outgoing_queue_timeout` | float      | `1.0`                 | When > 0, `enqueue_outgoing` waits up to this many seconds for space before dropping the payload.        |
 
 > **Note**
 > The peer‑to‑peer *route* used for object discovery is always enabled.
@@ -47,14 +53,15 @@ config = {
     "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": 52780,
-    "use_ipv6": False,
-    "default_seeds": [],
-    "additional_seeds": [
-        "127.0.0.1:7374"
-    ]
-}
+    "cold_storage_path": "./data/node1",
+    "cold_storage_advertise_limit": 1000,   # -1 unlimited, 0 disable, >0 limit
+    "incoming_port": 52780,
+    "use_ipv6": False,
+    "default_seed": None,
+    "additional_seeds": [
+        "127.0.0.1:7374"
+    ]
+}
 
 node = Node(config)
 # … your code …
@@ -132,7 +139,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.
@@ -157,6 +164,7 @@ python3 -m unittest tests.node.test_current_validator
 python3 -m unittest tests.node.test_node_connection
 python3 -m unittest tests.node.test_node_init
 python3 -m unittest tests.node.test_node_validation
+python3 -m unittest tests.node.config.default_seed
 python3 -m unittest tests.node.tokenize
 python3 -m unittest tests.node.parse
 python3 -m unittest tests.node.function

{astreum-0.3.25 → astreum-0.3.46}/pyproject.toml

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

{astreum-0.3.25 → astreum-0.3.46}/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.25 → astreum-0.3.46}/src/astreum/communication/__init__.py

@@ -1,11 +1,15 @@
-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 .incoming_queue import enqueue_incoming
+from .outgoing_queue import enqueue_outgoing
+from .setup import communication_setup
+
+__all__ = [
+    "Message",
+    "Peer",
+    "Route",
+    "enqueue_incoming",
+    "enqueue_outgoing",
+    "communication_setup",
+]

astreum-0.3.46/src/astreum/communication/difficulty.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .. import Node
+
+
+def message_difficulty(node: "Node") -> int:
+    """Compute current message difficulty based on incoming queue pressure."""
+    size = node.incoming_queue_size
+    limit = node.incoming_queue_size_limit
+
+    if limit <= 0:
+        return 1
+
+    pressure = size / limit
+    if pressure < 0.70:
+        value = 1
+    elif pressure < 0.75:
+        value = 3
+    elif pressure < 0.80:
+        value = 5
+    elif pressure < 0.85:
+        value = 8
+    elif pressure < 0.90:
+        value = 12
+    elif pressure < 0.93:
+        value = 16
+    elif pressure < 0.95:
+        value = 19
+    elif pressure < 0.97:
+        value = 22
+    elif pressure < 0.98:
+        value = 24
+    else:
+        value = 26
+
+    return max(1, min(255, value))

{astreum-0.3.25 → astreum-0.3.46}/src/astreum/communication/handlers/handshake.py

@@ -1,18 +1,20 @@
-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 __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+
+from ..outgoing_queue import enqueue_outgoing
 from ..models.peer import Peer
 from ..models.message import Message, MessageTopic
 from ..models.ping import Ping
-
-if TYPE_CHECKING:
-    from .... import Node
-
-
+from ..difficulty import message_difficulty
+
+if TYPE_CHECKING:
+    from .... import Node
+
+
 def handle_handshake(node: "Node", addr: Sequence[object], message: Message) -> bool:
     """Handle incoming handshake messages.
 
@@ -25,6 +27,7 @@ def handle_handshake(node: "Node", addr: Sequence[object], message: Message) ->
         try:
             ping_payload = Ping(
                 is_validator=bool(getattr(node, "validation_public_key", None)),
+                difficulty=message_difficulty(node),
                 latest_block=latest_block,
             ).to_bytes()
             ping_msg = Message(
@@ -33,7 +36,12 @@ def handle_handshake(node: "Node", addr: Sequence[object], message: Message) ->
                 sender=node.relay_public_key,
             )
             ping_msg.encrypt(peer.shared_key_bytes)
-            node.outgoing_queue.put((ping_msg.to_bytes(), peer_address))
+            enqueue_outgoing(
+                node,
+                peer_address,
+                message=ping_msg,
+                difficulty=peer.difficulty,
+            )
         except Exception as exc:
             node.logger.debug(
                 "Failed sending handshake ping to %s:%s: %s",
@@ -41,48 +49,57 @@ def handle_handshake(node: "Node", addr: Sequence[object], message: Message) ->
                 peer_address[1],
                 exc,
             )
-    sender_public_key_bytes = message.sender_bytes
-    try:
-        sender_key = X25519PublicKey.from_public_bytes(sender_public_key_bytes)
-    except Exception as exc:
-        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)
-
+    sender_public_key_bytes = message.sender_bytes
+    try:
+        sender_key = X25519PublicKey.from_public_bytes(sender_public_key_bytes)
+    except Exception as exc:
+        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)
+    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,
-        )
-    except Exception:
-        return True
-
-    node.add_peer(sender_public_key_bytes, peer)
-    node.peer_route.add_peer(sender_public_key_bytes, peer)
-
+
+    try:
+        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.outgoing_queue.put((response.to_bytes(), peer_address))
+    enqueue_outgoing(
+        node,
+        peer_address,
+        message=response,
+        difficulty=peer.difficulty,
+    )
     _queue_handshake_ping(peer, peer_address)
     return True