astreum 0.2.35__py3-none-any.whl → 0.2.37__py3-none-any.whl

astreum/__init__.py

@@ -1 +1,9 @@
-from ._node import Node, Expr, Env, tokenize, parse
+"""Lightweight package initializer to avoid circular imports during tests.
+
+Exports are intentionally minimal; import submodules directly as needed:
+ - Node, Expr, Env, tokenize, parse -> from astreum._node or astreum.lispeum
+ - Validation types -> from astreum._validation
+ - Storage types -> from astreum._storage
+"""
+
+__all__: list[str] = []

astreum/_communication/__init__.py

@@ -0,0 +1,9 @@
+from .peer import Peer
+from .route import Route
+from .setup import communication_setup
+
+__all__ = [
+    "Peer",
+    "Route",
+    "communication_setup",
+]

astreum/_communication/peer.py

@@ -0,0 +1,11 @@
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from datetime import datetime, timezone
+
+class Peer:
+    shared_key: bytes
+    timestamp: datetime
+    latest_block: bytes
+
+    def __init__(self, my_sec_key: X25519PrivateKey, peer_pub_key: X25519PublicKey):
+        self.shared_key = my_sec_key.exchange(peer_pub_key)
+        self.timestamp = datetime.now(timezone.utc)

astreum/_communication/route.py

@@ -0,0 +1,25 @@
+from typing import Dict, List
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+
+class Route:
+    def __init__(self, relay_public_key: X25519PublicKey, bucket_size: int = 16):
+        self.relay_public_key_bytes = relay_public_key.public_bytes(encoding=Encoding.Raw, format=PublicFormat.Raw)
+        self.bucket_size = bucket_size
+        self.buckets: Dict[int, List[X25519PublicKey]] = {
+            i: [] for i in range(len(self.relay_public_key_bytes) * 8)
+        }
+        self.peers = {}
+
+    @staticmethod
+    def _matching_leading_bits(a: bytes, b: bytes) -> int:
+        for byte_index, (ba, bb) in enumerate(zip(a, b)):
+            diff = ba ^ bb
+            if diff:
+                return byte_index * 8 + (8 - diff.bit_length())
+        return len(a) * 8
+
+    def add_peer(self, peer_public_key: X25519PublicKey):
+        peer_public_key_bytes = peer_public_key.public_bytes(encoding=Encoding.Raw, format=PublicFormat.Raw)
+        bucket_idx = self._matching_leading_bits(self.relay_public_key_bytes, peer_public_key_bytes)
+        if len(self.buckets[bucket_idx]) < self.bucket_size:
+            self.buckets[bucket_idx].append(peer_public_key)  

astreum/_communication/setup.py

