astreum 0.2.40__py3-none-any.whl → 0.2.42__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,95 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional, Tuple
+
+from .._storage.atom import Atom, ZERO32
+from .._storage.patricia import PatriciaTrie
+from ..utils.integer import bytes_to_int, int_to_bytes
+
+
+@dataclass
+class Account:
+    balance: int
+    code: bytes
+    counter: int
+    data_hash: bytes
+    data: PatriciaTrie
+    hash: bytes = ZERO32
+    body_hash: bytes = ZERO32
+    atoms: List[Atom] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, balance: int = 0, data_hash: bytes = ZERO32, code: bytes = ZERO32, counter: int = 0) -> "Account":
+        account = cls(
+            balance=int(balance),
+            code=bytes(code),
+            counter=int(counter),
+            data_hash=bytes(data_hash),
+            data=PatriciaTrie(root_hash=bytes(data_hash)),
+        )
+        account.to_atom()
+        return account
+
+    @classmethod
+    def from_atom(cls, node: Any, account_id: bytes) -> "Account":
+        storage_get = node._local_get
+
+        type_atom = storage_get(account_id)
+        if type_atom is None or type_atom.data != b"account":
+            raise ValueError("not an account (type mismatch)")
+
+        def _read_atom(atom_id: Optional[bytes]) -> Optional[Atom]:
+            if not atom_id or atom_id == ZERO32:
+                return None
+            return storage_get(atom_id)
+
+        balance_atom = _read_atom(type_atom.next)
+        if balance_atom is None:
+            raise ValueError("malformed account (balance missing)")
+
+        code_atom = _read_atom(balance_atom.next)
+        if code_atom is None:
+            raise ValueError("malformed account (code missing)")
+
+        counter_atom = _read_atom(code_atom.next)
+        if counter_atom is None:
+            raise ValueError("malformed account (counter missing)")
+
+        data_atom = _read_atom(counter_atom.next)
+        if data_atom is None:
+            raise ValueError("malformed account (data missing)")
+
+        account = cls.create(
+            balance=bytes_to_int(balance_atom.data),
+            data_hash=data_atom.data,
+            counter=bytes_to_int(counter_atom.data),
+            code=code_atom.data,
+        )
+        if account.hash != account_id:
+            raise ValueError("account hash mismatch while decoding")
+        return account
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        # Build a single forward chain: account -> balance -> code -> counter -> data.
+        data_atom = Atom.from_data(data=bytes(self.data_hash))
+        counter_atom = Atom.from_data(
+            data=int_to_bytes(self.counter),
+            next_hash=data_atom.object_id(),
+        )
+        code_atom = Atom.from_data(
+            data=bytes(self.code),
+            next_hash=counter_atom.object_id(),
+        )
+        balance_atom = Atom.from_data(
+            data=int_to_bytes(self.balance),
+            next_hash=code_atom.object_id(),
+        )
+        type_atom = Atom.from_data(data=b"account", next_hash=balance_atom.object_id())
+
+        atoms = [data_atom, counter_atom, code_atom, balance_atom, type_atom]
+        account_hash = type_atom.object_id()
+        self.hash = account_hash
+        self.body_hash = account_hash
+        self.atoms = atoms
+        return account_hash, list(atoms)

astreum/_consensus/accounts.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+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] = {}
+
+    @property
+    def root_hash(self) -> Optional[bytes]:
+        return self._trie.root_hash
+
+    def get_account(self, address: bytes, node: Optional[Any] = None) -> Optional[Account]:
+        cached = self._cache.get(address)
+        if cached is not None:
+            return cached
+
+        if node is None:
+            raise ValueError("Accounts requires a node reference for trie access")
+
+        account_id: Optional[bytes] = self._trie.get(node, address)
+        if account_id is None:
+            return None
+
+        account = Account.from_atom(node, account_id)
+        self._cache[address] = account
+        return account
+
+    def set_account(self, address: bytes, account: Account) -> None:
+        self._cache[address] = account

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

astreum/_consensus/genesis.py

