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

astreum/_consensus/genesis.py

@@ -0,0 +1,72 @@
+
+from __future__ import annotations
+
+from typing import Any, List
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .account import Account
+from .block import Block
+from .._storage.atom import ZERO32
+from .._storage.patricia import PatriciaTrie
+from ..utils.integer import int_to_bytes
+
+TREASURY_ADDRESS = b"\x01" * 32
+BURN_ADDRESS = b"\x00" * 32
+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 = int_to_bytes(1)
+    stake_trie.put(storage_node=node, key=validator_pk, value=stake_amount)
+    stake_root = stake_trie.root_hash
+
+    # 2. Account trie with treasury, burn, and validator accounts.
+    accounts_trie = PatriciaTrie()
+
+    treasury_account = Account.create(balance=1, data=stake_root, counter=0)
+    accounts_trie.put(storage_node=node, key=TREASURY_ADDRESS, value=treasury_account.hash)
+
+    burn_account = Account.create(balance=0, data=b"", counter=0)
+    accounts_trie.put(storage_node=node, key=BURN_ADDRESS, value=burn_account.hash)
+
+    validator_account = Account.create(balance=0, data=b"", counter=0)
+    accounts_trie.put(storage_node=node, key=validator_pk, value=validator_account.hash)
+
+    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.to_atom()
+
+    block.hash = block_hash
+    return block

