astreum 0.1.16__tar.gz → 0.1.17__tar.gz

{astreum-0.1.16/src/astreum.egg-info → astreum-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.1.16
+Version: 0.1.17
 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.1.16 → astreum-0.1.17}/pyproject.toml

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

{astreum-0.1.16 → astreum-0.1.17}/src/astreum/node/relay/__init__.py

@@ -96,6 +96,9 @@ class Relay:
         # Initialize route table with our node ID
         self.route_table = RouteTable(self)
 
+        # Initialize storage index
+        self.storage_index: Dict[bytes, bytes] = {}
+
         # Start worker threads
         self._start_workers()
         

astreum-0.1.17/src/astreum/node/storage/merkle.py

@@ -0,0 +1,224 @@
+import blake3
+from .storage import Storage
+import astreum.utils.bytes_format as bytes_format bytes_format.decode, bytes_format.encode
+
+
+
+class MerkleTree:
+    def __init__(self, storage: Storage, root_hash: bytes = None, leaves: list[bytes] = None):
+        """
+        Initialize a Merkle tree from an existing root hash or by constructing a new tree from leaf data.
+        
+        If a list of leaf data is provided, the tree will be built from the bottom up,
+        every node will be stored in the provided storage, and the computed root hash
+        will be used as the tree's identifier.
+        
+        :param storage: A Storage instance used for storing and retrieving tree nodes.
+        :param root_hash: An optional existing root hash of a Merkle tree.
+        :param leaves: An optional list of leaf data (each as bytes). If provided, a new tree is built.
+        :raises ValueError: If neither root_hash nor leaves is provided.
+        """
+        self.storage = storage
+        if leaves is not None:
+            self.root_hash = self.build_tree_from_leaves(leaves)
+        elif root_hash is not None:
+            self.root_hash = root_hash
+        else:
+            raise ValueError("Either root_hash or leaves must be provided.")
+
+    def build_tree_from_leaves(self, leaves: list[bytes]) -> bytes:
+        """
+        Construct a Merkle tree from a list of leaf data and store each node in storage.
+        
+        Each leaf data entry is wrapped in a MerkleNode (with leaf=True) and stored.
+        Then, nodes are paired (duplicating the last node if needed when the count is odd)
+        to form parent nodes. For each parent node, the data is the concatenation of its
+        two child hashes. This process repeats until a single root hash remains.
+        
+        :param leaves: A list of bytes objects, each representing leaf data.
+        :return: The computed root hash of the newly built tree.
+        """
+        # Create leaf nodes and store them.
+        current_level = []
+        for leaf_data in leaves:
+            leaf_node = MerkleNode(True, leaf_data)
+            leaf_hash = leaf_node.hash()
+            self.storage.put(leaf_hash, leaf_node.to_bytes())
+            current_level.append(leaf_hash)
+
+        # Build the tree upward until one node remains.
+        while len(current_level) > 1:
+            next_level = []
+            # If an odd number of nodes, duplicate the last node.
+            if len(current_level) % 2 == 1:
+                current_level.append(current_level[-1])
+            for i in range(0, len(current_level), 2):
+                left_hash = current_level[i]
+                right_hash = current_level[i + 1]
+                # Create a parent node from the concatenated child hashes.
+                parent_node = MerkleNode(False, left_hash + right_hash)
+                parent_hash = parent_node.hash()
+                self.storage.put(parent_hash, parent_node.to_bytes())
+                next_level.append(parent_hash)
+            current_level = next_level
+
+        # The remaining hash is the root of the tree.
+        return current_level[0]
+
+    def get(self, index: int, level: int = 0) -> bytes:
+        """
+        Retrieve the data stored in the leaf at a given index.
+        
+        The method traverses the tree from the root, using the binary representation
+        of the index to choose which branch to follow at each level. It assumes that
+        non-leaf nodes store two child hashes concatenated together (each 32 bytes).
+        
+        :param index: The index of the leaf to retrieve. The bits of this number determine the path.
+        :param level: The current tree level (used internally for recursion).
+        :return: The data stored in the target leaf node, or None if not found.
+        """
+        current_node = MerkleNode.from_storage(self.storage, self.root_hash)
+        if current_node is None:
+            return None
+
+        # If at a leaf node, return its data.
+        if current_node.leaf:
+            return current_node.data
+
+        # For non-leaf nodes, extract the left and right child hashes.
+        left_hash = current_node.data[:32]
+        right_hash = current_node.data[32:64]
+
+        # Use the bit at position `level` in the index to select the branch:
+        # 0 selects the left branch, 1 selects the right branch.
+        bit = (index >> level) & 1
+        next_hash = left_hash if bit == 0 else right_hash
+
+        # Recursively traverse the tree.
+        return MerkleTree(self.storage, root_hash=next_hash).get(index, level + 1)
+
+    def set(self, index: int, new_data: bytes) -> None:
+        """
+        Update the leaf at the specified index with new data, rebuilding all affected nodes.
+        
+        The update process recursively creates new nodes for the branch from the updated leaf
+        back to the root. At each step, the old node is removed from storage and replaced with
+        a new node that reflects the updated hash.
+        
+        :param index: The index of the leaf node to update.
+        :param new_data: The new data (as bytes) to store in the leaf.
+        """
+        self.root_hash = self._update(self.root_hash, index, 0, new_data)
+
+    def _update(self, node_hash: bytes, index: int, level: int, new_data: bytes) -> bytes:
+        """
+        Recursive helper function to update a node on the path to the target leaf.
+        
+        For a leaf node, a new node is created with the updated data.
+        For an internal node, the correct branch (determined by the index and level) is updated,
+        and a new parent node is constructed from the updated child hash and the unchanged sibling hash.
+        
+        :param node_hash: The hash of the current node to update.
+        :param index: The target leaf index whose path is being updated.
+        :param level: The current depth in the tree.
+        :param new_data: The new data to set at the target leaf.
+        :return: The hash of the newly constructed node replacing the current node.
+        :raises Exception: If the node is not found in storage.
+        """
+        current_node = MerkleNode.from_storage(self.storage, node_hash)
+        if current_node is None:
+            raise Exception("Node not found in storage")
+
+        if current_node.leaf:
+            # At the leaf, create a new node with updated data.
+            new_leaf = MerkleNode(True, new_data)
+            new_hash = new_leaf.hash()
+            self.storage.put(new_hash, new_leaf.to_bytes())
+            self.storage.delete(node_hash)  # Remove the outdated node.
+            return new_hash
+        else:
+            # For non-leaf nodes, update the correct branch.
+            left_hash = current_node.data[:32]
+            right_hash = current_node.data[32:64]
+            bit = (index >> level) & 1
+
+            if bit == 0:
+                new_left_hash = self._update(left_hash, index, level + 1, new_data)
+                new_right_hash = right_hash
+            else:
+                new_left_hash = left_hash
+                new_right_hash = self._update(right_hash, index, level + 1, new_data)
+
+            # Create a new parent node with updated child hashes.
+            updated_node_data = new_left_hash + new_right_hash
+            new_node = MerkleNode(False, updated_node_data)
+            new_node_hash = new_node.hash()
+            self.storage.put(new_node_hash, new_node.to_bytes())
+            self.storage.delete(node_hash)  # Remove the outdated parent node.
+            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.17/src/astreum/node/storage/patricia.py

