blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/structures/core/base.py

@@ -0,0 +1,100 @@
+"""Result containers for blockchainkit.structures."""
+
+from dataclasses import dataclass
+
+from blockchainkit._validation import integer
+
+
+@dataclass(frozen=True)
+class MerkleProof:
+    """Leaf position, leaf count, and bottom-up siblings (None for promotion)."""
+
+    index: int
+    leaf_count: int
+    siblings: tuple[bytes | None, ...]
+
+
+@dataclass(frozen=True)
+class ProofStep:
+    """One level of Merkle-proof verification, from the leaf toward the root.
+
+    Attributes
+    ----------
+    side : {"left", "right", "promoted"}
+        Where the sibling sits: ``"left"`` means hash(sibling || current),
+        ``"right"`` means hash(current || sibling), and ``"promoted"`` means
+        the node had no sibling and moved up unchanged.
+    sibling : bytes or None
+        The sibling digest from the proof (``None`` when promoted).
+    digest : bytes
+        The node digest after this step.
+    """
+
+    side: str
+    sibling: bytes | None
+    digest: bytes
+
+
+@dataclass(frozen=True)
+class MerkleTrace:
+    """Every step of reconstructing a root from a leaf and its proof.
+
+    Attributes
+    ----------
+    leaf_digest : bytes
+        The domain-separated hash of the leaf payload.
+    steps : tuple of ProofStep
+        Bottom-up reconstruction steps.
+    root : bytes
+        The count-bound root the proof reconstructs.
+    valid : bool
+        Whether that root equals the trusted root.
+    """
+
+    leaf_digest: bytes
+    steps: tuple[ProofStep, ...]
+    root: bytes
+    valid: bool
+
+
+@dataclass(frozen=True, order=True)
+class OutPoint:
+    """A reference to one coin: the creating transaction's id and the output index."""
+
+    txid: bytes
+    index: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.txid, bytes) or len(self.txid) != 32:
+            raise ValueError("txid must be 32 bytes")
+        integer(self.index, "index")
+
+    def __repr__(self) -> str:
+        return f"OutPoint({self.txid.hex()[:12]}..., {self.index})"
+
+
+@dataclass(frozen=True)
+class Coin:
+    """An unspent output: who owns it and how much it holds."""
+
+    owner: str
+    amount: int
+
+
+@dataclass(frozen=True)
+class SparseMerkleProof:
+    """Siblings from the leaf up, and the value at the key (None if absent)."""
+
+    key: bytes
+    value: bytes | None
+    siblings: tuple[bytes, ...]
+
+
+@dataclass(frozen=True)
+class MMRProof:
+    """Path from a leaf to its peak, plus every peak and the range size."""
+
+    index: int
+    size: int
+    siblings: tuple[bytes, ...]
+    peaks: tuple[bytes, ...]

blockchainkit/structures/systems/__init__.py

@@ -0,0 +1,45 @@
+"""Concrete authenticated structures, ledgers, and chains."""
+
+from blockchainkit.structures.systems.block import Block, BlockHeader
+from blockchainkit.structures.systems.bloom import BloomFilter
+from blockchainkit.structures.systems.chain import Blockchain
+from blockchainkit.structures.systems.hash_chain import hash_chain, verify_one_time_password
+from blockchainkit.structures.systems.headers import verify_header_chain
+from blockchainkit.structures.systems.ledger import Ledger
+from blockchainkit.structures.systems.merkle import (
+    MerkleTree,
+    bitcoin_merkle_root,
+    consistency_proof,
+    trace_proof,
+    verify_consistency,
+    verify_proof,
+)
+from blockchainkit.structures.systems.mmr import MerkleMountainRange, verify_mmr_proof
+from blockchainkit.structures.systems.sparse_merkle import SparseMerkleTree, verify_sparse_proof
+from blockchainkit.structures.systems.transaction import Transaction, address
+from blockchainkit.structures.systems.utxo import UTXOSet, UTXOTransaction
+
+__all__ = [
+    "Block",
+    "BlockHeader",
+    "BloomFilter",
+    "Blockchain",
+    "hash_chain",
+    "verify_one_time_password",
+    "verify_header_chain",
+    "Ledger",
+    "MerkleTree",
+    "bitcoin_merkle_root",
+    "consistency_proof",
+    "trace_proof",
+    "verify_consistency",
+    "verify_proof",
+    "MerkleMountainRange",
+    "verify_mmr_proof",
+    "SparseMerkleTree",
+    "verify_sparse_proof",
+    "Transaction",
+    "address",
+    "UTXOSet",
+    "UTXOTransaction",
+]

