astreum 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

astreum/models/merkle.py

@@ -217,6 +217,7 @@ class MerkleTree:
         leaf.value = value
         self._invalidate(leaf)
         new_hash = leaf.hash()
+        self.nodes[new_hash] = leaf
 
         # bubble updated hashes
         for parent, old_hash, went_right in reversed(stack):

astreum/models/patricia.py

@@ -1,8 +1,19 @@
 import blake3
 from typing import Callable, Dict, List, Optional, Tuple
-from astreum import format
+from ..format import encode, decode
 
 class PatriciaNode:
+    """
+    A node in a compressed-key Patricia trie.
+
+    Attributes:
+        key_len (int): Number of bits in the `key` prefix that are meaningful.
+        key (bytes): The MSB-aligned bit prefix (zero-padded in last byte).
+        value (Optional[bytes]): Stored payload (None for internal nodes).
+        child_0 (Optional[bytes]): Hash pointer for next-bit == 0.
+        child_1 (Optional[bytes]): Hash pointer for next-bit == 1.
+    """
+
     def __init__(
         self,
         key_len: int,
@@ -16,33 +27,64 @@ class PatriciaNode:
         self.value = value
         self.child_0 = child_0
         self.child_1 = child_1
-        self._hash: bytes | None = None
+        self._hash: Optional[bytes] = None
 
     def to_bytes(self) -> bytes:
-        return format.encode([self.key_len, self.key, self.value, self.child_0, self.child_1])
+        """
+        Serialize node fields to bytes using the shared encode format.
+        - key_len in a single byte.
+        - None pointers/values as empty bytes.
+        """
+        key_len_b = self.key_len.to_bytes(1, "big")
+        val_b = self.value if self.value is not None else b""
+        c0_b = self.child_0 if self.child_0 is not None else b""
+        c1_b = self.child_1 if self.child_1 is not None else b""
+        return encode([key_len_b, self.key, val_b, c0_b, c1_b])
 
     @classmethod
     def from_bytes(cls, blob: bytes) -> "PatriciaNode":
-        key_len, key, value, child_0, child_1 = format.decode(blob)
+        """
+        Deserialize a blob produced by to_bytes() back into a PatriciaNode.
+        Empty bytes are converted back to None for value/children.
+        """
+        key_len_b, key, val_b, c0_b, c1_b = decode(blob)
+        key_len = key_len_b[0]
+        value = val_b if val_b else None
+        child_0 = c0_b if c0_b else None
+        child_1 = c1_b if c1_b else None
         return cls(key_len, key, value, child_0, child_1)
-    
+
     def hash(self) -> bytes:
+        """
+        Compute and cache the BLAKE3 hash of this node's serialized form.
+        """
         if self._hash is None:
             self._hash = blake3.blake3(self.to_bytes()).digest()
         return self._hash
 
 class PatriciaTrie:
+    """
+    A compressed-key Patricia trie supporting get and put.
+    """
+
     def __init__(
         self,
         node_get: Callable[[bytes], Optional[bytes]],
         root_hash: Optional[bytes] = None,
     ) -> None:
+        """
+        :param node_get: function mapping node-hash -> serialized node bytes (or None)
+        :param root_hash: optional hash of existing root node
+        """
         self._node_get = node_get
         self.nodes: Dict[bytes, PatriciaNode] = {}
-        self.root_hash: Optional[bytes] = root_hash
+        self.root_hash = root_hash
 
     @staticmethod
     def _bit(buf: bytes, idx: int) -> bool:
+        """
+        Return the bit at position `idx` (MSB-first) from `buf`.
+        """
         byte_i, offset = divmod(idx, 8)
         return ((buf[byte_i] >> (7 - offset)) & 1) == 1
 
@@ -54,15 +96,22 @@ class PatriciaTrie:
         key: bytes,
         key_bit_offset: int,
     ) -> bool:
-        if key_bit_offset + prefix_len > len(key) * 8:
+        """
+        Check whether the `prefix_len` bits of `prefix` match
+        bits in `key` starting at `key_bit_offset`.
+        """
+        total_bits = len(key) * 8
+        if key_bit_offset + prefix_len > total_bits:
             return False
-
         for i in range(prefix_len):
             if cls._bit(prefix, i) != cls._bit(key, key_bit_offset + i):
                 return False
         return True
 
     def _fetch(self, h: bytes) -> Optional[PatriciaNode]:
+        """
+        Fetch a node by hash, using in-memory cache then external node_get.
+        """
         node = self.nodes.get(h)
         if node is None:
             raw = self._node_get(h)
@@ -72,8 +121,11 @@ class PatriciaTrie:
             self.nodes[h] = node
         return node
 
