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

astreum/_communication/util.py

@@ -0,0 +1,42 @@
+from typing import Tuple
+
+
+def address_str_to_host_and_port(address: str) -> Tuple[str, int]:
+    """Parse `host:port` (or `[ipv6]:port`) into a tuple."""
+    addr = address.strip()
+    if not addr:
+        raise ValueError("address cannot be empty")
+
+    host: str
+    port_str: str
+
+    if addr.startswith('['):
+        end = addr.find(']')
+        if end == -1:
+            raise ValueError("missing closing ']' in IPv6 address")
+        host = addr[1:end]
+        remainder = addr[end + 1 :]
+        if not remainder.startswith(':'):
+            raise ValueError("missing port separator after IPv6 address")
+        port_str = remainder[1:]
+    else:
+        if ':' not in addr:
+            raise ValueError("address must contain ':' separating host and port")
+        host, port_str = addr.rsplit(':', 1)
+
+    host = host.strip()
+    if not host:
+        raise ValueError("host cannot be empty")
+    port_str = port_str.strip()
+    if not port_str:
+        raise ValueError("port cannot be empty")
+
+    try:
+        port = int(port_str, 10)
+    except ValueError as exc:
+        raise ValueError(f"invalid port number: {port_str}") from exc
+
+    if not (0 < port < 65536):
+        raise ValueError(f"port out of range: {port}")
+
+    return host, port

astreum/_consensus/__init__.py

