astreum 0.2.36__py3-none-any.whl → 0.2.38__py3-none-any.whl

astreum/_validation/block.py

@@ -0,0 +1,296 @@
+
+from typing import Callable, List, Optional, Tuple
+
+from .._storage.atom import Atom, ZERO32
+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")
+
+
+def _make_typed_bytes(data: bytes) -> Tuple[bytes, List[Atom]]:
+    """Create a typed 'byte' atom for the given payload.
+
+    Returns (object_id, atoms_in_dependency_order).
+    """
+    val = Atom.from_data(data=data)
+    typ = Atom.from_data(data=b"byte", next_hash=val.object_id())
+    return typ.object_id(), [val, typ]
+
+
+def _make_list(child_ids: List[bytes]) -> Tuple[bytes, List[Atom]]:
+    """Create a typed 'list' atom for child object ids.
+
+    Encodes elements as a linked chain of element-atoms with data=child_id and
+    next pointing to the next element's object id. The list value atom contains
+    the element count and points to the head of the element chain. The type atom
+    identifies the structure as a list.
+    """
+    acc: List[Atom] = []
+    next_hash = ZERO32
+    elem_atoms: List[Atom] = []
+    # Build element chain in reverse, then flip to maintain forward order
+    for h in reversed(child_ids):
+        a = Atom.from_data(data=h, next_hash=next_hash)
+        next_hash = a.object_id()
+        elem_atoms.append(a)
+    elem_atoms.reverse()
+    head = next_hash
+    val = Atom.from_data(data=(len(child_ids)).to_bytes(8, "little"), next_hash=head)
+    typ = Atom.from_data(data=b"list", next_hash=val.object_id())
+    return typ.object_id(), acc + elem_atoms + [val, typ]
+
+
+class Block:
+    """Validation Block representation using Atom storage.
+
+    Top-level encoding:
+      block_id = list([ type_atom, body_list, signature_atom ])
+      where: type_atom      = Atom(data=b"block", next=body_list_id)
+             body_list      = list([...details...])
+             signature_atom = Atom(data=<signature-bytes>)
+
+    Details order in body_list:
+      0: previous_block                      (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_root_hash              (bytes)
+      6: delay_difficulty                    (int → big-endian bytes)
+      7: delay_output                        (bytes)
+      8: 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: bytes
+
+    # block details
+    number: Optional[int]
+    timestamp: Optional[int]
+    accounts_hash: Optional[bytes]
+    transactions_total_fees: Optional[int]
+    transactions_root_hash: Optional[bytes]
+    delay_difficulty: Optional[int]
+    delay_output: Optional[bytes]
+    validator_public_key: Optional[bytes]
+
+    # additional
+    body_hash: Optional[bytes]
+    signature: Optional[bytes]
+
+    def __init__(self) -> None:
+        # defaults for safety
+        self.hash = b""
+        self.previous_block = ZERO32
+        self.number = None
+        self.timestamp = None
+        self.accounts_hash = None
+        self.transactions_total_fees = None
+        self.transactions_root_hash = None
+        self.delay_difficulty = None
+        self.delay_output = None
+        self.validator_public_key = None
+        self.body_hash = None
+        self.signature = None
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        # Build body details as typed bytes, in defined order
+        details_ids: List[bytes] = []
+        atoms_acc: List[Atom] = []
+
+        def _emit(detail_bytes: bytes) -> None:
+            oid, ats = _make_typed_bytes(detail_bytes)
+            details_ids.append(oid)
+            atoms_acc.extend(ats)
+
+        # 0: previous_block
+        _emit(self.previous_block or ZERO32)
+        # 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_root_hash
+        _emit(self.transactions_root_hash or b"")
+        # 6: delay_difficulty
+        _emit(_int_to_be_bytes(self.delay_difficulty))
+        # 7: delay_output
+        _emit(self.delay_output or b"")
+        # 8: validator_public_key
+        _emit(self.validator_public_key or b"")
+
+        # Build body list
+        body_id, body_atoms = _make_list(details_ids)
+        atoms_acc.extend(body_atoms)
+        self.body_hash = body_id
+
+        # Type atom points to body list
+        type_atom = Atom.from_data(data=b"block", next_hash=body_id)
+
+        # Signature atom (raw byte payload)
+        sig_atom = Atom.from_data(data=self.signature or b"", next_hash=ZERO32)
+
+        # Main block list: [type_atom, body_list, signature]
+        main_id, main_atoms = _make_list([type_atom.object_id(), body_id, sig_atom.object_id()])
+        atoms_acc.append(type_atom)
+        atoms_acc.append(sig_atom)
+        atoms_acc.extend(main_atoms)
+
+        self.hash = main_id
+        return self.hash, atoms_acc
+
+    @classmethod
+    def from_atom(cls, storage_get: Callable[[bytes], Optional[Atom]], block_id: bytes) -> "Block":
+        # 1) Expect main list
+        main_typ = storage_get(block_id)
+        if main_typ is None or main_typ.data != b"list":
+            raise ValueError("not a block (main list missing)")
+        main_val = storage_get(main_typ.next)
+        if main_val is None:
+            raise ValueError("malformed block list (missing value)")
+        # length is little-endian u64 per storage format
+        if len(main_val.data) < 1:
+            raise ValueError("malformed block list (length)")
+        head = main_val.next
+
+        # read first 2 elements: [type_atom_id, body_list_id]
+        first_elem = storage_get(head)
+        if first_elem is None:
+            raise ValueError("malformed block list (head element)")
+        type_atom_id = first_elem.data
+        second_elem = storage_get(first_elem.next)
+        if second_elem is None:
+            raise ValueError("malformed block list (second element)")
+        body_list_id = second_elem.data
+        # optional 3rd element: signature atom id
+        third_elem = storage_get(second_elem.next) if second_elem.next else None
+        sig_atom_id: Optional[bytes] = third_elem.data if third_elem is not None else None
+
+        # 2) Validate type atom and linkage to body
+        type_atom = storage_get(type_atom_id)
+        if type_atom is None or type_atom.data != b"block" or type_atom.next != body_list_id:
+            raise ValueError("not a block (type atom)")
+
+        # 3) Parse body list of details
+        body_typ = storage_get(body_list_id)
+        if body_typ is None or body_typ.data != b"list":
+            raise ValueError("malformed body (type)")
+        body_val = storage_get(body_typ.next)
+        if body_val is None:
+            raise ValueError("malformed body (value)")
+        cur_elem_id = body_val.next
+
+        def _read_typed_bytes(elem_id: bytes) -> bytes:
+            elem = storage_get(elem_id)
+            if elem is None:
+                return b""
+            child_id = elem.data
+            typ = storage_get(child_id)
+            if typ is None or typ.data != b"byte":
+                return b""
+            val = storage_get(typ.next)
+            return val.data if val is not None else b""
+
+        details: List[bytes] = []
+        # We read up to 9 fields if present
+        for _ in range(9):
+            if not cur_elem_id:
+                break
+            b = _read_typed_bytes(cur_elem_id)
+            details.append(b)
+            nxt = storage_get(cur_elem_id)
+            cur_elem_id = nxt.next if nxt is not None else b""
+
+        b = cls()
+        b.hash = block_id
+        b.body_hash = body_list_id
+
+        # Map details back per the defined order
+        get = lambda i: details[i] if i < len(details) else b""
+        b.previous_block = get(0) or ZERO32
+        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_root_hash = get(5) or None
+        b.delay_difficulty = _be_bytes_to_int(get(6))
+        b.delay_output = get(7) or None
+        b.validator_public_key = get(8) or None
+
+        # 4) Parse signature if present (supports raw or typed 'byte' atom)
+        if sig_atom_id is not None:
+            sa = storage_get(sig_atom_id)
+            if sa is not None:
+                if sa.data == b"byte":
+                    sval = storage_get(sa.next)
+                    b.signature = sval.data if sval is not None else b""
+                else:
+                    b.signature = sa.data
+
+        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
+        if self.previous_block and self.previous_block != ZERO32:
+            # If previous block cannot be loaded, treat as unverifiable, not malicious
+            try:
+                prev = Block.from_atom(storage_get, self.previous_block)
+            except Exception:
+                return False
+            prev_ts = int(prev.timestamp or 0)
+            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/_validation/chain.py

@@ -0,0 +1,63 @@
+# 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
+
+            if blk.previous_block == ZERO32:
+                break
+            # Move to previous block using cache-aware loader
+            blk = load_block(blk.previous_block)
+
+        self.validated_upto_block = blk
+        return blk

astreum/_validation/fork.py

@@ -0,0 +1,98 @@
+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
+            
+            nxt = load_block(blk.previous_block)
+            if nxt is None:
+                return False
+            blk = nxt

astreum/_validation/setup.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from queue import Empty, Queue
+from typing import Any, Dict, Optional, Tuple
+
+from cryptography.hazmat.primitives import serialization
+
+from .block import Block
+from .chain import Chain
+from .fork import Fork
+from .._storage.atom import ZERO32, Atom
+
+
+@dataclass
+class Transaction:
+    """Lightweight transaction view for validation processing."""
+
+    recipient: bytes
+    sender: bytes
+    amount: int
+    counter: int
+
+
+def current_validator(node: Any) -> bytes:
+    """Return the current validator identifier. Override downstream."""
+    raise NotImplementedError("current_validator must be implemented by the host node")
+
+
+def apply_transaction(node: Any, block: object, transaction_hash: bytes) -> None:
+    """Apply transaction to the candidate block. Override downstream."""
+    pass
+
+
+def validation_setup(node: Any) -> None:
+    # Shared state
+    node.validation_lock = getattr(node, "validation_lock", threading.RLock())
+
+    # Public maps per your spec
+    # - chains: Dict[root, Chain]
+    # - forks:  Dict[head, Fork]
+    node.chains = getattr(node, "chains", {})
+    node.forks = getattr(node, "forks", {})
+
+    # Pending transactions queue (hash-only entries)
+    node._validation_transaction_queue = getattr(
+        node, "_validation_transaction_queue", Queue()
+    )
+    # Single work queue of grouped items: (latest_block_hash, set(peer_ids))
+    node._validation_verify_queue = getattr(
+        node, "_validation_verify_queue", Queue()
+    )
+    node._validation_stop_event = getattr(
+        node, "_validation_stop_event", threading.Event()
+    )
+
+    def enqueue_transaction_hash(tx_hash: bytes) -> None:
+        """Schedule a transaction hash for validation processing."""
+        if not isinstance(tx_hash, (bytes, bytearray)):
+            raise TypeError("transaction hash must be bytes-like")
+        node._validation_transaction_queue.put(bytes(tx_hash))
+
+    node.enqueue_transaction_hash = enqueue_transaction_hash
+
+    def _process_peers_latest_block(latest_block_hash: bytes, peer_ids: set[Any]) -> None:
+        """Assign a peer to a fork for its latest block without merging forks.
+
+        Flow:
+        - Create a new Fork for `latest_block_hash` and validate it, using
+          stop_heads composed of current fork heads to short-circuit when
+          ancestry meets an existing fork head.
+        - If a matching fork head is found and is not malicious, copy its
+          structural fields (root, validated_upto, chain_fork_position) onto
+          the new fork.
+        - Add all peers in `peer_ids` to the new fork and remove each from any
+          previous fork they followed.
+        - Persist the new fork under `node.forks[latest_block_hash]`.
+        """
+        new_fork = Fork(head=latest_block_hash)
+
+        current_fork_heads = {fk.head for fk in node.forks.values() if fk.head != latest_block_hash}
+
+        new_fork.validate(storage_get=node._local_get, stop_heads=current_fork_heads)
+
+        # update new_fork with details of the fork with head of validated_upto
+        if new_fork.validated_upto and new_fork.validated_upto in node.forks:
+            ref = node.forks[new_fork.validated_upto]
+            # if the matched fork is malicious, disregard this new fork entirely
+            if getattr(ref, "malicious_block_hash", None):
+                return
+            # copy structural fields exactly
+            new_fork.root = ref.root
+            new_fork.validated_upto = ref.validated_upto
+            new_fork.chain_fork_position = ref.chain_fork_position
+
+        # add peers to new fork and remove them from any old forks
+        for peer_id in peer_ids:
+            new_fork.add_peer(peer_id)
+            # Remove this peer from all other forks
+            for h, fk in list(node.forks.items()):
+                if h != latest_block_hash:
+                    fk.remove_peer(peer_id)
+
+        # persist the fork
+        node.forks[latest_block_hash] = new_fork
+
+
+    # Discovery worker: watches peers and enqueues head changes
+    def _discovery_worker():
+        stop = node._validation_stop_event
+        while not stop.is_set():
+            try:
+                peers = getattr(node, "peers", None)
+                if isinstance(peers, dict):
+                    # Snapshot as (peer_id, latest_block_hash) pairs
+                    pairs = [
+                        (peer_id, bytes(latest))
+                        for peer_id, peer in list(peers.items())
+                        if isinstance((latest := getattr(peer, "latest_block", None)), (bytes, bytearray)) and latest
+                    ]
+                    # Group peers by latest block hash
+                    latest_keys = {hb for _, hb in pairs}
+                    grouped: Dict[bytes, set[Any]] = {
+                        hb: {pid for pid, phb in pairs if phb == hb}
+                        for hb in latest_keys
+                    }
+
+                    # Replace queue contents with current groups
+                    try:
+                        while True:
+                            node._validation_verify_queue.get_nowait()
+                    except Empty:
+                        pass
+                    for latest_b, peer_set in grouped.items():
+                        node._validation_verify_queue.put((latest_b, peer_set))
+            except Exception:
+                pass
+            finally:
+                time.sleep(0.5)
+
+    # Verification worker: computes root/height and applies peer→fork assignment
+    def _verify_worker():
+        stop = node._validation_stop_event
+        while not stop.is_set():
+            # Take a snapshot of all currently queued groups
+            batch: list[tuple[bytes, set[Any]]] = []
+            try:
+                while True:
+                    item = node._validation_verify_queue.get_nowait()
+                    batch.append(item)
+            except Empty:
+                pass
+
+            if not batch:
+                time.sleep(0.1)
+                continue
+
+            # Process the snapshot; new items enqueued during processing
+            # will be handled in the next iteration
+            for latest_b, peers in batch:
+                try:
+                    _process_peers_latest_block(latest_b, peers)
+                except Exception:
+                    pass
+
+    def _validation_worker() -> None:
+        """Consume pending transactions when scheduled to validate."""
+        stop = node._validation_stop_event
+        while not stop.is_set():
+            validation_public_key = getattr(node, "validation_public_key", None)
+            if not validation_public_key:
+                time.sleep(0.5)
+                continue
+
+            scheduled_validator = current_validator(node)
+
+            if scheduled_validator != validation_public_key:
+                time.sleep(0.5)
+                continue
+
+            try:
+                current_hash = node._validation_transaction_queue.get_nowait()
+            except Empty:
+                time.sleep(0.1)
+                continue
+
+            new_block = Block()
+            new_block.validator_public_key = getattr(node, "validation_public_key", None)
+            
+            while True:
+                try:
+                    apply_transaction(node, new_block, current_hash)
+                except NotImplementedError:
+                    node._validation_transaction_queue.put(current_hash)
+                    time.sleep(0.5)
+                    break
+                except Exception:
+                    # Skip problematic transaction; leave block as-is.
+                    pass
+
+                try:
+                    current_hash = node._validation_transaction_queue.get_nowait()
+                except Empty:
+                    break
+
+    # Start workers as daemons
+    node.validation_discovery_thread = threading.Thread(
+        target=_discovery_worker, daemon=True, name="validation-discovery"
+    )
+    node.validation_verify_thread = threading.Thread(
+        target=_verify_worker, daemon=True, name="validation-verify"
+    )
+    node.validation_worker_thread = threading.Thread(
+        target=_validation_worker, daemon=True, name="validation-worker"
+    )
+    node.validation_discovery_thread.start()
+    node.validation_verify_thread.start()
+    if getattr(node, "validation_secret_key", None):
+        node.validation_worker_thread.start()