-    def get(self, key: bytes) -> Optional["PatriciaNode"]:
-        """Return the node that stores *key*, or ``None`` if absent."""
+    def get(self, key: bytes) -> Optional[bytes]:
+        """
+        Return the stored value for `key`, or None if absent.
+        """
+        # Empty trie?
         if self.root_hash is None:
             return None
 
@@ -81,40 +133,42 @@ class PatriciaTrie:
         if node is None:
             return None
 
-        key_pos = 0
+        key_pos = 0  # bit offset into key
 
         while node is not None:
-            # 1️⃣ Verify that this node's (possibly sub‑byte) prefix matches.
+            # 1) Check that this node's prefix matches the key here
             if not self._match_prefix(node.key, node.key_len, key, key_pos):
                 return None
             key_pos += node.key_len
 
-            # 2️⃣ If every bit of *key* has been matched, success only if the
-            #     node actually stores a value.
+            # 2) If we've consumed all bits of the search key:
             if key_pos == len(key) * 8:
-                return node if node.value is not None else None
+                # Return value only if this node actually stores one
+                return node.value
 
-            # 3️⃣ Decide which branch to follow using the next bit of *key*.
+            # 3) Decide which branch to follow via next bit
             try:
                 next_bit = self._bit(key, key_pos)
-            except IndexError:  # key ended prematurely
+            except IndexError:
                 return None
 
             child_hash = node.child_1 if next_bit else node.child_0
-            if child_hash is None:  # dead end – key not present
-                return None
+            if child_hash is None:
+                return None  # dead end
 
-            # 4️⃣ Fetch the child node via unified helper.
+            # 4) Fetch child and continue descent
             node = self._fetch(child_hash)
-            if node is None:  # dangling pointer
-                return None
+            if node is None:
+                return None  # dangling pointer
 
-            key_pos += 1  # we just consumed one routing bit
+            key_pos += 1  # consumed routing bit
 
         return None
-    
+
     def put(self, key: bytes, value: bytes) -> None:
-        """Insert or update ``key`` with ``value`` in‑place."""
+        """
+        Insert or update `key` with `value` in-place.
+        """
         total_bits = len(key) * 8
 
         # S1 – Empty trie → create root leaf
@@ -126,7 +180,7 @@ class PatriciaTrie:
         # S2 – traversal bookkeeping
         stack: List[Tuple[PatriciaNode, bytes, int]] = []  # (parent, parent_hash, dir_bit)
         node = self._fetch(self.root_hash)
-        assert node is not None  # root must exist now
+        assert node is not None
         key_pos = 0
 
         # S4 – main descent loop
@@ -144,6 +198,7 @@ class PatriciaTrie:
                 self._invalidate_hash(node)
                 node.value = value
                 new_hash = node.hash()
+                self.nodes[new_hash] = node
                 self._bubble(stack, new_hash)
                 return
 
@@ -162,9 +217,11 @@ class PatriciaTrie:
             # 4.8 – fetch child and continue
             node = self._fetch(child_hash)
             if node is None:
-                # Dangling pointer – treat as append missing leaf
-                self._append_leaf(stack[-1][0], next_bit, key, key_pos, value, stack[:-1])
+                # Dangling pointer: treat as missing child
+                parent, _, _ = stack[-1]
+                self._append_leaf(parent, next_bit, key, key_pos, value, stack[:-1])
                 return
+
             key_pos += 1  # consumed routing bit
 
     def _append_leaf(
@@ -176,18 +233,20 @@ class PatriciaTrie:
         value: bytes,
         stack: List[Tuple[PatriciaNode, bytes, int]],
     ) -> None:
-        # key_pos points to routing bit; leaf stores the *rest* after that bit
+        # key_pos points to routing bit; leaf stores the rest after that bit
         tail_len = len(key) * 8 - (key_pos + 1)
         tail_bits, tail_len = self._bit_slice(key, key_pos + 1, tail_len)
         leaf = self._make_node(tail_bits, tail_len, value, None, None)
 
-        # attach
+        # attach to parent
         if dir_bit:
             parent.child_1 = leaf.hash()
         else:
             parent.child_0 = leaf.hash()
+
         self._invalidate_hash(parent)
         new_parent_hash = parent.hash()
+        self.nodes[new_parent_hash] = parent
         self._bubble(stack, new_parent_hash)
 
     def _split_and_insert(
@@ -198,52 +257,121 @@ class PatriciaTrie:
         key_pos: int,
         value: bytes,
     ) -> None:
-        """Split ``node`` at first divergent bit and insert new leaf for *key*."""
-        # Compute LCP between node.key and remaining key bits
+        # ➊—find longest-common-prefix (lcp) as before …
         max_lcp = min(node.key_len, len(key) * 8 - key_pos)
         lcp = 0
         while lcp < max_lcp and self._bit(node.key, lcp) == self._bit(key, key_pos + lcp):
             lcp += 1
 
-        # Common prefix bits → new internal node
+        # divergence bit values (taken **before** we mutate node.key)
+        old_div_bit = self._bit(node.key, lcp)
+        new_div_bit = self._bit(key, key_pos + lcp)
+
+        # ➋—internal node that holds the common prefix
         common_bits, common_len = self._bit_slice(node.key, 0, lcp)
         internal = self._make_node(common_bits, common_len, None, None, None)
 
-        # Trim old node prefix
-        old_suffix_bits, old_suffix_len = self._bit_slice(node.key, lcp, node.key_len - lcp)
+        # ➌—trim the *existing* node’s prefix **after** the divergence bit
+        old_suffix_bits, old_suffix_len = self._bit_slice(
+            node.key,
+            lcp + 1,                       # start *after* divergence bit
+            node.key_len - lcp - 1         # may be zero
+        )
         node.key = old_suffix_bits
         node.key_len = old_suffix_len
-        self._invalidate_hash(node)  # will be re‑hashed when attached
-        old_div_bit = self._bit(node.key, 0) if old_suffix_len > 0 else False
+        self._invalidate_hash(node)
+        new_node_hash = node.hash()
+        self.nodes[new_node_hash] = node
 
-        # New key leaf
-        new_key_tail_len = len(key) * 8 - (key_pos + lcp + 1)
-        new_tail_bits, new_tail_len = self._bit_slice(key, key_pos + lcp + 1, new_key_tail_len)
+        # ➍—new leaf for the key being inserted (unchanged)
+        new_tail_len = len(key) * 8 - (key_pos + lcp + 1)
+        new_tail_bits, _ = self._bit_slice(key, key_pos + lcp + 1, new_tail_len)
         leaf = self._make_node(new_tail_bits, new_tail_len, value, None, None)
-        new_div_bit = self._bit(key, key_pos + lcp)
 
-        # Attach children to internal
+        # ➎—hang the two children off the internal node
         if old_div_bit:
-            internal.child_1 = node.hash()
-            internal.child_0 = leaf.hash() if not new_div_bit else internal.child_0
+            internal.child_1 = new_node_hash
+            internal.child_0 = leaf.hash()
         else:
-            internal.child_0 = node.hash()
-            internal.child_1 = leaf.hash() if new_div_bit else internal.child_1
+            internal.child_0 = new_node_hash
+            internal.child_1 = leaf.hash()
+
+        # ➏—rehash up to the root (unchanged)
         self._invalidate_hash(internal)
         internal_hash = internal.hash()
+        self.nodes[internal_hash] = internal
 
-        # Rewire parent link or set as root
         if not stack:
             self.root_hash = internal_hash
             return
 
-        parent, parent_old_hash, dir_bit = stack.pop()
+        parent, _, dir_bit = stack.pop()
         if dir_bit == 0:
             parent.child_0 = internal_hash
         else:
             parent.child_1 = internal_hash
         self._invalidate_hash(parent)
-        parent_new_hash = parent.hash()
-        self._bubble(stack, parent_new_hash)
+        self._bubble(stack, parent.hash())
+
+
+    def _make_node(
+        self,
+        prefix_bits: bytes,
+        prefix_len: int,
+        value: Optional[bytes],
+        child0: Optional[bytes],
+        child1: Optional[bytes],
+    ) -> PatriciaNode:
+        node = PatriciaNode(prefix_len, prefix_bits, value, child0, child1)
+        self.nodes[node.hash()] = node
+        return node
 
+    def _invalidate_hash(self, node: PatriciaNode) -> None:
+        """Clear cached hash so next .hash() recomputes."""
+        node._hash = None  # type: ignore
 