@@ -0,0 +1,104 @@
+import socket, threading
+from queue import Queue
+from typing import Tuple, Optional
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .. import Node
+
+from .import Route
+
+def load_x25519(hex_key: Optional[str]) -> X25519PrivateKey:
+    """DH key for relaying (always X25519)."""
+    return 
+
+def load_ed25519(hex_key: Optional[str]) -> Optional[ed25519.Ed25519PrivateKey]:
+    """Signing key for validation (Ed25519), or None if absent."""
+    return ed25519.Ed25519PrivateKey.from_private_bytes(bytes.fromhex(hex_key)) \
+           if hex_key else None
+
+def make_routes(
+    relay_pk: X25519PublicKey,
+    val_sk: Optional[ed25519.Ed25519PrivateKey]
+) -> Tuple[Route, Optional[Route]]:
+    """Peer route (DH pubkey) + optional validation route (ed pubkey)."""
+    peer_rt = Route(relay_pk)
+    val_rt  = Route(val_sk.public_key()) if val_sk else None
+    return peer_rt, val_rt
+
+def setup_udp(
+    bind_port: int,
+    use_ipv6: bool
+) -> Tuple[socket.socket, int, Queue, threading.Thread, threading.Thread]:
+    fam  = socket.AF_INET6 if use_ipv6 else socket.AF_INET
+    sock = socket.socket(fam, socket.SOCK_DGRAM)
+    if use_ipv6:
+        sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 0)
+    sock.bind(("::" if use_ipv6 else "0.0.0.0", bind_port or 0))
+    port = sock.getsockname()[1]
+
+    q    = Queue()
+    pop  = threading.Thread(target=lambda: None, daemon=True)
+    proc = threading.Thread(target=lambda: None, daemon=True)
+    pop.start(); proc.start()
+    return sock, port, q, pop, proc
+
+def setup_outgoing(
+    use_ipv6: bool
+) -> Tuple[socket.socket, Queue, threading.Thread]:
+    fam  = socket.AF_INET6 if use_ipv6 else socket.AF_INET
+    sock = socket.socket(fam, socket.SOCK_DGRAM)
+    q    = Queue()
+    thr  = threading.Thread(target=lambda: None, daemon=True)
+    thr.start()
+    return sock, q, thr
+
+def make_maps():
+    """Empty lookup maps: peers and addresses."""
+    return 
+
+def communication_setup(node: "Node", config: dict):
+    node.use_ipv6              = config.get('use_ipv6', False)
+
+    # key loading
+    node.relay_secret_key      = load_x25519(config.get('relay_secret_key'))
+    node.validation_secret_key = load_ed25519(config.get('validation_secret_key'))
+
+    # derive pubs + routes
+    node.relay_public_key      = node.relay_secret_key.public_key()
+    node.peer_route, node.validation_route = make_routes(
+        node.relay_public_key,
+        node.validation_secret_key
+    )
+
+    # sockets + queues + threads
+    (node.incoming_socket,
+        node.incoming_port,
+        node.incoming_queue,
+        node.incoming_populate_thread,
+        node.incoming_process_thread
+    ) = setup_udp(config.get('incoming_port', 7373), node.use_ipv6)
+
+    (node.outgoing_socket,
+        node.outgoing_queue,
+        node.outgoing_thread
+    ) = setup_outgoing(node.use_ipv6)
+
+    # other workers & maps
+    node.object_request_queue = Queue()
+    node.peer_manager_thread  = threading.Thread(
+        target=node._relay_peer_manager,
+        daemon=True
+    )
+    node.peer_manager_thread.start()
+
+    node.peers, node.addresses = {}, {} # peers: Dict[X25519PublicKey,Peer], addresses: Dict[(str,int),X25519PublicKey]
+
+    # bootstrap pings
+    for addr in config.get('bootstrap', []):
+        node._send_ping(addr)

astreum/_lispeum/__init__.py

@@ -0,0 +1,16 @@
+from .expression import Expr
+from .environment import Env
+from .low_evaluation import low_eval
+from .meter import Meter
+from .parser import parse, ParseError
+from .tokenizer import tokenize
+
+__all__ = [
+    "Env",
+    "Expr",
+    "low_eval",
+    "Meter",
+    "parse",
+    "tokenize",
+    "ParseError",
+]

astreum/_lispeum/environment.py

@@ -0,0 +1,13 @@
+from ast import Expr
+from typing import Dict, Optional
+import uuid
+
+
+class Env:
+    def __init__(
+        self,
+        data: Optional[Dict[str, Expr]] = None,
+        parent_id: Optional[uuid.UUID] = None,
+    ):
+        self.data: Dict[bytes, Expr] = {} if data is None else data
+        self.parent_id = parent_id

astreum/_lispeum/expression.py

