astreum 0.2.61__py3-none-any.whl → 0.3.9__py3-none-any.whl

astreum/consensus/models/account.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Tuple
+
+from ...storage.models.atom import Atom, ZERO32, AtomKind
+from ...storage.models.trie import Trie
+from ...utils.integer import bytes_to_int, int_to_bytes
+
+
+@dataclass
+class Account:
+    balance: int
+    code_hash: bytes
+    counter: int
+    data_hash: bytes
+    data: Trie
+    atom_hash: bytes = ZERO32
+    atoms: List[Atom] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, balance: int = 0, data_hash: bytes = ZERO32, code_hash: bytes = ZERO32, counter: int = 0) -> "Account":
+        account = cls(
+            balance=int(balance),
+            code_hash=bytes(code_hash),
+            counter=int(counter),
+            data_hash=bytes(data_hash),
+            data=Trie(root_hash=bytes(data_hash)),
+        )
+        atom_hash, atoms = account.to_atom()
+        account.atom_hash = atom_hash
+        account.atoms = atoms
+        return account
+
+    @classmethod
+    def from_atom(cls, node: Any, root_id: bytes) -> "Account":
+
+        account_atoms = node.get_atom_list_from_storage(root_hash=root_id)
+
+        if account_atoms is None or len(account_atoms) != 5:
+            raise ValueError("malformed account atom list")
+
+        type_atom, balance_atom, code_atom, counter_atom, data_atom = account_atoms
+        
+        if type_atom.data != b"account":
+            raise ValueError("not an account (type mismatch)")
+
+        account = cls.create(
+            balance=bytes_to_int(balance_atom.data),
+            data_hash=data_atom.data,
+            counter=bytes_to_int(counter_atom.data),
+            code_hash=code_atom.data,
+        )
+
+        return account
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        data_atom = Atom(
+            data=bytes(self.data_hash),
+            kind=AtomKind.LIST,
+        )
+        counter_atom = Atom(
+            data=int_to_bytes(self.counter),
+            next_id=data_atom.object_id(),
+            kind=AtomKind.BYTES,
+        )
+        code_atom = Atom(
+            data=bytes(self.code_hash),
+            next_id=counter_atom.object_id(),
+            kind=AtomKind.LIST,
+        )
+        balance_atom = Atom(
+            data=int_to_bytes(self.balance),
+            next_id=code_atom.object_id(),
+            kind=AtomKind.BYTES,
+        )
+        type_atom = Atom(
+            data=b"account",
+            next_id=balance_atom.object_id(),
+            kind=AtomKind.SYMBOL,
+        )
+
+        atoms = [data_atom, counter_atom, code_atom, balance_atom, type_atom]
+        return type_atom.object_id(), list(atoms)