+    def _bubble(
+        self,
+        stack: List[Tuple[PatriciaNode, bytes, int]],
+        new_hash: bytes
+    ) -> None:
+        """
+        Propagate updated child-hash `new_hash` up the ancestor stack,
+        rebasing each parent's pointer, invalidating and re-hashing.
+        """
+        while stack:
+            parent, old_hash, dir_bit = stack.pop()
+            if dir_bit == 0:
+                parent.child_0 = new_hash
+            else:
+                parent.child_1 = new_hash
+            self._invalidate_hash(parent)
+            new_hash = parent.hash()
+            self.nodes[new_hash] = parent
+        self.root_hash = new_hash
+
+    def _bit_slice(
+        self,
+        buf: bytes,
+        start_bit: int,
+        length: int
+    ) -> tuple[bytes, int]:
+        """
+        Extract `length` bits from `buf` starting at `start_bit` (MSB-first),
+        returning (bytes, bit_len) with zero-padding.
+        """
+        if length == 0:
+            return b"", 0
+
+        total = int.from_bytes(buf, "big")
+        bits_in_buf = len(buf) * 8
+
+        # shift so slice ends at LSB
+        shift = bits_in_buf - (start_bit + length)
+        slice_int = (total >> shift) & ((1 << length) - 1)
+
+        # left-align to MSB of first byte
+        pad = (8 - (length % 8)) % 8
+        slice_int <<= pad
+        byte_len = (length + 7) // 8
+        return slice_int.to_bytes(byte_len, "big"), length

{astreum-0.2.14.dist-info → astreum-0.2.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.14
+Version: 0.2.16
 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

{astreum-0.2.14.dist-info → astreum-0.2.16.dist-info}/RECORD

@@ -1,10 +1,6 @@
 astreum/__init__.py,sha256=y2Ok3EY_FstcmlVASr80lGR_0w-dH-SXDCCQFmL6uwA,28
 astreum/format.py,sha256=X4tG5GGPweNCE54bHYkLFiuLTbmpy5upO_s1Cef-MGA,2711
 astreum/node.py,sha256=dPloCXuDyIn3-KDqxlgl3jxsonJlFMLi_quwJRsoLC8,46259
-astreum/_node/__init__.py,sha256=7yz1YHo0DCUgUQvJf75qdUo_ocl5-XZRU-Vc2NhcvJs,18639
-astreum/_node/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-astreum/_node/storage/merkle.py,sha256=XCQBrHbwI0FuPTCUwHOy-Kva3uWbvCdw_-13hRPf1UI,10219
-astreum/_node/storage/patricia.py,sha256=tynxn_qETCU9X7yJdeh_0GHpC8Pzcoq4CWrSZlMUeRc,11546
 astreum/crypto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/crypto/ed25519.py,sha256=FRnvlN0kZlxn4j-sJKl-C9tqiz_0z4LZyXLj3KIj1TQ,1760
 astreum/crypto/quadratic_form.py,sha256=pJgbORey2NTWbQNhdyvrjy_6yjORudQ67jBz2ScHptg,4037
@@ -15,11 +11,11 @@ astreum/lispeum/parser.py,sha256=jQRzZYvBuSg8t_bxsbt1-WcHaR_LPveHNX7Qlxhaw-M,116
 astreum/lispeum/tokenizer.py,sha256=J-I7MEd0r2ZoVqxvRPlu-Afe2ZdM0tKXXhf1R4SxYTo,1429
 astreum/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 astreum/models/block.py,sha256=NKYyxL6_BrtXRgcgIrnkYsobX0Z_bGqQT-fQ_09zEOo,3226
-astreum/models/merkle.py,sha256=ceH4yJlt82XDTXe46hyoU88QIaGVOsVDsBZeDnOJYv8,8590
-astreum/models/patricia.py,sha256=D7UVU4b6Yvn2_McI35VoMEbpqwR8OmZon5LGoUSRADo,8913
+astreum/models/merkle.py,sha256=E850dITZmuQS2LmQt2yA_luy0a3QjHgSbL2ibQAmYJc,8627
+astreum/models/patricia.py,sha256=WtfwVufZazFTOjVDnSDI0I3ghetm3GBzAwqNQevOlJ8,12974
 astreum/models/transaction.py,sha256=Vu0cfmh80S31nEbxyJfv1dk9_zqtgGNyMdhlM0uQF4E,2611
-astreum-0.2.14.dist-info/licenses/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
-astreum-0.2.14.dist-info/METADATA,sha256=hW59JgJ5SxnVi7OJSrCuMT2XHIwYQonvD-3JITr-wok,5478
-astreum-0.2.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-astreum-0.2.14.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
-astreum-0.2.14.dist-info/RECORD,,
+astreum-0.2.16.dist-info/licenses/LICENSE,sha256=gYBvRDP-cPLmTyJhvZ346QkrYW_eleke4Z2Yyyu43eQ,1089
+astreum-0.2.16.dist-info/METADATA,sha256=u_O4mRcn4Ve_9zpgQQIatLYzF_R2K_jY-hxLQQ1HMLg,5478
+astreum-0.2.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+astreum-0.2.16.dist-info/top_level.txt,sha256=1EG1GmkOk3NPmUA98FZNdKouhRyget-KiFiMk0i2Uz0,8
+astreum-0.2.16.dist-info/RECORD,,