@@ -0,0 +1,20 @@
+from .account import Account
+from .accounts import Accounts
+from .block import Block
+from .chain import Chain
+from .fork import Fork
+from .receipt import Receipt
+from .transaction import Transaction
+from .setup import consensus_setup
+
+
+__all__ = [
+    "Block",
+    "Chain",
+    "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.storage_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

@@ -0,0 +1,311 @@
+
+from typing import Any, Callable, List, Optional, Tuple, TYPE_CHECKING
+
+from .._storage.atom import Atom, AtomKind, ZERO32
+
+if TYPE_CHECKING:
+    from .._storage.patricia import PatriciaTrie
+    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: previous_block_hash                 (bytes)
+      1: number                              (int -> big-endian bytes)
+      2: timestamp                           (int -> big-endian bytes)
+      3: accounts_hash                       (bytes)
+      4: transactions_total_fees             (int -> big-endian bytes)
+      5: transactions_hash                   (bytes)
+      6: receipts_hash                       (bytes)
+      7: delay_difficulty                    (int -> big-endian bytes)
+      8: delay_output                        (bytes)
+      9: validator_public_key                (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
+    hash: bytes
+    previous_block_hash: bytes
+    previous_block: Optional["Block"]
+
+    # block details
+    number: Optional[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]
+    delay_output: Optional[bytes]
+    validator_public_key: Optional[bytes]
+
+    # additional
+    body_hash: Optional[bytes]
+    signature: Optional[bytes]
+
+    # structures
+    accounts: Optional["PatriciaTrie"]
+    transactions: Optional[List["Transaction"]]
+    receipts: Optional[List["Receipt"]]
+    
+    
+
+    def __init__(self) -> None:
+        # defaults for safety
+        self.hash = b""
+        self.previous_block_hash = ZERO32
+        self.previous_block = None
+        self.number = None
+        self.timestamp = None
+        self.accounts_hash = None
+        self.transactions_total_fees = None
+        self.transactions_hash = None
+        self.receipts_hash = None
+        self.delay_difficulty = None
+        self.delay_output = None
+        self.validator_public_key = None
+        self.body_hash = None
+        self.signature = None
+        self.accounts = None
+        self.transactions = None
+        self.receipts = None
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        # Build body details as direct byte atoms, in defined order
+        details_ids: List[bytes] = []
+        block_atoms: List[Atom] = []
+
+        def _emit(detail_bytes: bytes) -> None:
+            atom = Atom.from_data(data=detail_bytes, kind=AtomKind.BYTES)
+            details_ids.append(atom.object_id())
+            block_atoms.append(atom)
+
+        # 0: previous_block_hash
+        _emit(self.previous_block_hash)
+        # 1: number
+        _emit(_int_to_be_bytes(self.number))
+        # 2: timestamp
+        _emit(_int_to_be_bytes(self.timestamp))
+        # 3: accounts_hash
+        _emit(self.accounts_hash or b"")
+        # 4: transactions_total_fees
+        _emit(_int_to_be_bytes(self.transactions_total_fees))
+        # 5: transactions_hash
+        _emit(self.transactions_hash or b"")
+        # 6: receipts_hash
+        _emit(self.receipts_hash or b"")
+        # 7: delay_difficulty
+        _emit(_int_to_be_bytes(self.delay_difficulty))
+        # 8: delay_output
+        _emit(self.delay_output or b"")
+        # 9: validator_public_key
+        _emit(self.validator_public_key or b"")
+
+        # Build body list chain (head points to the first detail atom id)
+        body_atoms: List[Atom] = []
+        body_head = ZERO32
+        for child_id in reversed(details_ids):
+            node = Atom.from_data(data=child_id, next_hash=body_head, kind=AtomKind.BYTES)
+            body_head = node.object_id()
+            body_atoms.append(node)
+        body_atoms.reverse()
+
+        block_atoms.extend(body_atoms)
+
+        body_list_atom = Atom.from_data(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.from_data(data=self.signature, next_hash=self.body_hash, kind=AtomKind.BYTES)
+        type_atom = Atom.from_data(data=b"block", next_hash=sig_atom.object_id(), kind=AtomKind.SYMBOL)
+
+        block_atoms.append(body_list_atom)
+        block_atoms.append(sig_atom)
+        block_atoms.append(type_atom)
+
+        self.hash = type_atom.object_id()
+        return self.hash, block_atoms
+
+    @classmethod
+    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, "storage_get", None)
+        if not callable(storage_get):
+            raise TypeError(
+                "Block.from_atom requires a node with 'storage_get' or a callable storage getter"
+            )
+
+        def _atom_kind(atom: Optional[Atom]) -> Optional[AtomKind]:
+            kind_value = getattr(atom, "kind", None)
+            if isinstance(kind_value, AtomKind):
+                return kind_value
+            if isinstance(kind_value, int):
+                try:
+                    return AtomKind(kind_value)
+                except ValueError:
+                    return None
+            return None
+
+        def _require_atom(atom_id: Optional[bytes], context: str, expected_kind: Optional[AtomKind] = None) -> Atom:
+            if not atom_id or atom_id == ZERO32:
+                raise ValueError(f"missing {context}")
+            atom = storage_get(atom_id)
+            if atom is None:
+                raise ValueError(f"missing {context}")
+            if expected_kind is not None:
+                kind = _atom_kind(atom)
+                if kind is not expected_kind:
+                    raise ValueError(f"malformed {context}")
+            return atom
+
+        def _read_list(head_id: Optional[bytes], context: str) -> List[bytes]:
+            entries: List[bytes] = []
+            current = head_id
+            if not current or current == ZERO32:
+                return entries
+            while current and current != ZERO32:
+                node = storage_get(current)
+                if node is None:
+                    raise ValueError(f"missing list node while decoding {context}")
+                node_kind = _atom_kind(node)
+                if node_kind is not AtomKind.BYTES:
+                    raise ValueError(f"list element must be bytes while decoding {context}")
+                if len(node.data) != len(ZERO32):
+                    raise ValueError(f"list element payload has unexpected length while decoding {context}")
+                entries.append(node.data)
+                current = node.next
+            return entries
+
+        type_atom = _require_atom(block_id, "block type atom", AtomKind.SYMBOL)
+        if type_atom.data != b"block":
+            raise ValueError("not a block (type atom payload)")
+
+        sig_atom = _require_atom(type_atom.next, "block signature atom", AtomKind.BYTES)
+        body_list_id = sig_atom.next
+        body_list_atom = _require_atom(body_list_id, "block body list atom", AtomKind.LIST)
+        if body_list_atom.next and body_list_atom.next != ZERO32:
+            raise ValueError("malformed block (body list tail)")
+
+        body_child_ids = _read_list(body_list_atom.data, "block body")
+
+        details: List[bytes] = []
+        for idx, child_id in enumerate(body_child_ids):
+            if idx >= 10:
+                break
+            if not child_id or child_id == ZERO32:
+                details.append(b"")
+                continue
+            detail_atom = storage_get(child_id)
+            details.append(detail_atom.data if detail_atom is not None else b"")
+
+        if len(details) < 10:
+            details.extend([b""] * (10 - len(details)))
+
+        b = cls()
+        b.hash = block_id
+        b.body_hash = body_list_id
+
+        get = lambda i: details[i] if i < len(details) else b""
+        b.previous_block_hash = get(0) or ZERO32
+        b.previous_block = None
+        b.number = _be_bytes_to_int(get(1))
+        b.timestamp = _be_bytes_to_int(get(2))
+        b.accounts_hash = get(3) or None
+        b.transactions_total_fees = _be_bytes_to_int(get(4))
+        b.transactions_hash = get(5) or None
+        b.receipts_hash = get(6) or None
+        b.delay_difficulty = _be_bytes_to_int(get(7))
+        b.delay_output = get(8) or None
+        b.validator_public_key = get(9) or None
+
+        b.signature = sig_atom.data if sig_atom is not None else None
+
+        return b
+
+    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.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

astreum/_consensus/chain.py

@@ -0,0 +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)
+            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

@@ -0,0 +1,100 @@
+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)
+            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