astreum/_consensus/receipt.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Tuple
+
+from .._storage.atom import Atom, AtomKind, ZERO32
+
+STATUS_SUCCESS = 0
+STATUS_FAILED = 1
+
+
+def _int_to_be_bytes(value: Optional[int]) -> bytes:
+    if value is None:
+        return b""
+    value = int(value)
+    if value == 0:
+        return b"\x00"
+    size = (value.bit_length() + 7) // 8
+    return value.to_bytes(size, "big")
+
+
+def _be_bytes_to_int(data: Optional[bytes]) -> int:
+    if not data:
+        return 0
+    return int.from_bytes(data, "big")
+
+
+@dataclass
+class Receipt:
+    transaction_hash: bytes = ZERO32
+    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."""
+        if self.status not in (STATUS_SUCCESS, STATUS_FAILED):
+            raise ValueError("unsupported receipt status")
+
+        detail_specs = [
+            (bytes(self.transaction_hash), AtomKind.LIST),
+            (_int_to_be_bytes(self.status), AtomKind.BYTES),
+            (_int_to_be_bytes(self.cost), AtomKind.BYTES),
+            (bytes(self.logs), AtomKind.BYTES),
+        ]
+
+        detail_atoms: List[Atom] = []
+        next_hash = ZERO32
+        for payload, kind in reversed(detail_specs):
+            atom = Atom.from_data(data=payload, next_hash=next_hash, kind=kind)
+            detail_atoms.append(atom)
+            next_hash = atom.object_id()
+        detail_atoms.reverse()
+
+        type_atom = Atom.from_data(
+            data=b"receipt",
+            next_hash=next_hash,
+            kind=AtomKind.SYMBOL,
+        )
+
+        self.hash = type_atom.object_id()
+        atoms = detail_atoms + [type_atom]
+        return self.hash, 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,
+        storage_get: Callable[[bytes], Optional[Atom]],
+        receipt_id: bytes,
+    ) -> Receipt:
+        """Materialise a Receipt from Atom storage."""
+        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
+
+        type_atom = storage_get(receipt_id)
+        if type_atom is None:
+            raise ValueError("missing receipt type atom")
+        if _atom_kind(type_atom) is not AtomKind.SYMBOL:
+            raise ValueError("malformed receipt (type kind)")
+        if type_atom.data != b"receipt":
+            raise ValueError("not a receipt (type payload)")
+
+        details: List[Atom] = []
+        current = type_atom.next
+        while current and current != ZERO32 and len(details) < 4:
+            atom = storage_get(current)
+            if atom is None:
+                raise ValueError("missing receipt detail atom")
+            details.append(atom)
+            current = atom.next
+
+        if current and current != ZERO32:
+            raise ValueError("too many receipt fields")
+        if len(details) != 4:
+            raise ValueError("incomplete receipt fields")
+
+        tx_atom, status_atom, cost_atom, logs_atom = details
+
+        if _atom_kind(tx_atom) is not AtomKind.LIST:
+            raise ValueError("receipt transaction hash must be list-kind")
+        if any(_atom_kind(atom) is not AtomKind.BYTES for atom in [status_atom, cost_atom, logs_atom]):
+            raise ValueError("receipt detail atoms must be bytes-kind")
+
+        transaction_hash_bytes = tx_atom.data or ZERO32
+        status_bytes = status_atom.data
+        cost_bytes = cost_atom.data
+        logs_bytes = logs_atom.data
+
+        status_value = _be_bytes_to_int(status_bytes)
+        if status_value not in (STATUS_SUCCESS, STATUS_FAILED):
+            raise ValueError("unsupported receipt status")
+
+        return cls(
+            transaction_hash=transaction_hash_bytes or ZERO32,
+            cost=_be_bytes_to_int(cost_bytes),
+            logs=logs_bytes,
+            status=status_value,
+            hash=bytes(receipt_id),
+        )

astreum/_consensus/setup.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import threading
+from queue import Queue
+from typing import Any, Optional
+
+from .workers import (
+    make_discovery_worker,
+    make_validation_worker,
+    make_verify_worker,
+)
+from .genesis import create_genesis_block
+from ..utils.bytes import hex_to_bytes
+
+
+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 consensus_setup(node: Any, config: Optional[dict] = None) -> None:
+    config = config or {}
+
+    # 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", {})
+
+    node.latest_block_hash = None
+    latest_block_hex = config.get("latest_block_hash")
+    if latest_block_hex is not None:
+        node.latest_block_hash = hex_to_bytes(latest_block_hex, expected_length=32)
+    node.latest_block = None
+
+    # 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
+
+    verify_worker = make_verify_worker(node)
+    validation_worker = make_validation_worker(
+        node, current_validator=current_validator
+    )
+
+    # Start workers as daemons
+    discovery_worker = make_discovery_worker(node)
+    node.consensus_discovery_thread = threading.Thread(
+        target=discovery_worker, daemon=True, name="consensus-discovery"
+    )
+    node.consensus_verify_thread = threading.Thread(
+        target=verify_worker, daemon=True, name="consensus-verify"
+    )
+    node.consensus_validation_thread = threading.Thread(
+        target=validation_worker, daemon=True, name="consensus-validation"
+    )
+    node.consensus_discovery_thread.start()
+    node.consensus_verify_thread.start()
+
+    validator_secret_hex = config.get("validation_secret_key")
+    if validator_secret_hex:
+        validator_secret_bytes = hex_to_bytes(validator_secret_hex, expected_length=32)
+        try:
+            from cryptography.hazmat.primitives import serialization
+            from cryptography.hazmat.primitives.asymmetric import ed25519
+
+            validator_private = ed25519.Ed25519PrivateKey.from_private_bytes(
+                validator_secret_bytes
+            )
+        except Exception as exc:
+            raise ValueError("invalid validation_secret_key") from exc
+
+        validator_public_bytes = validator_private.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+
+        node.validation_secret_key = validator_private
+        node.validation_public_key = validator_public_bytes
+
+        if node.latest_block_hash is None:
+            genesis_block = create_genesis_block(
+                node,
+                validator_public_key=validator_public_bytes,
+                validator_secret_key=validator_secret_bytes,
+            )
+            genesis_hash, genesis_atoms = genesis_block.to_atom()
+            if hasattr(node, "_local_set"):
+                for atom in genesis_atoms:
+                    try:
+                        node._local_set(atom.object_id(), atom)
+                    except Exception:
+                        pass
+            node.latest_block_hash = genesis_hash
+            node.latest_block = genesis_block
+
+        node.consensus_validation_thread.start()

astreum/_consensus/transaction.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional, Tuple
+
+from .._storage.atom import Atom, AtomKind, ZERO32
+from ..utils.integer import bytes_to_int, int_to_bytes
+from .account import Account
+from .genesis import TREASURY_ADDRESS
+from .receipt import STATUS_FAILED, Receipt, STATUS_SUCCESS
+
+@dataclass
+class Transaction:
+    amount: int
+    counter: int
+    data: bytes = b""
+    recipient: bytes = b""
+    sender: bytes = b""
+    signature: bytes = b""
+    hash: bytes = ZERO32
+
+    def to_atom(self) -> Tuple[bytes, List[Atom]]:
+        """Serialise the transaction, returning (object_id, atoms)."""
+        body_child_ids: List[bytes] = []
+        acc: List[Atom] = []
+
+        def emit(payload: bytes) -> None:
+            atom = Atom.from_data(data=payload, kind=AtomKind.BYTES)
+            body_child_ids.append(atom.object_id())
+            acc.append(atom)
+
+        emit(int_to_bytes(self.amount))
+        emit(int_to_bytes(self.counter))
+        emit(bytes(self.data))
+        emit(bytes(self.recipient))
+        emit(bytes(self.sender))
+
+        # Build the linked list of body entry references.
+        body_atoms: List[Atom] = []
+        body_head = ZERO32
+        for child_id in reversed(body_child_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()
+        acc.extend(body_atoms)
+
+        body_list_atom = Atom.from_data(data=body_head, kind=AtomKind.LIST)
+        acc.append(body_list_atom)
+        body_list_id = body_list_atom.object_id()
+
+        signature_atom = Atom.from_data(
+            data=bytes(self.signature),
+            next_hash=body_list_id,
+            kind=AtomKind.BYTES,
+        )
+        type_atom = Atom.from_data(
+            data=b"transaction",
+            next_hash=signature_atom.object_id(),
+            kind=AtomKind.SYMBOL,
+        )
+
+        acc.append(signature_atom)
+        acc.append(type_atom)
+
+        self.hash = type_atom.object_id()
+        return self.hash, acc
+
+    @classmethod
+    def from_atom(
+        cls,
+        node: Any,
+        transaction_id: bytes,
+    ) -> Transaction:
+        storage_get = getattr(node, "storage_get", None)
+        if not callable(storage_get):
+            raise NotImplementedError("node does not expose a 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 head_id and head_id != ZERO32 else None
+            while current:
+                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"invalid list node while decoding {context}")
+                if len(node.data) != len(ZERO32):
+                    raise ValueError(f"malformed list entry while decoding {context}")
+                entries.append(node.data)
+                nxt = node.next
+                current = nxt if nxt and nxt != ZERO32 else None
+            return entries
+
+        def _read_detail_bytes(entry_id: Optional[bytes]) -> bytes:
+            if not entry_id or entry_id == ZERO32:
+                return b""
+            detail_atom = storage_get(entry_id)
+            return detail_atom.data if detail_atom is not None else b""
+
+        type_atom = _require_atom(transaction_id, "transaction type atom", AtomKind.SYMBOL)
+        if type_atom.data != b"transaction":
+            raise ValueError("not a transaction (type atom payload)")
+
+        signature_atom = _require_atom(type_atom.next, "transaction signature atom", AtomKind.BYTES)
+        body_list_atom = _require_atom(signature_atom.next, "transaction body list atom", AtomKind.LIST)
+        if body_list_atom.next and body_list_atom.next != ZERO32:
+            raise ValueError("malformed transaction (body list tail)")
+
+        body_entry_ids = _read_list(body_list_atom.data, "transaction body")
+        if len(body_entry_ids) < 5:
+            body_entry_ids.extend([ZERO32] * (5 - len(body_entry_ids)))
+
+        amount_bytes = _read_detail_bytes(body_entry_ids[0])
+        counter_bytes = _read_detail_bytes(body_entry_ids[1])
+        data_bytes = _read_detail_bytes(body_entry_ids[2])
+        recipient_bytes = _read_detail_bytes(body_entry_ids[3])
+        sender_bytes = _read_detail_bytes(body_entry_ids[4])
+
+        return cls(
+            amount=bytes_to_int(amount_bytes),
+            counter=bytes_to_int(counter_bytes),
+            data=data_bytes,
+            recipient=recipient_bytes,
+            sender=sender_bytes,
+            signature=signature_atom.data,
+            hash=bytes(transaction_id),
+        )
+
+
+def apply_transaction(node: Any, block: object, transaction_hash: bytes) -> None:
+    """Apply transaction to the candidate block. Override downstream."""
+    transaction = Transaction.from_atom(node, transaction_hash)
+
+    accounts = block.accounts
+
+    sender_account = accounts.get_account(address=transaction.sender, node=node)
+
+    if sender_account is None:
+        return
+    
+    tx_cost = 1 + transaction.amount
+
+    if sender_account.balance < tx_cost:
+        low_sender_balance_receipt = Receipt(
+            transaction_hash=transaction_hash,
+            cost=0,
+            logs=b"low sender balance",
+            status=STATUS_FAILED
+        )
+        low_sender_balance_receipt.atomize()
+        block.receipts.append(receipt)
+        block.transactions.append(transaction)
+        return
+
+    recipient_account = accounts.get_account(address=transaction.recipient, node=node)
+
+    if recipient_account is None:
+        recipient_account = Account.create()
+
+    if transaction.recipient == TREASURY_ADDRESS:
+        stake_trie = recipient_account.data
+        existing_stake = stake_trie.get(node, transaction.sender)
+        current_stake = bytes_to_int(existing_stake)
+        new_stake = current_stake + transaction.amount
+        stake_trie.put(node, transaction.sender, int_to_bytes(new_stake))
+        recipient_account.data_hash = stake_trie.root_hash or ZERO32
+        recipient_account.balance += transaction.amount
+    else:
+        recipient_account.balance += transaction.amount
+
+    sender_account.balance -= tx_cost
+
+    block.accounts.set_account(address=sender_account)
+
+    block.accounts.set_account(address=recipient_account)
+
+    block.transactions.append(transaction_hash)
+
+    receipt = Receipt(
+        transaction_hash=bytes(transaction_hash),
+        cost=0,
+        logs=b"",
+        status=STATUS_SUCCESS,
+    )
+    receipt.atomize()
+    block.receipts.append(receipt)

astreum/_consensus/workers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Worker thread factories for the consensus subsystem.
+"""
+
+from .discovery import make_discovery_worker
+from .validation import make_validation_worker
+from .verify import make_verify_worker
+
+__all__ = ["make_discovery_worker", "make_verify_worker", "make_validation_worker"]

astreum/_consensus/workers/discovery.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import time
+from queue import Empty
+from typing import Any, Dict, Set, Tuple
+
+
+def make_discovery_worker(node: Any):
+    """
+    Build the discovery worker bound to the given node.
+
+    The returned callable mirrors the previous inline worker in ``setup.py``.
+    """
+
+    def _discovery_worker() -> None:
+        stop = node._validation_stop_event
+        while not stop.is_set():
+            try:
+                peers = getattr(node, "peers", None)
+                if isinstance(peers, dict):
+                    pairs: list[Tuple[Any, bytes]] = [
+                        (peer_id, bytes(latest))
+                        for peer_id, peer in list(peers.items())
+                        if isinstance(
+                            (latest := getattr(peer, "latest_block", None)),
+                            (bytes, bytearray),
+                        )
+                        and latest
+                    ]
+                    latest_keys: Set[bytes] = {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
+                    }
+
+                    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)
+
+    return _discovery_worker