@@ -0,0 +1,37 @@
+from typing import List, Optional
+
+
+class Expr:
+    class ListExpr:
+        def __init__(self, elements: List['Expr']):
+            self.elements = elements
+        
+        def __repr__(self):
+            if not self.elements:
+                return "()"
+            inner = " ".join(str(e) for e in self.elements)
+            return f"({inner} list)"
+        
+    class Symbol:
+        def __init__(self, value: str):
+            self.value = value
+
+        def __repr__(self):
+            return f"({self.value} symbol)"
+        
+    class Bytes:
+        def __init__(self, value: bytes):
+            self.value = value
+
+        def __repr__(self):
+            return f"({self.value} bytes)"
+        
+    class Error:
+        def __init__(self, topic: str, origin: Optional['Expr'] = None):
+            self.topic = topic
+            self.origin  = origin
+
+        def __repr__(self):
+            if self.origin is None:
+                return f'({self.topic} error)'
+            return f'({self.origin} {self.topic} error)'

astreum/_lispeum/high_evaluation.py

@@ -0,0 +1,177 @@
+from typing import List, Union
+import uuid
+
+from .environment import Env
+from .expression import Expr
+from .meter import Meter
+
+
+def high_eval(self, env_id: uuid.UUID, expr: Expr, meter = None) -> Expr:
+
+        if meter is None:
+            meter = Meter()
+
+        # ---------- atoms ----------
+        if isinstance(expr, Expr.Error):
+            return expr
+
+        if isinstance(expr, Expr.Symbol):
+            bound = self.env_get(env_id, expr.value.encode())
+            if bound is None:
+                return Expr.Error(f"unbound symbol '{expr.value}'", origin=expr)
+            return bound
+
+        if not isinstance(expr, Expr.ListExpr):
+            return expr  # Expr.Byte or other literals passthrough
+
+        # ---------- empty / single ----------
+        if len(expr.elements) == 0:
+            return expr
+        if len(expr.elements) == 1:
+            return self.high_eval(env_id=env_id, expr=expr.elements[0], meter=meter)
+
+        tail = expr.elements[-1]
+
+        # ---------- (value name def) ----------
+        if isinstance(tail, Expr.Symbol) and tail.value == "def":
+            if len(expr.elements) < 3:
+                return Expr.Error("def expects (value name def)", origin=expr)
+            name_e = expr.elements[-2]
+            if not isinstance(name_e, Expr.Symbol):
+                return Expr.Error("def name must be symbol", origin=name_e)
+            value_e = expr.elements[-3]
+            value_res = self.high_eval(env_id=env_id, expr=value_e, meter=meter)
+            if isinstance(value_res, Expr.Error):
+                return value_res
+            self.env_set(env_id, name_e.value.encode(), value_res)
+            return value_res
+
+        # ---- LOW-LEVEL call: ( arg1 arg2 ... ( (body) sk ) ) ----
+        if isinstance(tail, Expr.ListExpr):
+            inner = tail.elements
+            if len(inner) >= 2 and isinstance(inner[-1], Expr.Symbol) and inner[-1].value == "sk":
+                body_expr = inner[-2]
+                if not isinstance(body_expr, Expr.ListExpr):
+                    return Expr.Error("sk body must be list", origin=body_expr)
+
+                # helper: turn an Expr into a contiguous bytes buffer
+                def to_bytes(v: Expr) -> Union[bytes, Expr.Error]:
+                    if isinstance(v, Expr.Byte):
+                        return bytes([v.value & 0xFF])
+                    if isinstance(v, Expr.ListExpr):
+                        # expect a list of Expr.Byte
+                        out: bytearray = bytearray()
+                        for el in v.elements:
+                            if isinstance(el, Expr.Byte):
+                                out.append(el.value & 0xFF)
+                            else:
+                                return Expr.Error("byte list must contain only Byte", origin=el)
+                        return bytes(out)
+                    if isinstance(v, Expr.Error):
+                        return v
+                    return Expr.Error("argument must resolve to Byte or (Byte ...)", origin=v)
+
+                # resolve ALL preceding args into bytes (can be Byte or List[Byte])
+                args_exprs = expr.elements[:-1]
+                arg_bytes: List[bytes] = []
+                for a in args_exprs:
+                    v = self.high_eval(env_id=env_id, expr=a, meter=meter)
+                    if isinstance(v, Expr.Error):
+                        return v
+                    vb = to_bytes(v)
+                    if isinstance(vb, Expr.Error):
+                        return vb
+                    arg_bytes.append(vb)
+
+                # build low-level code with $0-based placeholders ($0 = first arg)
+                code: List[bytes] = []
+
+                def emit(tok: Expr) -> Union[None, Expr.Error]:
+                    if isinstance(tok, Expr.Symbol):
+                        name = tok.value
+                        if name.startswith("$"):
+                            idx_s = name[1:]
+                            if not idx_s.isdigit():
+                                return Expr.Error("invalid sk placeholder", origin=tok)
+                            idx = int(idx_s)  # $0 is first
+                            if idx < 0 or idx >= len(arg_bytes):
+                                return Expr.Error("arity mismatch in sk placeholder", origin=tok)
+                            code.append(arg_bytes[idx])
+                            return None
+                        code.append(name.encode())
+                        return None
+
+                    if isinstance(tok, Expr.Byte):
+                        code.append(bytes([tok.value & 0xFF]))
+                        return None
+
+                    if isinstance(tok, Expr.ListExpr):
+                        rv = self.high_eval(env_id, tok, meter=meter)
+                        if isinstance(rv, Expr.Error):
+                            return rv
+                        rb = to_bytes(rv)
+                        if isinstance(rb, Expr.Error):
+                            return rb
+                        code.append(rb)
+                        return None
+
+                    if isinstance(tok, Expr.Error):
+                        return tok
+
+                    return Expr.Error("invalid token in sk body", origin=tok)
+
+                for t in body_expr.elements:
+                    err = emit(t)
+                    if isinstance(err, Expr.Error):
+                        return err
+
+                # Execute low-level code built from sk-body using the caller's meter
+                res = self.low_eval(code, meter=meter)
+                return res
+
+        # ---------- (... (body params fn))  HIGH-LEVEL CALL ----------
+        if isinstance(tail, Expr.ListExpr):
+            fn_form = tail
+            if (len(fn_form.elements) >= 3
+                and isinstance(fn_form.elements[-1], Expr.Symbol)
+                and fn_form.elements[-1].value == "fn"):
+
+                body_expr   = fn_form.elements[-3]
+                params_expr = fn_form.elements[-2]
+
+                if not isinstance(body_expr, Expr.ListExpr):
+                    return Expr.Error("fn body must be list", origin=body_expr)
+                if not isinstance(params_expr, Expr.ListExpr):
+                    return Expr.Error("fn params must be list", origin=params_expr)
+
+                params: List[bytes] = []
+                for p in params_expr.elements:
+                    if not isinstance(p, Expr.Symbol):
+                        return Expr.Error("fn param must be symbol", origin=p)
+                    params.append(p.value.encode())
+
+                args_exprs = expr.elements[:-1]
+                if len(args_exprs) != len(params):
+                    return Expr.Error("arity mismatch", origin=expr)
+
+                arg_bytes: List[bytes] = []
+                for a in args_exprs:
+                    v = self.high_eval(env_id, a, meter=meter)
+                    if isinstance(v, Expr.Error):
+                        return v
+                    if not isinstance(v, Expr.Byte):
+                        return Expr.Error("argument must resolve to Byte", origin=a)
+                    arg_bytes.append(bytes([v.value & 0xFF]))
+
+                # child env, bind params -> Expr.Byte
+                child_env = uuid.uuid4()
+                self.environments[child_env] = Env(parent_id=env_id)
+                for name_b, val_b in zip(params, arg_bytes):
+                    self.env_set(child_env, name_b, Expr.Byte(val_b[0]))
+
+                # evaluate HL body, metered from the top
+                return self.high_eval(child_env, body_expr, meter=meter)
+
+        # ---------- default: resolve each element and return list ----------
+        resolved: List[Expr] = [self.high_eval(env_id, e, meter=meter) for e in expr.elements]
+        return Expr.ListExpr(resolved)