@@ -0,0 +1,289 @@
+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
+
+
+def common_prefix_length(a: bytes, b: bytes) -> int:
+    """Return the number of common prefix bytes between a and b."""
+    i = 0
+    while i < len(a) and i < len(b) and a[i] == b[i]:
+        i += 1
+    return i
+
+
+class PatriciaNode:
+    def __init__(self, key: bytes, value: Optional[bytes], children: Optional[List[bytes]] = None):
+        """
+        Initialize a Patricia node.
+        
+        :param key: A compressed part of the key.
+        :param value: The stored value (if this node represents a complete key) or None.
+        :param children: A list of child node hashes (bytes). The children are ordered by the first
+                         byte of the child's key.
+        """
+        self.key = key
+        self.value = value
+        self.children = children if children is not None else []
+        self._hash: Optional[bytes] = None
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> 'PatriciaNode':
+        """
+        Deserialize a PatriciaNode from its byte representation.
+        
+        Expected format: [key, value, children]
+        where children is a list of child node hashes (bytes).
+        """
+        decoded = bytes_format.decode(data)
+        key, value, children = decoded
+        return cls(key, value, children)
+
+    @classmethod
+    def from_storage(cls, storage: Storage, hash_value: bytes) -> Optional['PatriciaNode']:
+        """
+        Retrieve and deserialize a PatriciaNode 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 PatriciaNode 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 PatriciaNode into bytes using the Astreum format.
+        
+        Structure: [key, value, children]
+        """
+        return bytes_format.encode([self.key, self.value, self.children])
+
+    def hash(self) -> bytes:
+        """
+        Compute (or retrieve a cached) Blake3 hash over the node's serialized bytes.
+        """
+        if self._hash is None:
+            self._hash = blake3.blake3(self.to_bytes()).digest()
+        return self._hash
+
+    def invalidate_hash(self) -> None:
+        """Clear the cached hash so that it is recomputed on next use."""
+        self._hash = None
+
+
+class PatriciaTrie:
+    def __init__(self, storage: Storage, root_hash: Optional[bytes] = None):
+        """
+        Initialize a Patricia Trie.
+        
+        :param storage: A Storage instance for persisting nodes.
+        :param root_hash: Optionally, an existing root hash. If None, the trie is empty.
+        """
+        self.storage = storage
+        self.root_hash = root_hash
+
+    def get(self, key: bytes) -> Optional[bytes]:
+        """
+        Retrieve the value associated with the given key.
+        
+        :param key: The key (as bytes) to search for.
+        :return: The stored value if found, otherwise None.
+        """
+        if self.root_hash is None:
+            return None
+        return self._get(self.root_hash, key)
+
+    def _get(self, node_hash: bytes, key: bytes) -> Optional[bytes]:
+        node = PatriciaNode.from_storage(self.storage, node_hash)
+        if node is None:
+            return None
+
+        cp_len = common_prefix_length(key, node.key)
+        # If node.key completely matches the beginning of key...
+        if cp_len == len(node.key):
+            if cp_len == len(key):
+                return node.value
+            remainder = key[cp_len:]
+            branch = remainder[0]
+            child_hash = self._find_child(node.children, branch)
+            if child_hash is None:
+                return None
+            return self._get(child_hash, remainder)
+        return None
+
+    def put(self, key: bytes, value: bytes) -> None:
+        """
+        Insert or update the key with the provided value.
+        
+        :param key: The key (as bytes) to insert.
+        :param value: The value (as bytes) to associate with the key.
+        """
+        if self.root_hash is None:
+            new_node = PatriciaNode(key, value, [])
+            new_hash = new_node.hash()
+            self.storage.put(new_hash, new_node.to_bytes())
+            self.root_hash = new_hash
+        else:
+            self.root_hash = self._put(self.root_hash, key, value)
+
+    def _put(self, node_hash: bytes, key: bytes, value: bytes) -> bytes:
+        """
+        Recursive helper for inserting or updating a key.
+        
+        Returns the new hash for the node that replaces the current node.
+        """
+        node = PatriciaNode.from_storage(self.storage, node_hash)
+        if node is None:
+            # Node missing: create a new leaf.
+            new_node = PatriciaNode(key, value, [])
+            new_hash = new_node.hash()
+            self.storage.put(new_hash, new_node.to_bytes())
+            return new_hash
+
+        cp_len = common_prefix_length(key, node.key)
+        len_node_key = len(node.key)
+        len_key = len(key)
+
+        # Case 1: Exact match: update the value.
+        if cp_len == len_node_key and cp_len == len_key:
+            node.value = value
+            node.invalidate_hash()
+            new_hash = node.hash()
+            self.storage.put(new_hash, node.to_bytes())
+            self.storage.delete(node_hash)
+            return new_hash
+
+        # Case 2: Node key is a prefix of key (descend to child).
+        if cp_len == len_node_key:
+            remainder = key[cp_len:]
+            branch = remainder[0]
+            child_hash = self._find_child(node.children, branch)
+            if child_hash is not None:
+                new_child_hash = self._put(child_hash, remainder, value)
+                # Update the child pointer in the list.
+                idx = self._find_child_index(node.children, branch)
+                if idx is None:
+                    raise Exception("Child not found during update.")
+                node.children[idx] = new_child_hash
+            else:
+                # Create a new leaf for the remainder.
+                new_leaf = PatriciaNode(remainder, value, [])
+                new_leaf_hash = new_leaf.hash()
+                self.storage.put(new_leaf_hash, new_leaf.to_bytes())
+                self._insert_child(node.children, new_leaf_hash)
+            node.invalidate_hash()
+            new_hash = node.hash()
+            self.storage.put(new_hash, node.to_bytes())
+            self.storage.delete(node_hash)
+            return new_hash
+
+        # Case 3: Key is a prefix of node.key (split node).
+        if cp_len == len_key and cp_len < len_node_key:
+            old_suffix = node.key[cp_len:]
+            node.key = old_suffix  # update node to hold only the suffix
+            node.invalidate_hash()
+
+            # Create a new branch node with the key as prefix and value.
+            branch_node = PatriciaNode(key, value, [])
+            # The existing node becomes a child of the branch.
+            self._insert_child(branch_node.children, node.hash())
+            branch_hash = branch_node.hash()
+            self.storage.put(branch_hash, branch_node.to_bytes())
+            self.storage.put(node.hash(), node.to_bytes())
+            self.storage.delete(node_hash)
+            return branch_hash
+
+        # Case 4: Partial common prefix (split into a branch with two children).
+        if cp_len < len_node_key and cp_len < len_key:
+            common_prefix = key[:cp_len]
+            old_suffix = node.key[cp_len:]
+            new_suffix = key[cp_len:]
+            branch_node = PatriciaNode(common_prefix, None, [])
+            
+            # Adjust the existing node.
+            node.key = old_suffix
+            node.invalidate_hash()
+            self._insert_child(branch_node.children, node.hash())
+
+            # Create a new leaf for the new key’s remaining portion.
+            new_leaf = PatriciaNode(new_suffix, value, [])
+            new_leaf_hash = new_leaf.hash()
+            self.storage.put(new_leaf_hash, new_leaf.to_bytes())
+            self._insert_child(branch_node.children, new_leaf_hash)
+
+            branch_hash = branch_node.hash()
+            self.storage.put(branch_hash, branch_node.to_bytes())
+            self.storage.put(node.hash(), node.to_bytes())
+            self.storage.delete(node_hash)
+            return branch_hash
+
+        raise Exception("Unhandled case in PatriciaTrie.put")
+
+    def _find_child(self, children: List[bytes], branch: int) -> Optional[bytes]:
+        """
+        Perform a binary search over the ordered children list to find the child hash whose
+        branch (first byte of its key) equals the target branch.
+        """
+        lo = 0
+        hi = len(children)
+        while lo < hi:
+            mid = (lo + hi) // 2
+            child_hash = children[mid]
+            child_node = PatriciaNode.from_storage(self.storage, child_hash)
+            if child_node is None or not child_node.key:
+                raise Exception("Child node missing or has empty key.")
+            child_branch = child_node.key[0]
+            if child_branch == branch:
+                return child_hash
+            elif child_branch < branch:
+                lo = mid + 1
+            else:
+                hi = mid
+        return None
+
+    def _find_child_index(self, children: List[bytes], branch: int) -> Optional[int]:
+        """
+        Similar to _find_child but returns the index in the list.
+        """
+        lo = 0
+        hi = len(children)
+        while lo < hi:
+            mid = (lo + hi) // 2
+            child_hash = children[mid]
+            child_node = PatriciaNode.from_storage(self.storage, child_hash)
+            if child_node is None or not child_node.key:
+                raise Exception("Child node missing or has empty key.")
+            child_branch = child_node.key[0]
+            if child_branch == branch:
+                return mid
+            elif child_branch < branch:
+                lo = mid + 1
+            else:
+                hi = mid
+        return None
+
+    def _insert_child(self, children: List[bytes], new_child_hash: bytes) -> None:
+        """
+        Insert a new child hash into the ordered children list.
+        """
+        new_child_node = PatriciaNode.from_storage(self.storage, new_child_hash)
+        if new_child_node is None or not new_child_node.key:
+            raise Exception("New child node missing or has empty key.")
+        new_branch = new_child_node.key[0]
+        lo = 0
+        hi = len(children)
+        while lo < hi:
+            mid = (lo + hi) // 2
+            child_hash = children[mid]
+            child_node = PatriciaNode.from_storage(self.storage, child_hash)
+            if child_node is None or not child_node.key:
+                raise Exception("Child node missing or has empty key.")
+            child_branch = child_node.key[0]
+            if child_branch < new_branch:
+                lo = mid + 1
+            else:
+                hi = mid
+        children.insert(lo, new_child_hash)

