astreum 0.2.40__py3-none-any.whl → 0.2.41__py3-none-any.whl

astreum/_consensus/__init__.py

@@ -1,3 +1,5 @@
+from .account import Account
+from .accounts import Accounts
 from .block import Block
 from .chain import Chain
 from .fork import Fork
@@ -12,5 +14,7 @@ __all__ = [
     "Fork",
     "Receipt",
     "Transaction",
+    "Account",
+    "Accounts",
     "consensus_setup",
 ]

astreum/_consensus/account.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, List, Optional, Tuple
+
+from .._storage.atom import Atom, ZERO32
+
+
+def _int_to_be_bytes(value: int) -> bytes:
+    value = int(value)
+    if value < 0:
+        raise ValueError("account integers must be non-negative")
+    if value == 0:
+        return b"\x00"
+    size = (value.bit_length() + 7) // 8
+    return value.to_bytes(size, "big")
+
+
+def _be_bytes_to_int(data: Optional[bytes]) -> int:
+    if not data:
+        return 0
+    return int.from_bytes(data, "big")
+
+
+def _make_list(child_ids: List[bytes]) -> Tuple[bytes, List[Atom]]:
+    next_hash = ZERO32
+    elements: List[Atom] = []
+    for child_id in reversed(child_ids):
+        elem = Atom.from_data(data=child_id, next_hash=next_hash)
+        next_hash = elem.object_id()
+        elements.append(elem)
+    elements.reverse()
+    value_atom = Atom.from_data(
+        data=len(child_ids).to_bytes(8, "little"),
+        next_hash=next_hash,
+    )
+    type_atom = Atom.from_data(data=b"list", next_hash=value_atom.object_id())
+    atoms = elements + [value_atom, type_atom]
+    return type_atom.object_id(), atoms
+
+
+def _resolve_storage_get(source: Any) -> Callable[[bytes], Optional[Atom]]:
+    if callable(source):
+        return source
+    getter = getattr(source, "_local_get", None)
+    if callable(getter):
+        return getter
+    raise TypeError("Account.from_atom needs a callable storage getter or node with '_local_get'")
+
+
+def _read_list_entries(
+    storage_get: Callable[[bytes], Optional[Atom]],
+    start: bytes,
+) -> List[bytes]:
+    entries: List[bytes] = []
+    current = start if start and start != ZERO32 else b""
+    while current:
+        elem = storage_get(current)
+        if elem is None:
+            break
+        entries.append(elem.data)
+        nxt = elem.next
+        current = nxt if nxt and nxt != ZERO32 else b""
+    return entries
+
+
+@dataclass
+class Account:
+    _balance: int
+    _data: bytes
+    _nonce: int
+    hash: bytes = ZERO32
+    atoms: List[Atom] = field(default_factory=list)
+
+    @staticmethod
+    def _encode(balance: int, data: bytes, nonce: int) -> Tuple[bytes, List[Atom]]:
+        balance_atom = Atom.from_data(data=_int_to_be_bytes(balance))
+        data_atom = Atom.from_data(data=bytes(data))
+        nonce_atom = Atom.from_data(data=_int_to_be_bytes(nonce))
+
+        field_atoms = [balance_atom, data_atom, nonce_atom]
+        field_ids = [a.object_id() for a in field_atoms]
+
+        body_id, body_atoms = _make_list(field_ids)
+        type_atom = Atom.from_data(data=b"account", next_hash=body_id)
+        top_id, top_atoms = _make_list([type_atom.object_id(), body_id])
+
+        atoms = field_atoms + body_atoms + [type_atom] + top_atoms
+        return top_id, atoms
+
+    @classmethod
+    def create(cls, balance: int, data: bytes, nonce: int) -> "Account":
+        account_hash, atoms = cls._encode(balance, data, nonce)
+        return cls(
+            _balance=int(balance),
+            _data=bytes(data),
+            _nonce=int(nonce),
+            hash=account_hash,
+            atoms=atoms,
+        )
+
+    @classmethod
+    def from_atom(cls, source: Any, account_id: bytes) -> "Account":
+        storage_get = _resolve_storage_get(source)
+
+        outer_list = storage_get(account_id)
+        if outer_list is None or outer_list.data != b"list":
+            raise ValueError("not an account (outer list missing)")
+
+        outer_value = storage_get(outer_list.next)
+        if outer_value is None:
+            raise ValueError("malformed account (outer value missing)")
+
+        entries = _read_list_entries(storage_get, outer_value.next)
+        if len(entries) < 2:
+            raise ValueError("malformed account (type/body missing)")
+
+        type_atom_id, body_id = entries[0], entries[1]
+        type_atom = storage_get(type_atom_id)
+        if type_atom is None or type_atom.data != b"account":
+            raise ValueError("not an account (type mismatch)")
+
+        body_list = storage_get(body_id)
+        if body_list is None or body_list.data != b"list":
+            raise ValueError("malformed account body (type)")
+
+        body_value = storage_get(body_list.next)
+        if body_value is None:
+            raise ValueError("malformed account body (value)")
+
+        field_ids = _read_list_entries(storage_get, body_value.next)
+        if len(field_ids) < 3:
+            field_ids.extend([ZERO32] * (3 - len(field_ids)))
+
+        def _read_field(field_id: bytes) -> bytes:
+            if not field_id or field_id == ZERO32:
+                return b""
+            atom = storage_get(field_id)
+            return atom.data if atom is not None else b""
+
+        balance_bytes = _read_field(field_ids[0])
+        data_bytes = _read_field(field_ids[1])
+        nonce_bytes = _read_field(field_ids[2])
+
+        account = cls.create(
+            balance=_be_bytes_to_int(balance_bytes),
+            data=data_bytes,
+            nonce=_be_bytes_to_int(nonce_bytes),
+        )
+        if account.hash != account_id:
+            raise ValueError("account hash mismatch while decoding")
+        return account
+
+    def balance(self) -> int:
+        return self._balance
+
+    def data(self) -> bytes:
+        return self._data
+
+    def nonce(self) -> int:
+        return self._nonce
+
+    def body_hash(self) -> bytes:
+        return self.hash
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        account_hash, atoms = self._encode(self._balance, self._data, self._nonce)
+        self.hash = account_hash
+        self.atoms = atoms
+        return account_hash, list(atoms)