astreum/_lispeum/low_evaluation.py

@@ -0,0 +1,123 @@
+from typing import Dict, List, Union
+from .expression import Expr
+from .meter import Meter
+
+def tc_to_int(b: bytes) -> int:
+    """bytes -> int using two's complement (width = len(b)*8)."""
+    if not b:
+        return 0
+    return int.from_bytes(b, "big", signed=True)
+
+def int_to_tc(n: int, width_bytes: int) -> bytes:
+    """int -> bytes (two's complement, fixed width)."""
+    if width_bytes <= 0:
+        return b"\x00"
+    return n.to_bytes(width_bytes, "big", signed=True)
+
+def min_tc_width(n: int) -> int:
+    """minimum bytes to store n in two's complement."""
+    if n == 0:
+        return 1
+    w = 1
+    while True:
+        try:
+            n.to_bytes(w, "big", signed=True)
+            return w
+        except OverflowError:
+            w += 1
+
+def nand_bytes(a: bytes, b: bytes) -> bytes:
+    """Bitwise NAND on two byte strings, zero-extending to max width."""
+    w = max(len(a), len(b), 1)
+    au = int.from_bytes(a.rjust(w, b"\x00"), "big", signed=False)
+    bu = int.from_bytes(b.rjust(w, b"\x00"), "big", signed=False)
+    mask = (1 << (w * 8)) - 1
+    resu = (~(au & bu)) & mask
+    return resu.to_bytes(w, "big", signed=False)
+
+def low_eval(self, code: List[bytes], meter: Meter) -> Expr:
+        
+        heap: Dict[bytes, bytes] = {}
+
+        stack: List[bytes] = []
+        pc = 0
+
+        while True:
+            if pc >= len(code):
+                if len(stack) != 1:
+                    return Expr.Error("bad stack")
+                # wrap successful result as an Expr.Bytes
+                return Expr.Bytes(stack.pop())
+
+            tok = code[pc]
+            pc += 1
+
+            # ---------- ADD ----------
+            if tok == b"add":
+                if len(stack) < 2:
+                    return Expr.Error("underflow")
+                b_b = stack.pop()
+                a_b = stack.pop()
+                a_i = tc_to_int(a_b)
+                b_i = tc_to_int(b_b)
+                res_i = a_i + b_i
+                width = max(len(a_b), len(b_b), min_tc_width(res_i))
+                res_b = int_to_tc(res_i, width)
+                # charge for both operands' byte widths
+                if not meter.charge_bytes(len(a_b) + len(b_b)):
+                    return Expr.Error("meter limit")
+                stack.append(res_b)
+                continue
+
+            # ---------- NAND ----------
+            if tok == b"nand":
+                if len(stack) < 2:
+                    return Expr.Error("underflow")
+                b_b = stack.pop()
+                a_b = stack.pop()
+                res_b = nand_bytes(a_b, b_b)
+                # bitwise cost: 2 * max(len(a), len(b))
+                if not meter.charge_bytes(2 * max(len(a_b), len(b_b), 1)):
+                    return Expr.Error("meter limit")
+                stack.append(res_b)
+                continue
+
+            # ---------- JUMP ----------
+            if tok == b"jump":
+                if len(stack) < 1:
+                    return Expr.Error("underflow")
+                tgt_b = stack.pop()
+                if not meter.charge_bytes(1):
+                    return Expr.Error("meter limit")
+                tgt_i = tc_to_int(tgt_b)
+                if tgt_i < 0 or tgt_i >= len(code):
+                    return Expr.Error("bad jump")
+                pc = tgt_i
+                continue
+
+            # ---------- HEAP GET ----------
+            if tok == b"heap_get":
+                if len(stack) < 1:
+                    return Expr.Error("underflow")
+                key = stack.pop()
+                val = heap.get(key) or b""
+                # get cost: 1
+                if not meter.charge_bytes(1):
+                    return Expr.Error("meter limit")
+                stack.append(val)
+                continue
+
+            # ---------- HEAP SET ----------
+            if tok == b"heap_set":
+                if len(stack) < 2:
+                    return Expr.Error("underflow")
+                val = stack.pop()
+                key = stack.pop()
+                if not meter.charge_bytes(len(val)):
+                    return Expr.Error("meter limit")
+                heap[key] = val
+                continue
+
+            # if no opcode matched above, treat token as literal
+            # not an opcode → literal blob
+            stack.append(tok)

