astreum 0.1.19__tar.gz → 0.2.0__tar.gz

astreum-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: astreum
+Version: 0.2.0
+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
+Project-URL: Issues, https://github.com/astreum/lib/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
+
+# Astreum Python Library
+
+Python library to interact with the Astreum blockchain and its Lispeum 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 |
+| -------------- | ---- | ------- | ----------- |
+| `machine-only` | bool | `True`  | When        |
+
+|   |
+| - |
+
+| **True** the node starts in *machine‑only* mode: no storage subsystem and no relay networking – only the Lispeum VM. Set to **False** to enable storage and relay features. |            |                |                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `relay_secret_key`                                                                                                                                                          | hex string | Auto‑generated | Ed25519 private key that identifies the node on the network. If omitted a fresh keypair is generated and kept in‑memory. |
+| `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.                                                    |
+
+### Networking
+
+| Parameter       | Type                    | Default | Description                                                                         |
+| --------------- | ----------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `use_ipv6`      | bool                    | `False` | Listen on IPv6 as well as IPv4.                                                     |
+| `incoming_port` | int                     | `7373`  | UDP port the relay binds to.                                                        |
+| `bootstrap`     | list\[tuple\[str, int]] | `[]`    | Initial peers used to join the network, e.g. `[ ("bootstrap.astreum.org", 7373) ]`. |
+
+> **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 = {
+    "machine-only": False,                   # run full node
+    "relay_secret_key": "ab…cd",             # optional – hex encoded
+    "validation_secret_key": "12…34",        # optional – validator
+    "storage_path": "./data/node1",
+    "storage_get_relay_timeout": 5,
+    "incoming_port": 7373,
+    "use_ipv6": False,
+    "bootstrap": [
+        ("bootstrap.astreum.org", 7373),
+        ("127.0.0.1", 7374)
+    ]
+}
+
+node = Node(config)
+# … your code …
+```
+
+## Lispeum Machine Quickstart
+
+The Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated *session* (lexical environment).
+
+```python
+from astreum.node import Node
+from astreum.machine.tokenizer import tokenize
+from astreum.machine.parser import parse
+
+# 1. Spin‑up a stand‑alone VM (machine‑only node).
+node = Node({"machine-only": True})
+
+# 2. Create a fresh session (environment).
+session_id = node.machine_session_create()
+
+# 3. Convert Lispeum source → Expr AST.
+source = '(+ 1 (* 2 3))'
+expr, _ = parse(tokenize(source))
+
+# 4. Evaluate inside that session.
+env = node.sessions[session_id]           # fetch the Env
+result = node.machine_expr_eval(env, expr)  # -> Expr.Integer(7)
+
+print(result.value)  # 7
+```
+
+### Handling errors
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize` fileciteturn1file1
+* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+
+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)
+```
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize` fileciteturn1file1
+* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+
+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)
+```
+
+---
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests
+```

astreum-0.2.0/README.md

@@ -0,0 +1,126 @@
+# Astreum Python Library
+
+Python library to interact with the Astreum blockchain and its Lispeum 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 |
+| -------------- | ---- | ------- | ----------- |
+| `machine-only` | bool | `True`  | When        |
+
+|   |
+| - |
+
+| **True** the node starts in *machine‑only* mode: no storage subsystem and no relay networking – only the Lispeum VM. Set to **False** to enable storage and relay features. |            |                |                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `relay_secret_key`                                                                                                                                                          | hex string | Auto‑generated | Ed25519 private key that identifies the node on the network. If omitted a fresh keypair is generated and kept in‑memory. |
+| `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.                                                    |
+
+### Networking
+
+| Parameter       | Type                    | Default | Description                                                                         |
+| --------------- | ----------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `use_ipv6`      | bool                    | `False` | Listen on IPv6 as well as IPv4.                                                     |
+| `incoming_port` | int                     | `7373`  | UDP port the relay binds to.                                                        |
+| `bootstrap`     | list\[tuple\[str, int]] | `[]`    | Initial peers used to join the network, e.g. `[ ("bootstrap.astreum.org", 7373) ]`. |
+
+> **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 = {
+    "machine-only": False,                   # run full node
+    "relay_secret_key": "ab…cd",             # optional – hex encoded
+    "validation_secret_key": "12…34",        # optional – validator
+    "storage_path": "./data/node1",
+    "storage_get_relay_timeout": 5,
+    "incoming_port": 7373,
+    "use_ipv6": False,
+    "bootstrap": [
+        ("bootstrap.astreum.org", 7373),
+        ("127.0.0.1", 7374)
+    ]
+}
+
+node = Node(config)
+# … your code …
+```
+
+## Lispeum Machine Quickstart
+
+The Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated *session* (lexical environment).
+
+```python
+from astreum.node import Node
+from astreum.machine.tokenizer import tokenize
+from astreum.machine.parser import parse
+
+# 1. Spin‑up a stand‑alone VM (machine‑only node).
+node = Node({"machine-only": True})
+
+# 2. Create a fresh session (environment).
+session_id = node.machine_session_create()
+
+# 3. Convert Lispeum source → Expr AST.
+source = '(+ 1 (* 2 3))'
+expr, _ = parse(tokenize(source))
+
+# 4. Evaluate inside that session.
+env = node.sessions[session_id]           # fetch the Env
+result = node.machine_expr_eval(env, expr)  # -> Expr.Integer(7)
+
+print(result.value)  # 7
+```
+
+### Handling errors
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize` fileciteturn1file1
+* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+
+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)
+```
+
+Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
+
+* Unterminated string literals are caught by `tokenize` fileciteturn1file1
+* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+
+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)
+```
+
+---
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests
+```

{astreum-0.1.19 → astreum-0.2.0}/pyproject.toml

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

astreum-0.2.0/src/astreum/__init__.py

@@ -0,0 +1 @@
+from node import Node

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/__init__.py

@@ -8,7 +8,7 @@ from .relay import Relay, Topic
 from ..machine import AstreumMachine
 from .utils import hash_data
 from .validation.block import Block
-from .storage import Storage
+from .storage.storage import Storage
 
 class Node:
     def __init__(self, config: dict):

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/relay/envelope.py

@@ -34,7 +34,7 @@ import os
 from dataclasses import dataclass
 from typing import Optional, Tuple, List
 from .message import Message, Topic
-from astreum.utils.bytes_format import encode, decode
+from astreum.format import encode, decode
 from ..utils import hash_data
 
 @dataclass

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/relay/message.py

@@ -6,7 +6,7 @@ import struct
 from enum import IntEnum, auto
 from dataclasses import dataclass
 from typing import Optional
-from astreum.utils.bytes_format import encode, decode
+from astreum.format import encode, decode
 
 class Topic(IntEnum):
     """

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/storage/merkle.py

@@ -1,7 +1,71 @@
 import blake3
 from .storage import Storage
-import astreum.utils.bytes_format as bytes_format bytes_format.decode, bytes_format.encode
+from astreum import format
 
+class MerkleNode:
+    def __init__(self, leaf: bool, data: bytes):
+        """
+        Initialize a Merkle node.
+        
+        For a leaf node, `data` is the actual content to be stored.
+        For an internal node, `data` should be the concatenation of the two child hashes.
+        
+        :param leaf: A boolean flag indicating whether this node is a leaf node (True) or an internal node (False).
+        :param data: The node's data. For leaves, the stored data; for internal nodes, concatenated child hashes.
+        """
+        self.leaf = leaf
+        self.data = data
+        self._hash = None  # Cached hash value to avoid recomputation.
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> 'MerkleNode':
+        """
+        Deserialize a MerkleNode from its byte representation.
+        
+        The input bytes are expected to be in the Astreum format, containing a leaf flag and node data.
+        
+        :param data: The serialized node data.
+        :return: A new MerkleNode instance.
+        """
+        leaf_flag, node_data = format.decode(data)
+        return cls(True if leaf_flag == 1 else False, node_data)
+
+    @classmethod
+    def from_storage(cls, storage: Storage, hash_value: bytes) -> 'MerkleNode' or None:
+        """
+        Retrieve and deserialize a MerkleNode from storage using its hash.
+        
+        :param storage: The Storage instance used to retrieve the node.
+        :param hash_value: The hash key under which the node is stored.
+        :return: A MerkleNode instance if found, otherwise None.
+        """
+        node_bytes = storage.get(hash_value)
+        if node_bytes is None:
+            return None
+        return cls.from_bytes(node_bytes)
+
+    def to_bytes(self) -> bytes:
+        """
+        Serialize the MerkleNode into bytes using the Astreum format.
+        
+        The format encodes a list containing the leaf flag and the node data.
+        
+        :return: The serialized bytes representing the node.
+        """
+        return format.encode([1 if self.leaf else 0, self.data])
+
+    def hash(self) -> bytes:
+        """
+        Compute (or retrieve a cached) hash of the node using the Blake3 algorithm.
+        
+        For leaf nodes, the hash is computed over the actual data.
+        For internal nodes, the hash is computed over the concatenated child hashes.
+        
+        :return: The Blake3 digest of the node's data.
+        """
+        if self._hash is None:
+            self._hash = blake3.blake3(self.data).digest()
+        return self._hash
 
 
 class MerkleTree:
@@ -158,67 +222,3 @@ class MerkleTree:
             return new_node_hash
 
 
-class MerkleNode:
-    def __init__(self, leaf: bool, data: bytes):
-        """
-        Initialize a Merkle node.
-        
-        For a leaf node, `data` is the actual content to be stored.
-        For an internal node, `data` should be the concatenation of the two child hashes.
-        
-        :param leaf: A boolean flag indicating whether this node is a leaf node (True) or an internal node (False).
-        :param data: The node's data. For leaves, the stored data; for internal nodes, concatenated child hashes.
-        """
-        self.leaf = leaf
-        self.data = data
-        self._hash = None  # Cached hash value to avoid recomputation.
-
-    @classmethod
-    def from_bytes(cls, data: bytes) -> 'MerkleNode':
-        """
-        Deserialize a MerkleNode from its byte representation.
-        
-        The input bytes are expected to be in the Astreum format, containing a leaf flag and node data.
-        
-        :param data: The serialized node data.
-        :return: A new MerkleNode instance.
-        """
-        leaf_flag, node_data = bytes_format.decode(data)
-        return cls(True if leaf_flag == 1 else False, node_data)
-
-    @classmethod
-    def from_storage(cls, storage: Storage, hash_value: bytes) -> 'MerkleNode' or None:
-        """
-        Retrieve and deserialize a MerkleNode from storage using its hash.
-        
-        :param storage: The Storage instance used to retrieve the node.
-        :param hash_value: The hash key under which the node is stored.
-        :return: A MerkleNode instance if found, otherwise None.
-        """
-        node_bytes = storage.get(hash_value)
-        if node_bytes is None:
-            return None
-        return cls.from_bytes(node_bytes)
-
-    def to_bytes(self) -> bytes:
-        """
-        Serialize the MerkleNode into bytes using the Astreum format.
-        
-        The format encodes a list containing the leaf flag and the node data.
-        
-        :return: The serialized bytes representing the node.
-        """
-        return bytes_format.encode([1 if self.leaf else 0, self.data])
-
-    def hash(self) -> bytes:
-        """
-        Compute (or retrieve a cached) hash of the node using the Blake3 algorithm.
-        
-        For leaf nodes, the hash is computed over the actual data.
-        For internal nodes, the hash is computed over the concatenated child hashes.
-        
-        :return: The Blake3 digest of the node's data.
-        """
-        if self._hash is None:
-            self._hash = blake3.blake3(self.data).digest()
-        return self._hash

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/storage/patricia.py

@@ -1,7 +1,7 @@
 import blake3
 from typing import Optional, List
 from .storage import Storage
-import astreum.utils.bytes_format as bytes_format bytes_format.decode, bytes_format.encode
+import astreum.format as format format.decode, format.encode
 
 
 def common_prefix_length(a: bytes, b: bytes) -> int:
@@ -35,7 +35,7 @@ class PatriciaNode:
         Expected format: [key, value, children]
         where children is a list of child node hashes (bytes).
         """
-        decoded = bytes_format.decode(data)
+        decoded = format.decode(data)
         key, value, children = decoded
         return cls(key, value, children)
 
@@ -59,7 +59,7 @@ class PatriciaNode:
         
         Structure: [key, value, children]
         """
-        return bytes_format.encode([self.key, self.value, self.children])
+        return format.encode([self.key, self.value, self.children])
 
     def hash(self) -> bytes:
         """

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/storage/storage.py

@@ -39,6 +39,8 @@ class Storage:
         self.pending_requests = {}  # hash -> (start_time, event)
         self.request_lock = threading.Lock()
 
+        
+
     def put(self, data_hash: bytes, data: bytes) -> bool:
         """Store data with its hash. Returns True if successful, False if space limit exceeded."""
         data_size = len(data)

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/utils.py

@@ -4,7 +4,7 @@ Utility functions for the Astreum blockchain.
 
 import blake3
 
-def hash_data(data: bytes) -> bytes:
+def blake3_hash(data: bytes) -> bytes:
     """
     Hash data using BLAKE3.
     

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/validation/account.py

@@ -1,7 +1,7 @@
 from typing import Optional
 from ..storage.patricia import PatriciaTrie
 
-import astreum.utils.bytes_format as bytes_format
+import astreum.format as format
 class Account:
     def __init__(self, public_key: bytes, balance: int, code: bytes, counter: int, data: bytes, secret_key: Optional[bytes] = None):
         """
@@ -30,7 +30,7 @@ class Account:
         
         The public_key (and optional secret_key) must be provided separately.
     """
-        decoded = bytes_format.decode(data)
+        decoded = format.decode(data)
         balance, code, counter, account_data = decoded
         return cls(public_key, balance, code, counter, account_data, secret_key=secret_key)
     
@@ -40,7 +40,7 @@ class Account:
         
         Format: [balance, code, counter, data]
         """
-        return bytes_format.encode([
+        return format.encode([
             self.balance,
             self.code,
             self.counter,

{astreum-0.1.19/src/astreum/node → astreum-0.2.0/src/astreum/_node}/validation/transaction.py

@@ -1,7 +1,7 @@
 from typing import Optional
 import time
 from .account import Account, get_account_from_storage
-import astreum.utils.bytes_format as bytes_format
+import astreum.format as format
 
 class Transaction:
     def __init__(
@@ -36,7 +36,7 @@ class Transaction:
         Returns:
             Transaction object
         """
-        decoded = bytes_format.decode(data)
+        decoded = format.decode(data)
         sender_public_key, recipient_public_key, amount, tx_data, counter, timestamp, signature = decoded
         
         sender_account = None
@@ -63,7 +63,7 @@ class Transaction:
         
         Format: [sender_hash, recipient_hash, amount, data, counter, timestamp, signature]
         """
-        return bytes_format.encode([
+        return format.encode([
             self.sender.public_key,
             self.recipient.public_key,
             self.amount,

astreum-0.2.0/src/astreum/lispeum/__init__.py

@@ -0,0 +1,2 @@
+from parser import parse
+from tokenizer import tokenize

{astreum-0.1.19 → astreum-0.2.0}/src/astreum/lispeum/parser.py

@@ -1,6 +1,6 @@
 from typing import List, Tuple
 from astreum.machine.error import ParseError
-from astreum.lispeum.expression import Expr
+from astreum.node import Expr
 
 
 def parse(tokens: List[str]) -> Tuple[Expr, List[str]]:

astreum-0.2.0/src/astreum/machine/environment.py

@@ -0,0 +1,4 @@
+from typing import Dict, Optional
+from astreum.lispeum.expression import Expr
+
+