astreum/_consensus/accounts.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from .._storage.atom import Atom
+from .._storage.patricia import PatriciaTrie
+from .account import Account
+
+
+class Accounts:
+    def __init__(
+        self,
+        root_hash: Optional[bytes] = None,
+    ) -> None:
+        self._trie = PatriciaTrie(root_hash=root_hash)
+        self._cache: Dict[bytes, Account] = {}
+        self._staged: Dict[bytes, Account] = {}
+        self._staged_hashes: Dict[bytes, bytes] = {}
+        self._staged_atoms: Dict[bytes, Iterable[Atom]] = {}
+        self._node: Optional[Any] = None
+
+    @property
+    def root_hash(self) -> Optional[bytes]:
+        return self._trie.root_hash
+
+    def _resolve_node(self, node: Optional[Any]) -> Any:
+        if node is not None:
+            if self._node is None:
+                self._node = node
+            return node
+        if self._node is None:
+            raise ValueError("Accounts requires a node reference for trie access")
+        return self._node
+
+    def get_account(self, address: bytes, *, node: Optional[Any] = None) -> Optional[Account]:
+        if address in self._staged:
+            return self._staged[address]
+
+        cached = self._cache.get(address)
+        if cached is not None:
+            return cached
+
+        storage_node = self._resolve_node(node)
+        account_id: Optional[bytes] = self._trie.get(storage_node, address)
+        if account_id is None:
+            return None
+
+        account = Account.from_atom(storage_node, account_id)
+        self._cache[address] = account
+        return account
+
+    def set_account(self, address: bytes, account: Account) -> None:
+        account_hash, atoms = account.to_atom()
+        self._staged[address] = account
+        self._staged_hashes[address] = account_hash
+        self._staged_atoms[address] = tuple(atoms)
+        self._cache[address] = account
+
+    def staged_items(self) -> Iterable[Tuple[bytes, Account]]:
+        return self._staged.items()
+
+    def staged_hashes(self) -> Dict[bytes, bytes]:
+        return dict(self._staged_hashes)
+
+    def staged_atoms(self) -> Dict[bytes, Iterable[Atom]]:
+        return {addr: tuple(atoms) for addr, atoms in self._staged_atoms.items()}