astreum/_lispeum/meter.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+
+class Meter:
+    def __init__(self, enabled: bool = True, limit: Optional[int] = None):
+        self.enabled = enabled
+        self.limit: Optional[int] = limit
+        self.used: int = 0
+
+    def charge_bytes(self, n: int) -> bool:
+        if not self.enabled:
+            return True
+        if n < 0:
+            n = 0
+        if self.limit is not None and (self.used + n) >= self.limit:
+            return False
+        self.used += n
+        return True

astreum/_lispeum/parser.py

@@ -0,0 +1,56 @@
+from typing import List, Tuple
+from src.astreum._lispeum import Expr
+
+class ParseError(Exception):
+    pass
+
+def _parse_one(tokens: List[str], pos: int = 0) -> Tuple[Expr, int]:
+    if pos >= len(tokens):
+        raise ParseError("unexpected end")
+    tok = tokens[pos]
+
+    if tok == '(':  # list
+        items: List[Expr] = []
+        i = pos + 1
+        while i < len(tokens):
+            if tokens[i] == ')':
+                # special-case error form at close: (origin topic err) or (topic err)
+                if len(items) >= 3 and isinstance(items[-1], Expr.Symbol) and items[-1].value == 'err' and isinstance(items[-2], Expr.Symbol):
+                    return Expr.Error(items[-2].value, origin=items[-3]), i + 1
+                if len(items) == 2 and isinstance(items[-1], Expr.Symbol) and items[-1].value == 'err' and isinstance(items[-2], Expr.Symbol):
+                    return Expr.Error(items[-2].value), i + 1
+                return Expr.ListExpr(items), i + 1
+            expr, i = _parse_one(tokens, i)
+            items.append(expr)
+        raise ParseError("expected ')'")
+
+    if tok == ')':
+        raise ParseError("unexpected ')'")
+
+    # try integer → Bytes (variable-length two's complement)
+    try:
+        n = int(tok)
+        # encode as minimal-width signed two's complement, big-endian
+        def int_to_min_tc(v: int) -> bytes:
+            """Return the minimal-width signed two's complement big-endian
+            byte encoding of integer v. Width expands just enough so that
+            decoding with signed=True yields the same value and sign.
+            Example: 0 -> b"\x00", 127 -> b"\x7f", 128 -> b"\x00\x80".
+            """
+            if v == 0:
+                return b"\x00"
+            w = 1
+            while True:
+                try:
+                    return v.to_bytes(w, "big", signed=True)
+                except OverflowError:
+                    w += 1
+
+        return Expr.Bytes(int_to_min_tc(n)), pos + 1
+    except ValueError:
+        return Expr.Symbol(tok), pos + 1
+
+def parse(tokens: List[str]) -> Tuple[Expr, List[str]]:
+    """Parse tokens into an Expr and return (expr, remaining_tokens)."""
+    expr, next_pos = _parse_one(tokens, 0)
+    return expr, tokens[next_pos:]

astreum/_lispeum/tokenizer.py

@@ -0,0 +1,22 @@
+from typing import List
+
+
+def tokenize(source: str) -> List[str]:
+    tokens: List[str] = []
+    cur: List[str] = []
+    for ch in source:
+        if ch.isspace():
+            if cur:
+                tokens.append("".join(cur))
+                cur = []
+            continue
+        if ch in ("(", ")"):
+            if cur:
+                tokens.append("".join(cur))
+                cur = []
+            tokens.append(ch)
+            continue
+        cur.append(ch)
+    if cur:
+        tokens.append("".join(cur))
+    return tokens