blockchainkit/structures/systems/block.py

@@ -0,0 +1,144 @@
+"""Immutable blocks with canonical headers and transaction commitments."""
+
+from dataclasses import dataclass
+from functools import cached_property
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import UINT64_LIMIT
+from blockchainkit.crypto import sha256
+from blockchainkit.structures.systems.merkle import MerkleTree
+from blockchainkit.structures.systems.transaction import Transaction
+from blockchainkit.structures.utils.encoding import canonical_json
+
+
+def _check_uint64(value: int, name: str) -> None:
+    integer(value, name)
+    if value >= UINT64_LIMIT:
+        raise ValueError(f"{name} must fit an unsigned 64-bit integer")
+
+
+@dataclass(frozen=True)
+class BlockHeader:
+    """The 80-byte-style summary a light client downloads instead of a block.
+
+    It commits to the block's transactions through ``merkle_root`` alone, so
+    its hash, and therefore its proof of work, can be checked without them.
+    ``Block.to_header().hash == Block.hash``.
+
+    Parameters
+    ----------
+    previous_hash, merkle_root : bytes
+        32-byte digests.
+    height, timestamp, difficulty, nonce : int
+        As for :class:`Block`.
+    """
+
+    previous_hash: bytes = bytes(32)
+    merkle_root: bytes = bytes(32)
+    height: int = 0
+    timestamp: int = 0
+    difficulty: int = 8
+    nonce: int = 0
+
+    def __post_init__(self) -> None:
+        for name in ("previous_hash", "merkle_root"):
+            value = getattr(self, name)
+            if not isinstance(value, bytes) or len(value) != 32:
+                raise ValueError(f"{name} must be 32 bytes")
+        for name in ("height", "timestamp", "nonce", "difficulty"):
+            _check_uint64(getattr(self, name), name)
+        if self.difficulty > 256:
+            raise ValueError("difficulty cannot exceed 256 bits")
+
+    def encode(self) -> bytes:
+        """Return the canonical bytes that are hashed."""
+        return canonical_json(
+            {
+                "version": 1,
+                "previous_hash": self.previous_hash.hex(),
+                "merkle_root": self.merkle_root.hex(),
+                "height": self.height,
+                "timestamp": self.timestamp,
+                "difficulty": self.difficulty,
+                "nonce": self.nonce,
+            }
+        )
+
+    @cached_property
+    def hash(self) -> bytes:
+        """Return SHA-256 of the canonical header."""
+        return sha256(self.encode())
+
+
+@dataclass(frozen=True)
+class Block:
+    """A teaching block, not a Bitcoin/Ethereum wire-format block.
+
+    Parameters
+    ----------
+    previous_hash : bytes
+        Parent digest, or 32 zero bytes for genesis.
+    transactions : tuple of Transaction
+        Ordered signed transfers; copied into an immutable tuple.
+    height, timestamp, nonce : int
+        Nonnegative 64-bit integers; timestamps use simulation units.
+    difficulty : int
+        Number of required leading zero hash bits, between 0 and 256.
+
+    Notes
+    -----
+    The Merkle root and the block hash are computed once and cached. A
+    miner never rebuilds the transaction tree: it calls ``header(nonce=...)``
+    with candidate nonces, as real miners vary only the header.
+    """
+
+    previous_hash: bytes = bytes(32)
+    transactions: tuple[Transaction, ...] = ()
+    height: int = 0
+    timestamp: int = 0
+    difficulty: int = 8
+    nonce: int = 0
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.previous_hash, bytes) or len(self.previous_hash) != 32:
+            raise ValueError("previous_hash must be 32 bytes")
+        object.__setattr__(self, "transactions", tuple(self.transactions))
+        if any(not isinstance(tx, Transaction) for tx in self.transactions):
+            raise TypeError("transactions must contain Transaction instances")
+        for name in ("height", "timestamp", "nonce", "difficulty"):
+            _check_uint64(getattr(self, name), name)
+        if self.difficulty > 256:
+            raise ValueError("difficulty cannot exceed 256 bits")
+
+    @cached_property
+    def merkle_root(self) -> bytes:
+        """Return the count-bound commitment to ordered signed transactions."""
+        return MerkleTree(tx.to_bytes() for tx in self.transactions).root
+
+    def header(self, nonce: int | None = None) -> bytes:
+        """Return canonical bytes committing to all consensus-relevant fields.
+
+        Parameters
+        ----------
+        nonce : int, optional
+            A candidate nonce to place in the header instead of ``self.nonce``.
+            ``block.header(nonce=n)`` equals ``replace(block, nonce=n).header()``
+            without rebuilding the Merkle tree.
+        """
+        return self.to_header(nonce).encode()
+
+    def to_header(self, nonce: int | None = None) -> BlockHeader:
+        """Return this block's header, optionally with a candidate nonce."""
+        return BlockHeader(
+            self.previous_hash,
+            self.merkle_root,
+            self.height,
+            self.timestamp,
+            self.difficulty,
+            self.nonce if nonce is None else nonce,
+        )
+
+    @cached_property
+    def hash(self) -> bytes:
+        """Return SHA-256 of the canonical header."""
+        return sha256(self.header())