astreum-0.1.17/src/astreum/node/validation/account.py

@@ -0,0 +1,99 @@
+from typing import Optional
+from ..storage.patricia import PatriciaTrie
+
+import astreum.utils.bytes_format as bytes_format
+class Account:
+    def __init__(self, public_key: bytes, balance: int, code: bytes, counter: int, data: bytes, secret_key: Optional[bytes] = None):
+        """
+        Initialize an Account.
+
+        :param public_key: The public key used as the account identifier (used as trie key).
+        :param balance: The account balance.
+        :param code: The associated code (for example, smart contract code).
+        :param counter: A transaction counter (nonce).
+        :param data: Additional account data.
+        :param secret_key: (Optional) The account’s secret key.
+        """
+        self.public_key = public_key
+        self.secret_key = secret_key  # Optional private key.
+        self.balance = balance
+        self.code = code
+        self.counter = counter
+        self.data = data
+
+    @classmethod
+    def from_bytes(cls, public_key: bytes, data: bytes, secret_key: Optional[bytes] = None) -> 'Account':
+        """
+        Deserialize an Account from its byte representation.
+        
+        Expected format: [balance, code, counter, data]
+        
+        The public_key (and optional secret_key) must be provided separately.
+    """
+        decoded = bytes_format.decode(data)
+        balance, code, counter, account_data = decoded
+        return cls(public_key, balance, code, counter, account_data, secret_key=secret_key)
+    
+    def to_bytes(self) -> bytes:
+        """
+        Serialize the Account into bytes.
+        
+        Format: [balance, code, counter, data]
+        """
+        return bytes_format.encode([
+            self.balance,
+            self.code,
+            self.counter,
+            self.data
+        ])
+
+
+class Accounts(PatriciaTrie):
+    """
+    Accounts is a PatriciaTrie storing Account objects.
+    
+    The trie key is the account’s public key (bytes), while the value is the account data
+    (serialized with balance, code, counter, and data only).
+    
+    You can instantiate Accounts with a storage instance and, if available, a root hash
+    representing an existing trie.
+    """
+    def get_account(self, public_key: bytes) -> Optional[Account]:
+        """
+        Retrieve an account using its public key.
+
+        :param public_key: The public key (bytes) of the account.
+        :return: The Account instance if found, else None.
+        """
+        raw = self.get(public_key)
+        if raw is None:
+            return None
+        return Account.from_bytes(public_key, raw)
+
+    def put_account(self, account: Account) -> None:
+        """
+        Insert or update an account in the trie.
+
+        :param account: The Account instance to store.
+        """
+        self.put(account.public_key, account.to_bytes())
+
+def get_account_from_storage(public_key: bytes, accounts: Accounts, storage: Storage) -> Optional[Account]:
+    # 1. get account details hash
+    # 2. resolve storage objects to get account details
+    # 3. return account
+    return None
+
+# Example of instantiation:
+#
+# Assuming you have an instance of Storage (e.g., from your storage module), you can create
+# an Accounts instance either as an empty trie or using an existing root hash:
+#
+#   storage = Storage()
+#
+#   # To instantiate an empty Accounts trie:
+#   accounts = Accounts(storage)
+#
+#   # To instantiate with an existing trie root hash:
+#   existing_root_hash = b'...'  # This would be loaded from persistent storage.
+#   accounts = Accounts(storage, root_hash=existing_root_hash)

astreum-0.1.17/src/astreum/node/validation/block.py

@@ -0,0 +1,30 @@
+class Block:
+    @classmethod
+    def from_bytes(cls, validator) -> 'Block':
+        """
+        Deserialize an Account from its byte representation.
+        
+        Expected format: [balance, code, counter, data]
+        
+        The public_key (and optional secret_key) must be provided separately.
+    """
+        decoded = bytes_format.decode(data)
+        balance, code, counter, account_data = decoded
+        return cls(public_key, balance, code, counter, account_data, secret_key=secret_key)
+    
+    def to_bytes(self) -> bytes:
+        """
+        Serialize the Account into bytes.
+        
+        Format: [balance, code, counter, data]
+        """
+        return bytes_format.encode([
+            self.balance,
+            self.code,
+            self.counter,
+            self.data
+        ])
+
+class Chain:
+    def __init__(self, latest_block: Block):
+        self.latest_block = latest_block