astreum/consensus/models/accounts.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ...storage.models.atom import Atom, ZERO32
+from ...storage.models.trie import Trie
+from .account import Account
+
+
+class Accounts:
+    def __init__(
+        self,
+        root_hash: Optional[bytes] = None,
+    ) -> None:
+        self._trie = Trie(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
+
+    def update_trie(self, node: Any) -> List[Atom]:
+        """
+        Serialise cached accounts, ensure their associated data tries are materialised,
+        and return all atoms that must be stored (data tries, account records, and the
+        accounts trie nodes themselves).
+        """
+
+        def _node_atoms(trie: Trie) -> List[Atom]:
+            emitted: List[Atom] = []
+            if not trie.nodes:
+                return emitted
+            for node_hash in sorted(trie.nodes.keys()):
+                trie_node = trie.nodes[node_hash]
+                head_hash, atoms = trie_node.to_atoms()
+                if head_hash != node_hash:
+                    continue
+                emitted.extend(atoms)
+            return emitted
+
+        data_atoms: List[Atom] = []
+        account_atoms: List[Atom] = []
+
+        for address, account in self._cache.items():
+            account.data_hash = account.data.root_hash or ZERO32
+            data_atoms.extend(_node_atoms(account.data))
+
+            account_id, atoms = account.to_atom()
+            self._trie.put(node, address, account_id)
+            account_atoms.extend(atoms)
+
+        trie_atoms = _node_atoms(self._trie)
+        return data_atoms + account_atoms + trie_atoms

astreum/consensus/models/block.py

@@ -0,0 +1,364 @@
+
+from typing import Any, Callable, List, Optional, Tuple, TYPE_CHECKING
+
+from ...storage.models.atom import Atom, AtomKind, ZERO32, hash_bytes
+
+if TYPE_CHECKING:
+    from ...storage.models.trie import Trie
+    from .transaction import Transaction
+    from .receipt import Receipt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.exceptions import InvalidSignature
+
+
+def _int_to_be_bytes(n: Optional[int]) -> bytes:
+    if n is None:
+        return b""
+    n = int(n)
+    if n == 0:
+        return b"\x00"
+    size = (n.bit_length() + 7) // 8
+    return n.to_bytes(size, "big")
+
+
+def _be_bytes_to_int(b: Optional[bytes]) -> int:
+    if not b:
+        return 0
+    return int.from_bytes(b, "big")
+
+
+class Block:
+    """Validation Block representation using Atom storage.
+
+    Top-level encoding:
+      block_id = type_atom.object_id()
+      chain: type_atom --next--> signature_atom --next--> body_list_atom --next--> ZERO32
+      where: type_atom        = Atom(kind=AtomKind.SYMBOL, data=b"block")
+             signature_atom   = Atom(kind=AtomKind.BYTES, data=<signature-bytes>)
+             body_list_atom   = Atom(kind=AtomKind.LIST,  data=<body_head_id>)
+
+    Details order in body_list:
+      0: chain                               (byte)
+      1: previous_block_hash                 (bytes)
+      2: number                              (int -> big-endian bytes)
+      3: timestamp                           (int -> big-endian bytes)
+      4: accounts_hash                       (bytes)
+      5: transactions_total_fees             (int -> big-endian bytes)
+      6: transactions_hash                   (bytes)
+      7: receipts_hash                       (bytes)
+      8: delay_difficulty                    (int -> big-endian bytes)
+      9: validator_public_key               (bytes)
+      10: nonce                              (int -> big-endian bytes)
+
+    Notes:
+      - "body tree" is represented here by the body_list id (self.body_hash), not
+        embedded again as a field to avoid circular references.
+      - "signature" is a field on the class but is not required for validation
+        navigation; include it in the instance but it is not encoded in atoms
+        unless explicitly provided via details extension in the future.
+    """
+
+    # essential identifiers
+    atom_hash: Optional[bytes]
+    chain_id: int
+    previous_block_hash: bytes
+    previous_block: Optional["Block"]
+
+    # block details
+    number: int
+    timestamp: Optional[int]
+    accounts_hash: Optional[bytes]
+    transactions_total_fees: Optional[int]
+    transactions_hash: Optional[bytes]
+    receipts_hash: Optional[bytes]
+    delay_difficulty: Optional[int]
+    validator_public_key: Optional[bytes]
+    nonce: Optional[int]
+
+    # additional
+    body_hash: Optional[bytes]
+    signature: Optional[bytes]
+
+    # structures
+    accounts: Optional["Trie"]
+    transactions: Optional[List["Transaction"]]
+    receipts: Optional[List["Receipt"]]
+    
+    def __init__(
+        self,
+        *,
+        chain_id: int,
+        previous_block_hash: bytes,
+        previous_block: Optional["Block"],
+        number: int,
+        timestamp: Optional[int],
+        accounts_hash: Optional[bytes],
+        transactions_total_fees: Optional[int],
+        transactions_hash: Optional[bytes],
+        receipts_hash: Optional[bytes],
+        delay_difficulty: Optional[int],
+        validator_public_key: Optional[bytes],
+        nonce: Optional[int] = None,
+        signature: Optional[bytes] = None,
+        atom_hash: Optional[bytes] = None,
+        body_hash: Optional[bytes] = None,
+        accounts: Optional["Trie"] = None,
+        transactions: Optional[List["Transaction"]] = None,
+        receipts: Optional[List["Receipt"]] = None,
+    ) -> None:
+        self.atom_hash = atom_hash
+        self.chain_id = chain_id
+        self.previous_block_hash = previous_block_hash
+        self.previous_block = previous_block
+        self.number = number
+        self.timestamp = timestamp
+        self.accounts_hash = accounts_hash
+        self.transactions_total_fees = transactions_total_fees
+        self.transactions_hash = transactions_hash
+        self.receipts_hash = receipts_hash
+        self.delay_difficulty = delay_difficulty
+        self.validator_public_key = validator_public_key
+        self.nonce = nonce
+        self.body_hash = body_hash
+        self.signature = signature
+        self.accounts = accounts
+        self.transactions = transactions
+        self.receipts = receipts
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        # Build body details as direct byte atoms, in defined order
+        detail_payloads: List[bytes] = []
+        block_atoms: List[Atom] = []
+
+        def _emit(detail_bytes: bytes) -> None:
+            detail_payloads.append(detail_bytes)
+
+        # 0: chain
+        _emit(_int_to_be_bytes(self.chain_id))
+        # 1: previous_block_hash
+        _emit(self.previous_block_hash)
+        # 2: number
+        _emit(_int_to_be_bytes(self.number))
+        # 3: timestamp
+        _emit(_int_to_be_bytes(self.timestamp))
+        # 4: accounts_hash
+        _emit(self.accounts_hash or b"")
+        # 5: transactions_total_fees
+        _emit(_int_to_be_bytes(self.transactions_total_fees))
+        # 6: transactions_hash
+        _emit(self.transactions_hash or b"")
+        # 7: receipts_hash
+        _emit(self.receipts_hash or b"")
+        # 8: delay_difficulty
+        _emit(_int_to_be_bytes(self.delay_difficulty))
+        # 9: validator_public_key
+        _emit(self.validator_public_key or b"")
+        # 10: nonce
+        _emit(_int_to_be_bytes(self.nonce))
+
+        # Build body list chain directly from detail atoms
+        body_head = ZERO32
+        detail_atoms: List[Atom] = []
+        for payload in reversed(detail_payloads):
+            atom = Atom(data=payload, next_id=body_head, kind=AtomKind.BYTES)
+            detail_atoms.append(atom)
+            body_head = atom.object_id()
+        detail_atoms.reverse()
+
+        block_atoms.extend(detail_atoms)
+
+        body_list_atom = Atom(data=body_head, kind=AtomKind.LIST)
+        self.body_hash = body_list_atom.object_id()
+
+        # Signature atom links to body list atom; type atom links to signature atom
+        sig_atom = Atom(
+            data=bytes(self.signature or b""),
+            next_id=self.body_hash,
+            kind=AtomKind.BYTES,
+        )
+        type_atom = Atom(data=b"block", next_id=sig_atom.object_id(), kind=AtomKind.SYMBOL)
+
+        block_atoms.append(body_list_atom)
+        block_atoms.append(sig_atom)
+        block_atoms.append(type_atom)
+
+        self.atom_hash = type_atom.object_id()
+        return self.atom_hash, block_atoms
+
+    @classmethod
+    def from_atom(cls, node: Any, block_id: bytes) -> "Block":
+
+        block_header = node.get_atom_list_from_storage(block_id)
+        if block_header is None or len(block_header) != 3:
+            raise ValueError("malformed block atom chain")
+        type_atom, sig_atom, body_list_atom = block_header
+
+        if type_atom.kind is not AtomKind.SYMBOL or type_atom.data != b"block":
+            raise ValueError("not a block (type atom payload)")
+        if sig_atom.kind is not AtomKind.BYTES:
+            raise ValueError("malformed block (signature atom kind)")
+        if body_list_atom.kind is not AtomKind.LIST:
+            raise ValueError("malformed block (body list atom kind)")
+        if body_list_atom.next_id != ZERO32:
+            raise ValueError("malformed block (body list tail)")
+
+        detail_atoms = node.get_atom_list_from_storage(body_list_atom.data)
+        if detail_atoms is None:
+            raise ValueError("missing block body list nodes")
+
+        if len(detail_atoms) != 11:
+            raise ValueError("block body must contain exactly 11 detail entries")
+
+        detail_values: List[bytes] = []
+        for detail_atom in detail_atoms:
+            if detail_atom.kind is not AtomKind.BYTES:
+                raise ValueError("block body detail atoms must be bytes")
+            detail_values.append(detail_atom.data)
+
+        (
+            chain_bytes,
+            prev_bytes,
+            number_bytes,
+            timestamp_bytes,
+            accounts_bytes,
+            fees_bytes,
+            transactions_bytes,
+            receipts_bytes,
+            delay_diff_bytes,
+            validator_bytes,
+            nonce_bytes,
+        ) = detail_values
+
+        return cls(
+            chain_id=_be_bytes_to_int(chain_bytes),
+            previous_block_hash=prev_bytes or ZERO32,
+            previous_block=None,
+            number=_be_bytes_to_int(number_bytes),
+            timestamp=_be_bytes_to_int(timestamp_bytes),
+            accounts_hash=accounts_bytes or None,
+            transactions_total_fees=_be_bytes_to_int(fees_bytes),
+            transactions_hash=transactions_bytes or None,
+            receipts_hash=receipts_bytes or None,
+            delay_difficulty=_be_bytes_to_int(delay_diff_bytes),
+            validator_public_key=validator_bytes or None,
+            nonce=_be_bytes_to_int(nonce_bytes),
+            signature=sig_atom.data if sig_atom is not None else None,
+            atom_hash=block_id,
+            body_hash=body_list_atom.object_id(),
+        )
+
+    def validate(self, storage_get: Callable[[bytes], Optional[Atom]]) -> bool:
+        """Validate this block against storage.
+
+        Checks:
+        - Signature: signature must verify over the body list id using the
+          validator's public key.
+        - Timestamp monotonicity: if previous block exists (not ZERO32), this
+          block's timestamp must be >= previous.timestamp + 1.
+        """
+        # Unverifiable if critical fields are missing
+        if not self.body_hash:
+            return False
+        if not self.signature:
+            return False
+        if not self.validator_public_key:
+            return False
+        if self.timestamp is None:
+            return False
+
+        # 1) Signature check over body hash
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(bytes(self.validator_public_key))
+            pub.verify(self.signature, self.body_hash)
+        except InvalidSignature as e:
+            raise ValueError("invalid signature") from e
+
+        # 2) Timestamp monotonicity against previous block
+        prev_ts: Optional[int] = None
+        prev_hash = self.previous_block_hash or ZERO32
+
+        if self.previous_block is not None:
+            prev_ts = int(self.previous_block.timestamp or 0)
+            prev_hash = self.previous_block.atom_hash or prev_hash or ZERO32
+
+        if prev_hash and prev_hash != ZERO32 and prev_ts is None:
+            # If previous block cannot be loaded, treat as unverifiable, not malicious
+            try:
+                prev = Block.from_atom(storage_get, prev_hash)
+            except Exception:
+                return False
+            prev_ts = int(prev.timestamp or 0)
+
+        if prev_hash and prev_hash != ZERO32:
+            if prev_ts is None:
+                return False
+            cur_ts = int(self.timestamp or 0)
+            if cur_ts < prev_ts + 1:
+                raise ValueError("timestamp must be at least prev+1")
+
+        return True
+
+    @staticmethod
+    def _leading_zero_bits(buf: bytes) -> int:
+        """Return the number of leading zero bits in the provided buffer."""
+        zeros = 0
+        for byte in buf:
+            if byte == 0:
+                zeros += 8
+                continue
+            zeros += 8 - int(byte).bit_length()
+            break
+        return zeros
+
+    @staticmethod
+    def calculate_delay_difficulty(
+        *,
+        previous_timestamp: Optional[int],
+        current_timestamp: Optional[int],
+        previous_difficulty: Optional[int],
+        target_spacing: int = 2,
+    ) -> int:
+        """
+        Adjust the delay difficulty based on how quickly the previous block was produced.
+
+        The previous block difficulty is increased if the spacing is below the target,
+        decreased if above, and returned unchanged when the target spacing is met.
+        """
+        base_difficulty = max(1, int(previous_difficulty or 1))
+        if previous_timestamp is None or current_timestamp is None:
+            return base_difficulty
+
+        spacing = max(0, int(current_timestamp) - int(previous_timestamp))
+        if spacing <= 1:
+            adjusted = base_difficulty * 1.618
+        elif spacing == target_spacing:
+            adjusted = float(base_difficulty)
+        elif spacing > target_spacing:
+            adjusted = base_difficulty * 0.618
+        else:
+            adjusted = float(base_difficulty)
+
+        return max(1, int(round(adjusted)))
+
+    def generate_nonce(
+        self,
+        *,
+        difficulty: int,
+    ) -> int:
+        """
+        Find a nonce that yields a block hash with the required leading zero bits.
+
+        The search starts from the current nonce and iterates until the target
+        difficulty is met.
+        """
+        target = max(1, int(difficulty))
+        start = int(self.nonce or 0)
+        nonce = start
+        while True:
+            self.nonce = nonce
+            block_hash, _ = self.to_atom()
+            leading_zeros = self._leading_zero_bits(block_hash)
+            if leading_zeros >= target:
+                self.atom_hash = block_hash
+                return nonce
+            nonce += 1

astreum/{_consensus → consensus/models}/chain.py

@@ -1,7 +1,7 @@
-# chain.py
+# chain.py
 from typing import Callable, Dict, Optional
 from .block import Block
-from .._storage.atom import ZERO32, Atom
+from ...storage.models.atom import ZERO32, Atom
 
 class Chain:
     def __init__(self, head_block: Block):
@@ -10,7 +10,7 @@ class Chain:
         # 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)
+        self.fork_position: Optional[bytes] = getattr(head_block, "atom_hash", None)
         # Mark the first malicious block encountered during validation; None means not found
         self.malicious_block_hash: Optional[bytes] = None
 
@@ -35,14 +35,14 @@ class Chain:
         def load_block(bid: bytes) -> Block:
             if bid in block_cache:
                 return block_cache[bid]
-            b = Block.from_atom(get_cached, 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]
+        if getattr(blk, "atom_hash", None):
+            block_cache[blk.atom_hash] = blk  # type: ignore[attr-defined]
 
         # Walk back, validating each block
         while True:
@@ -51,7 +51,7 @@ class Chain:
                 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)