astreum/_consensus/block.py

@@ -1,5 +1,5 @@
 
-from typing import Callable, List, Optional, Tuple, TYPE_CHECKING
+from typing import Any, Callable, List, Optional, Tuple, TYPE_CHECKING
 
 from .._storage.atom import Atom, ZERO32
 
@@ -181,7 +181,14 @@ class Block:
         return self.hash, atoms_acc
 
     @classmethod
-    def from_atom(cls, storage_get: Callable[[bytes], Optional[Atom]], block_id: bytes) -> "Block":
+    def from_atom(cls, source: Any, block_id: bytes) -> "Block":
+        storage_get: Optional[Callable[[bytes], Optional[Atom]]]
+        if callable(source):
+            storage_get = source
+        else:
+            storage_get = getattr(source, "_local_get", None)
+        if not callable(storage_get):
+            raise TypeError("Block.from_atom requires a node with '_local_get' or a callable storage getter")
         # 1) Expect main list
         main_typ = storage_get(block_id)
         if main_typ is None or main_typ.data != b"list":

astreum/_consensus/chain.py

@@ -1,66 +1,66 @@
 # chain.py
-from typing import Callable, Dict, Optional
-from .block import Block
-from .._storage.atom import ZERO32, Atom
-
-class Chain:
-    def __init__(self, head_block: Block):
-        self.head_block = head_block
-        self.validated_upto_block = None
-        # Root (genesis) hash for this chain; set by validation setup when known
-        self.root: Optional[bytes] = None
-        # Fork position: the head hash of the default/current fork for this chain
-        self.fork_position: Optional[bytes] = getattr(head_block, "hash", None)
-        # Mark the first malicious block encountered during validation; None means not found
-        self.malicious_block_hash: Optional[bytes] = None
-
-    def validate(self, storage_get: Callable[[bytes], Atom]) -> Block:
-        """Validate the chain from head to genesis and return the root block.
-
-        Incorporates per-block validation (signature on body and timestamp
-        monotonicity). Uses a simple cache to avoid duplicate Atom fetches and
-        duplicate block decoding during the backward walk.
-        """
-        # Atom and Block caches for this validation pass
-        atom_cache: Dict[bytes, Optional[Atom]] = {}
-        block_cache: Dict[bytes, Block] = {}
-
-        def get_cached(k: bytes) -> Optional[Atom]:
-            if k in atom_cache:
-                return atom_cache[k]
-            a = storage_get(k)
-            atom_cache[k] = a
-            return a
-
-        def load_block(bid: bytes) -> Block:
-            if bid in block_cache:
-                return block_cache[bid]
-            b = Block.from_atom(get_cached, bid)  # type: ignore[arg-type]
-            block_cache[bid] = b
-            return b
-
-        blk = self.head_block
-        # Ensure head is in cache if it has a hash
-        if getattr(blk, "hash", None):
-            block_cache[blk.hash] = blk  # type: ignore[attr-defined]
-
-        # Walk back, validating each block
-        while True:
-            # Validate current block (signature over body, timestamp rule)
-            try:
-                blk.validate(get_cached)  # may decode previous but uses cached atoms
-            except Exception:
-                # record first failure point then propagate
-                self.malicious_block_hash = getattr(blk, "hash", None)
-                raise
-
-            prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32
-            if prev_hash == ZERO32:
-                break
-            # Move to previous block using cache-aware loader
-            prev_blk = load_block(prev_hash)
-            blk.previous_block = prev_blk  # cache the object for any downstream use
-            blk = prev_blk
-
-        self.validated_upto_block = blk
-        return blk
+from typing import Callable, Dict, Optional
+from .block import Block
+from .._storage.atom import ZERO32, Atom
+
+class Chain:
+    def __init__(self, head_block: Block):
+        self.head_block = head_block
+        self.validated_upto_block = None
+        # Root (genesis) hash for this chain; set by validation setup when known
+        self.root: Optional[bytes] = None
+        # Fork position: the head hash of the default/current fork for this chain
+        self.fork_position: Optional[bytes] = getattr(head_block, "hash", None)
+        # Mark the first malicious block encountered during validation; None means not found
+        self.malicious_block_hash: Optional[bytes] = None
+
+    def validate(self, storage_get: Callable[[bytes], Atom]) -> Block:
+        """Validate the chain from head to genesis and return the root block.
+
+        Incorporates per-block validation (signature on body and timestamp
+        monotonicity). Uses a simple cache to avoid duplicate Atom fetches and
+        duplicate block decoding during the backward walk.
+        """
+        # Atom and Block caches for this validation pass
+        atom_cache: Dict[bytes, Optional[Atom]] = {}
+        block_cache: Dict[bytes, Block] = {}
+
+        def get_cached(k: bytes) -> Optional[Atom]:
+            if k in atom_cache:
+                return atom_cache[k]
+            a = storage_get(k)
+            atom_cache[k] = a
+            return a
+
+        def load_block(bid: bytes) -> Block:
+            if bid in block_cache:
+                return block_cache[bid]
+            b = Block.from_atom(get_cached, bid)
+            block_cache[bid] = b
+            return b
+
+        blk = self.head_block
+        # Ensure head is in cache if it has a hash
+        if getattr(blk, "hash", None):
+            block_cache[blk.hash] = blk  # type: ignore[attr-defined]
+
+        # Walk back, validating each block
+        while True:
+            # Validate current block (signature over body, timestamp rule)
+            try:
+                blk.validate(get_cached)  # may decode previous but uses cached atoms
+            except Exception:
+                # record first failure point then propagate
+                self.malicious_block_hash = getattr(blk, "hash", None)
+                raise
+
+            prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32
+            if prev_hash == ZERO32:
+                break
+            # Move to previous block using cache-aware loader
+            prev_blk = load_block(prev_hash)
+            blk.previous_block = prev_blk  # cache the object for any downstream use
+            blk = prev_blk
+
+        self.validated_upto_block = blk
+        return blk