@@ -0,0 +1,141 @@
+
+from __future__ import annotations
+
+from typing import Any, Iterable, List, Optional, Tuple
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .account import Account
+from .block import Block
+from .._storage.atom import Atom, ZERO32
+from .._storage.patricia import PatriciaTrie, PatriciaNode
+
+TREASURY_ADDRESS = b"\x01" * 32
+BURN_ADDRESS = b"\x00" * 32
+
+
+def _int_to_be_bytes(value: int) -> bytes:
+    if value < 0:
+        raise ValueError("integer fields in genesis must be non-negative")
+    if value == 0:
+        return b"\x00"
+    length = (value.bit_length() + 7) // 8
+    return value.to_bytes(length, "big")
+
+
+def _make_list(child_ids: List[bytes]) -> Tuple[bytes, List[Atom]]:
+    next_hash = ZERO32
+    chain: 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()
+        chain.append(elem)
+    chain.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 = chain + [value_atom, type_atom]
+    return type_atom.object_id(), atoms
+
+
+def _store_atoms(node: Any, atoms: Iterable[Atom]) -> None:
+    setter = getattr(node, "_local_set", None)
+    if not callable(setter):
+        raise TypeError("node must expose '_local_set(object_id, atom)'")
+    for atom in atoms:
+        setter(atom.object_id(), atom)
+
+
+def _persist_trie(trie: PatriciaTrie, node: Any) -> None:
+    for patricia_node in trie.nodes.values():
+        _, atoms = patricia_node.to_atoms()
+        _store_atoms(node, atoms)
+
+
+if not hasattr(PatriciaNode, "to_bytes"):
+    def _patricia_node_to_bytes(self: PatriciaNode) -> bytes:  # type: ignore[no-redef]
+        fields = [
+            bytes([self.key_len]) + self.key,
+            self.child_0 or ZERO32,
+            self.child_1 or ZERO32,
+            self.value or b"",
+        ]
+        encoded: List[bytes] = []
+        for field in fields:
+            encoded.append(len(field).to_bytes(4, "big"))
+            encoded.append(field)
+        return b"".join(encoded)
+
+    PatriciaNode.to_bytes = _patricia_node_to_bytes  # type: ignore[attr-defined]
+
+
+def create_genesis_block(node: Any, validator_public_key: bytes, validator_secret_key: bytes) -> Block:
+    validator_pk = bytes(validator_public_key)
+
+    if len(validator_pk) != 32:
+        raise ValueError("validator_public_key must be 32 bytes")
+
+    # 1. Stake trie with single validator stake of 1 (encoded on 32 bytes).
+    stake_trie = PatriciaTrie()
+    stake_amount = (1).to_bytes(32, "big")
+    stake_trie.put(node, validator_pk, stake_amount)
+    _persist_trie(stake_trie, node)
+    stake_root = stake_trie.root_hash or ZERO32
+
+    # 2. Account trie with treasury, burn, and validator accounts.
+    accounts_trie = PatriciaTrie()
+
+    treasury_account = Account.create(balance=1, data=stake_root, counter=0)
+    treasury_account_id, treasury_atoms = treasury_account.to_atom()
+    _store_atoms(node, treasury_atoms)
+    accounts_trie.put(node, TREASURY_ADDRESS, treasury_account_id)
+
+    burn_account = Account.create(balance=0, data=b"", counter=0)
+    burn_account_id, burn_atoms = burn_account.to_atom()
+    _store_atoms(node, burn_atoms)
+    accounts_trie.put(node, BURN_ADDRESS, burn_account_id)
+
+    validator_account = Account.create(balance=0, data=b"", counter=0)
+    validator_account_id, validator_atoms = validator_account.to_atom()
+    _store_atoms(node, validator_atoms)
+    accounts_trie.put(node, validator_pk, validator_account_id)
+
+    _persist_trie(accounts_trie, node)
+
+    accounts_root = accounts_trie.root_hash
+    if accounts_root is None:
+        raise ValueError("genesis accounts trie is empty")
+
+    # 3. Assemble block metadata.
+    block = Block()
+    block.previous_block_hash = ZERO32
+    block.number = 0
+    block.timestamp = 0
+    block.accounts_hash = accounts_root
+    block.accounts = accounts_trie
+    block.transactions_total_fees = 0
+    block.transactions_hash = ZERO32
+    block.receipts_hash = ZERO32
+    block.delay_difficulty = 0
+    block.delay_output = b""
+    block.validator_public_key = validator_pk
+    block.transactions = []
+    block.receipts = []
+
+    # 4. Sign the block body with the validator secret key.
+    block.signature = b""
+    block.to_atom()
+
+    if block.body_hash is None:
+        raise ValueError("failed to materialise genesis block body")
+
+    secret = Ed25519PrivateKey.from_private_bytes(validator_secret_key)
+    block.signature = secret.sign(block.body_hash)
+    block_hash, block_atoms = block.to_atom()
+    _store_atoms(node, block_atoms)
+
+    block.hash = block_hash
+    return block

astreum/_consensus/receipt.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Callable, List, Optional, Tuple
 
 from .._storage.atom import Atom, ZERO32
@@ -77,6 +77,8 @@ class Receipt:
     cost: int = 0
     logs: bytes = b""
     status: int = 0
+    hash: bytes = ZERO32
+    atoms: List[Atom] = field(default_factory=list)
 
     def to_atom(self) -> Tuple[bytes, List[Atom]]:
         """Serialise the receipt into Atom storage."""
@@ -109,6 +111,13 @@ class Receipt:
 
         return top_list_id, atoms
 
+    def atomize(self) -> Tuple[bytes, List[Atom]]:
+        """Generate atoms for this receipt and cache them."""
+        receipt_id, atoms = self.to_atom()
+        self.hash = receipt_id
+        self.atoms = atoms
+        return receipt_id, atoms
+
     @classmethod
     def from_atom(
         cls,
@@ -164,4 +173,5 @@ class Receipt:
             cost=_be_bytes_to_int(cost_bytes),
             logs=logs_bytes,
             status=status_value,
+            hash=bytes(receipt_id),
         )