+                self.malicious_block_hash = getattr(blk, "atom_hash", None)
                 raise
 
             prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32

astreum/{_consensus → consensus/models}/fork.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from typing import Optional, Set, Any, Callable, Dict
+from typing import Optional, Set, Any, Callable, Dict
 from .block import Block
-from .._storage.atom import ZERO32, Atom
+from ...storage.models.atom import ZERO32, Atom
 
 
 class Fork:
@@ -64,7 +64,7 @@ class Fork:
             if bid in block_cache:
                 return block_cache[bid]
             try:
-                b = Block.from_atom(get_cached, bid)
+                b = Block.from_atom(get_cached, bid)
             except Exception:
                 return None
             block_cache[bid] = b
@@ -80,16 +80,16 @@ class Fork:
                 blk.validate(get_cached)  # type: ignore[arg-type]
             except Exception:
                 # mark the first failure point
-                self.malicious_block_hash = blk.hash
+                self.malicious_block_hash = blk.atom_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
+            if stop_heads and blk.atom_hash in stop_heads:
+                self.validated_upto = blk.atom_hash
                 return True
 
-            if blk.hash == self.chain_fork_position:
-                self.validated_upto = blk.hash
+            if blk.atom_hash == self.chain_fork_position:
+                self.validated_upto = blk.atom_hash
                 return True
             
             prev_hash = blk.previous_block_hash if hasattr(blk, "previous_block_hash") else ZERO32