astreum/_consensus/fork.py

@@ -1,100 +1,100 @@
-from __future__ import annotations
-
+from __future__ import annotations
+
 from typing import Optional, Set, Any, Callable, Dict
-from .block import Block
-from .._storage.atom import ZERO32, Atom
-
-
-class Fork:
-    """A branch head within a Chain (same root).
-
-    - head:       current tip block id (bytes)
-    - peers:      identifiers (e.g., peer pubkey objects) following this head
-    - root:       genesis block id for this chain (optional)
-    - validated_upto: earliest verified ancestor (optional)
-    - chain_fork_position: the chain's fork anchor relevant to this fork
-    """
-
-    def __init__(
-        self,
-        head: bytes,
-    ) -> None:
-        self.head: bytes = head
-        self.peers: Set[Any] = set()
-        self.root: Optional[bytes] = None
-        self.validated_upto: Optional[bytes] = None
-        self.chain_fork_position: Optional[bytes] = None
-        # Mark the first block found malicious during validation; None means not found
-        self.malicious_block_hash: Optional[bytes] = None
-
-    def add_peer(self, peer_id: Any) -> None:
-        self.peers.add(peer_id)
-
-    def remove_peer(self, peer_id: Any) -> None:
-        self.peers.discard(peer_id)
-
-    def validate(
-        self,
-        storage_get: Callable[[bytes], Optional[object]],
-        stop_heads: Optional[Set[bytes]] = None,
-    ) -> bool:
-        """Validate only up to the chain fork position, not genesis.
-
-        Returns True if self.head descends from self.chain_fork_position (or if
-        chain_fork_position is None/equals head), and updates validated_upto to
-        that anchor. If stop_heads is provided, returns True early if ancestry
-        reaches any of those heads, setting validated_upto to the matched head.
-        Returns False if ancestry cannot be confirmed.
-        """
-        if self.chain_fork_position is None or self.chain_fork_position == self.head:
-            self.validated_upto = self.head
-            return True
-        # Caches to avoid double fetching/decoding
-        atom_cache: Dict[bytes, Optional[Atom]] = {}
-        block_cache: Dict[bytes, Block] = {}
-
-        def get_cached(k: bytes) -> Optional[Atom]:
-            if k in atom_cache:
-                return atom_cache[k]
-            a = storage_get(k)  # type: ignore[call-arg]
-            atom_cache[k] = a  # may be None if missing
-            return a
-
-        def load_block(bid: bytes) -> Optional[Block]:
-            if bid in block_cache:
-                return block_cache[bid]
-            try:
-                b = Block.from_atom(get_cached, bid)  # type: ignore[arg-type]
-            except Exception:
-                return None
-            block_cache[bid] = b
-            return b
-
-        blk = load_block(self.head)
-        if blk is None:
-            # Missing head data: unverifiable, not malicious
-            return False
-        # Walk up to fork anchor, validating each block signature + timestamp
-        while True:
-            try:
-                blk.validate(get_cached)  # type: ignore[arg-type]
-            except Exception:
-                # mark the first failure point
-                self.malicious_block_hash = blk.hash
-                return False
-
-            # Early-exit if we met another known fork head
-            if stop_heads and blk.hash in stop_heads:
-                self.validated_upto = blk.hash
-                return True
-
-            if blk.hash == self.chain_fork_position:
-                self.validated_upto = blk.hash
-                return True
-            
-            prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32
-            nxt = load_block(prev_hash)
-            if nxt is None:
-                return False
-            blk.previous_block = nxt  # cache for future use
-            blk = nxt
+from .block import Block
+from .._storage.atom import ZERO32, Atom
+
+
+class Fork:
+    """A branch head within a Chain (same root).
+
+    - head:       current tip block id (bytes)
+    - peers:      identifiers (e.g., peer pubkey objects) following this head
+    - root:       genesis block id for this chain (optional)
+    - validated_upto: earliest verified ancestor (optional)
+    - chain_fork_position: the chain's fork anchor relevant to this fork
+    """
+
+    def __init__(
+        self,
+        head: bytes,
+    ) -> None:
+        self.head: bytes = head
+        self.peers: Set[Any] = set()
+        self.root: Optional[bytes] = None
+        self.validated_upto: Optional[bytes] = None
+        self.chain_fork_position: Optional[bytes] = None
+        # Mark the first block found malicious during validation; None means not found
+        self.malicious_block_hash: Optional[bytes] = None
+
+    def add_peer(self, peer_id: Any) -> None:
+        self.peers.add(peer_id)
+
+    def remove_peer(self, peer_id: Any) -> None:
+        self.peers.discard(peer_id)
+
+    def validate(
+        self,
+        storage_get: Callable[[bytes], Optional[object]],
+        stop_heads: Optional[Set[bytes]] = None,
+    ) -> bool:
+        """Validate only up to the chain fork position, not genesis.
+
+        Returns True if self.head descends from self.chain_fork_position (or if
+        chain_fork_position is None/equals head), and updates validated_upto to
+        that anchor. If stop_heads is provided, returns True early if ancestry
+        reaches any of those heads, setting validated_upto to the matched head.
+        Returns False if ancestry cannot be confirmed.
+        """
+        if self.chain_fork_position is None or self.chain_fork_position == self.head:
+            self.validated_upto = self.head
+            return True
+        # Caches to avoid double fetching/decoding
+        atom_cache: Dict[bytes, Optional[Atom]] = {}
+        block_cache: Dict[bytes, Block] = {}
+
+        def get_cached(k: bytes) -> Optional[Atom]:
+            if k in atom_cache:
+                return atom_cache[k]
+            a = storage_get(k)  # type: ignore[call-arg]
+            atom_cache[k] = a  # may be None if missing
+            return a
+
+        def load_block(bid: bytes) -> Optional[Block]:
+            if bid in block_cache:
+                return block_cache[bid]
+            try:
+                b = Block.from_atom(get_cached, bid)
+            except Exception:
+                return None
+            block_cache[bid] = b
+            return b
+
+        blk = load_block(self.head)
+        if blk is None:
+            # Missing head data: unverifiable, not malicious
+            return False
+        # Walk up to fork anchor, validating each block signature + timestamp
+        while True:
+            try:
+                blk.validate(get_cached)  # type: ignore[arg-type]
+            except Exception:
+                # mark the first failure point
+                self.malicious_block_hash = blk.hash
+                return False
+
+            # Early-exit if we met another known fork head
+            if stop_heads and blk.hash in stop_heads:
+                self.validated_upto = blk.hash
+                return True
+
+            if blk.hash == self.chain_fork_position:
+                self.validated_upto = blk.hash
+                return True
+            
+            prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32
+            nxt = load_block(prev_hash)
+            if nxt is None:
+                return False
+            blk.previous_block = nxt  # cache for future use
+            blk = nxt