blockchainkit/structures/systems/bloom.py

@@ -0,0 +1,81 @@
+"""Bloom filters (1970): compact set membership with false positives but no false negatives.
+
+Bitcoin's lightweight clients (BIP 37, 2012) sent full nodes a Bloom filter
+of their addresses, so nodes could forward matching transactions without
+the client listing its addresses outright. The false positives were meant
+to give privacy; in practice they leaked much of it.
+"""
+
+from math import exp, log
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import BLOOM_DOMAIN
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+class BloomFilter:
+    """An array of ``size`` bits, set at ``hashes`` positions per added item.
+
+    An item is reported present if all its positions are set. Items that
+    were added are always found; others are wrongly found with probability
+    about ``(1 - exp(-k n / m))**k``.
+
+    Parameters
+    ----------
+    size : int
+        Number of bits m.
+    hashes : int
+        Number of positions k per item.
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import BloomFilter
+    >>> bloom = BloomFilter(256, 3)
+    >>> bloom.add(b"alice")
+    >>> b"alice" in bloom
+    True
+    """
+
+    def __init__(self, size: int, hashes: int) -> None:
+        integer(size, "size", 1)
+        integer(hashes, "hashes", 1)
+        self._size, self._hashes = size, hashes
+        self._bits = bytearray((size + 7) // 8)
+        self._count = 0
+
+    def _positions(self, item: bytes) -> list[int]:
+        if not isinstance(item, bytes):
+            raise TypeError("items must be bytes")
+        return [
+            int.from_bytes(sha256(BLOOM_DOMAIN + i.to_bytes(4, "big") + item), "big") % self._size
+            for i in range(self._hashes)
+        ]
+
+    def add(self, item: bytes) -> None:
+        """Set the item's bit positions."""
+        for position in self._positions(item):
+            self._bits[position // 8] |= 1 << (position % 8)
+        self._count += 1
+
+    def __contains__(self, item: object) -> bool:
+        if not isinstance(item, bytes):
+            return False
+        return all(self._bits[p // 8] >> (p % 8) & 1 for p in self._positions(item))
+
+    def __len__(self) -> int:
+        return self._count
+
+    @property
+    def fill_ratio(self) -> float:
+        """Fraction of bits set."""
+        return sum(bin(byte).count("1") for byte in self._bits) / self._size
+
+    @staticmethod
+    def false_positive_rate(size: int, hashes: int, items: int) -> float:
+        """Return Bloom's estimate ``(1 - exp(-k n / m))**k``."""
+        return float((1 - exp(-hashes * items / size)) ** hashes)
+
+    @staticmethod
+    def optimal_hash_count(size: int, items: int) -> int:
+        """Return the k minimizing false positives, ``round((m / n) ln 2)``."""
+        return max(1, round(size / items * log(2)))

blockchainkit/structures/systems/chain.py

@@ -0,0 +1,131 @@
+"""Cumulative-work fork selection for a fixed-difficulty chain."""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from blockchainkit.consensus.systems.pow import expected_trials, valid_pow
+from blockchainkit.structures.systems.block import Block
+from blockchainkit.structures.systems.ledger import Ledger
+
+
+class Blockchain:
+    """Store valid forks and select the tip with greatest cumulative work.
+
+    Parameters
+    ----------
+    genesis : Block
+        Mined, empty height-zero block with a zero parent hash.
+    initial_state : Ledger, optional
+        Shared initial allocation and chain ID.
+
+    Notes
+    -----
+    Difficulty is fixed by genesis; a child cannot lower its own target.
+    Equal-work ties select the lexicographically smaller hash, so peers with
+    the same block set converge independent of arrival order. This teaching
+    tie-break is not Bitcoin's first-seen behavior. Each fork retains its own
+    ledger snapshot, so reorganizations restore balances and nonces.
+
+    Keeping a full snapshot per block makes reorganizations easy to inspect,
+    at a memory cost proportional to blocks times accounts. Real nodes keep
+    one state and undo data instead.
+    """
+
+    def __init__(self, genesis: Block, initial_state: Ledger | None = None) -> None:
+        if genesis.height != 0 or genesis.previous_hash != bytes(32) or genesis.transactions:
+            raise ValueError("genesis must have height zero, zero parent, and no transactions")
+        if not valid_pow(genesis):
+            raise ValueError("genesis proof of work is invalid")
+        self._blocks = {genesis.hash: genesis}
+        self._states = {genesis.hash: Ledger() if initial_state is None else initial_state}
+        self._work = {genesis.hash: expected_trials(genesis.difficulty)}
+        self._tip = genesis.hash
+        self._difficulty = genesis.difficulty
+
+    def __repr__(self) -> str:
+        return (
+            f"Blockchain(height={self.tip.height}, blocks={len(self._blocks)}, "
+            f"tip={self._tip.hex()[:16]}..., cumulative_work={self.cumulative_work})"
+        )
+
+    @property
+    def tip(self) -> Block:
+        """Return the selected canonical tip."""
+        return self._blocks[self._tip]
+
+    @property
+    def state(self) -> Ledger:
+        """Return the selected tip's validated ledger snapshot."""
+        return self._states[self._tip]
+
+    @property
+    def cumulative_work(self) -> int:
+        """Return total expected hash trials represented by the canonical chain."""
+        return self._work[self._tip]
+
+    @property
+    def blocks(self) -> Mapping[bytes, Block]:
+        """Read-only view of every stored block by hash, including side forks."""
+        return MappingProxyType(self._blocks)
+
+    def tips(self) -> tuple[Block, ...]:
+        """Return the blocks that have no child: the tip of every fork.
+
+        Ordered as fork choice ranks them: most cumulative work first, ties
+        broken by the smaller hash. The first tip is always :attr:`tip`.
+        """
+        parents = {block.previous_hash for block in self._blocks.values()}
+        leaves = [digest for digest in self._blocks if digest not in parents]
+        leaves.sort(key=lambda digest: (-self._work[digest], digest))
+        return tuple(self._blocks[digest] for digest in leaves)
+
+    def work_at(self, block_hash: bytes) -> int:
+        """Return the cumulative expected work of the chain ending at a stored block.
+
+        Raises KeyError for an unknown hash.
+        """
+        return self._work[block_hash]
+
+    def state_at(self, block_hash: bytes) -> Ledger:
+        """Return the ledger snapshot after a stored block, on whichever fork it lies.
+
+        Raises KeyError for an unknown hash.
+        """
+        return self._states[block_hash]
+
+    def contains(self, block_hash: bytes) -> bool:
+        """Return whether this node already knows a block, including side forks."""
+        return block_hash in self._blocks
+
+    def add(self, block: Block) -> bool:
+        """Validate and store a child; return whether the preferred tip changed.
+
+        Unknown parents raise ValueError. Networking experiments can buffer
+        such blocks until their parents arrive. Duplicate blocks are ignored.
+        """
+        digest = block.hash
+        if digest in self._blocks:
+            return False
+        parent = self._blocks.get(block.previous_hash)
+        if parent is None:
+            raise ValueError("unknown parent")
+        if block.height != parent.height + 1 or block.timestamp < parent.timestamp:
+            raise ValueError("invalid height or timestamp before parent")
+        if block.difficulty != self._difficulty or not valid_pow(block):
+            raise ValueError("invalid difficulty or proof of work")
+        state = self._states[parent.hash].apply(block.transactions)
+        work = self._work[parent.hash] + expected_trials(block.difficulty)
+        self._blocks[digest], self._states[digest], self._work[digest] = block, state, work
+        preferred = work > self._work[self._tip] or (
+            work == self._work[self._tip] and digest < self._tip
+        )
+        if preferred:
+            self._tip = digest
+        return preferred
+
+    def canonical_blocks(self) -> tuple[Block, ...]:
+        """Return the selected chain from genesis through tip."""
+        result = [self.tip]
+        while result[-1].height:
+            result.append(self._blocks[result[-1].previous_hash])
+        return tuple(reversed(result))

blockchainkit/structures/systems/hash_chain.py

@@ -0,0 +1,35 @@
+"""Lamport's hash chains (1981): one-time passwords from repeated hashing.
+
+Hash a secret seed n times. The server stores only the last link. To log in,
+the user reveals the link before it; the server hashes it once, compares,
+and stores the revealed link as the new anchor. An eavesdropper who captures
+a password learns a value the server will never accept again, and cannot
+compute the next one without inverting the hash. This became S/KEY (1995).
+"""
+
+import hmac
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def hash_chain(seed: bytes, length: int) -> tuple[bytes, ...]:
+    """Return ``(H(seed), H(H(seed)), ..., H^length(seed))``.
+
+    >>> from blockchainkit.structures import hash_chain
+    >>> len(hash_chain(b"seed", 3))
+    3
+    """
+    if not isinstance(seed, bytes):
+        raise TypeError("seed must be bytes")
+    integer(length, "length", 1)
+    links, current = [], seed
+    for _ in range(length):
+        current = sha256(current)
+        links.append(current)
+    return tuple(links)
+
+
+def verify_one_time_password(password: bytes, anchor: bytes) -> bool:
+    """Return whether ``H(password)`` equals the stored anchor (constant-time)."""
+    return isinstance(password, bytes) and hmac.compare_digest(sha256(password), anchor)

blockchainkit/structures/systems/headers.py

@@ -0,0 +1,54 @@
+"""Simplified payment verification: checking a chain of headers without blocks.
+
+Nakamoto's whitepaper (section 8) observed that a client can verify a payment
+without downloading the blockchain: keep only the block headers, check that
+they link and carry proof of work, and ask for a Merkle proof that the
+transaction is in one of them. Trust shifts to an assumption: the
+heaviest header chain is the one honest miners extended.
+"""
+
+from collections.abc import Sequence
+
+from blockchainkit.consensus.systems.pow import expected_trials, target
+from blockchainkit.structures.systems.block import BlockHeader
+
+
+def verify_header_chain(headers: Sequence[BlockHeader]) -> int:
+    """Check that headers link by hash and carry their proof of work.
+
+    Parameters
+    ----------
+    headers : sequence of BlockHeader
+        Consecutive headers, oldest first (not necessarily from genesis).
+
+    Returns
+    -------
+    int
+        The expected work they represent, the sum of ``2**difficulty``.
+
+    Raises
+    ------
+    ValueError
+        The list is empty, a header does not link to its predecessor, or a
+        hash misses its target.
+
+    Examples
+    --------
+    >>> import blockchainkit as bk
+    >>> genesis = bk.consensus.mine(bk.structures.Block(difficulty=4)).block
+    >>> bk.structures.verify_header_chain([genesis.to_header()])
+    16
+    """
+    if not headers:
+        raise ValueError("an empty header chain proves nothing")
+    work = 0
+    for index, header in enumerate(headers):
+        if index and (
+            header.previous_hash != headers[index - 1].hash
+            or header.height != headers[index - 1].height + 1
+        ):
+            raise ValueError(f"header {index} does not link to its predecessor")
+        if int.from_bytes(header.hash, "big") > target(header.difficulty):
+            raise ValueError(f"header {index} misses its proof of work target")
+        work += expected_trials(header.difficulty)
+    return work

blockchainkit/structures/systems/ledger.py

@@ -0,0 +1,87 @@
+"""Immutable account balances and nonces, updated atomically by signed transfers."""
+
+from collections.abc import Iterable, Mapping
+from types import MappingProxyType
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import DEFAULT_CHAIN_ID
+from blockchainkit.structures.systems.transaction import Transaction
+from blockchainkit.structures.utils.accounts import is_account_id
+
+
+class Ledger:
+    """An immutable view of account balances and next expected nonces.
+
+    Initial balances are a shared simulation configuration, not a minting
+    transaction. All peers must start with the same allocation and chain ID.
+    Applying a batch returns a new state; failures leave the old state intact.
+    """
+
+    def __init__(
+        self,
+        balances: Mapping[str, int] | None = None,
+        nonces: Mapping[str, int] | None = None,
+        *,
+        chain_id: str = DEFAULT_CHAIN_ID,
+    ) -> None:
+        if not isinstance(chain_id, str) or not 1 <= len(chain_id) <= 128:
+            raise ValueError("chain_id must contain 1 to 128 characters")
+        for mapping in (balances or {}, nonces or {}):
+            for account, value in mapping.items():
+                if not is_account_id(account):
+                    raise ValueError("account IDs must be 64 lowercase hex characters")
+                integer(value, "account value")
+        self._balances = MappingProxyType(dict(balances or {}))
+        self._nonces = MappingProxyType(dict(nonces or {}))
+        self._chain_id = chain_id
+
+    def __repr__(self) -> str:
+        return (
+            f"Ledger(chain_id={self._chain_id!r}, accounts={len(self._balances)}, "
+            f"supply={self.total_supply})"
+        )
+
+    @property
+    def total_supply(self) -> int:
+        """Return the sum of all balances, which transfers never change.
+
+        Every transfer debits one account and credits another by the same
+        amount: Pacioli's double-entry rule. A change in total supply would
+        mean money was created or destroyed.
+        """
+        return sum(self._balances.values())
+
+    @property
+    def balances(self) -> Mapping[str, int]:
+        """Read-only account balances in integer units."""
+        return self._balances
+
+    @property
+    def nonces(self) -> Mapping[str, int]:
+        """Read-only next expected sequence numbers (missing accounts start at 0)."""
+        return self._nonces
+
+    @property
+    def chain_id(self) -> str:
+        """Return the signature domain accepted by this ledger."""
+        return self._chain_id
+
+    def apply(self, transactions: Iterable[Transaction]) -> "Ledger":
+        """Validate and atomically apply transfers in order, returning a new ledger.
+
+        Rejects invalid signatures, wrong chain IDs, replayed/out-of-order
+        nonces, and insufficient funds. Self-transfers still consume a nonce.
+        """
+        balances, nonces = dict(self.balances), dict(self.nonces)
+        for tx in transactions:
+            if tx.chain_id != self.chain_id or not tx.is_valid():
+                raise ValueError("wrong chain ID or invalid signature")
+            sender = tx.sender_address
+            if tx.nonce != nonces.get(sender, 0):
+                raise ValueError("unexpected account nonce (replay or out-of-order transfer)")
+            if tx.amount > balances.get(sender, 0):
+                raise ValueError("insufficient funds")
+            balances[sender] = balances.get(sender, 0) - tx.amount
+            balances[tx.recipient] = balances.get(tx.recipient, 0) + tx.amount
+            nonces[sender] = tx.nonce + 1
+        return Ledger(balances, nonces, chain_id=self.chain_id)